OpenClaw 故障排查教程，status doctor logs 使用指南

当 OpenClaw 不工作时，最容易浪费时间的做法是“凭感觉改配置”。官方故障排查页给出的建议很明确：先看状态和日志，再针对具体症状处理。

先跑这组诊断命令#

官方给出的第一组排查命令如下：

openclaw status
openclaw status --all
openclaw status --deep
openclaw gateway probe
openclaw channels status --probe
openclaw gateway status
openclaw logs --follow

这些命令的用途可以这样理解：

• openclaw status：快速概览
• openclaw status --all：适合整理成调试报告
• openclaw status --deep：检查 Gateway 健康和提供商探测
• openclaw gateway probe：确认 CLI 实际探测的是哪一个 Gateway
• openclaw channels status --probe：确认渠道状态
• openclaw gateway status：看监管程序、PID、最后退出状态
• openclaw logs --follow：看实时错误

日志优先看哪里#

官方建议日志排查优先级如下：

1. openclaw logs --follow
2. /tmp/openclaw/openclaw-YYYY-MM-DD.log
3. 如果是 macOS LaunchAgent，再看：

$OPENCLAW_STATE_DIR/logs/gateway.log
$OPENCLAW_STATE_DIR/logs/gateway.err.log

4. 如果是 Linux systemd 用户服务，再看：

journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager

服务已安装但没有运行#

官方对这个问题的标准排查是：

openclaw gateway status
openclaw doctor

同时查看：

openclaw logs --follow

如果需要更多日志，可以把配置调高：

{ "logging": { "level": "debug" } }

或者只提高控制台详细程度：

{ "logging": { "consoleLevel": "debug", "consoleStyle": "pretty" } }

端口 18789 被占用#

如果报“地址已被使用”，官方建议先执行：

openclaw gateway status

这个命令会告诉你：

• 当前是否已经有 Gateway 在运行
• 是否有 SSH 隧道等监听器正在占用端口

处理方式通常只有两种：

• 停掉原有服务
• 或改用另一个端口

服务显示运行，但端口没监听#

这是另一个非常常见的误区。官方解释是：

• 监管程序认为进程“还活着”，不等于 Gateway 真的成功绑定端口
• 真正可信的是探测结果和最后错误日志

这时重点检查：

1. gateway.mode 是否为 local
2. CLI 是否在探测错误的远程地址
3. 非 loopback 绑定时是否配置了 gateway.auth.token
4. 是否误把 token 写到了 gateway.remote.token

官方明确指出：

• 本地认证要用 gateway.auth.token
• gateway.remote.token 只用于远程 CLI 调用
• gateway.token 会被忽略

Dashboard 在 HTTP 下连接失败#

如果你通过局域网 HTTP 地址直接打开 Dashboard，出现：

• device identity required
• connect failed

官方给出的原因是：

• 浏览器运行在非安全上下文
• WebCrypto 无法生成设备身份

推荐修复顺序：

1. 用 Tailscale Serve 走 HTTPS
2. 或直接本机打开 http://127.0.0.1:18789/
3. 如果必须走 HTTP，再考虑：

{
  "gateway": {
    "controlUi": {
      "allowInsecureAuth": true
    }
  }
}

模型认证问题#

官方故障排查页里一个很典型的问题是：

No API key found for provider "anthropic"

它的根因通常是：

• 当前智能体没有自己的认证存储
• 新智能体不会自动继承主智能体密钥

虽然官方示例讲的是 Anthropic，但排查思路对其他提供商也适用：确认你配置的是当前智能体、当前 Gateway 主机、当前 profile，而不是别的环境。

获取帮助时应该附带什么#

如果你准备去 GitHub 提 issue，官方建议至少提供：

• OpenClaw 版本
• 相关日志片段
• 可复现步骤
• 脱敏后的配置

一套实用的排查顺序#

如果你现在就遇到问题，建议按这个顺序：

1. openclaw status
2. openclaw gateway status
3. openclaw logs --follow
4. openclaw doctor
5. 再根据报错去看渠道、模型或远程访问配置

这样效率最高，也最符合官方文档的排查路径。