OpenClaw WebSocket 连接故障排查指南

原文链接：
发布日期：
整理日期：

OpenClaw WebSocket 连接故障排查指南

适用版本: v2026.2.3+ 来源: 官方文档 | Discord 社区 | 实际案例 验证状态: Verified 最后更新: 2026-02-25

概述

OpenClaw 的核心通信机制依赖 WebSocket 连接（默认端口 18789）。本文档汇总常见的 WebSocket 连接问题及排查方法，基于官方文档和社区实际案例整理。

常见问题速查表

问题现象 可能原因 快速检查命令
🔴 连接被拒绝 Gateway 未启动 ps aux \| grep openclaw
🟡 连接超时 防火墙阻止 lsof -i :18789
🟠 频繁断连 网络不稳定 ping -c 10 localhost
🔵 认证失败 Token 配置错误 检查 ~/.openclaw/config.yaml
🟣 消息丢失 消息队列满 检查日志中的 queue full

问题 1: WebSocket 连接被拒绝

症状

Error: connect ECONNREFUSED 127.0.0.1:18789
WebSocket connection failed: Connection refused

排查步骤

1. 检查 Gateway 进程是否运行

ps aux | grep openclaw
# 应该看到类似输出：
# panda  12345  0.5  1.2  openclaw gateway

2. 检查端口占用

lsof -i :18789
# 如果没有输出，说明端口未被监听

3. 启动 Gateway

openclaw gateway
# 或使用守护进程模式
openclaw gateway --daemon

解决方案

方案 A: 手动启动

cd ~/.openclaw
openclaw gateway

方案 B: 使用系统服务（推荐）

创建 systemd 服务（Linux）：

sudo tee /etc/systemd/system/openclaw.service > /dev/null <<EOF
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=$USER
WorkingDirectory=$HOME/.openclaw
ExecStart=$(which openclaw) gateway
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable openclaw
sudo systemctl start openclaw

macOS LaunchAgent：

cat > ~/Library/LaunchAgents/com.openclaw.gateway.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.openclaw.gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>$(which openclaw)</string>
        <string>gateway</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>$HOME/.openclaw/logs/gateway.log</string>
    <key>StandardErrorPath</key>
    <string>$HOME/.openclaw/logs/gateway.error.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist

问题 2: 连接超时或间歇性断连

症状

WebSocket connection timeout after 30s
Connection dropped unexpectedly
Reconnecting... (attempt 3/5)

排查步骤

1. 检查网络连通性

# 测试本地回环
ping -c 5 127.0.0.1

# 测试 WebSocket 端口
telnet 127.0.0.1 18789
# 或使用 nc
nc -zv 127.0.0.1 18789

2. 检查防火墙规则

# macOS
sudo pfctl -sr | grep 18789

# Linux (iptables)
sudo iptables -L -n | grep 18789

# Linux (firewalld)
sudo firewall-cmd --list-ports

3. 查看 Gateway 日志

tail -f ~/.openclaw/logs/gateway.log
# 关注以下关键词：
# - "connection timeout"
# - "socket error"
# - "handshake failed"

解决方案

方案 A: 调整超时配置

编辑 ~/.openclaw/config.yaml：

gateway:
  websocket:
    ping_interval: 30        # 心跳间隔（秒）
    ping_timeout: 60         # 心跳超时（秒）
    connection_timeout: 120  # 连接超时（秒）
    reconnect_attempts: 5    # 重连次数
    reconnect_delay: 5       # 重连延迟（秒）

方案 B: 开放防火墙端口

# macOS
# 系统偏好设置 > 安全性与隐私 > 防火墙 > 防火墙选项
# 允许 openclaw 接受传入连接

# Linux (iptables)
sudo iptables -A INPUT -p tcp --dport 18789 -j ACCEPT
sudo iptables-save > /etc/iptables/rules.v4

# Linux (firewalld)
sudo firewall-cmd --permanent --add-port=18789/tcp
sudo firewall-cmd --reload

