Gateway 深度故障排查指南

概述

OpenClaw Gateway 是连接客户端与核心服务的关键组件。当 Gateway 出现问题时，所有频道的消息处理都会受到影响。本文将系统性地介绍 Gateway 故障排查方法。

诊断第一步：运行 Doctor

openclaw doctor

Doctor 命令会自动检测常见问题，输出示例：

✓ Node.js version: v20.11.0
✓ Configuration file: valid
✗ Gateway connection: failed
  → Error: ECONNREFUSED 127.0.0.1:3000
✓ Model provider: openai connected
✗ Channel: telegram - webhook not configured

根据 Doctor 的输出，定位具体问题类别。

网络问题排查

端口被占用

# 检查端口占用
lsof -i :3000
# 或使用
netstat -tlnp | grep 3000

解决方法：修改 Gateway 端口或终止占用进程：

{
  "gateway": {
    "port": 3001
  }
}

防火墙阻拦

# 检查防火墙规则
sudo ufw status
sudo iptables -L -n

# 放行 Gateway 端口
sudo ufw allow 3000/tcp

DNS 解析失败

# 测试 DNS 解析
nslookup api.openai.com
dig api.openai.com

# 检查 /etc/resolv.conf
cat /etc/resolv.conf

如果 DNS 有问题，可以配置备用 DNS：

echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf

SSL/TLS 问题

# 测试 SSL 连接
openssl s_client -connect api.openai.com:443

# 检查证书
curl -vI https://api.openai.com

常见的 SSL 错误及解决：

UNABLE_TO_GET_ISSUER_CERT：安装 CA 证书包
CERT_HAS_EXPIRED：更新系统时间
SELF_SIGNED_CERT：配置 NODE_TLS_REJECT_UNAUTHORIZED=0（仅开发环境）

配置问题排查

配置文件语法错误

# 验证配置文件
openclaw configure --validate

常见语法问题：

JSON 末尾多余的逗号
缺少引号的字符串值
嵌套层级错误

环境变量未设置

# 检查所有必要的环境变量
openclaw doctor --check-env

确保以下关键变量已设置：

# 检查密钥
openclaw secrets list

模型配置错误

# 测试特定模型
openclaw doctor --provider openai --model gpt-4o

运行时问题排查

内存泄漏

# 查看进程内存使用
ps aux | grep openclaw

# 监控内存变化
watch -n 5 "ps -o pid,rss,vsz,comm -p $(pgrep -f openclaw)"

如果内存持续增长，检查以下设置：

{
  "gateway": {
    "maxMemory": "512m",
    "historyLimit": 50,
    "sessionTimeout": 3600
  }
}

高延迟问题

启用详细日志定位瓶颈：

{
  "gateway": {
    "logLevel": "debug",
    "logTimings": true
  }
}

查看日志中的时间分布：

# 过滤延迟相关日志
grep "timing" ~/.openclaw/logs/gateway.log

频繁重启

检查进程管理器日志：

# PM2
pm2 logs openclaw --lines 100

# systemd
journalctl -u openclaw -n 100

常见重启原因：

内存超出限制（OOM Kill）
未捕获的异常
模型供应商返回异常响应

频道连接问题

Webhook 不可达

# 测试 webhook URL
curl -X POST https://your-domain.com/webhook/telegram \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

WebSocket 断开

检查 WebSocket 连接日志：

grep "websocket" ~/.openclaw/logs/gateway.log | tail -20

日志分析

查看实时日志

openclaw logs --follow

按级别过滤

openclaw logs --level error --since "1h"

导出日志用于分析

openclaw logs --since "24h" --output gateway-debug.log

恢复步骤

当问题严重到需要重置时：

# 1. 停止服务
openclaw stop

# 2. 清除缓存
openclaw cache clear

# 3. 重新验证配置
openclaw configure --validate

# 4. 重启服务
openclaw start

总结

Gateway 故障排查的核心思路是：先用 Doctor 命令快速定位问题类别，再通过日志和专项检查深入定位根因。保持日志级别在 info 以上可以帮助事后分析，同时建议配置监控告警，在问题发生时第一时间收到通知。