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