跳到主要内容

故障排查

本章汇总 OpenClaw 常见问题的诊断方法和解决方案。当你遇到问题时，按照本章的步骤逐一排查，大多数问题都能快速定位和解决。

快速诊断流程​

如果只有 2 分钟，按照以下顺序快速诊断：

第一步：检查基础状态（30 秒）​

# 查看整体状态
openclaw status

# 查看完整状态报告
openclaw status --all

确认：

  • 配置的渠道显示正常
  • 没有明显的认证错误

第二步：检查 Gateway 连接（20 秒）​

# 探测 Gateway 是否可达
openclaw gateway probe

# 查看 Gateway 运行状态
openclaw gateway status

预期结果：

  • Reachable: yes（Gateway 可达）
  • Runtime: running（运行中）
  • RPC probe: ok（RPC 正常）

注意：RPC: limited - missing scope: operator.read 是诊断功能降级，不是连接失败。

第三步：运行诊断工具（30 秒）​

# 运行完整诊断
openclaw doctor

# 自动修复问题
openclaw doctor --fix

第四步：检查渠道状态（20 秒）​

# 查看渠道连接状态
openclaw channels status --probe

预期结果：渠道显示 connected 或 ready。

第五步：查看日志（20 秒）​

# 实时查看日志
openclaw logs --follow

观察是否有重复的致命错误。

常见问题分类​

问题：收不到回复​

诊断步骤：

  1. 确认 Gateway 运行正常：

    openclaw gateway status
    # 应该显示 Runtime: running 和 RPC probe: ok

  2. 确认渠道连接正常：

    openclaw channels status --probe
    # 应该显示 connected 或 ready

  3. 确认发送者已授权：

    • 检查 DM policy 配置
    • 确认发送者在 allowFrom 列表中

常见原因及解决：

日志关键词原因解决方法
drop guild message (mention required)Discord 群消息未 @ 提及在群消息中 @Bot
pairing request发送者未授权批准配对请求或添加到 allowFrom
blocked / allowlist发送者/群组被过滤更新 allowFrom 配置

问题：Dashboard 或 Control UI 无法连接​

诊断步骤：

  1. 确认 Dashboard URL：

    openclaw gateway status
    # 查看 Dashboard: http://... 输出

  2. 确认 RPC 正常：

    openclaw gateway status
    # 应该显示 RPC probe: ok

  3. 检查日志中是否有认证循环

常见原因及解决：

日志关键词原因解决方法
device identity requiredHTTP 环境无法完成设备认证使用 HTTPS 或本地访问
AUTH_TOKEN_MISMATCHToken 不匹配检查 gateway.auth.token 配置
gateway connect failed:URL/端口错误或不可达确认 Gateway 地址和端口
unauthorized（重复）认证信息错误重新配置 Token 或密码

问题：Gateway 无法启动​

诊断步骤：

# 查看服务状态
openclaw gateway status

# 查看日志
openclaw logs --tail 100

常见原因及解决：

日志关键词原因解决方法
Gateway start blocked: set gateway.mode=localGateway 模式未设置设置 gateway.mode=local
refusing to bind gateway ... without auth非本地绑定未配置认证配置 Token 或密码认证
another gateway instance is already listening端口被占用停止旧实例或更换端口
EADDRINUSE端口被占用更换端口：openclaw gateway --port 18790

问题：渠道连接正常但消息不流动​

诊断步骤：

# 深度检查渠道状态
openclaw channels status --probe

# 查看渠道日志
openclaw channels logs --channel telegram

常见原因及解决：

日志关键词原因解决方法
mention required群消息提及门控在群消息中 @Bot
pairing / pending发送者待批准批准配对请求
not_in_channelBot 未加入频道邀请 Bot 加入
missing_scope / Forbidden权限不足检查 Bot 权限配置
401/403Token 无效或过期重新配置渠道认证

问题：定时任务未执行​

诊断步骤：

# 检查 Cron 状态
openclaw cron list

# 查看执行历史
openclaw cron runs --id task-name

常见原因及解决：

日志关键词原因解决方法
cron: scheduler disabledCron 被禁用启用 Cron：openclaw cron enable
heartbeat skipped + reason=quiet-hours静默时段调整静默时段配置
requests-in-flight主通道忙碌等待当前任务完成
unknown accountId目标账号不存在检查配置中的 accountId

问题：Node 配对成功但工具失败​

诊断步骤：

# 检查 Node 状态
openclaw status --deep

# 查看日志中的错误
openclaw logs --grep "NODE"

常见原因及解决：

日志关键词原因解决方法
NODE_BACKGROUND_UNAVAILABLENode App 在后台将 Node App 切换到前台
*_PERMISSION_REQUIRED系统权限未授予在系统设置中授予权限
SYSTEM_RUN_DENIED: approval required等待审批执行 /approve 命令
SYSTEM_RUN_DENIED: allowlist miss命令不在允许列表更新 exec allowlist 配置

