一、前提与约束

• 无域名：仅通过 https://<服务器IP> 访问，需使用自签名证书（浏览器会提示不安全，需手动信任或继续访问）。

• OpenClaw 要求：远程访问必须使用 wss://，不能使用明文 ws://；网关需保持 bind: "loopback"，仅由 Nginx 代理访问。

• 认证：在 OpenClaw 网关侧启用 token认证（也可选用 password，见后文）。

二、OpenClaw 网关配置（密码认证）

在配置 Nginx 之前，先让 OpenClaw 使用密码认证，并允许来自 Nginx 的 Origin（即 https://<你的IP>）。

2.1 编辑 ~/.openclaw/openclaw.json

在 gateway 段中设置：

"gateway": {
  "port": 18789,
  "mode": "local",
  "bind": "loopback",
  "controlUi": {
    "allowedOrigins": [
      "http://127.0.0.1:18789",
      "http://localhost:18789",
      "https://YOUR_SERVER_IP"
    ]
  },
  "auth": {
    "mode": "token",
    "password": "你的访问令牌"
  },
  "trustedProxies": ["127.0.0.1"]
}

说明：

• 将 YOUR_SERVER_IP 替换为服务器公网 IP（例如 x.x.x.x）。若通过 https://IP:443 访问，Origin 一般为 https://YOUR_SERVER_IP，无需写端口。

• trustedProxies 为可选。当 Nginx 与网关同机部署时，填 ["127.0.0.1"] 可让网关信任来自本机（Nginx）的代理头，消除日志中的 "Proxy headers detected from untrusted address" 警告。

• auth.mode: "password" 表示使用密码认证；客户端需在请求中携带 Authorization: Bearer <密码> 或通过 URL 参数传递（见下文访问方式）。

2.2 重启网关

systemctl --user restart openclaw-gateway.service
# 或
openclaw gateway start

三、安装 Nginx

1. Alibaba Cloud Linux 3 / CentOS 8 / RHEL 8

# 1. 更新系统包
sudo dnf update -y# 
2. 添加 Nginx 官方稳定源
sudo tee /etc/yum.repos.d/nginx.repo <<-'EOF'
[nginx-stable]
name=nginx stable repo
baseurl=https://nginx.org/packages/rhel/8/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true
EOF
# 3. 安装
 Nginxsudo dnf install -y nginx

# 4. 验证安装
nginx -v

2. CentOS 7 / Alibaba Cloud Linux 2

# 1. 更新系统包
sudo yum update -y
# 2. 添加 Nginx 官方稳定源
sudo tee /etc/yum.repos.d/nginx.repo <<-'EOF'
[nginx-stable]
name=nginx stable repo
baseurl=https://nginx.org/packages/centos/7/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
EOF
# 3. 安装 
Nginxsudo yum install -y nginx

# 4. 验证安装
nginx -v

3. Ubuntu / Debian

# 1. 更新系统包
sudo apt update && sudo apt upgrade -y
# 2. 安装
 Nginxsudo apt install -y nginx

# 3. 验证安装
nginx -v

四、生成自签名证书（仅 IP、无域名）

无域名时无法使用 Let's Encrypt，需自签名证书。将 YOUR_SERVER_IP 换成实际 IP（如 x.x.x.x）：

sudo mkdir -p /etc/nginx/ssl
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/nginx/ssl/openclaw.key \
  -out /etc/nginx/ssl/openclaw.crt \
  -subj "/CN=OpenClaw" \
  -addext "subjectAltName=IP:YOUR_SERVER_IP"

注意：若使用公网 IP，请填公网 IP；若仅内网访问，填内网 IP。浏览器访问会提示"连接不是私密连接"，需手动接受或继续访问方可使用。

五、Nginx 反向代理配置

5.1 创建站点配置

找到Nginx配置目录，我的系统是 Alibaba Cloud Linux 3，Nginx 配置目录是

/etc/nginx/conf.d/

创建配置文件

vim /etc/nginx/conf.d/openclaw.conf

写入以下内容（将 YOUR_SERVER_IP 替换为实际 IP）：

# OpenClaw 反向代理（仅 IP、无域名，HTTPS + WSS）
# 上游：OpenClaw 网关默认端口 18789，仅监听本机
upstream openclaw_backend {
    server 127.0.0.1:18789;
    keepalive 64;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    # 无域名时用 IP 或 default_server
    server_name YOUR_SERVER_IP;

    ssl_certificate     /etc/nginx/ssl/openclaw.crt;
    ssl_certificate_key /etc/nginx/ssl/openclaw.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    # 日志（可选）
    access_log /var/log/nginx/openclaw_access.log;
    error_log  /var/log/nginx/openclaw_error.log;

    location / {
        proxy_pass http://openclaw_backend;
        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 86400s;
        proxy_send_timeout 86400s;
    }
}

