5.6 KiB
5.6 KiB
OpenClaw 故障排查指南
快速诊断命令
# 首选诊断流程
openclaw status # 基本状态
openclaw status --all # 完整诊断（可分享）
openclaw status --deep # 深度检测
openclaw doctor # 健康检查
openclaw logs --follow # 实时日志
常见问题
Gateway 无法启动
症状:
Error: Invalid config
Gateway start blocked: set gateway.mode=local
原因: 配置不完整或模式错误
解决方案:
# 运行向导配置
openclaw configure
# 或直接设置
openclaw config set gateway.mode local
# 允许无配置启动（临时）
openclaw gateway --allow-unconfigured
Token 不匹配
症状:
gateway connect failed: unauthorized: token mismatch
解决方案:
# 检查本地 Token
openclaw config get gateway.auth.token
# 同步 Token 到远程主机
ssh user@host "openclaw config set gateway.auth.token 'your-token'"
Telegram 消息发送失败
症状:
fetch failed
Network request for 'sendMessage' failed!
排查步骤:
# 1. 检查 Telegram 状态
openclaw status | grep telegram
# 2. 检查代理配置
echo $https_proxy
echo $http_proxy
# 3. 重启 Gateway
openclaw gateway restart
# 4. 检查 Bot Token
openclaw config get channels.telegram.botToken
模型调用失败
症状:
Error: Model not found
anthropic/claude-opus-4 is not available
排查步骤:
# 1. 检查模型配置
openclaw config get models.providers
# 2. 验证配置文件
cat ~/.openclaw/openclaw.json | python3 -m json.tool
# 3. 设置正确模型
openclaw config set agents.defaults.model.primary "deepseek/deepseek-chat"
# 4. 检查认证
openclaw models status
端口被占用 (18789)
症状:
Error: Port 18789 already in use
排查步骤:
# 1. 检查端口占用
lsof -nP -iTCP:18789 -sTCP:LISTEN
# 2. 查看 Gateway 状态
openclaw gateway status
# 3. 停止现有 Gateway
openclaw gateway stop
# 4. 或使用其他端口
openclaw config set gateway.port 18790
openclaw gateway restart
消息不触发响应
排查步骤:
# 1. 检查发送者是否在允许列表
openclaw status | grep AllowFrom
# 2. 群聊检查是否需要 @
openclaw logs --follow | grep blocked
# 3. 检查配对状态
openclaw pairing list telegram
WhatsApp 连接问题
排查步骤:
# 1. 检查状态
openclaw status
openclaw status --deep
# 2. 查看连接日志
openclaw logs --follow | grep -i "connection\|disconnect"
# 3. 重新登录
openclaw channels logout whatsapp
openclaw channels login whatsapp --verbose
# 4. 检查凭证
ls -la ~/.openclaw/credentials/whatsapp/
媒体发送失败
排查步骤:
# 1. 验证文件存在
ls -la /path/to/file.jpg
# 2. 检查文件大小限制
# 图片: max 6MB
# 音频/视频: max 16MB
# 文档: max 100MB
# 3. 检查日志
openclaw logs | grep -i media
内存使用过高
原因: 对话历史保留过多
解决方案:
# 设置会话历史限制
openclaw config set session.historyLimit 100
# 或定期重启 Gateway
openclaw gateway restart
macOS 特定问题
App 崩溃（权限提示）
# 重置 TCC 缓存
tccutil reset All bot.molt.mac.debug
Gateway 卡在 "Starting..."
# 1. 停止 supervisor
openclaw gateway stop
launchctl bootout gui/$UID/bot.molt.gateway
# 2. 检查端口
lsof -nP -iTCP:18789 -sTCP:LISTEN
# 3. 强制停止
kill -TERM <PID>
kill -9 <PID>
Linux 特定问题
浏览器无法启动（Chrome）
# 安装 Chrome
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
# 配置路径
openclaw config set browser.executablePath "/usr/bin/google-chrome-stable"
服务相关问题
服务已安装但未运行
# 检查服务状态
openclaw gateway status
# 查看服务日志
journalctl --user -u openclaw-gateway.service -n 200 --no-pager
# 查看最近错误
openclaw logs | grep -i error
服务环境变量问题
# Gateway 服务使用最小 PATH
# 手动设置环境变量
export https_proxy=http://192.168.0.66:7890
export http_proxy=http://192.168.0.66:7890
# 或在配置中设置
openclaw config set env.vars.HTTPS_PROXY "http://192.168.0.66:7890"
诊断命令速查
| 命令 | 用途 |
|---|---|
openclaw status |
基本状态 |
openclaw status --all |
完整诊断 |
openclaw status --deep |
深度检测 |
openclaw doctor |
健康检查 |
openclaw doctor --fix |
自动修复 |
openclaw logs --follow |
实时日志 |
openclaw logs --since 1h |
最近 1 小时日志 |
openclaw gateway status |
服务状态 |
openclaw gateway probe |
Gateway 探测 |
openclaw channels status |
通道状态 |
openclaw models status |
模型状态 |
日志位置
| 类型 | 位置 |
|---|---|
| Gateway 日志 | /tmp/openclaw/openclaw-YYYY-MM-DD.log |
| 服务日志 | journalctl --user -u openclaw-gateway.service |
| 媒体缓存 | $OPENCLAW_STATE_DIR/media/ |
| 凭证 | $OPENCLAW_STATE_DIR/credentials/ |
恢复出厂设置
⚠️ 此操作会删除所有会话和配置
openclaw gateway stop
trash ~/.openclaw
openclaw channels login # 重新配对
openclaw gateway restart
获取帮助
- 检查日志:
openclaw logs --follow - 搜索 GitHub Issues
- 提供以下信息:
- OpenClaw 版本
- 相关日志片段
- 复现步骤
- 配置（脱敏后）
最后更新: 2026-02-04