跳转至

通用故障排查

分诊入口。2 分钟完成诊断,然后跳转到深度页面。

前 60 秒

按顺序运行以下阶梯命令:

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

良好的输出,每项一行:

  • openclaw triage 会写入一份经脱敏、可供智能体使用的诊断报告,并在 Gateway 可达时生成支持归档。有关智能体交接选项,请参阅 Triage。
  • openclaw status 显示已配置的渠道,且无认证错误。
  • openclaw status --all 生成一份完整、可共享的报告。
  • openclaw gateway probe 显示 Reachable: yes。Capability: ... 是检查所证明的认证级别。缺少 operator.read 作用域会限制读取诊断信息;这并不意味着连接失败。
  • openclaw gateway status 显示 Runtime: running、成功的连通性检查,以及一个合理的 Capability: ...。添加 --require-rpc 以额外要求读作用域的 RPC 证明。
  • openclaw doctor 报告没有阻塞性的配置/服务错误。
  • openclaw channels status --probe 在 gateway 可达时返回每个账户的实时传输状态(works / audit ok);不可达时回退为仅配置摘要。
  • openclaw logs --follow 显示稳定的活动,没有重复的致命错误。

Assistant 感觉受限或缺少工具

检查有效的工具配置(tool profile):

openclaw status
openclaw status --all
openclaw doctor

常见原因:

  • tools.profile: "minimal" 仅允许 session_status 和仅更新的 gateway。
  • tools.profile: "messaging" 较为狭窄,适用于仅聊天的智能体。
  • tools.profile: "coding" 选择仓库、文件、shell 和运行时相关工作。
  • tools.profile: "full" 是本地引导(onboarding)的默认配置。它会移除核心 profile 过滤,并选择可选的插件工具,但受独立限制约束。
  • 未设置 profile 时,核心工具不受过滤,但本身不会选择可选的插件工具。除非再次运行 onboarding,否则现有配置保持不变。
  • 每个智能体的 agents.entries.*.tools 会为单个智能体收窄或扩展根 profile。

更改 profile 后,重启或重新加载 Gateway,然后使用 openclaw status --all 重新检查。请单独检查聊天中的 Execution permissions(执行权限)菜单;选择 Full 工具并不会授予 Full Access,也不会配置缺失的插件。完整 profile/group 表格:Tool profiles。

Anthropic 长上下文 429

HTTP 429: rate_limit_error: Extra usage is required for long context requests → Anthropic 429:长上下文需要额外用量。

本地 OpenAI 兼容后端直接可用,但在 OpenClaw 中失败

你的本地/自托管 /v1 后端可以直接通过 /v1/chat/completions 检查,但在 openclaw infer model run 或正常的智能体轮次中失败:

  1. 错误提到 messages[].content 期望字符串:设置 models.providers.<provider>.models[].compat.requiresStringContent: true。
  2. 仅在 OpenClaw 智能体轮次仍然失败:设置 models.providers.<provider>.models[].compat.supportsTools: false 并重试。
  3. 较小的直接调用正常,但较大的 OpenClaw prompt 导致后端崩溃:这是上游模型/服务器的限制,不是 OpenClaw 的 bug。请继续参阅 Local OpenAI-compatible backend passes direct checks but agent runs fail。

插件安装因缺少 openclaw extensions 而失败

package.json missing openclaw.extensions 意味着插件包使用了 OpenClaw 不再接受的形态。

