AI突然罢工了?5分钟自查搞定9成故障

本文属于「小龙虾养成记」系列第 27 篇 · 高阶篇

老周急眼了。

上个月他用小龙虾（OpenClaw）做季度汇报，眼看要收尾了，AI突然卡住不动。光标闪了半天，吐出一句"抱歉，遇到了一些问题"，然后就再也没动静了。

他试了刷新页面、重启浏览器、清缓存……折腾了40分钟，最后发现只是对话历史太长、上下文爆了。砍掉一半历史消息，三秒钟恢复正常。

"早知道查一下命令，五分钟解决的事。" 他后来跟我吐槽。

这是真实场景。我访谈了20多位小龙虾深度用户，发现90%的故障根本不需要找客服——只是大家不知道有这些命令。

今天这篇，专门解决这个问题。

先搞清楚问题在哪：诊断三板斧

遇到故障别慌，先跑这三个命令，基本能定位80%的问题。

第一板斧：看状态

openclaw status

这条命令会告诉你：

• 服务是否在线
• 当前对话数
• API调用状态
• 最近一次心跳时间

正常输出长这样：

✓ Gateway:  在线 (延迟 23ms)
✓ API:      就绪 (今日调用 142/500)
✓ Memory:   使用中 (对话历史 1.2MB)
✓ Plugins:  全部加载
最后检查: 2024-01-15 14:32:07

**如果看到 Gateway: 离线**，先别急，试试重启网关（见下方修复命令）。

第二板斧：看日志

openclaw logs --level error --lines 50

这条会抓取最近50条错误日志。日志里藏着问题的答案——是网络超时、还是配置错误、还是某个插件崩了。

输出示例：

[14:31:05] ERROR  API调用超时 (连接 10.0.0.5:8080 失败)
[14:31:06] ERROR  插件 openclaw-plugin-pdf 加载失败: 签名验证失败
[14:31:07] WARN   对话上下文超限 (当前 128K / 限制 200K)

看日志有个技巧：先看最新的错误，问题往往就藏在那几条里。

第三板斧：查配置

openclaw config check

这条命令会扫描你的配置文件，找出：

• 缺失的必要参数
• 格式错误
• 权限问题

输出示例：

✓ config.yaml 格式正确
✗ API密钥未设置 (请运行 openclaw config set api_key YOUR_KEY)
✓ 插件目录可访问
✓ 日志目录可写入

7大常见故障：完整排查手册

故障1：小龙虾突然不回复了

场景还原：你发了一条消息，光标转了几秒，然后……就没然后了。

排查命令链：

# 第一步：检查服务状态
openclaw status

# 第二步：看有没有错误日志
openclaw logs --level error --lines 20

# 第三步：检查网络连通性
openclaw network ping

# 第四步：如果状态显示"离线"，尝试重启网关
openclaw gateway restart

可能的原因和修复：

真实案例： 去年双十一，有个用户连续对话3小时，突然不响应了。一查日志，发现是触发了"单会话最大token限制"保护机制。执行 openclaw session trim --keep-last 20 裁剪到最近20条消息，立刻恢复。

故障2：回复越来越慢，从3秒变成30秒

场景还原：刚开始用挺快的，用着用着越来越慢，最后慢到想砸键盘。

排查命令链：

# 第一步：检查响应延迟基线
openclaw status | grep "延迟"

# 第二步：查看内存和上下文占用
openclaw memory stats

# 第三步：检查是否有大文件在加载
openclaw files list --size-limit 10MB

原因和修复：

实测数据对比：

故障3：输出内容乱码或格式崩溃

场景还原：你让它写代码，它给你一串乱码。你让它列清单，它给你一团浆糊。

排查命令链：

# 第一步：检查模型状态
openclaw model info

# 第二步：重置当前会话的输出解析器
openclaw parser reset

# 第三步：清除可能的特殊字符缓存
openclaw cache clear --type output

这条故障有个特点： 往往是上下文污染导致的。比如你之前粘贴了一段带特殊格式的文本，残留影响了后续输出。

修复后建议： 用 openclaw session export 导出重要对话，开启新会话继续工作。

故障4：文件上传失败

场景还原：你想上传PDF让它总结，结果显示"上传失败"。或者上传到一半卡住。

排查命令链：

# 第一步：检查文件格式和大小
openclaw files validate yourfile.pdf

# 第二步：检查上传服务状态
openclaw upload status

# 第三步：尝试分片上传（大于20MB的文件）
openclaw upload split yourfile.pdf --chunk 5MB

文件上传规格（截至2024年1月）：

常见坑：

• 坑：文件名带中文或空格
  症状：路径解析失败
  解法：重命名为纯英文+下划线，如 report_q1_2024.pdf

• 坑：PDF是扫描件没OCR
  症状：上传成功但内容检索为空
  解法：先本地OCR处理，或使用 openclaw ocr run filename.pdf

故障5：API调用失败

场景还原：你在开发文档里看到可以调用API，兴冲冲写了几行代码，结果报错：401 Unauthorized 或者 429 Rate Limited。

