故障排查速查表

先记住一个原则：先看服务状态，再看配置，再看网络。

1) Bot 不回复

排查步骤

1. 执行 openclaw status，确认 Gateway: running
2. 执行 openclaw health，确认无阻塞错误
3. 核对 Bot Token 是否完整
4. 核对 allowedUsers 是否包含你的用户 ID
5. 执行 openclaw gateway restart 后再测 3 条消息

2) API 返回 401

常见根因

• 使用了错误密钥类型（AccessKey 不是模型 API Key）
• API Key 过期或复制错误
• 模型名填写错误
• 账号没有模型权限

修复动作

1. 重新粘贴正确 sk-... Key
2. 更换一个已开通权限的模型
3. 重启网关后复测

3) API 返回 429

含义

请求过快、并发过高或额度不足。

修复动作

1. 降低并发和重试次数
2. 临时切低成本模型
3. 观察 10 分钟错误率是否恢复

4) 响应很慢

排查步骤

1. 先用轻量模型验证链路
2. 减少上下文消息数量
3. 检查本机网络与代理
4. 检查是否同时开了太多机器人通道

5) 技能不可用

排查步骤

1. openclaw skill list 查看是否已安装
2. 重新安装对应技能
3. 重启 Gateway 并复测

6) 站内搜不到答案

必查项

1. 是否执行了 npm run build:search
2. public/pagefind/ 是否已生成
3. Cloudflare 部署是否使用最新产物

7) 最小诊断命令集

openclaw status
openclaw health
openclaw gateway restart
npm run build:search

8) 什么时候该回滚

满足任一条件就回滚：

1. 错误率持续 10 分钟高于 10%
2. 机器人连续不可用超过 5 分钟
3. 关键业务无法恢复

回滚后要补一条：记录根因与预防动作，避免再次发生。