故障排查
如果你只有 2 分钟时间，把这个页面当作分诊入口。
前 60 秒
按顺序依次运行以下命令：
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→ 预期的网关目标可达。openclaw gateway status→Runtime: running且RPC probe: ok。openclaw doctor→ 无阻塞性的配置/服务错误。openclaw channels status --probe→ 频道报告connected或ready。openclaw logs --follow→ 稳定活动，无重复的致命错误。
Anthropic 长上下文 429 错误
如果你看到：
HTTP 429: rate_limit_error: Extra usage is required for long context requests，
请前往 /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 <npm-spec>。
示例：
{
"name": "@openclaw/my-plugin",
"version": "1.2.3",
"openclaw": {
"extensions": ["./dist/index.js"]
}
}参考：/tools/plugin#distribution-npm
决策树
flowchart TD
A[OpenClaw 无法正常工作] --> B{哪个环节先出问题}
B --> C[没有回复]
B --> D[仪表盘或控制界面无法连接]
B --> E[网关无法启动或服务未运行]
B --> F[频道已连接但消息不流通]
B --> G[定时任务或心跳未触发或未送达]
B --> H[节点已配对但摄像头/画布/屏幕/exec 失败]
B --> I[浏览器工具失败]
C --> C1[/没有回复 章节/]
D --> D1[/控制界面 章节/]
E --> E1[/网关 章节/]
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 策略为 open/allowlist）
常见日志特征：
- `drop guild message (mention required` → Discord 的提及门控拦截了消息。
- `pairing request` → 发送者未获批准，正在等待 DM 配对审批。
- `blocked` / `allowlist` 出现在频道日志中 → 发送者、房间或群组被过滤。
深入文档：
- [/gateway/troubleshooting#no-replies](/docs/gateway/troubleshooting#no-replies)
- [/channels/troubleshooting](/docs/channels/troubleshooting)
- [/channels/pairing](/docs/channels/pairing)仪表盘或控制界面无法连接
```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/troubleshooting#dashboard-control-ui-connectivity](/docs/gateway/troubleshooting#dashboard-control-ui-connectivity)
- [/web/control-ui](/docs/web/control-ui)
- [/gateway/authentication](/docs/gateway/authentication)网关无法启动或服务已安装但未运行
```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` → 网关模式未设置/为 remote。
- `refusing to bind gateway ... without auth` → 非回环地址绑定但未设置令牌/密码。
- `another gateway instance is already listening` 或 `EADDRINUSE` → 端口已被占用。
深入文档：
- [/gateway/troubleshooting#gateway-service-not-running](/docs/gateway/troubleshooting#gateway-service-not-running)
- [/gateway/background-process](/docs/gateway/background-process)
- [/gateway/configuration](/docs/gateway/configuration)频道已连接但消息不流通
```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
```
正常输出：
- 频道传输层已连接。
- 配对/白名单检查通过。
- 需要 @提及 的场景中提及已被检测到。
常见日志特征：
- `mention required` → 群组提及门控阻止了消息处理。
- `pairing` / `pending` → DM 发送者尚未获批。
- `not_in_channel`、`missing_scope`、`Forbidden`、`401/403` → 频道权限令牌问题。
深入文档：
- [/gateway/troubleshooting#channel-connected-messages-not-flowing](/docs/gateway/troubleshooting#channel-connected-messages-not-flowing)
- [/channels/troubleshooting](/docs/channels/troubleshooting)定时任务或心跳未触发或未送达
```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` → 心跳投递目标账户不存在。
深入文档：
- [/gateway/troubleshooting#cron-and-heartbeat-delivery](/docs/gateway/troubleshooting#cron-and-heartbeat-delivery)
- [/automation/troubleshooting](/docs/automation/troubleshooting)
- [/gateway/heartbeat](/docs/gateway/heartbeat)节点已配对但摄像头/画布/屏幕/exec 工具失败
```bash
openclaw status
openclaw gateway status
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw logs --follow
```
正常输出：
- 节点列为已连接且已配对，角色为 `node`。
- 你要调用的命令对应的能力存在。
- 该工具的权限状态为已授予。
常见日志特征：
- `NODE_BACKGROUND_UNAVAILABLE` → 将节点应用切换到前台。
- `*_PERMISSION_REQUIRED` → 操作系统权限被拒绝/缺失。
- `SYSTEM_RUN_DENIED: approval required` → exec 审批待处理。
- `SYSTEM_RUN_DENIED: allowlist miss` → 命令不在 exec 白名单中。
深入文档：
- [/gateway/troubleshooting#node-paired-tool-fails](/docs/gateway/troubleshooting#node-paired-tool-fails)
- [/nodes/troubleshooting](/docs/nodes/troubleshooting)
- [/tools/exec-approvals](/docs/tools/exec-approvals)浏览器工具失败
```bash
openclaw status
openclaw gateway status
openclaw browser status
openclaw logs --follow
openclaw doctor
```
正常输出：
- 浏览器状态显示 `running: true` 并选择了浏览器/配置文件。
- `openclaw` 配置文件启动成功或 `chrome` 中继已连接标签页。
常见日志特征：
- `Failed to start Chrome CDP on port` → 本地浏览器启动失败。
- `browser.executablePath not found` → 配置的浏览器路径不正确。
- `Chrome extension relay is running, but no tab is connected` → 扩展未连接。
- `Browser attachOnly is enabled ... not reachable` → 仅附加模式下没有可用的 CDP 目标。
深入文档：
- [/gateway/troubleshooting#browser-tool-fails](/docs/gateway/troubleshooting#browser-tool-fails)
- [/tools/browser-linux-troubleshooting](/docs/tools/browser-linux-troubleshooting)
- [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/docs/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
- [/tools/chrome-extension](/docs/tools/chrome-extension)