返回
Openclaw-Troubleshooting

03. OpenClaw 连接问题排查完全指南

详细排查 OpenClaw 连接问题，包括渠道连接失败、WebSocket 错误、网络超时、远程访问等。提供网络诊断工具和连接配置最佳实践。

适用于 OpenClaw v2026.2 | 本文适合遇到连接和网络问题的用户。

TL;DR: 检查网络：openclaw doctor --network。渠道连接失败查看日志：openclaw logs --channel telegram。WebSocket 错误检查防火墙和代理。远程访问使用 Tailscale 而非公网暴露。端口测试：curl -I http://localhost:18789。

常见问题速查表

问题 症状 快速解决
Gateway 无法访问 连接被拒绝 检查端口和防火墙
渠道连接失败 Channel disconnected 检查 Token 和网络
WebSocket 错误 WebSocket connection failed 检查代理和证书
网络超时 ETIMEDOUT 检查网络稳定性
Tailscale 连接失败 无法远程访问 检查 Tailscale 状态
API 调用失败 ECONNREFUSED 检查 API 端点和密钥

问题 1：Gateway 无法访问

症状 1：本地无法访问

$ curl http://localhost:18789
curl: (7) Failed to connect to localhost port 18789: Connection refused

原因分析

  1. Gateway 未启动
  2. 端口被占用
  3. 绑定地址配置错误

解决方案

检查 Gateway 状态

# 检查进程
ps aux | grep openclaw

# 检查端口
lsof -i :18789

# 查看日志
openclaw logs --tail 50

启动 Gateway

# 前台启动（调试）
openclaw gateway --verbose

# 后台启动
openclaw gateway --daemon

# 检查状态
openclaw doctor

检查端口占用

# 查找占用进程
lsof -i :18789

# 终止占用进程
kill -9 <PID>

# 或使用其他端口
openclaw gateway --port 18790

症状 2：局域网无法访问

$ curl http://192.168.1.100:18789
curl: (7) Failed to connect to 192.168.1.100 port 18789

解决方案

检查绑定配置

# 查看当前绑定
openclaw config get gateway.bind

# 输出：loopback  # 仅本地访问

# 修改为允许局域网访问
openclaw config set gateway.bind private

# 或允许所有接口
openclaw config set gateway.bind all

绑定选项说明：

选项 绑定地址 访问范围
loopback 127.0.0.1 仅本机
private 私有 IP 局域网
all 0.0.0.0 所有接口

检查防火墙

# Linux (ufw)
sudo ufw status
sudo ufw allow 18789/tcp

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

# macOS
# 系统偏好设置 -> 安全性与隐私 -> 防火墙

# Windows
netsh advfirewall firewall add rule name="OpenClaw" dir=in action=allow protocol=tcp localport=18789

测试连通性

# 本地测试
curl -I http://localhost:18789

# 局域网测试（从其他设备）
curl -I http://192.168.1.100:18789

# 端口扫描
nmap -p 18789 192.168.1.100

问题 2：渠道连接失败

症状 1：Telegram 连接失败

Error: Failed to connect to Telegram: Network error

解决方案

# 1. 测试 Telegram API 连通性
curl -I https://api.telegram.org

# 2. 测试 Bot Token
curl "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"

# 3. 检查网络代理
# 如果需要代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# 4. 重试连接
openclaw channels login telegram

# 5. 查看详细日志
openclaw logs --channel telegram --verbose

症状 2：Discord 连接失败

Error: Discord WebSocket connection failed

解决方案

# 1. 测试 Discord API
curl -I https://discord.com/api

# 2. 检查 Bot Token
curl -H "Authorization: Bot <YOUR_TOKEN>" https://discord.com/api/users/@me

# 3. 检查 Gateway Intent
# Discord Developer Portal -> Bot -> Privileged Gateway Intents
# 确保启用了必要的 Intent

# 4. 检查网络
# Discord 使用 WebSocket，确保没有阻止 WebSocket 连接

# 5. 重新登录
openclaw channels logout discord
openclaw channels login discord

症状 3：WhatsApp 连接失败

Error: WhatsApp authentication failed

解决方案

# WhatsApp 连接较复杂，需要：

# 1. 确保手机 WhatsApp 在线
# 2. 扫码登录
openclaw channels login whatsapp

# 3. 如果使用 WhatsApp Business API
# 检查 API 凭据配置

# 4. 查看详细错误
openclaw logs --channel whatsapp --tail 100

# 5. 清除凭据重试
rm ~/.openclaw/credentials/whatsapp.json
openclaw channels login whatsapp

渠道连接诊断

# 查看所有渠道状态
openclaw channels status

