Skip to main content

​
故障排查

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

​
前 60 秒

按顺序运行以下命令： 
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 → 目标网关可访问。
  • openclaw gateway status → Runtime: running 和 RPC probe: ok。
  • openclaw doctor → 无阻塞配置/服务错误。
  • openclaw channels status --probe → 频道状态显示 connected 或 ready。
  • openclaw logs --follow → 活跃稳定，无重复致命错误。

​
Anthropic 长上下文 429

如果看到： HTTP 429: rate_limit_error: Extra usage is required for long context requests， 请访问 /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context。

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

若安装失败并提示 package.json missing openclaw.extensions，说明插件包使用了 OpenClaw 已不再接受的旧格式。 插件包修复步骤：
  1. 在 package.json 中添加 openclaw.extensions。
  2. 指定入口文件为构建后的运行时代码文件（通常为 ./dist/index.js）。
  3. 重新发布插件并再次运行 openclaw plugins install <npm-spec>。
示例： 
{
  "name": "@openclaw/my-plugin",
  "version": "1.2.3",
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}
参考文档：/tools/plugin#distribution-npm

​
决策树

openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
良好输出表现为：
  • Runtime: running
  • RPC probe: ok
  • 在 channels status --probe 中频道显示 connected/ready
  • 发送者显示已批准（或私信策略开放/白名单）
常见日志特征：
  • drop guild message (mention required → Discord 中提及限制阻止了消息。
  • pairing request → 发送者未批准，等待私信配对批准。
  • 频道日志中出现 blocked / allowlist → 发送者、房间或组被过滤。
深入页面：
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
良好输出表现为：
  • 在 openclaw gateway status 中显示 Dashboard: http://...
  • RPC probe: ok
  • 日志中无认证循环
常见日志特征：
  • device identity required → HTTP/非安全上下文无法完成设备认证。
  • unauthorized / 重新连接循环 → 令牌/密码错误或认证模式不匹配。
  • gateway connect failed: → UI 目标 URL/端口错误或网关无法访问。
深入页面：
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
良好输出表现为：
  • Service: ... (loaded)
  • Runtime: running
  • RPC probe: ok
常见日志特征：
  • Gateway start blocked: set gateway.mode=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 → 私信发送者尚未批准。
  • not_in_channel、missing_scope、Forbidden、401/403 → 频道权限令牌问题。
深入页面：
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 → 处于配置的非活跃时间。
  • requests-in-flight → 主线路忙，心跳唤醒被延迟。
  • unknown accountId → 心跳目标账号不存在。
深入页面：
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 → 执行审批等待中。
  • SYSTEM_RUN_DENIED: allowlist miss → 命令未在执行白名单内。
深入页面：
openclaw status
openclaw gateway status
openclaw browser status
openclaw logs --follow
openclaw doctor
良好输出表现为：
  • 浏览器状态显示 running: true 和已选择的浏览器/配置文件。
  • openclaw 配置文件启动，或 chrome 中继附加了标签页。
常见日志特征：
  • Failed to start Chrome CDP on port → 本地浏览器启动失败。
  • browser.executablePath not found → 配置的浏览器二进制路径错误。
  • Chrome extension relay is running, but no tab is connected → 扩展未附加标签页。
  • Browser attachOnly is enabled ... not reachable → 仅附加配置文件无活动 CDP 目标。
深入页面：