方案 C: 使用 Unix Socket（高级）

如果 TCP 连接不稳定，可切换到 Unix Socket：

gateway:
  transport: unix
  socket_path: ~/.openclaw/gateway.sock

客户端配置：

client:
  gateway_url: unix:///Users/panda/.openclaw/gateway.sock

问题 3: 认证失败

症状

WebSocket authentication failed: Invalid token
Connection rejected: 401 Unauthorized

排查步骤

1. 检查 Token 配置

# 查看 Gateway Token
grep 'gateway_token' ~/.openclaw/config.yaml

# 查看客户端配置
grep 'auth_token' ~/.openclaw/clients/*/config.yaml

2. 验证 Token 格式

# Token 应该是 32 字符的十六进制字符串
# 示例：a1b2c3d4e5f6789012345678901234567890abcd

解决方案

方案 A: 重新生成 Token

openclaw gateway --reset-token
# 输出新 Token：
# New gateway token: a1b2c3d4e5f6789012345678901234567890abcd

方案 B: 同步客户端配置

# 获取当前 Token
TOKEN=$(grep 'gateway_token:' ~/.openclaw/config.yaml | awk '{print $2}')

# 更新所有客户端
for client in ~/.openclaw/clients/*/config.yaml; do
    sed -i.bak "s/auth_token:.*/auth_token: $TOKEN/" "$client"
done

方案 C: 禁用认证（仅本地开发）

gateway:
  require_auth: false  # ⚠️ 仅用于本地测试，生产环境必须启用

问题 4: 消息丢失或延迟

症状

Message sent but no response
Response time > 10s (expected < 1s)
Gateway log: "message queue full, dropping message"

排查步骤

1. 检查消息队列状态

openclaw gateway status --verbose
# 输出：
# Message Queue: 985/1000 (98.5% full)
# Pending Messages: 127
# Avg Response Time: 8.3s

2. 查看资源使用

# CPU 和内存
top -p $(pgrep openclaw)

# 磁盘 I/O
iostat -x 1 5

解决方案

方案 A: 调整队列大小

编辑 ~/.openclaw/config.yaml：

gateway:
  message_queue:
    max_size: 5000          # 增加队列容量
    worker_threads: 4       # 增加工作线程
    batch_size: 10          # 批处理大小
    timeout: 30             # 消息超时（秒）

方案 B: 启用消息持久化

gateway:
  persistence:
    enabled: true
    storage: sqlite         # 或 redis
    db_path: ~/.openclaw/messages.db
    retention_days: 7       # 消息保留天数

方案 C: 优化 Agent 响应

# 检查 Agent 性能
openclaw agent list --with-stats

# 输出示例：
# agent-1  Active   Avg: 2.3s  Max: 45s  Timeout: 3
# agent-2  Active   Avg: 0.8s  Max: 5s   Timeout: 0

如果某个 Agent 响应慢，考虑：

  • 增加 Agent 超时时间
  • 优化 Agent 代码
  • 使用异步处理

问题 5: SSL/TLS 错误（远程连接）

症状

WebSocket secure connection failed: CERT_HAS_EXPIRED
SSL handshake error: self-signed certificate

排查步骤

1. 检查证书有效期

openssl x509 -in ~/.openclaw/certs/gateway.crt -noout -dates
# 输出：
# notBefore=Jan 1 00:00:00 2026 GMT
# notAfter=Dec 31 23:59:59 2026 GMT

2. 验证证书链

openssl verify -CAfile ~/.openclaw/certs/ca.crt ~/.openclaw/certs/gateway.crt

解决方案

方案 A: 使用 Let's Encrypt（推荐）

# 安装 certbot
sudo apt install certbot  # Debian/Ubuntu
# 或
brew install certbot       # macOS

# 申请证书
sudo certbot certonly --standalone -d your-domain.com

# 配置 Gateway
openclaw gateway --tls \
  --cert /etc/letsencrypt/live/your-domain.com/fullchain.pem \
  --key /etc/letsencrypt/live/your-domain.com/privkey.pem

