OpenClaw 故障排查指南

系统性解决常见问题的方法。

🔍 问题诊断流程

标准流程

1. 收集信息
   ↓
2. 定位问题
   ↓
3. 分析原因
   ↓
4. 实施解决
   ↓
5. 验证结果
   ↓
6. 记录总结

📋 问题分类

按类型分类

类型	症状	优先级
启动问题	网关无法启动	🔴 高
连接问题	无法连接平台	🔴 高
响应问题	AI 不回复/回复慢	🟡 中
功能问题	技能不工作	🟡 中
性能问题	系统卡顿/崩溃	🟢 低

🚨 启动问题

问题 1：网关无法启动

症状：

bash

$ openclaw gateway start
# 无响应或报错

诊断步骤：

bash

# 1. 检查端口占用
netstat -tlnp | grep 18789
# 输出：tcp  0  0 127.0.0.1:18789  0.0.0.0:*  LISTEN  1234/node

# 2. 查看配置文件
cat ~/.openclaw/openclaw.json | jq '.gateway'

# 3. 查看详细日志
openclaw logs --level debug --tail 100

# 4. 检查 Node.js 版本
node --version
# 应该 >= 20.0.0

解决方案：

bash

# 方案 1：停止占用端口的进程
kill -9 1234

# 方案 2：更换端口
export OPENCLAW_PORT=18790
openclaw gateway start

# 方案 3：重置配置
openclaw configure

问题 2：配置验证失败

症状：

bash

$ openclaw config validate
Error: Invalid configuration

诊断步骤：

bash

# 1. 检查 JSON 语法
cat ~/.openclaw/openclaw.json | jq .

# 2. 检查必需字段
openclaw config get --required

# 3. 检查凭证
openclaw credentials verify

解决方案：

bash

# 修复 JSON 语法
vim ~/.openclaw/openclaw.json

# 重新配置
openclaw configure

# 验证配置
openclaw config validate

🔌 连接问题

问题 3：飞书无法连接

症状：

消息发送失败
收不到消息
显示连接错误

诊断步骤：

bash

# 1. 检查飞书配置
openclaw channels info feishu

# 2. 测试连接
curl -I https://open.feishu.cn

# 3. 查看飞书日志
openclaw logs --grep feishu

# 4. 验证凭证
openclaw channels test feishu

解决方案：

bash

# 方案 1：更新凭证
openclaw configure --channel feishu

# 方案 2：检查权限
# 在飞书开放平台检查应用权限

# 方案 3：重启网关
openclaw gateway restart

问题 4：模型连接失败

症状：

Error: Failed to connect to model

诊断步骤：

bash

# 1. 检查模型配置
openclaw models list

# 2. 测试模型连接
openclaw models test qwen3.5-plus

# 3. 检查 API Key
echo $OPENCLAW_API_KEY

# 4. 测试 API 连接
curl -H "Authorization: Bearer $API_KEY" \
  https://api.dashscope.aliyuncs.com/api/v1/models

解决方案：

bash

# 方案 1：更新 API Key
export OPENCLAW_API_KEY="new-key"

# 方案 2：切换模型
openclaw models use qwen-plus

# 方案 3：检查网络
ping api.dashscope.aliyuncs.com

💬 响应问题

问题 5：AI 不回复

症状：

收到消息但 AI 不回复
长时间无响应

诊断步骤：

bash

# 1. 检查会话状态
openclaw sessions list

# 2. 查看消息队列
openclaw queue status

# 3. 检查资源使用
openclaw status --deep

# 4. 查看 AI 日志
openclaw logs --grep "agent\|model"

解决方案：

bash

# 方案 1：清理会话
openclaw sessions clean --idle 1h

# 方案 2：重启网关
openclaw gateway restart

# 方案 3：检查模型配额
# 登录 ModelStudio 查看用量

问题 6：回复太慢

症状：

响应时间超过 10 秒
用户体验差

诊断步骤：

bash

# 1. 测量响应时间
time openclaw message send "测试"

# 2. 检查网络延迟
ping api.dashscope.aliyuncs.com

# 3. 查看模型负载
openclaw models stats

# 4. 检查系统资源
top -p $(pgrep -f openclaw)

解决方案：

bash

# 方案 1：使用更快的模型
openclaw models use qwen-plus

# 方案 2：限制输出长度
# 在配置中设置 maxTokens: 500

# 方案 3：启用缓存
# 配置响应缓存

🛠️ 功能问题

问题 7：技能不工作

症状：

技能命令无响应
技能执行报错

诊断步骤：

bash

# 1. 列出技能
openclaw skills list

# 2. 检查技能状态
openclaw skills info weather

# 3. 测试技能
openclaw skills test weather --args "北京"

# 4. 查看技能日志
openclaw logs --grep skill

解决方案：

bash

# 方案 1：重新安装技能
openclaw skills uninstall weather
openclaw skills install weather

