OpenClaw 出问题了？本页是 60 秒快速分诊入口。按顺序执行 openclaw status → openclaw gateway probe → openclaw doctor → openclaw channels status --probe 等命令，从输出中定位问题类型，再跳转到对应深度文档。覆盖七种常见故障：无回复、Control UI 连接失败、网关无法启动、消息不流通、定时任务/心跳未触发、节点工具失败、浏览器工具失败，每类附典型日志和修复方向。

OpenClaw 故障排查：60秒诊断命令与七大场景定位

如果只有两分钟，用本页快速分诊。

前 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（Capability: ... 说明探测能验证的认证级别；Read probe: limited - missing scope: operator.read 是降级诊断，不是连接失败）
openclaw gateway status → Runtime: running、Connectivity probe: ok、合理的 Capability: ... 行。需要读范围 RPC 证据时可加 --require-rpc
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

本地 OpenAI 兼容后端直连成功但在 OpenClaw 中失败

如果本地或自托管的 /v1 后端能响应简单的直接 /v1/chat/completions 请求，但在 openclaw infer model run 或正常智能体交互中失败：

如果错误提到 messages[].content 期望字符串，设置 models.providers.<provider>.models[].compat.requiresStringContent: true。
如果后端仅在 OpenClaw 智能体交互中失败，设置 models.providers.<provider>.models[].compat.supportsTools: false 并重试。
如果小请求仍正常但较大的 OpenClaw 提示导致后端崩溃，则视为上游模型/服务器限制，跳转到深度文档：/openclaw/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail

插件安装失败（缺少 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"]
  }
}

参考：插件架构

插件存在但因可疑所有权被阻止

如果 openclaw doctor、设置过程或启动警告显示：

text

blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)
plugin present but blocked

说明插件文件的所有者与加载该文件的进程用户不同。不要删除插件配置，修复文件所有权或让 OpenClaw 以拥有状态目录的同一用户运行。

Docker 安装默认以 node（uid 1000）运行。修复 Docker 主机绑定挂载：

bash

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
openclaw doctor --fix

如果刻意以 root 运行 OpenClaw，则将受管理的插件根目录改为 root 所有：

bash

sudo chown -R root:root /path/to/openclaw-config/npm
openclaw doctor --fix

深度文档：

问题决策树

mermaid

flowchart TD
  A[OpenClaw 不工作] --> B{最先出问题的是什么}
  B --> C[无回复]
  B --> D[控制台或 Control UI 无法连接]
  B --> E[网关无法启动或服务未运行]
  B --> F[渠道已连接但消息不通]
  B --> G[Cron 或心跳未触发/未送达]
  B --> H[节点已配对但工具失败]
  B --> I[浏览器工具失败]

  C --> C1[/无回复场景/]
  D --> D1[/Control UI 场景/]
  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
Connectivity probe: ok
Capability: read-only、write-capable 或 admin-capable
渠道显示传输已连接，且在有支持时显示 works 或 audit ok
发送者已审批（或 DM 策略为开放/允许列表）

常见日志特征：

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
openclaw channels status --probe

正常输出特征：

openclaw gateway status 中显示 Dashboard: http://...
Connectivity probe: ok
Capability: read-only、write-capable 或 admin-capable
日志中无认证循环

常见日志特征：

device identity required → HTTP/非安全上下文无法完成设备认证
origin not allowed → 浏览器 Origin 不在 Control UI 网关目标允许列表中
AUTH_TOKEN_MISMATCH 带重试提示（canRetryWithDeviceToken=true）→ 系统可能自动用缓存的 device-token 重试一次
缓存的 token 重试会复用与此设备 token 关联的缓存作用域集。显式使用 deviceToken / 显式 scopes 的调用方会保留请求的作用域集
在异步 Tailscale Serve Control UI 路径上，对相同 {scope, ip} 的失败尝试会在限速器记录失败前串行化，因此第二个并发错误重试可能显示 retry later
too many failed authentication attempts (retry later) 来自 localhost 浏览器来源 → 同一 Origin 多次失败后暂时锁定；其他 localhost 来源使用独立桶
重试后仍有反复 unauthorized → token/password 错误、认证模式不匹配或设备 token 过期
gateway connect failed: → UI 指向错误 URL/端口或网关不可达

深度文档：

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

bash

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

正常输出特征：

Service: ... (loaded)
Runtime: running
Connectivity probe: ok
Capability: read-only、write-capable 或 admin-capable

常见日志特征：

Gateway start blocked: set gateway.mode=local 或 existing config is missing gateway.mode → 网关模式为 remote 或配置文件缺少 local 模式标记，需修复
refusing to bind gateway ... without auth → 非回环绑定但缺少有效认证路径（token/password 或已配置的 trusted-proxy）
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 → 渠道权限 token 问题

深度文档：

Cron 或心跳未触发/未送达

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 → cron 已禁用
heartbeat skipped 带 reason=quiet-hours → 当前在配置的静默时间段内
heartbeat skipped 带 reason=empty-heartbeat-file → HEARTBEAT.md 存在但只包含空白/标题骨架
heartbeat skipped 带 reason=no-tasks-due → HEARTBEAT.md 任务模式已启用但无任务间隔到期
heartbeat skipped 带 reason=alerts-disabled → 所有心跳可见性关闭（showOk、showAlerts、useIndicator 均为 off）
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 白名单中

