远程访问

默认情况下 Gateway 仅绑定到 127.0.0.1（本地回环），不接受外部连接。本文档介绍如何安全地启用远程访问（Remote Access）。

前提条件

启用远程访问前，请确保：

• [x] 已配置 Token 认证
• [x] 已准备 TLS 证书（或使用 Caddy 自动 HTTPS）
• [x] 了解网络安全风险

安全警告

永远不要在没有 TLS 加密和认证的情况下将 Gateway 暴露到公网。

启用远程访问

第 1 步：绑定所有接口

openclaw config set gateway.host "0.0.0.0"

或直接启动时指定：

openclaw gateway --host 0.0.0.0 --port 18789

第 2 步：配置认证

# 设置强 Token
export OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)"
echo "Token: $OPENCLAW_GATEWAY_TOKEN"

第 3 步：配置 HTTPS

选择以下任一方案。

HTTPS 方案

方案 A：Caddy（推荐）

Caddy 自动处理 HTTPS 证书申请与续期：

# /etc/caddy/Caddyfile
gateway.example.com {
    reverse_proxy 127.0.0.1:18789
}

# 启动 Caddy
sudo systemctl start caddy

最简方案

Caddy 是最简单的 HTTPS 方案 — 只需一行配置，证书全自动管理。

方案 B：Nginx + Let's Encrypt

# /etc/nginx/sites-available/openclaw
server {
    listen 443 ssl http2;
    server_name gateway.example.com;

    ssl_certificate     /etc/letsencrypt/live/gateway.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/gateway.example.com/privkey.pem;

    # WebSocket 支持
    location /ws {
        proxy_pass http://127.0.0.1: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;
        proxy_read_timeout 86400;
    }

    # HTTP API
    location / {
        proxy_pass http://127.0.0.1:18789;
        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;
    }
}

# 申请 Let's Encrypt 证书
sudo certbot --nginx -d gateway.example.com

# 启用配置
sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

WebSocket 超时

确保 proxy_read_timeout 设置足够大（推荐 86400 秒 = 24 小时），否则长时间空闲的 WebSocket 连接会被断开。

云部署网络

Docker 部署

# docker-compose.yml
version: "3.8"
services:
  openclaw:
    image: openclaw/gateway:latest
    ports:
      - "18789:18789"
    environment:
      - OPENCLAW_GATEWAY_HOST=0.0.0.0
      - OPENCLAW_GATEWAY_TOKEN=${GATEWAY_TOKEN}
    volumes:
      - openclaw-data:/root/.openclaw
    restart: unless-stopped

volumes:
  openclaw-data:

云服务商安全组

确保云服务器的安全组（Security Group）或防火墙允许入站流量：

端口	协议	来源	说明
443	TCP	0.0.0.0/0	HTTPS (反向代理)
18789	TCP	127.0.0.1	Gateway (仅本地)

端口不对外暴露

Gateway 端口 18789 不需要对外开放。反向代理在同一服务器上通过 127.0.0.1 转发即可。

防火墙配置

UFW (Ubuntu)

# 仅允许 HTTPS
sudo ufw allow 443/tcp
sudo ufw deny 18789/tcp
sudo ufw enable

firewalld (CentOS)

sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --permanent --remove-port=18789/tcp
sudo firewall-cmd --reload

连接测试

配置完成后，验证远程连接：

# 测试 HTTPS 端点
curl https://gateway.example.com/health

# 测试 WebSocket
wscat -c wss://gateway.example.com/ws

# 从客户端连接
openclaw connect --host gateway.example.com --port 443 --tls

相关文档

• 远程网关搭建 — 完整搭建教程
• Tailscale — 更简单的 VPN 方案
• 网络模型 — 连接架构详解
• 可信代理认证 — 反向代理认证