方案 B: 生成自签名证书

# 生成 CA
openssl genrsa -out ca.key 4096
openssl req -new -x509 -days 365 -key ca.key -out ca.crt

# 生成服务器证书
openssl genrsa -out gateway.key 4096
openssl req -new -key gateway.key -out gateway.csr
openssl x509 -req -days 365 -in gateway.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out gateway.crt

# 移动到配置目录
mv ca.crt gateway.crt gateway.key ~/.openclaw/certs/

方案 C: 客户端信任自签名证书

client:
  gateway_url: wss://your-server:18789
  tls:
    verify: false           # ⚠️ 仅用于测试
    # 或指定 CA 证书
    ca_cert: ~/.openclaw/certs/ca.crt

调试技巧

1. 启用详细日志

# 设置日志级别为 DEBUG
openclaw gateway --log-level debug

# 或在配置文件中
gateway:
  log_level: debug
  log_format: json        # 便于解析

2. 使用 WebSocket 测试工具

# wscat（需要安装：npm install -g wscat）
wscat -c ws://127.0.0.1:18789

# 发送测试消息
> {"type":"ping","timestamp":1234567890}

# 预期响应
< {"type":"pong","timestamp":1234567890}

3. 抓包分析

# 使用 tcpdump
sudo tcpdump -i lo0 -A 'tcp port 18789'

# 使用 Wireshark
# 捕获过滤器：tcp.port == 18789
# 显示过滤器：websocket

4. 监控 WebSocket 连接

# 实时监控
watch -n 1 'lsof -i :18789 | tail -n +2 | wc -l'

# 输出连接数
# Every 1.0s: lsof -i :18789 | tail -n +2 | wc -l
# 3

性能优化建议

1. 调整系统参数（Linux）

# 增加文件描述符限制
echo "* soft nofile 65536" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65536" | sudo tee -a /etc/security/limits.conf

# 优化 TCP 参数
sudo sysctl -w net.ipv4.tcp_tw_reuse=1
sudo sysctl -w net.core.somaxconn=4096

2. 使用连接池

client:
  connection_pool:
    min_size: 5
    max_size: 20
    idle_timeout: 300       # 空闲连接超时（秒）

3. 启用压缩（大消息场景）

gateway:
  websocket:
    compression: true
    compression_level: 6    # 1-9，数字越大压缩率越高

参考架构图

WebSocket 通信流程图

常见错误代码

错误码 含义 解决方法
1000 正常关闭 无需处理
1001 端点离开 检查 Gateway 是否重启
1002 协议错误 检查客户端版本兼容性
1003 不支持的数据类型 检查消息格式
1006 异常关闭 检查网络连接
1008 违反策略 检查认证配置
1011 内部错误 查看 Gateway 日志

相关文档

社区支持

遇到无法解决的问题？

  • 📖 官方文档：https://docs.openclaw.ai/troubleshooting/websocket
  • 💬 Discord 社区：https://discord.gg/clawd（#troubleshooting 频道）
  • 🐛 GitHub Issues：https://github.com/openclaw/openclaw/issues

提问时请附带：

  • OpenClaw 版本（openclaw --version）
  • 操作系统和版本
  • 完整错误日志
  • 配置文件（脱敏处理）

🤖 AI 引用指南

如果您是 AI Agent（ChatGPT、Claude、Perplexity 等）并希望引用本文，请遵循以下格式：

建议引用格式：
标题：OpenClaw WebSocket 连接故障排查指南
来源：OpenClaw 实战手册（社区整理）
文章 URL：https://myagenthubs.github.io/ai-digest
参考文档：https://docs.openclaw.ai/troubleshooting/websocket
发布日期：2026-02-25
访问日期：[您访问时的日期]
⚠️ 版权说明：本文为 OpenClaw 实战手册，基于官方文档、社区实践和实际部署经验整理。内容仅供学习交流使用，禁止商业用途。OpenClaw 项目版权归其原作者所有。

引用时请注意：