18. 调试与排障：从 doctor、gateway status、日志和状态目录开始

这篇解决什么问题

OpenClaw 出问题时，不要先猜。

先判断问题在哪一层：安装、配置、Gateway、Channel、Session、Agent Runtime、Provider、Tools、Cron，还是 Plugin/MCP。

先跑基础命令

openclaw doctor
openclaw gateway status
openclaw --version
node -v

如果 Gateway 没跑，先修 Gateway。

如果 Node 版本不够，先修 Node。

看状态目录

默认：

~/.openclaw

重点看：

openclaw.json
credentials/
agents/<agentId>/sessions/
agents/<agentId>/agent/auth-profiles.json
workspace/
cron/
logs/

如果设置了 OPENCLAW_STATE_DIR，要看那个目录，不要看错默认路径。

按层排查

1. CLI 是否能启动
2. Gateway 是否运行
3. channel 是否能收消息
4. pairing / allowlist 是否通过
5. session routing 是否正确
6. provider/auth profile 是否可用
7. tools 是否被 policy/sandbox 限制
8. delivery 是否成功

常见问题

平台不回复

先看 Gateway，再看 channel 凭证、webhook/长连接、pairing 和 allowlist。

CLI agent 能用，平台不能用

Runtime 和 provider 多半没问题，优先查 Gateway/channel。

平台能收到消息，但回答失败

查 provider、auth profile、模型名、rate limit。

工具不出现

查 tool policy、sandbox、sender/group policy、plugin 是否加载。

Cron 不执行

查 cron job 是否启用、cron service 是否运行、run log 是否有错误。

源码开发时的验证

官方 runtime workflow 给的默认 gate：

pnpm check

构建相关改动：

pnpm build

Agent runtime 相关改动更完整：

pnpm check && pnpm test

本教程站点自身验证用：

npm run build

实践：五分钟分层诊断

不要预设故障原因，先运行：

openclaw doctor
openclaw gateway status
openclaw --version
node -v

再查看当前实际状态目录是否有配置、session 和日志。用 3—5 分钟把观察结果归到安装、Gateway、Channel、Runtime/provider 或 tools policy 中的一层。

完成标准

• 四条基础命令均已执行并记录结果；
• 没有因 OPENCLAW_STATE_DIR 看错目录；
• 能给出一个有证据的层级判断，而不是一次重配全部系统。

多走一步

如果正在修改本教程站点，运行 npm run build；如果修改的是 OpenClaw 源码，则按改动范围选择本文列出的 pnpm gate。

下一篇看什么

下一篇看二开路线。