深度文档：

Exec 突然要求审批

bash

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

变化原因：

如果 tools.exec.host 未设置，默认值为 auto
host=auto 解析为 sandbox（沙箱运行时存在时）或 gateway（否则）
host=auto 仅影响路由；无提示的 "YOLO" 行为来自 security=full + ask=off（在 gateway/node 上）
在 gateway 和 node 上，未设置的 tools.exec.security 默认值为 full
未设置的 tools.exec.ask 默认值为 off
结果：如果看到审批，说明某些主机本地或按会话的策略已收紧 exec

恢复当前默认无审批行为：

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

更安全的替代方案：

如果只想稳定主机路由，仅设置 tools.exec.host=gateway
如果希望主机 exec 但在白名单之外需要审核，使用 security=allowlist + ask=on-miss
如果希望 host=auto 解析回 sandbox，启用沙箱模式

常见日志特征：

Approval required. → 命令等待 /approve ...
SYSTEM_RUN_DENIED: approval required → 节点主机 exec 审批待处理
exec host=sandbox requires a sandbox runtime for this session → 隐式/显式选择沙箱但沙箱模式关闭

深度文档：

浏览器工具失败

bash

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

正常输出特征：

浏览器状态显示 running: true 和所选浏览器/配置文件
openclaw 启动正常，或 user 可看到本地 Chrome 标签页

常见日志特征：

unknown command "browser" → plugins.allow 设置中未包含 browser
Failed to start Chrome CDP on port → 本地浏览器启动失败
browser.executablePath not found → 配置的二进制路径错误
browser.cdpUrl must be http(s) or ws(s) → 配置的 CDP URL 使用了不支持的协议
browser.cdpUrl has invalid port → 配置的 CDP URL 端口无效或超出范围
No Chrome tabs found for profile="user" → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页
Remote CDP for profile "<name>" is not reachable → 配置的远程 CDP 端点从本机不可达
Browser attachOnly is enabled ... not reachable 或 Browser attachOnly is enabled and CDP websocket ... is not reachable → 仅附加模式的配置文件没有活动的 CDP 目标
附加模式或远程 CDP 配置文件的 viewport / 暗色模式 / 语言 / 离线状态覆盖过时 → 运行 openclaw browser stop --browser-profile <name> 关闭活动控制会话并释放仿真状态，无需重启网关

深度文档：

常见问题

OpenClaw 无回复，`openclaw doctor` 显示无错误，怎么办？

执行 openclaw channels status --probe 检查每个渠道的实时传输状态。如果渠道显示 pending 或 pairing request，说明发送者未通过 DM 配对。也检查 openclaw logs --follow 中是否有 allowlist 字样，可能发送者被过滤了。

Control UI 一直显示"连接中"，怎么排查？

常见原因是浏览器 Origin 未在网关的 gateway.controlUi.allowedOrigins 允许列表中（日志报 origin not allowed）。也可能是网关 URL 或端口配置错误（日志报 gateway connect failed）。检查网关状态 openclaw gateway status 中的 Dashboard 地址是否正确。

Cron 任务设好了但从不触发，怎么调试？

运行 openclaw cron status 确认 cron 已启用（显示 enabled），再运行 openclaw cron runs --id <jobId> --limit 20 查看历史记录。日志中出现 heartbeat skipped reason=quiet-hours 说明当前在静默时间段内；出现 cron: scheduler disabled 说明 cron 配置被关闭。

OpenClaw 故障排查：60秒诊断命令与七大场景定位 ​

前 60 秒必跑命令 ​

Anthropic 长上下文 429 ​

本地 OpenAI 兼容后端直连成功但在 OpenClaw 中失败 ​

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

插件存在但因可疑所有权被阻止 ​

问题决策树 ​

无回复 ​

控制台或 Control UI 无法连接 ​

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

渠道已连接但消息不通 ​

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

节点已配对但工具失败（camera、canvas、screen、exec） ​

Exec 突然要求审批 ​

浏览器工具失败 ​

相关文档 ​

常见问题 ​

OpenClaw 无回复，openclaw doctor 显示无错误，怎么办？ ​

Control UI 一直显示"连接中"，怎么排查？ ​

Cron 任务设好了但从不触发，怎么调试？ ​

OpenClaw 故障排查：60秒诊断命令与七大场景定位

前 60 秒必跑命令

Anthropic 长上下文 429

本地 OpenAI 兼容后端直连成功但在 OpenClaw 中失败

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

插件存在但因可疑所有权被阻止

问题决策树

无回复

控制台或 Control UI 无法连接

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

渠道已连接但消息不通

Cron 或心跳未触发/未送达

节点已配对但工具失败（camera、canvas、screen、exec）

Exec 突然要求审批

浏览器工具失败

相关文档

常见问题

OpenClaw 无回复，`openclaw doctor` 显示无错误，怎么办？

Control UI 一直显示"连接中"，怎么排查？

Cron 任务设好了但从不触发，怎么调试？