OpenClaw 使用中常见问题大全:从报错到优化一篇搞定

OpenClaw 真正折腾人的阶段，往往不是安装，而是"明明已经跑起来了，但就是不正常"。比如 Gateway 服务在、消息不回;Telegram 连上了、群里却装死;Skills 明放进去了,就是不加载;Token 一晚上烧得飞快;升级之后又突然冒出 pairing required。这篇专门写给已经在用 OpenClaw 的人。内容基于官方排障文档、官方 FAQ、GitHub Issues 和社区讨论里反复出现的真实故障场景整理,尽量给你一套能直接照着走的排查顺序。

先记住一个总排查顺序

别一出问题就重装。官方文档给的排查梯子其实很实用,优先跑这几步:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe 很多问题走到第 3 步就已经能定位了。

1. Gateway 起不来,先看什么?

先看 openclaw gateway status。如果不是 Runtime: running,重点看三类问题:

配置不对
端口冲突
服务和 CLI 用的不是同一份配置官方文档明确提到,常见报错包括:
Gateway start blocked: set gateway.mode=local
refusing to bind gateway ... without auth
another gateway instance is already listening
EADDRINUSE 结论很简单:别一上来删目录,先确认模式、绑定、认证和端口。

2. `EADDRINUSE` 是什么情况?

就是端口被占了。这类问题在 GitHub Issues 里很常见,既可能是旧 Gateway 没退干净,也可能是浏览器 relay、插件子进程、Windows 重启残留进程把端口占住了。社区里甚至有人是旧的 clawdbot-gateway.service 还在跑,和新服务抢同一个端口。排法:

先看 openclaw gateway status
再看日志里具体是哪个端口
再判断是旧服务残留、插件端口冲突还是你自己另一个实例没关

3. Dashboard / Control UI 连不上怎么办?

先别急着怀疑前端。官方文档里这类问题通常跟认证链路有关,常见日志包括:

device identity required
device nonce mismatch
device signature invalid
AUTH_TOKEN_MISMATCH
PAIRING_REQUIRED 如果是远程访问,优先确认:

URL 对不对
当前 token 是不是最新的
客户端是不是在安全上下文里
设备 token 有没有漂移
是不是升级后认证策略变严了

4. 一直提示 `pairing required` 怎么办?

这不是小众问题,GitHub 上相关 issue 非常多。常见场景有三种:

控制台远程连接反复 1008 pairing required
节点连接时报 pairing required
更新后原来能用的设备突然又要重新配对官方排障文档和 issue 里比较一致的修复思路是:

先列出待审批设备
确认是不是旧设备 token 漂移
如果是升级后出的问题,重新 approve 一次
再检查是不是 token 验证和设备验证混用了旧状态一句话:这类问题很多不是"连不上",而是"身份状态不一致"。

5. Telegram 显示在线,但消息不回

这是高频中的高频。官方 Channel Troubleshooting 里给的检查顺序很明确:

看 pairing 状态
看 DM policy / allowlist
看群组是不是需要 mention
看 Bot privacy mode
看日志有没有 Telegram API 调用失败很多人以为"Bot 在线 = 一切正常",其实只是连接成功,消息路由不一定放行。

6. Telegram 群里不回我,私聊却正常

大概率不是坏了,而是策略问题。常见原因:

群里要求 @mention 才触发
Telegram 隐私模式让机器人看不到普通消息
group allowlist 没配好
你发的是群消息,但策略只放开了 DM 这类问题别先删机器人重加,先看群策略。

7. 日志里出现 `BOT_COMMANDS_TOO_MUCH` 怎么办?

这是真实高频 issue。 OpenClaw 在 Telegram 上注册原生命令和技能命令时,如果总量太多,就会触发 setMyCommands failed: BOT_COMMANDS_TOO_MUCH。GitHub 上不止一个 issue 都提到,多 Agent、技能太多、默认账号把所有 Agent 的技能命令都算进去时,最容易中招。解决思路:

