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

下一篇看什么

下一篇看二开路线。