🔧 故障排查指南

问题 1: 一键安装脚本执行失败

错误现象:

curl: (6) Could not resolve host: clawd.org.cn

诊断步骤:

# 1. 检查网络连接
ping clawd.org.cn
curl -I https://clawd.org.cn

# 2. 检查 DNS
cat /etc/resolv.conf
nslookup clawd.org.cn

# 3. 检查代理设置
echo $http_proxy
echo $https_proxy

解决方案:

# 方案 A: 修复 DNS
sudo echo "nameserver 8.8.8.8" >> /etc/resolv.conf

# 方案 B: 使用国内镜像（中国大陆）
curl -fsSL https://clawd.org.cn/install.sh | bash -s -- --mirror china

# 方案 C: 手动下载安装
wget https://clawd.org.cn/install.sh
bash install.sh

问题 2: Node.js 版本不兼容

错误现象:

npm ERR! engine Unsupported engine

解决方案:

# macOS - 使用 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# Linux - 使用 nodesource
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证
node --version  # 应显示 v18.x.x

问题 3: API Key 验证失败

诊断步骤:

# 1. 检查配置中的 API Key
openclaw config get model.apiKey

# 2. 测试 API 连接
curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-3-haiku-20240307","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

# 3. 检查账户状态（登录对应平台查看）

解决方案:

# 1. 更新 API Key
openclaw config set model.apiKey "new-api-key"

# 2. 验证配置
openclaw config validate

# 3. 测试连接
openclaw chat "Hello"

问题 4: 技能列表为空

诊断:

# 检查技能目录
ls -la ~/.openclaw/skills/

# 检查技能市场连接
curl -I https://clawhub.ai/api/skills

# 查看技能安装日志
openclaw logs --filter skills

解决方案:

# 1. 安装测试技能
openclaw skills install searxng

# 2. 验证安装
openclaw skills list

# 3. 如果仍然为空，重新初始化
openclaw init --reset-skills

问题 5: 技能执行超时

解决方案:

# 1. 增加超时时间
openclaw config set skills.timeout 60

# 2. 优化技能配置
openclaw skills config <技能名> --optimize

# 3. 检查技能依赖
openclaw skills check <技能名>

# 4. 重新安装技能
openclaw skills reinstall <技能名>

问题 6: 飞书消息发送失败

诊断步骤:

# 1. 检查渠道状态
openclaw channels status feishu

# 2. 测试发送
openclaw channels test feishu --message "测试消息"

# 3. 查看详细日志
openclaw logs --filter feishu --tail 50

解决方案:

# 1. 重新配置
openclaw channels config feishu --reset

# 2. 验证机器人状态（在飞书群中@机器人）

# 3. 检查飞书应用配置
# - 确认 App ID 和 App Secret 正确
# - 确认已开通消息权限
# - 确认事件订阅配置正确

问题 7: Telegram 机器人无响应

解决方案:

# 1. 验证 Bot Token
# 访问 https://api.telegram.org/bot<YOUR_TOKEN>/getMe

# 2. 重新配置
openclaw channels config telegram --reset

# 3. 关闭 Privacy Mode（如需读取群消息）
# 在@BotFather 发送：/setprivacy

# 4. 将机器人添加到群聊并授予管理员权限

问题 8: OpenClaw 命令无响应

诊断:

# 检查进程
ps aux | grep openclaw

# 查看系统资源
top
free -h
df -h

# 检查日志
openclaw logs --tail 100

解决方案:

# 1. 重启 OpenClaw
openclaw restart

# 2. 如果无效，强制重启
pkill -f openclaw
openclaw start

# 3. 清理缓存
openclaw cache clear

# 4. 检查磁盘空间
df -h ~/.openclaw

问题 9: 内存占用过高

解决方案:

# 1. 限制最大内存
export NODE_OPTIONS="--max-old-space-size=512"

# 2. 清理缓存
openclaw cache clear

# 3. 减少并发任务
openclaw config set concurrency.max 2

# 4. 定期重启
openclaw restart --schedule "0 */4 * * *"

问题 10: 检测到异常登录

紧急处理:

# 1. 立即更改所有 API Key
# 2. 检查配置文件权限
chmod 600 ~/.openclaw/config.json
chmod 700 ~/.openclaw

# 3. 查看访问日志
openclaw logs --filter auth --tail 100

# 4. 启用双因素认证（如支持）
openclaw security enable 2fa

# 5. 检查是否有未授权的访问
openclaw security audit