最全的OpenClaw 报错完全指南

青团

OpenClaw中文社团收集，OpenClaw整理

📌 前言

本文档整理了 OpenClaw 在日常使用中可能遇到的各类报错信息，并提供详细的排查思路和解决方案。无论你是刚入门的新手还是有一定经验的用户，都能在这里找到解决问题的线索。

快速诊断命令：

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

---## 一、Gateway 网关类报错

1.1 Gateway 无法启动

报错信息	原因	解决方案
Gateway start blocked: set gateway.mode=local	gateway mode 未设置	在配置中设置 gateway.mode: "local"
refusing to bind gateway ... without auth	非本地绑定但没有配置认证	配置 gateway.auth.mode 和 gateway.auth.token
another gateway instance is already listening / EADDRINUSE	端口已被占用	停止其他占用端口的程序，或使用 --port 指定新端口

查看端口占用 netstat -tlnp | grep 18789 # 或 ss -tlnp | grep 18789

1.2 Gateway 状态异常

问题： openclaw gateway status 显示 Runtime: running 但 RPC probe: failed

原因： 进程运行但 WebSocket 连接失败

解决步骤：

1. 检查端口监听状态
2. 查看日志具体错误：openclaw logs --follow
3. 确认配置文件的配置文件路径是否正确

问题： Config (cli) 和 Config (service) 显示不同

原因： CLI 和服务使用的配置文件路径不一致

解决：

openclaw gateway install --force

---## 二、认证授权类报错

2.1 Control UI 无法连接

• 检查 UI 配置的 Gateway 地址
• 确认 Gateway 是否运行| 报错信息 | 原因 | 解决方案 |
  | ------------------------ | --------------------------------------- | ----------------------------------------------- |
  | device identity required | 非安全上下文无法完成设备认证 | 使用 HTTPS 或确保在安全环境下访问 |
  | AUTH_TOKEN_MISMATCH | Token 不匹配 | 重新配置 token，确保 Control UI 和 Gateway 一致 |
  | repeated unauthorized | Token/密码错误，或 auth mode 不匹配 | 检查 gateway.auth 配置，重置 token |
  | gateway connect failed: | UI 指向错误的 URL/端口或 Gateway 不可达 | |

💡 快速修复：

生成新 token openclaw doctor --generate-gateway-token # 查看当前 token openclaw config get gateway.auth.token

2.2 模型认证失败

No credentials found for profile "anthropic:default"

原因： 找不到认证凭证

解决步骤：

1. 确认 auth profiles 位置正确：~/.openclaw/agents//agent/auth-profiles.json
2. 确认环境变量被 Gateway 正确加载
3. 使用 openclaw models status 检查认证状态

2.3 Dashboard 认证问题

本地访问 http://127.0.0.1:18789/ # 远程访问 - 使用 Tailscale Serve openclaw gateway --tailscale serve # 或 SSH 隧道 ssh -N -L 18789:127.0.0.1:18789 user@host

---## 三、频道消息类报错

3.1 消息发送成功但无回复

排查命令：

openclaw status openclaw gateway status openclaw channels status --probe openclaw pairing list --channel [--account ] openclaw logs --follow

常见原因：

• 检查 Bot 权限
• 刷新 Bot token| 日志关键词 | 含义 | 解决方案 |
  | ------------------------------------------------------- | -------------------------------- | -------------------------------------- |
  | drop guild message (mention required) | Discord 群组需要 @mention 机器人 | 在群组中 @mention 机器人 |
  | pairing request / pending | 发送者未通过配对审批 | 运行 openclaw pairing approve 审批 |
  | blocked / allowlist | 发送者被过滤 | 检查 channel 的 allowlist 配置 |
  | not_in_channel / missing_scope / Forbidden / 401/403 | 频道权限问题 | |

3.2 频道连接问题

mention required - 群组 mention gating 阻止了消息处理

not_in_channel / missing_scope / Forbidden / 401/403 - 频道权限 token 问题

解决步骤：

1. 检查 Bot 在频道中的权限
2. 确认 Bot token 仍然有效
3. 查看频道是否被删除或机器人被移除

---## 四、定时任务类报错

4.1 Cron 任务不触发

排查命令：

openclaw cron status openclaw cron list openclaw cron runs --id <**id> --limit 20 openclaw logs --follow

常见原因：

• 检查 heartbeat 配置的 activeHours
• 调整静默时段设置
• 等待当前任务完成
• 减少任务复杂度
• 检查目标配置
• 重新配置 heartbeat| 日志信息 | 原因 | 解决方案 |
  | --------------------------------------------------------- | ---------------------- | ----------------------------------- |
  | cron: scheduler disabled; **s will not run automatically | Cron 被禁用 | 在配置中启用 cron.enabled: true |
  | heartbeat skipped with reason=quiet-hours | 在静默时段外 | |
  | requests-in-flight | 主会话忙碌，心跳被延迟 | |
  | unknown accountId | 心跳投递目标账号不存在 | |