排查命令链：

# 第一步：验证API密钥
openclaw api validate-key

# 第二步：查看当日调用量和限制
openclaw api usage

# 第三步：如果触发了限流，等待冷却
openclaw api cooldown --check

API常见错误码：

故障6：自动化流程不执行

场景还原：你配置了一个自动摘要工作流，设置了触发条件，结果该跑的时候不跑。或者跑到一半卡住了。

排查命令链：

# 第一步：查看所有自动化任务状态
openclaw tasks list --all

# 第二步：查看具体任务的执行日志
openclaw tasks logs TASK_ID

# 第三步：手动触发测试
openclaw tasks run TASK_ID --dry-run

自动化流程常见问题：

故障7：知识库搜不到内容

场景还原：你上传了50份文档，想问"去年Q3的技术方案有哪些"，结果搜出来的是无关内容。

排查命令链：

# 第一步：检查文档索引状态
openclaw knowledge index --status

# 第二步：查看已索引的文档列表
openclaw knowledge docs --list

# 第三步：手动触发重新索引
openclaw knowledge reindex --docs "your_doc.pdf"

知识库问题有个特点： 往往不是"找不到"，而是"找到的都不是你想要的"。

这通常是关键词匹配的问题。试试：

• 用更精准的专业术语
• 尝试同义词扩展搜索
• 用 openclaw knowledge query --expand "AI" 开启语义扩展

避坑清单：7条血泪经验

什么时候你搞不定，必须找技术支持？

小龙虾不是万能的，有些问题超出了自助排查的范围。

必须联系技术支持的情况

1. 账号被锁定或异常

• 现象：密码正确但登录失败，无故被登出
• 自助排查无法解决：可能是账号风控或安全策略问题
• 找谁：官方技术支持（邮件kzfeedback@coze.email）

2. 数据丢失或损坏

• 现象：对话记录突然消失，知识库文件无法恢复
• 自助排查无法解决：需要后台数据修复
• 找谁：官方技术支持，附上时间戳和截图

3. 支付和订阅异常

• 现象：扣费金额不对，订阅状态异常
• 自助排查无法解决：涉及财务系统
• 找谁：官方客服，附上账单截图

4. 安全事件

• 现象：收到可疑登录通知，发现异常API调用
• 自助排查无法解决：需要安全团队介入
• 找谁：立即联系官方并修改所有密钥

⚠️ 注意： 联系技术支持时，请提供：

• openclaw status 完整输出
• openclaw logs --lines 100 日志文件
• 问题发生的确切时间（精确到分钟）
• 你尝试过的排查步骤

性能优化：让小龙虾跑得更快

优化一：定期清理对话历史

对话历史越长，响应越慢。每周执行一次清理：

# 查看各会话大小
openclaw session list --sort size

# 清理超过30天的对话
openclaw session clean --older-than 30d

# 导出重要对话后再删除
openclaw session export SESSION_ID --format markdown

优化二：禁用不需要的插件

插件越多，初始化越慢。只保留你真正用得上的：

# 查看已安装插件
openclaw plugins list

# 禁用插件
openclaw plugins disable plugin-name

# 查看插件加载时间
openclaw plugins benchmark

优化三：配置合适的网络参数

如果访问API经常超时，试试调整超时设置：

# 设置超时时间为30秒
openclaw config set timeout 30

# 设置重试次数为3次
openclaw config set retry 3

效率对比：

SOUL.md：给小龙虾装上自检能力

故障排查的经验要固化下来。打开你配置目录下的 SOUL.md，在末尾追加这段：

## 故障自检规则

### 触发时机
- 响应时间超过15秒 → 自动检查网络和网关状态
- 连续2次回答偏离主题 → 检查上下文是否被污染
- API调用失败 → 记录错误码，尝试2次重试

### 自检动作
1. 优先执行 `openclaw status` 自检
2. 根据症状匹配已知问题库
3. 给出"可能是X问题，可以试试Y命令"的提示
4. 无法解决时，提供完整的诊断信息供用户反馈

### 提示原则
- 不说"出错了"，说"可能是网络超时，可以试试重连"
- 不说"请稍后"，说"正在重试（2/3），预计10秒恢复"
- 给出明确的下一步行动，而不是干等着

这样配置后，小龙虾遇到问题会先自己诊断，给出有用的提示，而不是直接"死机"。

老周后来怎么样了？

开头说的老周，现在遇到问题不慌了。

上周他又遇到AI卡住，这次没用40分钟。看了一眼状态，发现是上下文超了，10秒钟 openclaw session trim，继续干活。

"知道是怎么回事，心里就不慌了。" 他原话。

工具出问题不可怕，可怕的是出了问题只能干等。

收藏这篇文章。下次小龙虾出问题，先来这里查一遍，90%的情况你自己能解决，不用等那一天。

本文命令基于 OpenClaw v2.x 版本，具体命令可能因版本而异，请以官方文档为准。