用途:这是一个 OpenClaw 网关诊断 playbook,以只读方式排查 Gateway、配置、secrets、channels 与端口故障。
主要能力:按因果顺序定位问题,覆盖无效配置或 schema 错误、SecretRef owner 降级、频道认证过期或被拒、EADDRINUSE、第二监听者、服务与配置端口不一致,以及 Gateway 崩溃循环。明确不猜测,要求用可观察证据确认。
使用方式:先收集信息,运行 openclaw doctor --lint、openclaw gateway status --deep、openclaw config validate、openclaw channels status、openclaw models status、openclaw channels logs --channel <id>。doctor --lint 为只读,发现项可 exit 1,读报告后继续后续检查;不要用普通 doctor 或 doctor --non-interactive 替代。受管安装可看 ./scripts/clawlog.sh 或网关启动时打印的日志路径,默认 /tmp/openclaw/openclaw-<date>.log。端口检查用 lsof -nP -iTCP:<port> -sTCP:LISTEN。
证明与报告:重复最小的只读探测并记录输出,例如 openclaw gateway status --deep 或 openclaw channels status --probe。若无法访问、日志或网关不可用,明确报告该阻塞,不要断言原因。
限制:不修改配置、不迁移状态、不更改服务;不执行 doctor --fix 或杀监听进程;密钥只报脱敏的 SecretRef owner 状态,绝不打印值。每个发现给出下一步动作,必要时指向 configure-channel、add-model-provider 或 cloud-image-bake;doctor --fix --non-interactive 仅作为单独批准步骤建议。报告中需声明未执行任何配置/服务修复或状态迁移。参考 https://docs.openclaw.ai/gateway/troubleshooting。