Update: 将子项目从 submodule 转为完整内容

- 移除 GovAI, nomifun-tauri, 算力盒子的 submodule 引用 - 添加所有子项目的完整源代码 - 保留原始 .git 为 .git.bak 备份
2026-07-04 19:20:46 +08:00
parent 54d6465fa7
commit f7a720204a
3360 changed files with 802660 additions and 3 deletions
@@ -0,0 +1,228 @@
+# 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
+```