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 无法启动

检查步骤：

检查配置文件是否存在：
bash
```
cat ~/.openclaw/openclaw.json
```

检查 gateway.mode 是否设置：

bash

openclaw config get gateway.mode

如果未设置，运行：

bash

openclaw config set gateway.mode local

检查端口是否被占用：

bash

# macOS
lsof -i :18789

# Linux
ss -ltnp | grep 18789

查看 Gateway 日志：

bash

# macOS (如果使用 launchd)
tail -f ~/Library/Logs/openclaw-gateway.log

# Linux (如果使用 systemd)
journalctl --user -u openclaw-gateway -f

问题 2：认证失败

检查步骤：

运行 doctor 检查认证健康：
bash
```
openclaw doctor
```

检查 API 密钥环境变量：

bash

echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

检查配置文件中的认证设置：
bash
```
openclaw config get agents.defaults.model
```
重新配置认证：
bash
```
openclaw configure --section models
```

问题 3：渠道连接失败

检查步骤：

检查渠道状态：
bash
```
openclaw channels status
```
检查渠道配置：
bash
```
openclaw config get channels
```
重新登录渠道：
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

故障排除流程

当用户遇到问题时，按以下流程处理：

确认安装状态
bash
```
openclaw --version
```
运行 Doctor 诊断
bash
```
openclaw doctor
```
检查 Gateway 状态
bash
```
openclaw gateway status
```
查看日志
- macOS: ./scripts/clawlog.sh 或系统日志
- Linux: journalctl --user -u openclaw-gateway
检查配置文件
bash
```
cat ~/.openclaw/openclaw.json
```
如果问题持续，建议用户：
- 查看最新 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