6.27 远程网关配置 - OpenClaw中文社区

本指南详细介绍如何配置远程 Gateway,包括网络设置、认证配置、跨网络访问等实践操作步骤。

概述

远程 Gateway 设置允许节点从不同的机器或网络连接到 Gateway。正确的配置需要平衡便利性和安全性,确保 Gateway 既可访问又受到充分保护。

快速开始

场景一: 本地开发 (默认)

最简单的配置,Gateway 和节点在同一台机器上:

# 启动 Gateway (默认配置)
openclaw gateway

# Gateway 自动监听 127.0.0.1:18789
# 本地节点自动连接

场景二: 局域网访问

通过 SSH 隧道在局域网内访问:

# 在服务器上启动 Gateway
openclaw gateway --port 18789

# 从客户端建立 SSH 隧道
ssh -L 18789:localhost:18789 user@server

# 客户端节点连接到本地端口
export OPENCLAW_GATEWAY=ws://localhost:18789
openclaw node start

场景三: 跨网络访问 (Tailscale)

使用 Tailscale 实现跨网络安全访问:

# 在服务器上配置 Tailscale Gateway
{
  "gateway": {
    "tailscale": {
      "mode": "serve"
    }
  }
}

openclaw gateway

# 从客户端通过 Tailscale 连接
export OPENCLAW_GATEWAY=ws://server-tailscale-name:18789
openclaw node start

详细配置步骤

步骤 1: 基础 Gateway 配置

创建或编辑配置文件 ~/.openclaw/config.json5:

{
  "gateway": {
    // 基础配置
    "port": 18789,
    "bind": "loopback",  // 默认: 仅本地访问
    
    // 认证配置
    "auth": {
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    },
    
    // 可选: 日志配置
    "logging": {
      "level": "info",
      "format": "json"
    }
  }
}

步骤 2: 设置认证

生成强密钥并设置环境变量:

# 生成安全的 token (32 字符以上)
openssl rand -hex 32

# 设置环境变量
export OPENCLAW_GATEWAY_TOKEN="your-generated-token-here"

# 或在配置文件中直接指定 (不推荐)
{
  "gateway": {
    "auth": {
      "token": "your-token-here"
    }
  }
}

步骤 3: 选择访问方式

方式 A: SSH 隧道 (推荐)

保持 Gateway loopback 绑定,通过 SSH 隧道访问:

# 服务器端: 无需额外配置,使用默认 loopback
openclaw gateway

# 客户端: 建立持久 SSH 隧道
ssh -f -N -L 18789:localhost:18789 user@remote-server

# 或使用 autossh 自动重连
autossh -M 0 -f -N -L 18789:localhost:18789 user@remote-server

方式 B: Tailscale (推荐)

使用 Tailscale 提供安全的跨网络访问:

1. 安装 Tailscale

# macOS
brew install tailscale

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

# 登录 Tailscale
sudo tailscale up

2. 配置 Gateway

{
  "gateway": {
    "port": 18789,
    "tailscale": {
      "mode": "serve",      // 仅 Tailnet 内可访问
      "bind": "tailnet",    // 绑定到 Tailscale 接口
      "auth": {
        "enabled": true,
        "allowedUsers": [
          "user@github",    // 允许的 Tailscale 用户
          "team@google"
        ]
      }
    },
    "auth": {
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    }
  }
}

# 启动 Gateway
openclaw gateway

3. 客户端连接

# 通过 Tailscale 设备名连接
export OPENCLAW_GATEWAY=ws://server-name:18789

# 或通过 Tailscale IP
export OPENCLAW_GATEWAY=ws://100.x.x.x:18789

openclaw node start

方式 C: 直接绑定 (不推荐)

安全警告

仅在完全信任的网络环境中使用,并配合强认证和防火墙规则。

{
  "gateway": {
    "bind": "0.0.0.0",  // 监听所有接口
    "port": 18789,
    "auth": {
      "token": "${VERY_STRONG_TOKEN}",
      "rateLimit": {
        "enabled": true,
        "maxRequests": 100,
        "windowMs": 60000
      }
    }
  }
}

# 配置防火墙规则 (示例: Ubuntu/ufw)
sudo ufw allow from 192.168.1.0/24 to any port 18789

步骤 4: 验证连接

# 检查 Gateway 状态
openclaw status

# 测试连接
curl http://localhost:18789

# 测试 WebSocket 连接
openclaw gateway ping

# 查看活动连接
openclaw gateway list-connections

多 Gateway 配置

运行多个 Gateway 实例需要隔离配置和端口:

