帮助
故障排除
如果你只有两分钟，可以用本页面作为快速诊断入口。
前 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 不再支持的旧格式。在插件包中 修复：
- 在
package.json中添加openclaw.extensions。 - 将条目指向构建后的运行时文件（通常是
./dist/index.js）。 - 重新发布插件，然后再次运行
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: runningRPC probe: ok- 你的频道在
channels status --probe中显示为 connected/ready - 发送者已获批准（或 DM 策略为开放/允许列表）
常见的日志特征：
drop guild message (mention required→ Discord 中的提及门控阻止了消息处理。pairing request→ 发送者未获批准，正在等待 DM 配对批准。- 频道日志中的
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:→ 界面指向了错误的 URL/端口，或网关不可达。
深入阅读：
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
正常的输出应该是：
Service: ... (loaded)Runtime: runningRPC probe: ok
常见的日志特征：
Gateway start blocked: set gateway.mode=local→ 网关模式未设置或为远程模式。refusing to bind gateway ... without auth→ 非环回绑定但没有设置令牌/密码。another gateway instance is already listening或EADDRINUSE→ 端口已被占用。
深入阅读：
- /gateway/troubleshooting#gateway-service-not-running
- /gateway/background-process
- /gateway/configuration
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 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→ 定时任务已禁用。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 目标。
深入阅读：