先减少技能数量
少开原生命令映射
多 Agent 场景下别让每个 Agent 都暴露一堆技能命令本质不是 Telegram 坏了,是你命令表太胖了。

8. Telegram 有网络错误、偶发发送失败怎么办?

官方文档给的方向很明确:查 api.telegram.org 的网络路径。尤其是 VPS 上常见这几类:

DNS 解析异常
IPv6 路由有问题
代理/防火墙拦截
上游网络抖动这种问题不要只盯 OpenClaw 日志,还要看宿主机网络环境。

9. Skills 放进去了,但就是不加载

先确认你放的位置对不对。官方 Skills 文档写得很明确,技能会从三类地方加载:

bundled skills
~/.openclaw/skills
<workspace>/skills 而且有优先级。常见坑有:

目录结构不对
没有 SKILL.md
front matter 不符合要求
依赖的二进制不在 PATH
依赖环境变量没配
技能虽然装了,但当前 session 没刷新

10. 为什么我明改了 Skill,聊天里却还是旧行为?

因为技能列表不是每一轮都重新全量扫描。官方文档写了,OpenClaw 会在 session 开始时快照当前可用技能。也就是说,技能或配置变更不一定立刻作用到现有会话。最稳的做法是:

开一个新 session 再试
确认 watcher 是否启用
确认这个技能当前机器和当前 Agent 真有资格加载

11. Skills 加载了,但执行时报缺二进制或权限

这也很常见。官方文档明确说了,requires.bins 是在宿主机检查;如果 Agent 跑在 sandbox 里,二进制还得存在于容器里。很多人踩坑就是宿主机有这个命令,容器里没有,于是看起来"技能存在",实际一跑就炸。所以这类问题要分清:

宿主机有没有
sandbox 里有没有
当前 Agent 有没有被工具策略拦掉

12. Token 消耗异常高,先查哪里?

先看是不是上下文太肥。官方 Token 文档已经写得很细:真正吃 Token 的不只是聊天内容,还包括系统提示、技能列表、workspace 文件、历史消息、工具结果、图片和摘要。排查顺序建议:

技能是不是装太多
AGENTS.md、USER.md、BOOTSTRAP.md 有没有写太长
会话是不是拖太久没 /compact
工具输出是不是太长
图片是不是太大太多

13. `/status` 里的上下文或 Token 显示不对,是不是一定计费错了?

不一定。 GitHub 上有好几个 issue 都在讨论 contextTokens 显示和模型真实上下文窗口不一致、切模型后显示为 0、默认写成 200000 等问题。也就是说,状态展示层和真实模型调用不一定完全等价。如果你怀疑有问题,先把它当成"显示和估算问题",不要立刻下结论说模型一定超配或平台一定乱扣费。

14. 为什么 Anthropic 会报 429 长上下文错误?

官方文档已经明确给出原因: 如果你启用了 context1m: true,但当前 Anthropic 凭据没有长上下文资格,就会报: HTTP 429: rate_limit_error: Extra usage is required for long context requests 解决思路只有三个方向:

关掉 context1m
换支持长上下文的计费凭据
给大模型配置 fallback

15. 多 Agent 场景下,为什么有的 Agent 能用工具,有的不能?

这通常不是 bug,而是策略生效了。官方多 Agent 文档列了很清楚的工具过滤顺序:全局 profile、provider profile、全局 allow/deny、Agent allow/deny、sandbox tool policy、subagent policy,后面的规则只能继续收紧,不能把前面禁掉的再放回来。所以排查重点不是"这个 Agent 为什么傻了",而是"它是不是被你自己的策略阉掉了"。

16. 多 Agent 下为什么技能、认证、行为不一致?

因为它们本来就是分开的。官方文档明确写了:每个 Agent 有自己的 agentDir 认证存储,凭据不共享;workspace 也可以独立;技能也分共享和每 Agent 独立。很多人以为加个 agent 只是"换个人设",其实它更像独立工作空间。

