通用故障排查

分诊入口。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 可达时生成支持归档。参见分诊了解代理交接选项。
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: ...。添加 --require-rpc 以同时要求读取范围的 RPC 证明。
openclaw doctor 报告没有阻塞性配置/服务错误。
openclaw channels status --probe 在 Gateway 可达时返回每个账户的实时传输状态（works / audit ok）；不可达时回退到仅配置摘要。
openclaw logs --follow 显示持续活动，没有重复的致命错误。

助手感觉受限或缺少工具¶

检查生效的工具配置：

openclaw status
openclaw status --all
openclaw doctor

常见原因：

tools.profile: "minimal" 允许 session_status 和仅更新的 gateway。
tools.profile: "messaging" 较窄，适用于仅聊天代理。
tools.profile: "coding" 选择仓库、文件、Shell 和运行时工作。
tools.profile: "full" 是本地入门默认值。它会移除核心配置过滤，并选择可选插件工具，但仍受独立限制约束。
未设置配置时，核心工具保持未过滤，但本身不会选择可选插件工具。除非重新运行入门流程，否则现有配置保持不变。
每个代理的 agents.entries.*.tools 覆盖项会为单个代理收窄或扩展根配置。

修改配置后，重启或重新加载 Gateway，然后使用 openclaw status --all 重新检查。请单独检查聊天中的 Execution permissions 菜单；完整工具选择不会授予 Full Access，也不会配置缺失的插件。完整配置/分组表：工具配置。

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 提示词会使后端崩溃：这是上游模型/服务器限制，而不是 OpenClaw 缺陷。继续参见本地 OpenAI 兼容后端通过直接探测但代理运行失败。

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

package.json missing openclaw.extensions 表示插件包使用了 OpenClaw 不再接受的结构。

在插件包中修复：

在 package.json 中添加 openclaw.extensions，指向已构建的运行时文件（通常是 ./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 时，缺失、缓慢、不可读或权限阻止的策略可执行文件会失败关闭。
批准版本时未将请求的 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>

参考：操作员安装策略

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

openclaw doctor、设置或启动警告显示：

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
Connectivity probe: ok
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 → 发送者、房间或群组被过滤。

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

仪表板或 Control UI 无法连接

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 → 可能会自动进行一次受信任的设备令牌重试，复用已配对令牌的缓存范围。
该重试之后反复出现 unauthorized → 令牌/密码错误、认证模式不匹配，或已配对的设备令牌已过期。
too many failed authentication attempts (retry later) → 来自该浏览器 Origin 的反复失败会被临时锁定；其他 localhost 源使用单独的桶。有关 Tailscale Serve 并发重试的细节，请参阅仪表板/Control UI 连接。
gateway connect failed: → UI 指向了错误的 URL/端口，或网关不可达。

深入页面：仪表板/Control UI 连接, Control UI, 认证

网关无法启动或服务已安装但未运行

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

正常输出：

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 → 非回环绑定但没有有效的认证路径（令牌/密码，或已配置时的可信代理）。
another gateway instance is already listening 或 EADDRINUSE → 端口已被占用。

深入页面：网关服务未运行, 监督和服务生命周期, 配置

通道已连接但消息未流动

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

正常输出：

通道传输已连接。
配对/允许列表检查通过。
在需要时检测到提及。

日志特征：

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

深入页面：通道已连接，消息未流动, 通道故障排查

定时任务或心跳未触发或未投递

openclaw status
openclaw gateway status
openclaw automations status
openclaw automations list
openclaw automations runs <jobId> --limit 20
openclaw logs --follow

节点已配对，但 camera/canvas/screen/exec 工具失败

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

正常输出：

节点显示为已连接，并与 node 角色配对。
你调用的命令存在对应的能力（capability）。
该工具的权限状态已授予。

日志特征：

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

日志特征：

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

深入阅读：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 配置上过期的视口/深色模式/语言/离线覆盖 → 运行 openclaw browser stop --browser-profile <name> 关闭控制会话并释放模拟状态，无需重启 gateway。

深入阅读：浏览器工具失败、缺少浏览器命令或工具、浏览器：Linux 故障排查、浏览器：WSL2/Windows 远程 CDP 故障排查

FAQ — 常见问题解答
Gateway 故障排查 — Gateway 特定问题
Doctor — 自动健康检查与修复
频道故障排查 — 频道连通性问题
定时任务：故障排查 — cron 和心跳问题

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

通用故障排查

前 60 秒¶

助手感觉受限或缺少工具¶

Anthropic 长上下文 429¶

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

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

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

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

决策树¶

相关¶