故障排除

如果你只有 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 → 目标 Gateway 可达。
  • openclaw gateway status → Runtime: running 和 RPC probe: ok。
  • openclaw doctor → 无阻塞性配置/服务错误。
  • openclaw channels status --probe → 频道报告 connected 或 ready。
  • openclaw logs --follow → 稳定活动，无重复致命错误。

决策树

flowchart TD
  A[OpenClaw 不工作] --> B{什么先出问题}
  B --> C[无回复]
  B --> D[仪表板或控制 UI 无法连接]
  B --> E[Gateway 无法启动或服务未运行]
  B --> F[频道已连接但消息不流动]
  B --> G[定时任务或心跳未触发或未送达]
  B --> H[Node 已配对但相机画布屏幕执行失败]
  B --> I[浏览器工具失败]

  C --> C1[/无回复部分/]
  D --> D1[/控制 UI 部分/]
  E --> E1[/Gateway 部分/]
  F --> F1[/频道流程部分/]
  G --> G1[/自动化部分/]
  H --> H1[/Node 工具部分/]
  I --> I1[/浏览器部分/]
```bash openclaw status openclaw gateway status openclaw channels status --probe openclaw pairing list --channel [--account ] openclaw logs --follow ``` 
良好的输出表现为：

- `Runtime: running`
- `RPC probe: ok`
- 你的频道在 `channels status --probe` 中显示 connected/ready
- 发送者已批准（或 DM 策略为 open/白名单）

常见日志特征：

- `drop guild message (mention required` → Discord 中提及 gating 阻止了消息。
- `pairing request` → 发送者未批准，等待 DM 配对批准。
- `blocked` / `allowlist` 在频道日志中 → 发送者、房间或组被过滤。

深入页面：

- [/zh/docs/gateway/troubleshooting#无回复](/zh/docs/gateway/troubleshooting#无回复)
- [/zh/docs/channels/troubleshooting](/zh/docs/channels/troubleshooting)
- [/zh/docs/channels/pairing](/zh/docs/channels/pairing)
 ```bash openclaw status openclaw gateway status openclaw logs --follow openclaw doctor openclaw channels status --probe ``` 
良好的输出表现为：

- `Dashboard: http://...` 在 `openclaw gateway status` 中显示
- `RPC probe: ok`
- 日志中无认证循环

常见日志特征：

- `device identity required` → HTTP/非安全上下文无法完成设备认证。
- `unauthorized` / 重连循环 → 令牌/密码错误或认证模式不匹配。
- `gateway connect failed:` → UI 指向错误的 URL/端口或 Gateway 不可达。

深入页面：

- [/zh/docs/gateway/troubleshooting#仪表板控制-ui-连接性](/zh/docs/gateway/troubleshooting#仪表板控制-ui-连接性)
- [/zh/docs/web/control-ui](/zh/docs/web/control-ui)
- [/zh/docs/gateway/authentication](/zh/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` → Gateway 模式未设置/为远程。
- `refusing to bind gateway ... without auth` → 无令牌/密码的 non-loopback 绑定。
- `another gateway instance is already listening` 或 `EADDRINUSE` → 端口已被占用。

深入页面：

- [/zh/docs/gateway/troubleshooting#gateway-服务未运行](/zh/docs/gateway/troubleshooting#gateway-服务未运行)
- [/zh/docs/gateway/background-process](/zh/docs/gateway/background-process)
- [/zh/docs/gateway/configuration](/zh/docs/gateway/configuration)
 ```bash openclaw status openclaw gateway status openclaw logs --follow openclaw doctor openclaw channels status --probe ``` 
良好的输出表现为：

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

常见日志特征：

- `mention required` → 组提及 gating 阻止处理。
- `pairing` / `pending` → DM 发送者尚未批准。
- `not_in_channel`、`missing_scope`、`Forbidden`、`401/403` → 频道权限令牌问题。

深入页面：

- [/zh/docs/gateway/troubleshooting#频道已连接消息不流动](/zh/docs/gateway/troubleshooting#频道已连接消息不流动)
- [/zh/docs/channels/troubleshooting](/zh/docs/channels/troubleshooting)
 ```bash openclaw status openclaw gateway status openclaw cron status openclaw cron list openclaw cron runs --id --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` → 心跳送达目标账户不存在。

深入页面：

- [/zh/docs/gateway/troubleshooting#定时任务和心跳送达](/zh/docs/gateway/troubleshooting#定时任务和心跳送达)
- [/zh/docs/automation/troubleshooting](/zh/docs/automation/troubleshooting)
- [/zh/docs/gateway/heartbeat](/zh/docs/gateway/heartbeat)
 ```bash openclaw status openclaw gateway status openclaw nodes status openclaw nodes describe --node openclaw logs --follow ``` 
良好的输出表现为：

- Node 列为已连接并为 `node` 角色配对。
- 你调用的命令存在能力。
- 工具的权限状态已授予。

常见日志特征：

- `NODE_BACKGROUND_UNAVAILABLE` → 将 node 应用带到前台。
- `*_PERMISSION_REQUIRED` → OS 权限被拒绝/缺失。
- `SYSTEM_RUN_DENIED: approval required` → 执行批准待定。
- `SYSTEM_RUN_DENIED: allowlist miss` → 命令不在执行白名单中。

深入页面：

- [/zh/docs/gateway/troubleshooting#node-已配对工具失败](/zh/docs/gateway/troubleshooting#node-已配对工具失败)
- [/zh/docs/nodes/troubleshooting](/zh/docs/nodes/troubleshooting)
- [/zh/docs/tools/exec-approvals](/zh/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 目标。

深入页面：

- [/zh/docs/gateway/troubleshooting#浏览器工具失败](/zh/docs/gateway/troubleshooting#浏览器工具失败)
- [/zh/docs/tools/browser-linux-troubleshooting](/zh/docs/tools/browser-linux-troubleshooting)
- [/zh/docs/tools/chrome-extension](/zh/docs/tools/chrome-extension)