每日备份 2026-06-10 12:57:13
This commit is contained in:
root-backup committed
1 parent
fda2ccb8c2
commit
3d2e638c6a
244 files changed
+58890
-3
No files matched your search
@@ -0,0 +1,298 @@
|
||||
# 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*
|
||||
Reference in new issue
Block a user