# 方案 2：更新技能
openclaw skills update weather

# 方案 3：检查依赖
cd ~/.openclaw/skills/weather
npm install

问题 8：记忆系统异常

症状：

记忆无法保存
搜索无结果

诊断步骤：

bash

# 1. 检查记忆文件
ls -la ~/.openclaw/workspace/memory/

# 2. 测试记忆搜索
openclaw memory search "测试"

# 3. 检查向量数据库
openclaw memory vector-stats

# 4. 查看记忆日志
openclaw logs --grep memory

解决方案：

bash

# 方案 1：重建索引
openclaw memory index --rebuild

# 方案 2：清理记忆
openclaw memory clean --older 30d

# 方案 3：修复数据库
openclaw memory repair

⚡ 性能问题

问题 9：内存占用高

症状：

内存使用超过 1GB
系统变慢

诊断步骤：

bash

# 1. 查看内存使用
ps aux | grep openclaw

# 2. 分析内存
openclaw status --memory

# 3. 查看会话数
openclaw sessions list | wc -l

# 4. 检查缓存
openclaw cache stats

解决方案：

bash

# 方案 1：清理会话
openclaw sessions clean --older 1d

# 方案 2：清理缓存
openclaw cache clear

# 方案 3：限制内存
export NODE_OPTIONS="--max-old-space-size=1024"

问题 10：CPU 使用率高

症状：

CPU 持续 100%
系统卡顿

诊断步骤：

bash

# 1. 查看 CPU 使用
top -p $(pgrep -f openclaw)

# 2. 分析性能
openclaw status --cpu

# 3. 查看并发数
openclaw sessions list --active

# 4. 检查任务队列
openclaw queue status

解决方案：

bash

# 方案 1：限制并发
# 在配置中设置 maxConcurrent: 4

# 方案 2：优化查询
# 启用缓存和索引

# 方案 3：升级硬件
# 增加 CPU 核心数

📊 诊断工具

内置工具

bash

# 完整诊断
openclaw doctor

# 健康检查
openclaw health check

# 性能分析
openclaw analyze

# 导出诊断信息
openclaw doctor --export > diagnosis.json

外部工具

bash

# 网络诊断
curl -I https://api.example.com
ping api.example.com
traceroute api.example.com

# 系统诊断
top
htop
iotop

# 日志分析
grep "ERROR" ~/.openclaw/logs/*.log

📋 故障排查检查清单

基础检查

[ ] 服务是否运行
[ ] 配置是否正确
[ ] 网络是否通畅
[ ] 权限是否足够
[ ] 资源是否充足

进阶检查

[ ] 日志是否有错误
[ ] 依赖是否正常
[ ] 缓存是否有效
[ ] 索引是否完整
[ ] 队列是否堵塞

深度检查

[ ] 代码逻辑是否正确
[ ] 数据流是否通畅
[ ] 性能是否达标
[ ] 安全是否合规
[ ] 备份是否完整

🆘 获取帮助

官方资源

社区支持

提交问题

bash

# 收集诊断信息
openclaw doctor --report

# 提交到 GitHub
# https://github.com/openclaw/openclaw/issues/new

提示

系统化的诊断流程让问题解决更高效！

🟢🐉 泡泡龙

OpenClaw 故障排查指南 ​

🔍 问题诊断流程 ​

标准流程 ​

📋 问题分类 ​

按类型分类 ​

🚨 启动问题 ​

问题 1：网关无法启动 ​

问题 2：配置验证失败 ​

🔌 连接问题 ​

问题 3：飞书无法连接 ​

问题 4：模型连接失败 ​

💬 响应问题 ​

问题 5：AI 不回复 ​

问题 6：回复太慢 ​

🛠️ 功能问题 ​

问题 7：技能不工作 ​

问题 8：记忆系统异常 ​

⚡ 性能问题 ​

问题 9：内存占用高 ​

问题 10：CPU 使用率高 ​

📊 诊断工具 ​

内置工具 ​

外部工具 ​

📋 故障排查检查清单 ​

基础检查 ​

进阶检查 ​

深度检查 ​

🆘 获取帮助 ​

官方资源 ​

社区支持 ​

提交问题 ​

OpenClaw 故障排查指南

🔍 问题诊断流程

标准流程

📋 问题分类

按类型分类

🚨 启动问题

问题 1：网关无法启动

问题 2：配置验证失败

🔌 连接问题

问题 3：飞书无法连接

问题 4：模型连接失败

💬 响应问题

问题 5：AI 不回复

问题 6：回复太慢

🛠️ 功能问题

问题 7：技能不工作

问题 8：记忆系统异常

⚡ 性能问题

问题 9：内存占用高

问题 10：CPU 使用率高

📊 诊断工具

内置工具

外部工具

📋 故障排查检查清单

基础检查

进阶检查

深度检查

🆘 获取帮助

官方资源

社区支持

提交问题