本页是 OpenClaw 故障排查的"急诊入口"。60 秒内用一组诊断命令快速定位问题，再跳转到对应深度文档。覆盖无响应、控制台连接失败、网关无法启动、消息不通、定时任务/心跳、节点工具、浏览器工具共七大场景。

OpenClaw 故障排查

两分钟内搞定？用本页做分诊入口。

前 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 → Reachable: yes（RPC: limited - missing scope: operator.read 是降级诊断，不是连接失败）
openclaw gateway status → Runtime: running 且 RPC probe: ok
openclaw doctor → 无阻断性配置/服务报错
openclaw channels status --probe → 网关可达时返回每账号的实时传输状态和 works 或 audit ok；网关不可达时仅返回配置摘要
openclaw logs --follow → 有持续活动，无重复性致命报错

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？说明插件包格式已过期。

修复方法（在插件包中操作）：

在 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[控制台或 Control UI 无法连接]
  B --> E[网关无法启动或服务未运行]
  B --> F[渠道已连接但消息不通]
  B --> G[Cron 或心跳未触发/未送达]
  B --> H[节点已配对但工具失败]
  B --> I[浏览器工具失败]

无响应

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、渠道显示 works 或 audit ok、发送者已审批。

常见日志特征：

drop guild message (mention required → Discord mention 过滤阻断消息
pairing request → 发送者未审批，等待 DM 配对
blocked / allowlist → 发送者、房间或群组被过滤

深度文档：网关故障排查、渠道配对

控制台或 Control UI 无法连接

bash

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

常见日志特征：

device identity required → 非安全上下文无法完成设备认证
origin not allowed → 浏览器 Origin 未在允许列表中
AUTH_TOKEN_MISMATCH + 重试提示 → 系统会用缓存 device-token 自动重试一次
too many failed authentication attempts → 同 Origin 多次失败后临时锁定
gateway connect failed: → UI 指向了错误 URL/端口或不可达网关

深度文档：Control UI、网关认证

网关无法启动或服务未运行

bash

openclaw gateway status
openclaw logs --follow
openclaw doctor

常见日志特征：

Gateway start blocked: set gateway.mode=local → 网关模式为 remote 或缺少 local 标记
refusing to bind gateway ... without auth → 非回环绑定但缺少有效认证路径
another gateway instance is already listening 或 EADDRINUSE → 端口已被占用

深度文档：网关后台进程、网关配置

渠道已连接但消息不通

常见日志特征：

mention required → 群组 mention 过滤阻断处理
pairing / pending → DM 发送者尚未审批
not_in_channel, missing_scope, Forbidden, 401/403 → 渠道权限 token 问题

深度文档：渠道故障排查

Cron 或心跳未触发/未送达

bash

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

常见日志特征：

cron: scheduler disabled → cron 已禁用
heartbeat skipped reason=quiet-hours → 当前在静默时间段内
heartbeat skipped reason=empty-heartbeat-file → HEARTBEAT.md 内容只有空白/标题
heartbeat skipped reason=no-tasks-due → 任务模式下无任务到期
requests-in-flight → 主通道忙，心跳唤醒被推迟
unknown accountId → 心跳投递目标账号不存在

深度文档：心跳配置、定时任务故障排查

节点已配对但工具失败

bash

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

常见日志特征：

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

深度文档：exec 审批

Exec 突然要求审批

bash

openclaw config get tools.exec.host
openclaw config get tools.exec.security
openclaw config get tools.exec.ask

host=auto 解析到 sandbox（沙箱存在时）或 gateway（否则）。不提示行为来自 security=full + ask=off 组合。

恢复默认无拦截：

bash

openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw gateway restart

深度文档：exec 工具、exec 审批

浏览器工具失败

bash

openclaw browser status
openclaw logs --follow
openclaw doctor

常见日志特征：

unknown command "browser" → plugins.allow 中未包含 browser
Failed to start Chrome CDP on port → 本地浏览器启动失败
browser.executablePath not found → 配置路径有误
No Chrome tabs found for profile="user" → 无打开的本地 Chrome 标签页
Remote CDP for profile "<name>" is not reachable → 远程 CDP 端点不可达

深度文档：浏览器工具

常见问题

Q: openclaw doctor 显示无错误但龙虾还是不响应，怎么办？

A: 跑 openclaw channels status --probe 检查每个渠道的实时传输状态，再看 openclaw logs --follow 中是否有 pairing request 或 allowlist 字样，说明发送者被过滤了。

Q: Control UI 打开后一直提示"连接中"，是什么原因？

A: 最常见原因是浏览器 Origin 未在网关允许列表（日志报 origin not allowed），或网关 URL/端口配置错误（日志报 gateway connect failed）。检查 gateway.controlUi.allowedOrigins 配置。

Q: Cron 任务设好了但从不触发，如何排查？

A: 运行 openclaw cron status 确认 cron 已启用，再跑 openclaw cron runs --id <jobId> --limit 20 查历史。日志有 heartbeat skipped reason=quiet-hours 说明当前在静默时间段内。

OpenClaw 故障排查 ​

前 60 秒必跑命令 ​

Anthropic 长上下文 429 ​

插件安装失败（缺少 openclaw extensions） ​

问题决策树 ​

无响应 ​

控制台或 Control UI 无法连接 ​

网关无法启动或服务未运行 ​

渠道已连接但消息不通 ​

Cron 或心跳未触发/未送达 ​

节点已配对但工具失败 ​

Exec 突然要求审批 ​

浏览器工具失败 ​

相关文档 ​

常见问题 ​

OpenClaw 故障排查

前 60 秒必跑命令

Anthropic 长上下文 429

插件安装失败（缺少 openclaw extensions）

问题决策树

无响应

控制台或 Control UI 无法连接

网关无法启动或服务未运行

渠道已连接但消息不通

Cron 或心跳未触发/未送达

节点已配对但工具失败

Exec 突然要求审批

浏览器工具失败

相关文档

常见问题