故障排除
本页帮助你诊断和解决常见问题。
诊断工具
Doctor 命令
bash
openclaw doctor这会检查：
- 系统环境和依赖
- Gateway 运行状态
- 配置文件有效性
- 安全设置
日志查看
bash
# 启动时查看详细日志
openclaw gateway --verbose
# 日志文件位置
~/.openclaw/logs/安装问题
Node 版本不兼容
症状: 安装失败或运行报错
解决方案:
bash
# 检查版本
node -v
# 使用 nvm 安装正确版本
nvm install 24
nvm use 24权限错误
症状: EACCES 或权限拒绝错误
解决方案:
bash
# 修复 npm 权限
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules
# 或使用 sudo 安装
sudo npm install -g openclaw网络问题
症状: 下载超时或连接失败
解决方案:
bash
# 配置镜像源
npm config set registry https://registry.npmmirror.com
# 或使用代理
npm config set proxy http://your-proxy:portGateway 问题
启动失败
症状: Gateway 无法启动
检查步骤:
- 端口是否被占用bash
lsof -i :18789 - 配置文件是否有效bash
cat ~/.openclaw/openclaw.json - 查看错误日志bash
openclaw gateway --verbose
Gateway 频繁重启
可能原因:
- 配置文件语法错误
- 端口冲突
- 资源不足
解决方案:
bash
# 验证配置
openclaw doctor
# 检查端口
netstat -an | grep 18789模型问题
API 调用失败
症状: 模型返回错误或无响应
检查步骤:
- API Key 是否正确bash
# 检查环境变量 echo $OPENAI_API_KEY - 网络是否可达bash
curl -I https://api.openai.com - 余额是否充足
模型响应慢
可能原因:
- 网络延迟
- 模型负载高
- 请求内容过长
优化建议:
- 使用更近的 API 端点
- 选择更快的模型
- 减少 context 长度
渠道问题
Telegram 无法连接
检查步骤:
- Bot Token 是否正确bash
echo $TELEGRAM_BOT_TOKEN - Bot 是否被封禁
- 网络是否可达 Telegram
WhatsApp 无法登录
症状: 扫码后无响应或掉线
解决方案:
bash
# 重新登录
openclaw channels logout whatsapp
openclaw channels login whatsappDiscord 消息无响应
检查步骤:
- Bot 是否在服务器中
- 是否有正确权限
- 频道是否在白名单
Skills 问题
Skill 安装失败
可能原因:
- 网络问题
- Skill 不兼容
- 权限问题
解决方案:
bash
# 检查 Skill 信息
openclaw skills show <skill-name>
# 手动安装
cd ~/.openclaw/workspace/skills
git clone <skill-repo>Skill 不工作
检查步骤:
- Skill 是否正确安装
- 查看 Gateway 日志中的错误
- 检查 Skill 配置
性能问题
内存占用高
可能原因:
- 会话历史过长
- 同时活跃会话过多
- 资源泄漏
解决方案:
bash
# 清理会话
openclaw session prune
# 重启 Gateway
openclaw gateway restart响应延迟
检查步骤:
- 服务器资源使用情况
- 网络延迟
- 模型 API 响应时间
安全问题
未授权访问
解决方案:
- 启用 DM 配对（默认开启）
- 设置白名单
- 启用密码认证
json
// ~/.openclaw/openclaw.json
{
"gateway": {
"auth": {
"mode": "password"
}
}
}数据安全
建议:
- 定期备份
~/.openclaw/目录 - 不要在配置文件中存储敏感信息
- 使用环境变量管理 API Keys
获取帮助
如果以上方案无法解决问题：
- 查看 GitHub Issues
- 在 社区 提问
- 提交新的 Issue（附带诊断信息）