通用故障排查
分诊入口。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):
常见原因:
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 或正常的智能体轮次中失败:
- 错误提到
messages[].content期望字符串:设置models.providers.<provider>.models[].compat.requiresStringContent: true。 - 仅在 OpenClaw 智能体轮次仍然失败:设置
models.providers.<provider>.models[].compat.supportsTools: false并重试。 - 较小的直接调用正常,但较大的 OpenClaw prompt 导致后端崩溃:这是上游模型/服务器的限制,不是 OpenClaw 的 bug。请继续参阅 Local OpenAI-compatible backend passes direct checks but agent runs fail。
插件安装因缺少 openclaw extensions 而失败¶
package.json missing openclaw.extensions 意味着插件包使用了 OpenClaw 不再接受的形态。
在插件包中修复:
- 将
openclaw.extensions添加到package.json,指向构建后的运行时文件(通常是./dist/index.js)。 - 重新发布,然后再次运行
openclaw plugins install <package>。
{
"name": "@openclaw/my-plugin",
"version": "1.2.3",
"openclaw": {
"extensions": ["./dist/index.js"]
}
}
安装策略阻止插件安装或更新¶
更新完成,但插件已过时、被禁用,或显示 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 plugins update --all,然后恢复更严格的规则。如果更新失败导致插件被禁用,请在重新启用前进行检查:
插件存在但因可疑所有权被阻止¶
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)运行。请修复主机绑定挂载:
如果你有意以 root 身份运行 OpenClaw,请改为修复受管理的插件根目录:
更深入的文档:被阻止插件路径所有权, 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 未触发或未投递
正常输出:
- `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 故障排查
相关¶
- FAQ — 常见问题
- Gateway 故障排查 — gateway 相关问题
- Doctor — 自动化健康检查和修复
- 通道故障排查 — 通道连接问题
- 计划任务:故障排查 — cron 和 heartbeat 问题
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw