OpenClaw 网关故障排查手册

2026-02-23 · 6 分钟故障排查

诊断工具

OpenClaw 提供了一套完整的诊断工具链，遇到问题时请按顺序使用：

# 第一步：运行综合诊断
openclaw doctor

# 第二步：查看详细状态
openclaw status

# 第三步：检查频道连接
openclaw channels status --probe

# 第四步：查看日志
openclaw logs

# 第五步：深度安全审计
openclaw security audit --deep

网关无法启动

配置文件校验失败

OpenClaw 对配置文件有严格的 JSON5 格式校验。如果配置有误，网关会拒绝启动，并且只允许运行诊断命令。

症状：启动时报 "Configuration validation failed"

排查：

# 自动诊断和修复配置问题
openclaw doctor --fix

常见的配置错误：

JSON5 语法错误（多余的逗号、缺少引号等）
使用了已废弃的配置项
字段类型不匹配

端口被占用

症状：报错 "EADDRINUSE" 或 "port already in use"

排查：

# 查看占用端口的进程
# Linux/macOS
lsof -i :18789

# Windows (PowerShell)
Get-NetTCPConnection -LocalPort 18789

解决：修改配置中的端口号：

{
  gateway: {
    port: 18790  // 换一个端口
  }
}

守护进程问题

症状：openclaw gateway status 显示未运行

排查：

# 查看服务状态
openclaw gateway status

# 手动前台启动（查看实时日志）
openclaw gateway --port 18789 --verbose

频道连接失败

通用排查步骤

# 探测所有频道的连接状态
openclaw channels status --probe

Discord 连接问题

常见原因：

Bot Token 无效或已过期
未开启 Message Content Intent
Bot 未被邀请到目标服务器

排查：

确认 Token 是否正确：检查 ~/.openclaw/.env 中的 DISCORD_BOT_TOKEN
前往 Discord 开发者门户检查 Privileged Gateway Intents 是否全部开启
重新生成邀请链接并邀请 Bot

消息发出但无回复

可能原因：

群聊中未 @ 提及 Bot（且 requireMention 已开启）
用户未通过配对审批
AI 模型 API 密钥无效

排查：

# 查看待审批的配对请求
openclaw pairing list

# 验证模型配置
openclaw models list

# 查看最近的日志
openclaw logs --tail 50

模型相关问题

API 密钥无效

症状：回复中出现认证错误

排查：

# 检查环境变量
openclaw status

# 验证密钥（以 Anthropic 为例）
curl -H "x-api-key: $ANTHROPIC_API_KEY" \
  https://api.anthropic.com/v1/messages \
  -d '{"model":"claude-sonnet-4-5","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

Ollama 本地模型不可用

症状：openclaw models list 中看不到 Ollama 模型

排查：

# 确认 Ollama 正在运行
curl http://localhost:11434/api/tags

# 确认环境变量已设置
echo $OLLAMA_API_KEY

# 重新拉取模型
ollama pull llama3.3

回复速度慢

可能原因：

模型服务器负载高
网络延迟
本地模型硬件性能不足

建议：

切换到更快的模型（如 Claude Sonnet 代替 Opus）
本地模型减小上下文窗口
检查网络连接质量

日志系统

日志位置

默认日志文件：/tmp/openclaw/openclaw-YYYY-MM-DD.log

日志级别调整

临时增加日志详细程度以便排查：

{
  logging: {
    level: "debug",        // debug | info | warn | error
    consoleStyle: "pretty" // pretty | compact | json
  }
}

排查完成后记得改回 info 级别。

分享诊断信息

需要向社区求助时，使用预脱敏的状态输出：

# 生成脱敏后的完整状态报告
openclaw status --all

这个命令会自动隐藏敏感信息（API 密钥、令牌等），可以安全地分享到社区。

常用修复命令速查

问题	命令
配置错误	`openclaw doctor --fix`
文件权限	`openclaw security audit --fix`
频道诊断	`openclaw channels status --probe`
查看日志	`openclaw logs --tail 100`
健康检查	`openclaw health`
重启网关	`openclaw gateway restart`