17. 更新后突然出问题,第一反应该做什么?

别先重装,先看变更和跑 doctor。官方排障文档专门提醒:升级后认证、URL 覆盖、绑定和配对身份状态都可能变化。正确动作是:

openclaw --version
openclaw doctor
openclaw gateway status
对照日志确认是配置变化、认证变化还是旧状态残留很多"更新把我搞坏了"其实是旧状态没迁干净。

18. 渠道显示 connected,但就是没消息流

官方文档对这个情况的判断非常明确:优先查 policy、权限和平台规则。比如:

pairing 还没批
allowlist 不匹配
group mention 策略拦了
缺 scope
401/403 也就是说,connected 只代表链路在线,不代表业务放行。

19. Heartbeat / cron 不执行怎么办?

别先怀疑定时表达式。官方 runbook 说先看:

openclaw cron status
openclaw cron list
openclaw cron runs
openclaw system heartbeat last 常见原因包括:
cron 根本没开
scheduler disabled
quiet hours 导致 heartbeat 被跳过
accountId 填错
directPolicy 把目标 DM 拦了

20. 真要排不动了,最有价值的求助信息是什么?

官方 FAQ 给的建议很靠谱,至少准备这些:

openclaw status
openclaw status --all
openclaw gateway status
openclaw doctor
最近日志片段这比你单独发一句"救命,OpenClaw 坏了"有用得多。社区里能快速帮上忙的,基本都靠这些基础信息判断。

最后一句:OpenClaw 的排错核心,不是"会不会命令",而是"先缩小范围"

一旦你把问题先分成几层:

Gateway 层
认证 / 配对层
渠道层
Skill / Tool 层
模型 / Token 层
多 Agent 策略层很多看起来很玄学的故障,其实都能很快收敛。 OpenClaw 不是不能排,而是最怕一出问题就把所有层一起动。

参考

OpenClaw 官方 FAQ:https://docs.openclaw.ai/help/faq
Gateway Troubleshooting:https://docs.openclaw.ai/gateway/troubleshooting
Channel Troubleshooting:https://docs.openclaw.ai/channels/troubleshooting
Skills 文档:https://docs.openclaw.ai/tools/skills
Token Use & Costs:https://docs.openclaw.ai/reference/token-use
Multi-Agent Sandbox & Tools:https://docs.openclaw.ai/tools/multi-agent-sandbox-tools
GitHub Issues:https://github.com/openclaw/openclaw/issues 如果你在找稳定又便宜的 API 中转,推荐试 manusn.com,配置简单,小白也能轻松上手。

先记住一个总排查顺序#

1. Gateway 起不来,先看什么?#

2. EADDRINUSE 是什么情况?#

3. Dashboard / Control UI 连不上怎么办?#

4. 一直提示 pairing required 怎么办?#

5. Telegram 显示在线,但消息不回#

6. Telegram 群里不回我,私聊却正常#

7. 日志里出现 BOT_COMMANDS_TOO_MUCH 怎么办?#

8. Telegram 有网络错误、偶发发送失败怎么办?#

9. Skills 放进去了,但就是不加载#

10. 为什么我明改了 Skill,聊天里却还是旧行为?#

11. Skills 加载了,但执行时报缺二进制或权限#

12. Token 消耗异常高,先查哪里?#

13. /status 里的上下文或 Token 显示不对,是不是一定计费错了?#

14. 为什么 Anthropic 会报 429 长上下文错误?#

15. 多 Agent 场景下,为什么有的 Agent 能用工具,有的不能?#

16. 多 Agent 下为什么技能、认证、行为不一致?#

17. 更新后突然出问题,第一反应该做什么?#

18. 渠道显示 connected,但就是没消息流#

19. Heartbeat / cron 不执行怎么办?#

20. 真要排不动了,最有价值的求助信息是什么?#

最后一句:OpenClaw 的排错核心,不是"会不会命令",而是"先缩小范围"#

参考#