299 lines
5.6 KiB
Markdown
299 lines
5.6 KiB
Markdown
# OpenClaw 故障排查指南
|
||
|
||
## 快速诊断命令
|
||
|
||
```bash
|
||
# 首选诊断流程
|
||
openclaw status # 基本状态
|
||
openclaw status --all # 完整诊断（可分享）
|
||
openclaw status --deep # 深度检测
|
||
openclaw doctor # 健康检查
|
||
openclaw logs --follow # 实时日志
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### Gateway 无法启动
|
||
|
||
**症状**:
|
||
```
|
||
Error: Invalid config
|
||
Gateway start blocked: set gateway.mode=local
|
||
```
|
||
|
||
**原因**: 配置不完整或模式错误
|
||
|
||
**解决方案**:
|
||
```bash
|
||
# 运行向导配置
|
||
openclaw configure
|
||
|
||
# 或直接设置
|
||
openclaw config set gateway.mode local
|
||
|
||
# 允许无配置启动（临时）
|
||
openclaw gateway --allow-unconfigured
|
||
```
|
||
|
||
### Token 不匹配
|
||
|
||
**症状**:
|
||
```
|
||
gateway connect failed: unauthorized: token mismatch
|
||
```
|
||
|
||
**解决方案**:
|
||
```bash
|
||
# 检查本地 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!
|
||
```
|
||
|
||
**排查步骤**:
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
**排查步骤**:
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
**排查步骤**:
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
### 消息不触发响应
|
||
|
||
**排查步骤**:
|
||
```bash
|
||
# 1. 检查发送者是否在允许列表
|
||
openclaw status | grep AllowFrom
|
||
|
||
# 2. 群聊检查是否需要 @
|
||
openclaw logs --follow | grep blocked
|
||
|
||
# 3. 检查配对状态
|
||
openclaw pairing list telegram
|
||
```
|
||
|
||
### WhatsApp 连接问题
|
||
|
||
**排查步骤**:
|
||
```bash
|
||
# 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/
|
||
```
|
||
|
||
### 媒体发送失败
|
||
|
||
**排查步骤**:
|
||
```bash
|
||
# 1. 验证文件存在
|
||
ls -la /path/to/file.jpg
|
||
|
||
# 2. 检查文件大小限制
|
||
# 图片: max 6MB
|
||
# 音频/视频: max 16MB
|
||
# 文档: max 100MB
|
||
|
||
# 3. 检查日志
|
||
openclaw logs | grep -i media
|
||
```
|
||
|
||
### 内存使用过高
|
||
|
||
**原因**: 对话历史保留过多
|
||
|
||
**解决方案**:
|
||
```bash
|
||
# 设置会话历史限制
|
||
openclaw config set session.historyLimit 100
|
||
|
||
# 或定期重启 Gateway
|
||
openclaw gateway restart
|
||
```
|
||
|
||
## macOS 特定问题
|
||
|
||
### App 崩溃（权限提示）
|
||
|
||
```bash
|
||
# 重置 TCC 缓存
|
||
tccutil reset All bot.molt.mac.debug
|
||
```
|
||
|
||
### Gateway 卡在 "Starting..."
|
||
|
||
```bash
|
||
# 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）
|
||
|
||
```bash
|
||
# 安装 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"
|
||
```
|
||
|
||
## 服务相关问题
|
||
|
||
### 服务已安装但未运行
|
||
|
||
```bash
|
||
# 检查服务状态
|
||
openclaw gateway status
|
||
|
||
# 查看服务日志
|
||
journalctl --user -u openclaw-gateway.service -n 200 --no-pager
|
||
|
||
# 查看最近错误
|
||
openclaw logs | grep -i error
|
||
```
|
||
|
||
### 服务环境变量问题
|
||
|
||
```bash
|
||
# 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/` |
|
||
|
||
## 恢复出厂设置
|
||
|
||
⚠️ **此操作会删除所有会话和配置**
|
||
|
||
```bash
|
||
openclaw gateway stop
|
||
trash ~/.openclaw
|
||
openclaw channels login # 重新配对
|
||
openclaw gateway restart
|
||
```
|
||
|
||
## 获取帮助
|
||
|
||
1. 检查日志: `openclaw logs --follow`
|
||
2. 搜索 GitHub Issues
|
||
3. 提供以下信息:
|
||
- OpenClaw 版本
|
||
- 相关日志片段
|
||
- 复现步骤
|
||
- 配置（脱敏后）
|
||
|
||
---
|
||
|
||
*最后更新: 2026-02-04*
|