使用 Profile

# Gateway 1 (默认)
openclaw gateway --port 18789

# Gateway 2 (使用 profile)
openclaw --profile rescue gateway --port 19001

# 检查状态
openclaw status                      # Gateway 1
openclaw --profile rescue status     # Gateway 2

必需的隔离配置

{
  "gateway": {
    "port": 19001,  // 不同的基础端口
    "bind": "loopback"
  },
  "agents": {
    "defaults": {
      "workspace": "/path/to/separate/workspace"
    }
  }
}

# 环境变量隔离
export OPENCLAW_CONFIG_PATH="~/.openclaw/rescue-config.json5"
export OPENCLAW_STATE_DIR="~/.openclaw/rescue-state"

高级配置

TLS/SSL 加密

{
  "gateway": {
    "port": 18789,
    "tls": {
      "enabled": true,
      "cert": "/path/to/cert.pem",
      "key": "/path/to/key.pem",
      "ca": "/path/to/ca.pem"  // 可选: 客户端证书验证
    }
  }
}

# 客户端连接使用 wss://
export OPENCLAW_GATEWAY=wss://server:18789

反向代理 (Nginx)

upstream openclaw_gateway {
    server 127.0.0.1:18789;
}

server {
    listen 443 ssl;
    server_name gateway.example.com;

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

    location / {
        proxy_pass http://openclaw_gateway;
        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;
        
        # WebSocket 超时
        proxy_read_timeout 86400;
    }
}

负载均衡

# Nginx 配置示例
upstream openclaw_gateways {
    least_conn;  # 最少连接算法
    server 192.168.1.10:18789 max_fails=3 fail_timeout=30s;
    server 192.168.1.11:18789 max_fails=3 fail_timeout=30s;
    server 192.168.1.12:18789 max_fails=3 fail_timeout=30s;
}

server {
    listen 443 ssl;
    server_name gateway.example.com;
    
    location / {
        proxy_pass http://openclaw_gateways;
        # ... WebSocket 配置同上
    }
}

监控和维护

健康检查

# 定期检查 Gateway 健康状态
*/5 * * * * openclaw status || /path/to/restart-gateway.sh

# restart-gateway.sh
#!/bin/bash
echo "Gateway unhealthy, restarting..."
openclaw gateway stop
sleep 5
openclaw gateway start

日志监控

# 实时查看日志
openclaw logs --follow

# 查看错误日志
openclaw logs --level error --last 100

# 导出日志
openclaw logs --format json > gateway-logs.json

性能监控

# 监控连接数
watch -n 5 'openclaw gateway list-connections | wc -l'

# 监控资源使用
top -p $(pgrep openclaw)

# 监控端口
netstat -an | grep 18789

故障排查

连接失败

# 1. 检查 Gateway 是否运行
openclaw status

# 2. 检查端口监听
lsof -i :18789    # macOS/Linux
netstat -an | grep 18789  # Windows

# 3. 测试网络连通性
ping server-address
telnet server-address 18789
nc -zv server-address 18789

# 4. 检查防火墙
sudo ufw status           # Linux
sudo iptables -L -n       # Linux
netsh advfirewall show currentprofile  # Windows

认证失败

# 验证 token 配置
openclaw config show | grep token

# 检查环境变量
echo $OPENCLAW_GATEWAY_TOKEN

# 测试认证
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
     http://localhost:18789

性能问题

# 增加资源限制
ulimit -n 4096  # 增加文件描述符限制

# 优化配置
{
  "gateway": {
    "maxConnections": 100,
    "requestTimeout": 30000,
    "keepAliveInterval": 60000
  }
}

安全检查清单

✅ Gateway 绑定到 loopback 或 tailnet
✅ 使用强认证 token (32+ 字符)
✅ Token 存储在环境变量而非配置文件
✅ 启用速率限制
✅ 配置 TLS/SSL (生产环境)
✅ 使用防火墙限制访问源
✅ 定期轮换认证凭据
✅ 启用审计日志
✅ 监控异常连接
✅ 保持软件更新

常用命令参考

# 启动配置
openclaw gateway --port 18789
openclaw --profile prod gateway --config /path/to/config.json5

# 状态检查
openclaw status
openclaw gateway health
openclaw gateway list-connections

# 配置管理
openclaw config show
openclaw config validate
openclaw config reload

# 日志
openclaw logs --follow
openclaw logs --level debug --last 1000

# 故障排查
openclaw doctor
openclaw gateway ping
openclaw gateway test-connection

概述