freedak
f7a720204a
- 移除 GovAI, nomifun-tauri, 算力盒子 的 submodule 引用 - 添加所有子项目的完整源代码 - 保留原始 .git 为 .git.bak 备份
229 lines
3.7 KiB
Markdown
229 lines
3.7 KiB
Markdown
# OpenClaw 故障排除指南
|
||
|
||
## 使用 Doctor 命令（主要诊断工具）
|
||
|
||
`openclaw doctor` 是 OpenClaw 的健康检查和修复工具。
|
||
|
||
### 基本诊断
|
||
|
||
```bash
|
||
openclaw doctor
|
||
```
|
||
|
||
这会检查：
|
||
|
||
- 配置文件健康状态
|
||
- Gateway 服务状态
|
||
- 认证配置
|
||
- 渠道连接状态
|
||
- Skills 状态
|
||
- 配置迁移需求
|
||
|
||
### 自动修复
|
||
|
||
```bash
|
||
openclaw doctor --repair
|
||
```
|
||
|
||
自动应用推荐的修复（包括重启服务）。
|
||
|
||
### 深度扫描
|
||
|
||
```bash
|
||
openclaw doctor --deep
|
||
```
|
||
|
||
扫描系统服务，查找额外的 Gateway 安装。
|
||
|
||
### 非交互模式
|
||
|
||
```bash
|
||
openclaw doctor --non-interactive
|
||
```
|
||
|
||
仅应用安全迁移，跳过需要人工确认的操作。
|
||
|
||
## 常见问题诊断
|
||
|
||
### 问题 1：Gateway 无法启动
|
||
|
||
**检查步骤：**
|
||
|
||
1. 检查配置文件是否存在：
|
||
|
||
```bash
|
||
cat ~/.openclaw/openclaw.json
|
||
```
|
||
|
||
2. 检查 `gateway.mode` 是否设置：
|
||
|
||
```bash
|
||
openclaw config get gateway.mode
|
||
```
|
||
|
||
如果未设置，运行：
|
||
|
||
```bash
|
||
openclaw config set gateway.mode local
|
||
```
|
||
|
||
3. 检查端口是否被占用：
|
||
|
||
```bash
|
||
# macOS
|
||
lsof -i :18789
|
||
|
||
# Linux
|
||
ss -ltnp | grep 18789
|
||
```
|
||
|
||
4. 查看 Gateway 日志：
|
||
|
||
```bash
|
||
# macOS (如果使用 launchd)
|
||
tail -f ~/Library/Logs/openclaw-gateway.log
|
||
|
||
# Linux (如果使用 systemd)
|
||
journalctl --user -u openclaw-gateway -f
|
||
```
|
||
|
||
### 问题 2：认证失败
|
||
|
||
**检查步骤：**
|
||
|
||
1. 运行 doctor 检查认证健康：
|
||
|
||
```bash
|
||
openclaw doctor
|
||
```
|
||
|
||
2. 检查 API 密钥环境变量：
|
||
|
||
```bash
|
||
echo $ANTHROPIC_API_KEY
|
||
echo $OPENAI_API_KEY
|
||
```
|
||
|
||
3. 检查配置文件中的认证设置：
|
||
|
||
```bash
|
||
openclaw config get agents.defaults.model
|
||
```
|
||
|
||
4. 重新配置认证：
|
||
```bash
|
||
openclaw configure --section models
|
||
```
|
||
|
||
### 问题 3：渠道连接失败
|
||
|
||
**检查步骤：**
|
||
|
||
1. 检查渠道状态：
|
||
|
||
```bash
|
||
openclaw channels status
|
||
```
|
||
|
||
2. 检查渠道配置：
|
||
|
||
```bash
|
||
openclaw config get channels
|
||
```
|
||
|
||
3. 重新登录渠道：
|
||
```bash
|
||
openclaw channels login
|
||
```
|
||
|
||
### 问题 4：配置文件权限问题
|
||
|
||
如果配置文件权限过宽，doctor 会警告并修复：
|
||
|
||
```bash
|
||
openclaw doctor --repair
|
||
```
|
||
|
||
或手动修复：
|
||
|
||
```bash
|
||
chmod 600 ~/.openclaw/openclaw.json
|
||
```
|
||
|
||
### 问题 5：服务未运行
|
||
|
||
**macOS (launchd):**
|
||
|
||
```bash
|
||
# 检查服务状态
|
||
launchctl list | grep openclaw
|
||
|
||
# 启动服务
|
||
launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist
|
||
|
||
# 或使用 OpenClaw 命令
|
||
openclaw gateway install
|
||
```
|
||
|
||
**Linux (systemd):**
|
||
|
||
```bash
|
||
# 检查服务状态
|
||
systemctl --user status openclaw-gateway
|
||
|
||
# 启动服务
|
||
systemctl --user start openclaw-gateway
|
||
|
||
# 启用自动启动
|
||
systemctl --user enable openclaw-gateway
|
||
```
|
||
|
||
## 故障排除流程
|
||
|
||
当用户遇到问题时，按以下流程处理：
|
||
|
||
1. **确认安装状态**
|
||
|
||
```bash
|
||
openclaw --version
|
||
```
|
||
|
||
2. **运行 Doctor 诊断**
|
||
|
||
```bash
|
||
openclaw doctor
|
||
```
|
||
|
||
3. **检查 Gateway 状态**
|
||
|
||
```bash
|
||
openclaw gateway status
|
||
```
|
||
|
||
4. **查看日志**
|
||
- macOS: `./scripts/clawlog.sh` 或系统日志
|
||
- Linux: `journalctl --user -u openclaw-gateway`
|
||
|
||
5. **检查配置文件**
|
||
|
||
```bash
|
||
cat ~/.openclaw/openclaw.json
|
||
```
|
||
|
||
6. **如果问题持续，建议用户：**
|
||
- 查看最新 GitHub README
|
||
- 访问 docs.openclaw.ai
|
||
- 在 Discord 社区寻求帮助
|
||
|
||
## macOS：launchctl 环境变量覆盖
|
||
|
||
如果之前运行过 `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（或 `...PASSWORD`），该值会覆盖配置文件，并可能导致持续的"未授权"错误。
|
||
|
||
```bash
|
||
launchctl getenv OPENCLAW_GATEWAY_TOKEN
|
||
launchctl getenv OPENCLAW_GATEWAY_PASSWORD
|
||
|
||
launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
|
||
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
|
||
```
|