OpenClaw Nginx 反向代理配置

2026年3月5日 · 阅读需 7 分钟

本文档说明在仅有 IP、无域名的场景下，使用 Nginx 反向代理 OpenClaw 网关，并通过 HTTPS/WSS 与 密码认证 安全访问。内容结合 OpenClaw 官方远程访问文档、认证说明以及本地安装文档整理。

一、前提与约束

无域名：仅通过 https://<服务器IP> 访问，需使用自签名证书（浏览器会提示不安全，需手动信任或继续访问）。
OpenClaw 要求：远程访问必须使用 wss://，不能使用明文 ws://；网关需保持 bind: "loopback"，仅由 Nginx 代理访问。
认证：在 OpenClaw 网关侧启用 password 认证（也可选用 token，见后文）。

二、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": "password",
    "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 参数传递（见下文访问方式）。
若希望用 Token 而非密码，可改为：
```
"auth": {
  "mode": "token",
  "token": "你的访问令牌"
}
```
访问时使用 ?token=你的访问令牌。

2.2 重启网关

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

三、安装 Nginx

以 Ubuntu/Debian 为例：

sudo apt update
sudo apt install -y nginx

确认 Nginx 已安装并可用：

sudo 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 创建站点配置

新建配置文件（例如只用于 OpenClaw 的 server 块）：

sudo nano /etc/nginx/sites-available/openclaw

写入以下内容（将 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 启用站点并检查配置

sudo ln -sf /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t

若无报错，重载 Nginx：

sudo systemctl reload nginx

六、防火墙与安全组

放行 443（HTTPS）。
若希望 HTTP 自动跳转 HTTPS，可加 80 并做 redirect（见下节）。
不要对公网开放 18789，网关仅对本机监听。

七、访问方式

7.1 浏览器访问 Control UI

地址：https://YOUR_SERVER_IP（例如 https://x.x.x.x）。
首次会提示证书不受信任，选择"高级" → "继续前往"即可（自签名证书正常现象）。
密码认证：
- 若 OpenClaw 使用 password 模式：在 Control UI 登录或连接时输入你配置的密码；或使用 URL 参数（若 UI 支持）：https://YOUR_SERVER_IP/?password=你的访问密码（具体以 OpenClaw 文档为准，有的版本用 ?token= 传密码）。
- 若使用 token 模式：https://YOUR_SERVER_IP/?token=你的访问令牌（不要用 #token=...，井号不会发给服务器）。

八、可选：HTTP 跳转 HTTPS

若希望 http://YOUR_SERVER_IP 自动跳转到 https://，可在 Nginx 中增加 80 端口的 server：

server {
    listen 80;
    listen [::]:80;
    server_name YOUR_SERVER_IP;
    return 301 https://$host$request_uri;
}

放在同一文件或单独配置中均可，然后 sudo nginx -t && sudo systemctl reload nginx。

九、故障排查

9.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 是前端路由行为，属正常。

9.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 配置示例
相关指南：OpenClaw 安装文档第六节「开启远程访问」、第十节「常见问题」

一、前提与约束​

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

2.1 编辑 ~/.openclaw/openclaw.json​

2.2 重启网关​

三、安装 Nginx​

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

五、Nginx 反向代理配置​

5.1 创建站点配置​

5.2 启用站点并检查配置​

六、防火墙与安全组​

七、访问方式​

7.1 浏览器访问 Control UI​

八、可选：HTTP 跳转 HTTPS​

九、故障排查​

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

9.2 常见现象速查表​

十、参考链接​

相关内容推荐