4.2 Heartbeat 不触发

检查 heartbeat 状态 openclaw status | grep -i heartbeat # 检查 HEARTBEAT.md 是否有效 # 如果文件只有空行和标题，OpenClaw 会跳过以节省 API 调用

---## 五、节点设备类报错

5.1 节点已配对但工具执行失败

排查命令 openclaw nodes status openclaw nodes describe --node openclaw logs --follow

常见报错：

• 在节点上批准
• 或设置自动审批规则
• 将命令添加到白名单
• 调整 exec allowlist 配置| 报错信息 | 原因 | 解决方案 |
  | -------------------------------------- | ------------------- | ------------------------ |
  | NODE_BACKGROUND_UNAVAILABLE | 节点应用未在前台 | 将节点应用切换到前台 |
  | *_PERMISSION_REQUIRED | 系统权限被拒绝/缺失 | 在设备设置中授予必要权限 |
  | SYSTEM_RUN_DENIED: approval required | exec 审批待定 | |
  | SYSTEM_RUN_DENIED: allowlist miss | 命令不在白名单 | |

---## 六、浏览器工具类报错

6.1 浏览器工具失败

排查命令 openclaw browser status openclaw logs --follow openclaw doctor

常见报错：

• 检查 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 | attach-only 模式没有活动的 CDP 目标* 确保浏览器已启动并连接 | |

---## 七、模型服务类报错

7.1 限流报错

HTTP 429: rate_limit_error

原因： Anthropic 配额/限流

解决方案：

• 如果是订阅账户，等待限流窗口重置或升级套餐
• 如果是 API key，查看 Anthropic Console 的使用/计费并提高限额
• 设置备用模型以便在限流时保持响应

HTTP 429: Extra usage is required for long context requests

原因： 凭证不符合长上下文计费资格

解决： 需要 API key 计费或订阅已启用 Extra Usage

7.2 模型相关报错

• 将模型添加到 agents.defaults.models
• 或移除允许列表限制
• 配置 MiniMax provider
• 或使用正确的模型 ID
• 发送 /new 开始新会话| 报错信息 | 原因 | 解决方案 |
  | --------------------------------------------------------------------- | ------------------ | -------- |
  | Model ... is not allowed | 模型不在允许列表中 | |
  | Unknown model: minimax/MiniMax-M2.5 | 提供商未配置 | |
  | LLM request rejected: messages.content.tool_use.input field required | 会话历史损坏 | |

---## 八、安装部署类报错

8.1 Windows 安装问题

问题	解决方案
git not found	安装 Git for Windows 并添加到 PATH
openclaw not recognized	将 npm 全局 bin 目录添加到 PATH
中文显示乱码	在 PowerShell 中执行：chcp 65001

8.2 安装卡住

详细输出模式重新运行 curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose # Beta 版本 + 详细输出 curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose

8.3 Onboarding 卡住

"Wake up my friend" 画面卡住，无回复

解决步骤：

1. 重启 Gateway：openclaw gateway restart
2. 检查状态和认证：openclaw status
3. 查看日志：openclaw logs --follow
4. 运行诊断：openclaw doctor

---## 九、插件技能类报错

9.1 插件安装失败

package.json missing openclaw.extensions

原因： 插件包使用的是 OpenClaw 不再接受的旧格式

解决：

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

正确格式示例 }

---## 十、会话上下文类报错

10.1 上下文溢出

context too large

解决方案：

• 使用 /compact 压缩会话
• 使用 /new 开始新会话
• 启用会话修剪 agents.defaults.contextPruning
• 使用更大上下文窗口的模型

10.2 内存遗忘问题

Memory 不断忘记之前的信息

最佳实践：

• 重要信息写入 MEMORY.md
• 日常记录写入 memory/YYYY-MM-DD.md
• 直接告诉 Bot 记住某些内容

---## 📋 快速诊断流程图

OpenClaw 不工作 ** **─ 没有回复 → 检查 channel 状态和 pairing **─ Dashboard 无法连接 → 检查 auth token 和网络 **─ Gateway 无法启动 → 检查端口占用和配置 **─ 消息不流动 → 检查 channel 权限和 mention 要求 **─ Cron/心跳不触发 → 检查配置和时区 **─ 节点工具失败 → 检查权限和配对状态 **─ 浏览器工具失败 → 检查 Chrome 安装和配置

---## 🔧 常用诊断命令速查

快速状态检查 openclaw status # 完整诊断报告 openclaw status --all # 网关状态 openclaw gateway status # 频道状态 openclaw channels status --probe # 模型状态 openclaw models status # 节点状态 openclaw nodes status # 定时任务 openclaw cron list # 查看日志 openclaw logs --follow # 系统诊断 openclaw doctor

---