在插件包中修复:

  1. 将 openclaw.extensions 添加到 package.json,指向构建后的运行时文件(通常是 ./dist/index.js)。
  2. 重新发布,然后再次运行 openclaw plugins install <package>。
{
  "name": "@openclaw/my-plugin",
  "version": "1.2.3",
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

参考:Plugin architecture

安装策略阻止插件安装或更新

更新完成,但插件已过时、被禁用,或显示 blocked by install policy、install policy failed closed 或 Disabled "<plugin>" after plugin update failure:请检查 security.installPolicy。

安装策略在插件安装和更新时运行。@openclaw/* 插件版本通常随 OpenClaw 版本一起更新,因此 OpenClaw 更新后可能需要匹配的插件更新,以便在更新后的同步期间保持一致。

除非你也维护相应的升级规则,否则应避免以下策略形态:

  • 将 OpenClaw 拥有的插件冻结到某个确切的旧版本(例如,仅允许 @openclaw/*@2026.5.3)。
  • 仅按来源类型阻止(每个 npm、网络或 request.mode: "update" 请求)。
  • 将策略命令视为可选:当启用了 security.installPolicy,如果策略可执行文件缺失、缓慢、不可读或被权限阻止,则会失败关闭(fail closed)。
  • 在批准版本时不检查请求的 openclawVersion 与插件候选元数据是否匹配。

优先采用允许受信任的 @openclaw/* 更新与当前主机兼容的规则,而不是永久固定某个版本。如果默认阻止 npm,请为你使用的插件 id 添加一个窄范围的例外,并将与安装相同的信任规则应用于 request.mode: "update"。

恢复:

openclaw doctor --deep
openclaw plugins update --all
openclaw status --all

如果策略是故意严格的,请在可信升级窗口期内放宽它,重新运行 openclaw plugins update --all,然后恢复更严格的规则。如果更新失败导致插件被禁用,请在重新启用前进行检查:

openclaw plugins inspect <plugin-id> --runtime --json
openclaw plugins enable <plugin-id>

参考:Operator install policy

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

openclaw doctor、setup 或启动警告显示:

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

插件文件的所有者与加载它们的进程属于不同的 Unix 用户。请勿删除插件配置;请修复文件所有权,或以拥有状态目录的用户身份运行 OpenClaw。

Docker 安装以 node(uid 1000)运行。请修复主机绑定挂载:

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

如果你有意以 root 身份运行 OpenClaw,请改为修复受管理的插件根目录:

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

更深入的文档:被阻止插件路径所有权, Docker:权限和 EACCES

决策树

flowchart TD
  A[OpenClaw is not working] --> B{What breaks first}
  B --> C[No replies]
  B --> D[Dashboard or Control UI will not connect]
  B --> E[Gateway will not start or service installed but not running]
  B --> F[Channel connects but messages do not flow]
  B --> G[Cron or heartbeat did not fire or did not deliver]
  B --> H[Node is paired but tool fails camera canvas screen exec]
  B --> I[Exec suddenly asks for approval]
  B --> J[Browser tool fails]

每个分支都是下方一个手风琴的标题。

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

正常输出:

  • Runtime: running
  • 成功的连接检查
  • Capability: read-only、write-capable 或 admin-capable
  • 通道显示传输已连接,并且在支持的情况下,channels status --probe 中显示 works 或 audit ok
  • 发送者已批准(或 DM 策略为 open/allowlist)

日志特征:

  • drop guild message (mention required → Discord 提及门控阻止了该消息。
  • pairing request → 发送者未批准,正在等待 DM 配对批准。
  • 通道日志中的 blocked / allowlist → 发送者、房间或群组被过滤。

深入页面:无回复, 通道故障排查, 配对

Dashboard 或 Control UI 无法连接
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

正常输出:

  • 在 openclaw gateway status 中显示 Dashboard: http://...
  • 成功的连接检查
  • Capability: read-only、write-capable 或 admin-capable
  • 日志中没有认证循环

日志特征:

  • device identity required → HTTP/非安全上下文无法完成设备认证。
  • origin not allowed → 浏览器 Origin 不被 Control UI 网关目标允许。
  • 带有 canRetryWithDeviceToken=true 的 AUTH_TOKEN_MISMATCH → 可能会自动进行一次受信任的 device-token 重试,复用已配对 token 的缓存 scopes。
  • 该重试之后反复出现 unauthorized → token/密码错误、认证模式不匹配,或过期的已配对设备 token。
  • too many failed authentication attempts (retry later) → 来自该浏览器 Origin 的反复失败会被临时锁定;其他 localhost 来源使用独立的桶。有关 Tailscale Serve 并发重试细节,请参阅 Dashboard/Control UI 连接。
  • gateway connect failed: → UI 指向了错误的 URL/端口,或网关不可达。

深入页面:Dashboard/Control UI 连接, Control UI, 认证

Gateway 无法启动或服务已安装但未运行
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

正常输出:

  • Service: ... (loaded)
  • Runtime: running
  • 成功的连接检查
  • Capability: read-only、write-capable 或 admin-capable

日志特征:

  • Gateway start blocked: set gateway.mode=local 或 existing config is missing gateway.mode → 网关模式为 remote,或配置缺少 local-mode 标记且需要修复。
  • refusing to bind gateway ... without auth → 非 loopback 绑定但没有有效的认证路径(token/密码,或在已配置时使用 trusted-proxy)。
  • another gateway instance is already listening 或 EADDRINUSE → 端口已被占用。

深入页面:Gateway 服务未运行, 监督与服务生命周期, 配置

通道已连接但消息不流转
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

正常输出:

  • 通道传输已连接。
  • 配对/allowlist 检查通过。
  • 在需要时检测到提及。

日志特征:

  • mention required → 群组提及门控阻止了处理。
  • pairing / pending → DM 发送者尚未批准。
  • not_in_channel、missing_scope、Forbidden、401/403 → 通道权限 token 问题。

深入页面:通道已连接,消息不流转, 通道故障排查

Cron 或 heartbeat 未触发或未投递
openclaw status
openclaw gateway status
openclaw automations status
openclaw automations list
openclaw automations runs <jobId> --limit 20
openclaw logs --follow

正常输出:

- `automations status` 显示调度器已启用,并存在下一次唤醒。
- `automations runs` 显示最近的 `ok` 条目。
- Heartbeat 已启用,且处于活动时段内。

日志特征:

- `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。
- `heartbeat skipped` 原因为 `quiet-hours` → 不在已配置的活动时段内。
- `heartbeat skipped` 原因为 `empty-heartbeat-file` → heartbeat 监控草稿仅包含空白、注释、标题、围栏或空清单脚手架。
- `heartbeat skipped` 原因为 `alerts-disabled` → `showOk`、`showAlerts` 和 `useIndicator` 均关闭。
- `requests-in-flight` → 主通道繁忙;heartbeat 唤醒被延迟。
- `unknown accountId` → heartbeat 投递目标账户不存在。

深入页面:[Cron 和 heartbeat 投递](../gateway/troubleshooting.md#cron-and-heartbeat-delivery)、[计划任务:故障排查](../automation/cron-jobs.md#troubleshooting)、[Heartbeat](../gateway/heartbeat.md)
节点已配对,但 camera canvas screen exec 工具失败
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 允许列表中。

深入页面:节点已配对,工具失败、节点故障排查、Exec 审批

Exec 突然要求审批
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;当 sandbox 运行时处于活动状态时解析为 sandbox,否则解析为 gateway。
  • host=auto 仅负责路由;无需提示的行为来自 gateway/node 上的 security=full 加上 ask=off。
  • 未设置 tools.exec.security 时,在 gateway/node 上默认为 full。
  • 未设置 tools.exec.ask 时默认为 off。
  • 如果你看到审批,说明某些主机本地或按会话的策略已将 exec 收紧,偏离了这些默认值。

恢复当前无需审批的默认值:

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,以便在允许列表未命中时进行审查。
  • 启用 sandbox 模式,使 host=auto 重新解析为 sandbox。

日志特征:

  • Approval required. → 命令正在等待 /approve ...。
  • SYSTEM_RUN_DENIED: approval required → 节点主机 exec 审批待处理。
  • exec host=sandbox requires a sandbox runtime for this session → 已隐式/显式选择 sandbox,但 sandbox 模式处于关闭状态。

深入页面:Exec、Exec 审批、安全:审计检查的内容

浏览器工具失败
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 → 仅附加配置文件没有可用的 CDP 目标。
  • 仅附加或远程 CDP 配置文件上存在过期的 viewport/dark-mode/locale/offline 覆盖 → 运行 openclaw browser stop --browser-profile <name> 以关闭控制会话并释放模拟状态,而无需重启 gateway。

深入页面:浏览器工具失败、缺少 browser 命令或工具、浏览器:Linux 故障排查、浏览器:WSL2/Windows 远程 CDP 故障排查

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw