doctor命令是OpenClaw/CodeBuddy生态中排查“看似无错实则失能”故障的结构化诊断工具，含check、inspect、export三种模式：check验证配置语法与核心字段完整性；inspect加--verbose定位具体错误行；export生成JSON日志用于跨环境比对。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在OpenClaw或CodeBuddy生态中遇到功能异常、模块加载失败、连接器报错却状态显示正常等“看似无错实则失能”的复杂故障时，仅靠日志滚动和手动猜测已失效，必须启用结构化诊断工具——doctor命令。
用doctor执行基础健康检查
这一步验证配置文件语法合法性与核心字段完整性，是所有排查的起点。
打开终端，进入OpenClaw安装根目录 → 执行./bin/doctor --mode=check（macOS/Linux）或bin\doctor.exe --mode=check（Windows）。
若返回非零退出码（如1或2），说明配置存在硬性错误：比如YAML缩进错位、必填字段为空、字段类型不匹配。此时不要跳过，【必须先修复该错误再继续后续诊断】，否则inspect和export模式将无法正确解析上下文。
启用详细模式定位具体出错行
基础检查只告诉你“config.yaml有错”，但不会说哪一行。inspect模式专治这种模糊报错。
方法一：直接运行./bin/doctor --mode=inspect --verbose，控制台会逐行输出解析过程，重点关注以[LINE X]开头的报错行。
方法二：同步查看生成的日志文件doctor-inspect-*.log，搜索CONTEXT_SNIPPET标记段落，里面会完整展示出错行及其前后两行原始内容——这能帮你一眼识别是多了一个冒号、少了一个横杠，还是引号没闭合。
注意：--verbose参数不可省略，不加它就看不到行号和上下文，等于白跑。
导出JSON日志做跨环境比对
当本地能跑、测试环境崩、生产环境偶发失败时，问题往往藏在配置差异里。人工肉眼比对YAML极易遗漏空格、换行、注释格式等隐形差异。
第一步：在任一环境执行./bin/doctor --mode=export --output=config-diag.json，生成结构化诊断快照。
第二步：用VS Code或DiffMerge等工具并排打开两个环境的config-diag.json，聚焦比对plugins、connectors、gateway三个顶层键下的字段值与嵌套结构。
第三步：重点检查enabled布尔值是否一致、port是否被其他进程占用、auth_token是否过期或被截断——这些才是跨环境故障的高频根源。