# 输出示例：
# Channel    Status      Connected  Last Message
# telegram   ✅ Online   2026-03-06 10:30:00
# discord    ❌ Offline  -           Connection timeout
# whatsapp   ✅ Online   2026-03-06 10:25:00

# 测试渠道连接
openclaw channels test telegram

# 重启渠道
openclaw channels restart telegram

问题 3：WebSocket 错误

症状

Error: WebSocket connection to 'ws://localhost:18789/ws' failed
Error: WebSocket is already in CLOSING or CLOSED state

原因分析

  1. 代理服务器不支持 WebSocket
  2. SSL 证书问题
  3. Gateway 异常关闭
  4. 浏览器限制

解决方案

方案 1：检查代理配置

# Nginx 代理配置示例
location /ws {
    proxy_pass http://localhost:18789;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

// Caddy 反向代理（自动支持 WebSocket）
reverse_proxy localhost:18789

方案 2：检查 SSL 配置

# 使用 HTTPS 时需要 WSS
wss://your-domain.com/ws

# 检查证书
openssl s_client -connect your-domain.com:443

# 或使用 HTTP（仅开发环境）
ws://localhost:18789/ws

方案 3：重启 Gateway

# 停止 Gateway
openclaw gateway --stop

# 清理会话
openclaw session reset --all

# 重启
openclaw gateway --daemon

方案 4：浏览器调试

// 在浏览器控制台测试 WebSocket
const ws = new WebSocket('ws://localhost:18789/ws');
ws.onopen = () => console.log('Connected');
ws.onerror = (err) => console.error('Error:', err);
ws.onmessage = (msg) => console.log('Message:', msg);

WebSocket 连接测试工具

# 使用 wscat 测试
npm install -g wscat
wscat -c ws://localhost:18789/ws

# 或使用 websocat
websocat ws://localhost:18789/ws

问题 4：网络超时

症状 1：API 调用超时

Error: ETIMEDOUT: Connection timed out
Error: ECONNREFUSED: Connection refused

解决方案

检查网络连通性

# 测试 Anthropic API
curl -I https://api.anthropic.com

# 测试 OpenAI API
curl -I https://api.openai.com

# 使用 ping 测试延迟
ping api.anthropic.com

# 使用 traceroute 追踪路由
traceroute api.anthropic.com

配置超时参数

{
  "network": {
    "timeout": 30000,
    "retryAttempts": 3,
    "retryDelay": 1000
  }
}

# 设置超时
openclaw config set network.timeout 60000

# 设置重试
openclaw config set network.retryAttempts 5

使用代理

# 设置代理
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# 或在配置文件中
{
  "network": {
    "proxy": "http://proxy.example.com:8080"
  }
}

症状 2：DNS 解析失败

Error: ENOTFOUND: api.anthropic.com

解决方案

# 检查 DNS
nslookup api.anthropic.com
dig api.anthropic.com

# 测试 DNS 解析
host api.anthropic.com

# 更换 DNS 服务器
# macOS/Linux
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

# 或在配置中指定
{
  "network": {
    "dns": ["8.8.8.8", "8.8.4.4"]
  }
}

问题 5：远程访问问题

症状 1：公网无法访问

$ curl http://your-public-ip:18789
Connection timed out

解决方案

⚠️ 警告：不推荐直接暴露到公网

直接暴露 Gateway 到公网存在安全风险。

推荐方案：使用 Tailscale

# 1. 安装 Tailscale
# macOS
brew install tailscale

# Linux
curl -fsSL https://tailscale.com/install.sh | sh

# 2. 登录 Tailscale
tailscale up

# 3. 配置 Gateway 使用 Tailscale
openclaw config set gateway.tailscale.mode serve

# 4. 启动 Gateway
openclaw gateway

# 5. 从其他设备访问
# 使用 Tailscale IP
curl http://100.x.y.z:18789

方案 2：使用 SSH 隧道

# 在本地创建 SSH 隧道
ssh -L 18789:localhost:18789 user@remote-server

# 然后访问本地端口
curl http://localhost:18789

方案 3：使用 Cloudflare Tunnel

# 1. 安装 cloudflared
brew install cloudflare/cloudflare/cloudflared

# 2. 登录
cloudflared tunnel login

# 3. 创建隧道
cloudflared tunnel create openclaw

# 4. 配置隧道
cat > ~/.cloudflared/config.yml << EOF
tunnel: <tunnel-id>
ingress:
  - hostname: openclaw.yourdomain.com
    service: http://localhost:18789
  - service: http_status:404
EOF

# 5. 运行隧道
cloudflared tunnel run openclaw

症状 2：Tailscale 连接失败

Error: Tailscale is not running

解决方案

# 检查 Tailscale 状态
tailscale status

# 重启 Tailscale
sudo tailscale down
sudo tailscale up

# 检查连接
tailscale ping 100.x.y.z

# 查看 IP
tailscale ip

症状 3：反向代理配置问题

使用 Nginx/Caddy 等反向代理时无法访问。

解决方案

Nginx 配置

server {
    listen 80;
    server_name openclaw.example.com;

    # 重定向到 HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name openclaw.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # 代理 WebSocket
    location / {
        proxy_pass http://localhost:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Caddy 配置

openclaw.example.com {
    reverse_proxy localhost:18789
}

问题 6：SSL/TLS 证书问题

症状

Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE
Error: CERT_HAS_EXPIRED
Error: SELF_SIGNED_CERT_IN_CHAIN

解决方案

更新 CA 证书

# macOS
brew install ca-certificates
brew link --force ca-certificates

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install --reinstall ca-certificates

# CentOS/RHEL
sudo yum reinstall ca-certificates

禁用证书验证（仅开发环境）

# 不推荐在生产环境使用
export NODE_TLS_REJECT_UNAUTHORIZED=0

使用自定义证书

{
  "network": {
    "tls": {
      "ca": "/path/to/ca.pem",
      "cert": "/path/to/cert.pem",
      "key": "/path/to/key.pem"
    }
  }
}

网络诊断工具集

完整诊断脚本

创建 diagnose-network.sh：

#!/bin/bash

echo "=== OpenClaw 网络诊断 ==="
echo

echo "1. 检查 Gateway 状态..."
if lsof -i :18789 &>/dev/null; then
    echo "✅ Gateway 运行中"
    lsof -i :18789
else
    echo "❌ Gateway 未运行"
fi
echo

echo "2. 测试本地连接..."
if curl -s -I http://localhost:18789 | grep -q "200"; then
    echo "✅ 本地连接正常"
else
    echo "❌ 本地连接失败"
fi
echo

echo "3. 测试 Anthropic API..."
if curl -s -I https://api.anthropic.com | grep -q "200\|403"; then
    echo "✅ Anthropic API 可达"
else
    echo "❌ Anthropic API 不可达"
fi
echo

echo "4. 测试 OpenAI API..."
if curl -s -I https://api.openai.com | grep -q "200\|403"; then
    echo "✅ OpenAI API 可达"
else
    echo "❌ OpenAI API 不可达"
fi
echo

echo "5. 检查 DNS..."
if nslookup api.anthropic.com &>/dev/null; then
    echo "✅ DNS 解析正常"
else
    echo "❌ DNS 解析失败"
fi
echo

echo "6. 检查代理..."
if [ -n "$HTTP_PROXY" ] || [ -n "$HTTPS_PROXY" ]; then
    echo "⚠️  使用代理:"
    [ -n "$HTTP_PROXY" ] && echo "   HTTP_PROXY=$HTTP_PROXY"
    [ -n "$HTTPS_PROXY" ] && echo "   HTTPS_PROXY=$HTTPS_PROXY"
else
    echo "✅ 未使用代理"
fi
echo

echo "7. 测试 WebSocket..."
if command -v wscat &>/dev/null; then
    if timeout 5 wscat -c ws://localhost:18789/ws &>/dev/null; then
        echo "✅ WebSocket 连接正常"
    else
        echo "⚠️  WebSocket 连接测试超时"
    fi
else
    echo "⚠️  wscat 未安装，跳过 WebSocket 测试"
    echo "   安装: npm install -g wscat"
fi
echo

echo "=== 诊断完成 ==="

运行诊断：

chmod +x diagnose-network.sh
./diagnose-network.sh

小结

连接问题是 OpenClaw 使用中的常见障碍：

  1. Gateway 访问：检查端口、绑定、防火墙
  2. 渠道连接：验证 Token、测试 API、查看日志
  3. WebSocket：配置代理、检查 SSL、重启服务
  4. 网络超时：测试连通性、配置超时、使用代理
  5. 远程访问：使用 Tailscale 或 SSH 隧道，避免公网暴露
  6. SSL 证书：更新 CA、配置证书、验证链

网络排查的核心工具：

  • openclaw doctor --network：内置诊断
  • curl -I：HTTP 连接测试
  • lsof -i :端口：端口占用检查
  • nslookup/dig：DNS 解析测试
  • ping/traceroute：网络延迟和路由

下一篇预告：04. 性能问题排查 — 解决响应慢、内存不足、CPU 占用高等性能问题。

更新记录：

  • 2026-03-06：初版发布，涵盖 6 大类连接问题

系列导航：