故障排查

如果你只有 2 分钟，用这个页面作为快速分诊入口。

前 60 秒

按顺序执行以下命令：

bash

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

各命令正常输出说明：

openclaw status → 显示已配置的频道，无明显认证报错。
openclaw status --all → 完整报告可正常输出并可分享。
openclaw gateway probe → 目标 Gateway 可达（Reachable: yes）。RPC: limited - missing scope: operator.read 表示诊断受限，不代表连接失败。
openclaw gateway status → Runtime: running 且 RPC probe: ok。
openclaw doctor → 无阻断性配置或服务错误。
openclaw channels status --probe → 频道显示 connected 或 ready。
openclaw logs --follow → 日志持续输出，没有反复出现的 fatal 错误。

Anthropic 长上下文 429 错误

如果看到： HTTP 429: rate_limit_error: Extra usage is required for long context requests，请前往 /openclaw/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context。

插件安装失败：缺少 openclaw extensions

如果安装报错 package.json missing openclaw.extensions，说明该插件包使用了 OpenClaw 不再支持的旧格式。

在插件包中修复：

在 package.json 中添加 openclaw.extensions 字段。
将入口指向编译后的运行时文件（通常是 ./dist/index.js）。
重新发布插件，再次运行 openclaw plugins install <package>。

示例：

json

{
  "name": "@openclaw/my-plugin",
  "version": "1.2.3",
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

参考：插件架构

决策树

mermaid

flowchart TD
  A[OpenClaw 出问题了] --> B{最先出问题的是什么}
  B --> C[没有回复]
  B --> D[Dashboard 或 Control UI 无法连接]
  B --> E[Gateway 无法启动或服务未运行]
  B --> F[频道已连接但消息不流转]
  B --> G[定时任务或心跳未触发或未投递]
  B --> H[节点已配对但 camera/canvas/screen exec 失败]
  B --> I[浏览器工具失败]

  C --> C1[/无回复章节/]
  D --> D1[/Control UI 章节/]
  E --> E1[/Gateway 章节/]
  F --> F1[/频道流转章节/]
  G --> G1[/自动化章节/]
  H --> H1[/节点工具章节/]
  I --> I1[/浏览器章节/]

没有回复

bash

openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow

正常输出应该是：

Runtime: running
RPC probe: ok
你的频道在 channels status --probe 中显示 connected/ready
发送方已通过审批（或 DM 策略为开放/白名单）

常见日志特征：

drop guild message (mention required → Discord 中 mention 门控拦截了消息。
pairing request → 发送方未通过审批，等待 DM 配对确认。
blocked / allowlist 出现在频道日志 → 发送方、房间或群组被过滤。

深度文档：

Dashboard 或 Control UI 无法连接

bash

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

正常输出应该是：

openclaw gateway status 中显示 Dashboard: http://...
RPC probe: ok
日志中没有认证死循环

常见日志特征：

device identity required → HTTP/非安全上下文无法完成设备认证。
AUTH_TOKEN_MISMATCH 伴有重试提示（canRetryWithDeviceToken=true）→ 可能自动尝试一次可信设备令牌重试。
重试后仍反复出现 unauthorized → 令牌/密码错误、认证模式不匹配，或配对设备令牌已过期。
gateway connect failed: → UI 指向了错误的 URL/端口，或 Gateway 不可达。

深度文档：

Gateway 无法启动或服务已安装但未运行

bash

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

正常输出应该是：

Service: ... (loaded)
Runtime: running
RPC probe: ok

常见日志特征：

Gateway start blocked: set gateway.mode=local → gateway 模式未设置或为 remote。
refusing to bind gateway ... without auth → 非 loopback 绑定但没有配置 token/密码。
another gateway instance is already listening 或 EADDRINUSE → 端口已被占用。

深度文档：

频道已连接但消息不流转

bash

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

正常输出应该是：

频道传输层已连接。
配对/白名单检查通过。
在需要的地方检测到了 mention。

常见日志特征：

mention required → 群组 mention 门控拦截了消息处理。
pairing / pending → DM 发送方尚未通过审批。
not_in_channel、missing_scope、Forbidden、401/403 → 频道权限令牌问题。

深度文档：

定时任务或心跳未触发或未投递

bash

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw logs --follow

正常输出应该是：

cron.status 显示已启用并有下次唤醒时间。
cron runs 显示近期有 ok 记录。
心跳已启用且不在活跃时段之外。

常见日志特征：

cron: scheduler disabled; jobs will not run automatically → 定时器已禁用。
heartbeat skipped 伴有 reason=quiet-hours → 在配置的活跃时段之外。
requests-in-flight → 主通道繁忙，心跳唤醒被推迟。
unknown accountId → 心跳投递目标账户不存在。

深度文档：

节点已配对但工具 camera/canvas/screen exec 失败

bash

openclaw status
openclaw gateway status
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw logs --follow

正常输出应该是：

节点以 node 角色列为已连接并已配对。
你调用的命令具有对应的能力声明。
该工具的权限状态为已授权。

常见日志特征：

NODE_BACKGROUND_UNAVAILABLE → 将节点 App 切换到前台。
*_PERMISSION_REQUIRED → 操作系统权限被拒绝或缺失。
SYSTEM_RUN_DENIED: approval required → exec 审批待处理。
SYSTEM_RUN_DENIED: allowlist miss → 命令不在 exec 白名单中。

深度文档：

浏览器工具失败

bash

openclaw status
openclaw gateway status
openclaw browser status
openclaw logs --follow
openclaw doctor

正常输出应该是：

浏览器状态显示 running: true 并有选定的浏览器/配置文件。
openclaw 可启动，或 user 能看到本地 Chrome 标签页。

常见日志特征：

Failed to start Chrome CDP on port → 本地浏览器启动失败。
browser.executablePath not found → 配置的二进制路径有误。
No Chrome tabs found for profile="user" → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。
Browser attachOnly is enabled ... not reachable → 仅附加模式的配置文件没有存活的 CDP 目标。

深度文档：

故障排查 ​

前 60 秒 ​

Anthropic 长上下文 429 错误 ​

插件安装失败：缺少 openclaw extensions ​

决策树 ​

故障排查

前 60 秒

Anthropic 长上下文 429 错误

插件安装失败：缺少 openclaw extensions

决策树