问题：Exec 突然要求审批​

原因分析：

当 tools.exec.host 未设置时，默认为 auto：

  • 如果有沙箱运行时，解析为 sandbox
  • 否则解析为 gateway

在 gateway 和 node 模式下：

  • 未设置 tools.exec.security 默认为 allowlist
  • 未设置 tools.exec.ask 默认为 on-miss

结果：普通主机命令可能暂停等待审批。

解决方案：

// 方案一：固定主机路由
{
  "tools": {
    "exec": {
      "host": "gateway"
    }
  }
}

// 方案二：保持审批但稳定路由
{
  "tools": {
    "exec": {
      "host": "gateway",
      "security": "allowlist",
      "ask": "on-miss"
    }
  }
}

// 方案三：启用沙箱模式
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

问题：浏览器工具失败​

诊断步骤：

# 检查浏览器状态
openclaw browser status

# 尝试启动浏览器
openclaw browser start

常见原因及解决：

日志关键词原因解决方法
unknown command "browser"插件未允许更新 plugins.allow 配置
Failed to start Chrome CDP on port浏览器启动失败检查浏览器安装
browser.executablePath not found路径配置错误更新浏览器路径配置
No Chrome tabs found for profile="user"没有打开的 Chrome 标签打开 Chrome 并访问页面
Browser attachOnly is enabled ... not reachable无法连接到 CDP检查 Chrome 远程调试配置

问题：Anthropic 长上下文 429 错误​

错误信息：

HTTP 429: rate_limit_error: Extra usage is required for long context requests

原因：Anthropic API 对长上下文请求有额外的配额限制。

解决方案：

  1. 检查你的 Anthropic API 配额
  2. 考虑使用较短的上下文
  3. 或升级 Anthropic API 套餐

问题：插件安装失败​

错误信息：

package.json missing openclaw.extensions

原因：插件使用了旧的配置格式。

解决方案（需要插件作者修复）：

  1. 在 package.json 中添加 openclaw.extensions
  2. 将入口指向构建后的运行时文件（通常是 ./dist/index.js）
  3. 重新发布插件

Doctor 诊断工具​

openclaw doctor 是自动化的健康检查工具，可以检测和修复许多常见问题。

基本用法​

# 运行诊断
openclaw doctor

# 自动修复问题
openclaw doctor --fix

# 深度诊断
openclaw doctor --deep

Doctor 能做什么​

检查项说明
配置验证检查配置文件格式和必填项
凭证检查验证 API Key 和认证配置
服务状态检查 Gateway 运行状态
渠道连接检查各渠道连接状态
记忆搜索检查嵌入向量配置
沙箱状态检查 Docker 可用性（如启用沙箱）
Cron 任务检查定时任务配置

自动修复功能​

--fix 选项可以自动修复以下问题：

  • 备份配置文件到 ~/.openclaw/openclaw.json.bak
  • 删除未知的配置项
  • 归档孤立的会话文件
  • 规范化 Cron 任务配置
  • 建议缺失的配置

注意：交互式提示只在终端环境下运行。无头运行（cron、Telegram、无终端）会跳过提示。

macOS launchctl 环境变量问题​

如果你之前运行过：

launchctl setenv OPENCLAW_GATEWAY_TOKEN ...

这个值会覆盖配置文件，可能导致持续的 "unauthorized" 错误。

解决方案：

# 删除 launchctl 环境变量
launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

# 重启 Gateway
openclaw gateway restart

日志查看​

实时日志​

# 实时查看日志
openclaw logs --follow

# 查看最近 100 行
openclaw logs --tail 100

# 按级别过滤
openclaw logs --level error

# 按关键词搜索
openclaw logs --grep "error"

渠道日志​

# 查看特定渠道日志
openclaw channels logs --channel telegram

# 查看所有渠道日志
openclaw channels logs --channel all --lines 500

日志文件位置​

日志存储在 ~/.openclaw/logs/ 目录下。

重置和清理​

重置配置​

# 备份并重置配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
openclaw setup --reset

清理会话​

# 清理旧会话
openclaw session prune --older-than 30d

完全重置​

# 停止服务
openclaw gateway stop

# 备份数据
cp -r ~/.openclaw ~/.openclaw.backup

# 删除并重新安装
rm -rf ~/.openclaw
openclaw setup

# 重新运行 onboarding
openclaw onboard

获取帮助​

如果以上步骤都无法解决问题，可以：

  1. 查看官方文档：docs.openclaw.ai
  2. 加入社区：Discord
  3. 提交问题：GitHub Issues

在提交问题时，请附上以下信息：

# 生成诊断报告
openclaw status --all > diagnostic.txt
openclaw doctor >> diagnostic.txt
openclaw logs --tail 200 >> diagnostic.txt

下一步​