要点：

• Upgrade 与 Connection "upgrade" 用于 WebSocket 升级，否则 Control UI 与 wss 无法正常工作。

• proxy_read_timeout / proxy_send_timeout 拉长，避免长连接被 Nginx 断开。

5.2 启用站点并检查配置

nginx -t   # 测试配置是否正确
systemctl restart nginx  # 重启生效

六、防火墙与安全组

• 放行 443（HTTPS）。

• 若希望 HTTP 自动跳转 HTTPS，可加 80 并做 redirect（见下节）。

• 不要对公网开放 18789，网关仅对本机监听。

七、访问方式

7.1 浏览器访问 Control UI

• 地址：https://YOUR_SERVER_IP（例如 https://x.x.x.x）。

• 首次会提示证书不受信任，选择"高级" → "继续前往"即可（自签名证书正常现象）。

• 密码认证：

  • 若使用 token 模式：https://YOUR_SERVER_IP/#token=你的访问令牌

八、故障排查

8.1 反代后首次访问的典型问题与处理顺序

通过 Nginx 反代首次用浏览器访问 https://YOUR_SERVER_IP/#token=... 时，常会依次遇到下面三类情况，按顺序处理即可。

1）提示 "origin not allowed"

• 原因：浏览器请求的 Origin 为 https://YOUR_SERVER_IP（经 Nginx 访问时的来源），未在网关白名单中。

• 处理：在 ~/.openclaw/openclaw.json 的 gateway.controlUi.allowedOrigins 中增加一项 https://YOUR_SERVER_IP（将 YOUR_SERVER_IP 换成实际 IP，无需写 :443）。保存后重启网关。

2）日志出现 "Proxy headers detected from untrusted address"

• 原因：网关收到了 Nginx 转发的 X-Forwarded-For 等代理头，但未把 Nginx 所在地址视为可信代理。

• 处理：在 gateway 中增加 "trustedProxies": ["127.0.0.1"]（Nginx 与网关同机时）。保存后重启网关。此步为可选，仅用于消除警告并改善"经代理的本地连接"识别。

3）连接失败：pairing required / not-paired（WebSocket code 1008）

• 原因：经反代访问时，浏览器设备会被视为"远程设备"，需在网关上完成一次设备配对后才能建立 WebSocket。与 Nginx 配置无关。

• 处理：在运行网关的服务器上执行：

openclaw devices list          # 查看 Pending 列表中的 Request ID
openclaw devices approve <Request ID>   # 批准该设备，例如 approve <Request ID>

• 批准后，刷新浏览器并再次访问 https://YOUR_SERVER_IP/#token=你的令牌，Control UI 应能正常连接。地址栏从 / 跳转到 /chat?session=main 是前端路由行为，属正常。

8.2 常见现象速查表

现象	可能原因	处理
502 Bad Gateway	网关未运行或 Nginx 连不上 18789	在服务器上执行 curl -I http://127.0.0.1:18789/，应为 200/3xx；执行 openclaw gateway start 或重启 systemd 服务。
origin not allowed	未把 https://YOUR_SERVER_IP 加入 allowedOrigins	在 gateway.controlUi.allowedOrigins 中增加 https://YOUR_SERVER_IP，重启网关。
Proxy headers from untrusted address（日志）	未配置可信代理	可选：在 gateway 中增加 "trustedProxies": ["127.0.0.1"]，重启网关。
pairing required / not-paired（1008）	浏览器设备尚未在网关上配对	在服务器执行 openclaw devices list，再 openclaw devices approve <Request ID>。
能打开页面但"与网关断开"	WebSocket 未正确代理或 Origin 未放行	确认 Nginx 配置中有 proxy_http_version 1.1、Upgrade、Connection "upgrade"；确认 gateway.controlUi.allowedOrigins 包含 https://YOUR_SERVER_IP。
认证失败	密码/ token 错误或未传	确认 openclaw.json 中 auth.mode 与 auth.password/auth.token 一致；URL 用 ?token= 或 ?password=（视版本而定），不要用 #。
SECURITY ERROR (ws 明文)	直接访问了 ws:// 或 http://IP:18789	必须通过 Nginx 的 https:// / wss:// 访问，不要直连 18789。

九、参考链接

• OpenClaw 远程访问 (SSH / Tailscale / WSS)

• OpenClaw 网关认证

• OpenClaw 配置示例