英文 Troubleshooting

2026年4月5日约 8 分钟

原始链接：https://docs.openclaw.ai/help/troubleshooting
来源章节：4. 官方文档：核心概念、模型与安全
来源小节：无
抓取方式：jina:https://r.jina.ai/http://docs.openclaw.ai/help/troubleshooting
抓取时间：2026-04-05 13:47:10
状态：ok

中文内容

一般故障排除 - OpenClaw

跳到主要内容

[OpenClaw主页！图片1：深色徽标！图片2：深色徽标](http://docs.openclaw.ai/)

图3：美国

英语

搜索...

Ctrl+K

搜索...

导航

帮助

一般故障排除

开始安装频道代理工具和插件模型平台网关和操作参考帮助

帮助

社区

OpenClaw 传说

#####环境与调试

压实内部结构

会话管理深入探讨

开发者设置

贡献

CI 管道

文档元

在此页面上

帮助

一般故障排除

故障排除

如果您只有 2 分钟的时间，请使用此页面作为分类前门。

前 60 秒

按顺序运行这个确切的梯子：

开爪状态
张开爪状态——全部
开放式网关探头
开爪网关状态
开爪医生
openclaw 通道状态--probe
openclaw 日志 --follow

一行输出良好：

openclaw status → 显示配置的通道并且没有明显的身份验证错误。
openclaw status --all → 完整报告已存在且可共享。
openclaw gatewayprobe → 预期网关目标可达（Reachable: yes）。 “RPC：受限 - 缺少范围：operator.read”是降级诊断，而不是连接失败。
openclaw gateway status → Runtime: running 和 RPCprobe: ok。
openclaw doctor → 无阻塞配置/服务错误。
openclaw 通道状态 --probe → 可到达的网关返回每个帐户的实时传输状态以及探测/审核结果，例如 works 或 audit ok；如果网关无法访问，该命令将回退到仅配置摘要。
openclaw log --follow → 活动稳定，没有重复的致命错误。

人择长上下文 429

如果您看到：“HTTP 429：rate_limit_error：长上下文请求需要额外使用”，请转至 /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context。

插件安装失败，缺少 openclaw 扩展

如果安装失败且“package.json缺少openclaw.extensions”，则插件包使用的是OpenClaw不再接受的旧形状。在插件包中修复：

将 openclaw.extensions 添加到 package.json 中。
将条目指向构建的运行时文件（通常为“./dist/index.js”）。
重新发布插件并再次运行 openclaw plugins install <package>。

示例：

{
  “名称”：“@openclaw/my-plugin”，
  “版本”：“1.2.3”，
  “张开爪”：{
    “扩展”：[“./dist/index.js”]
  }
}

参考：插件架构

决策树

没有回复

开爪状态
开爪网关状态
openclaw 通道状态--probe
openclaw 配对列表 --channel <channel> [--account <id>]
openclaw 日志 --follow

好的输出看起来像：

运行时：运行
RPC 探测：好的
您的频道显示传输已连接，并且在支持的情况下，在“channels status --probe”中显示“works”或“audit ok”
发件人似乎已获得批准（或 DM 政策已开放/允许列入名单）

常见的日志签名：

删除公会消息（需要提及 → 提及门控阻止了 Discord 中的消息。
配对请求 → 发送者未获批准并等待 DM 配对批准。
通道日志中的“阻止”/“允许列表”→ 发件人、房间或组被过滤。

深层页面：

仪表板或控制 UI 将无法连接

开爪状态
开爪网关状态
openclaw 日志 --follow
开爪医生
openclaw 通道状态--probe

好的输出看起来像：

Dashboard: http://... 显示在 openclaw gateway status 中
RPC 探测：好的
日志中没有身份验证循环

常见的日志签名：

需要设备身份 → HTTP/非安全上下文无法完成设备身份验证。
origin not allowed → 浏览器 Origin 不允许用于控制 UI 网关目标。
AUTH_TOKEN_MISMATCH 带有重试提示 (canRetryWithDeviceToken=true) → 可能会自动发生一个可信设备令牌重试。
缓存令牌重试重用与配对设备令牌一起存储的缓存范围集。显式“deviceToken”/显式“scopes”调用者会保留其请求的范围集。
在异步 Tailscale 服务控制 UI 路径上，在限制器记录失败之前，对同一“{scope, ip}”的失败尝试进行序列化，因此第二个并发错误重试可能已经显示“稍后重试”。
来自本地主机浏览器源的“身份验证尝试失败次数过多（稍后重试）” → 来自同一“源”的重复失败被暂时锁定；另一个本地主机源使用单独的存储桶。
重试后重复“未经授权” → 令牌/密码错误、身份验证模式不匹配或陈旧的配对设备令牌。
网关连接失败： → UI 瞄准了错误的 URL/端口或无法访问的网关。

深层页面：

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

开爪状态
开爪网关状态
openclaw 日志 --follow
开爪医生
openclaw 通道状态--probe

好的输出看起来像：

服务：...（已加载）
运行时：运行
RPC 探测：好的

常见的日志签名：

网关启动被阻止：设置 gateway.mode=local 或 现有配置缺少 gateway.mode → 网关模式为远程，或者配置文件缺少本地模式标记，应修复。
拒绝绑定网关...没有身份验证 → 没有有效网关身份验证路径（令牌/密码或配置的受信任代理）的非环回绑定。
另一个网关实例已经在侦听或EADDRINUSE → 端口已被占用。

深层页面：

通道已连接但消息不流动

开爪状态
开爪网关状态
openclaw 日志 --follow
开爪医生
openclaw 通道状态--probe

好的输出看起来像：

通道传输已连接。
配对/白名单检查通过。
在需要时检测提及。

常见的日志签名：

需要提及 → 群组提及门控被阻止处理。
配对 / 待定 → DM 发送者尚未获得批准。
not_in_channel、missing_scope、Forbidden、401/403 → 频道权限令牌问题。

深层页面：

Cron 或 heartbeat 未触发或未交付

开爪状态
开爪网关状态
开爪 cron 状态
openclaw cron 列表
openclaw cron 运行 --id <jobId> --limit 20
openclaw 日志 --follow

好的输出看起来像：

cron.status 显示在下次唤醒时启用。
cron running 显示最近的 ok 条目。
心跳已启用，且不在活动时间之外。

常见的日志签名：

cron：调度程序已禁用；作业不会自动运行 → cron 被禁用。
带有“reason=quiet-hours”的“心跳跳过” → 在配置的活动时间之外。
请求进行中 → 主通道繁忙；心跳唤醒被推迟。
unknown accountId → 心跳传递目标账户不存在。

深层页面：

节点已配对，但工具无法执行相机画布屏幕执行操作

开爪状态
开爪网关状态
张开爪节点状态
openclaw 节点描述 --node <idOrNameOrIp>
openclaw 日志 --follow

好的输出看起来像：

节点被列为已连接并与角色“节点”配对。
您正在调用的命令存在功能。
为该工具授予权限状态。

常见的日志签名：

NODE_BACKGROUND_UNAVAILABLE → 将节点应用程序带到前台。
*_PERMISSION_REQUIRED → 操作系统权限被拒绝/丢失。
SYSTEM_RUN_DENIED：需要批准 → 执行批准正在等待。
SYSTEM_RUN_DENIED: 允许列表未命中 → 命令不在执行允许列表中。

深层页面：

Exec突然请求批准

openclaw 配置获取tools.exec.host
openclaw 配置获取tools.exec.security
openclaw 配置获取tools.exec.ask
openclaw网关重启

改变了什么：

如果未设置“tools.exec.host”，则默认为“auto”。
当沙箱运行时处于活动状态时，“host=auto”解析为“sandbox”，否则解析为“gateway”。
host=auto 仅用于路由；无提示的“YOLO”行为来自网关/节点上的“security=full”加上“ask=off”。
在 gateway 和 node 上，取消设置 tools.exec.security 默认为 full。
取消设置tools.exec.ask默认为off。
结果：如果您看到批准，则某些主机本地或每会话策略将 exec 收紧，使其远离当前默认值。

恢复当前默认的不批准行为：

openclaw 配置集 tools.exec.host 网关
openclaw 配置集 tools.exec.security 已满
openclaw 配置设置 tools.exec.ask 关闭
openclaw网关重启

更安全的替代方案：

如果您只想稳定的主机路由，则仅设置 tools.exec.host=gateway。
如果您想要主机执行但仍想审查允许列表未命中情况，请使用“security=allowlist”和“ask=on-miss”。
如果您希望“host=auto”解析回“sandbox”，请启用沙箱模式。

常见的日志签名：

需要批准。 → 命令正在等待 /approve ...。
SYSTEM_RUN_DENIED：需要批准 → 节点主机执行批准正在等待。
exec host=sandbox 需要此会话的沙箱运行时 → 隐式/显式沙箱选择，但沙箱模式已关闭。

深层页面：

浏览器工具失败

开爪状态
开爪网关状态
打开爪浏览器状态
openclaw 日志 --follow
开爪医生

好的输出看起来像：

浏览器状态显示“正在运行：true”和所选的浏览器/配置文件。
openclaw 启动，或者 user 可以看到本地 Chrome 选项卡。

常见的日志签名：

unknown command "browser" 或 unknown command 'browser' → 设置了 plugins.allow 并且不包含 browser。
无法在端口上启动 Chrome CDP → 本地浏览器启动失败。
browser.executablePath not found → 配置的二进制路径错误。
browser.cdpUrl 必须是 http(s) 或 ws(s) → 配置的 CDP URL 使用不受支持的方案。
browser.cdpUrl 有无效端口 → 配置的 CDP URL 有错误或超出范围的端口。
找不到 profile="user" 的 Chrome 选项卡 → Chrome MCP 附加配置文件没有打开的本地 Chrome 选项卡。
配置文件“<名称>”的远程 CDP 不可访问 → 无法从该主机访问配置的远程 CDP 端点。
“浏览器 AttachOnly 已启用...不可访问”或“浏览器 AttachOnly 已启用且 CDP websocket ...不可访问”→ 仅附加配置文件没有实时 CDP 目标。
过时的视口/暗模式/区域设置/离线覆盖仅附加或远程 CDP 配置文件 → 运行 openclaw browser stop --browser-profile <name> 以关闭活动控制会话并释放模拟状态，而无需重新启动网关。

深层页面：

英文 Troubleshooting

中文内容

一般故障排除 - OpenClaw

帮助

社区

压实内部结构

开发者设置

贡献

文档元

一般故障排除

On this page

英文 Troubleshooting

中文内容

一般故障排除 - OpenClaw

帮助

社区

压实内部结构

开发者设置

贡献

文档元

一般故障排除

On this page