一、前提與約束

• 無域名：僅通過 https://<服務器IP> 訪問，需使用自簽名證書（瀏覽器會提示不安全，需手動信任或繼續(xù)訪問）。
• OpenClaw 要求：遠程訪問必須使用 wss://，不能使用明文 ws://；網(wǎng)關需保持 bind: "loopback"，僅由 Nginx 代理訪問。
• 認證：在 OpenClaw 網(wǎng)關側(cè)啟用 token認證（也可選用 password，見后文）。

二、OpenClaw 網(wǎng)關配置（密碼認證）

在配置 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 替換為服務器公網(wǎng) IP（例如 x.x.x.x）。若通過 https://IP:443 訪問，Origin 一般為 https://YOUR_SERVER_IP，無需寫端口。
• trustedProxies 為可選。當 Nginx 與網(wǎng)關同機部署時，填 ["127.0.0.1"] 可讓網(wǎng)關信任來自本機（Nginx）的代理頭，消除日志中的 "Proxy headers detected from untrusted address" 警告。
• auth.mode: "password" 表示使用密碼認證；客戶端需在請求中攜帶 Authorization: Bearer <密碼> 或通過 URL 參數(shù)傳遞（見下文訪問方式）。

2.2 重啟網(wǎng)關

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

三、安裝 Nginx

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

# 1. 更新系統(tǒng)包
sudo dnf update -y# 
2. 添加 Nginx 官方穩(wěn)定源
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. 更新系統(tǒng)包
sudo yum update -y
# 2. 添加 Nginx 官方穩(wěn)定源
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. 更新系統(tǒng)包
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"

注意：若使用公網(wǎng) IP，請?zhí)罟W(wǎng) IP；若僅內(nèi)網(wǎng)訪問，填內(nèi)網(wǎng) IP。瀏覽器訪問會提示"連接不是私密連接"，需手動接受或繼續(xù)訪問方可使用。

五、Nginx 反向代理配置

5.1 創(chuàng)建站點配置

找到Nginx配置目錄，我的系統(tǒng)是 Alibaba Cloud Linux 3，Nginx 配置目錄是

/etc/nginx/conf.d/

創(chuàng)建配置文件

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

寫入以下內(nèi)容（將 YOUR_SERVER_IP 替換為實際 IP）：

# OpenClaw 反向代理（僅 IP、無域名，HTTPS + WSS）
# 上游：OpenClaw 網(wǎng)關默認端口 18789，僅監(jiān)聽本機
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 自動跳轉(zhuǎn) HTTPS，可加 80 并做 redirect（見下節(jié)）。
• 不要對公網(wǎng)開放 18789，網(wǎng)關僅對本機監(jiān)聽。

七、訪問方式

7.1 瀏覽器訪問 Control UI

• 地址：https://YOUR_SERVER_IP（例如 https://x.x.x.x）。
• 首次會提示證書不受信任，選擇"高級" → "繼續(xù)前往"即可（自簽名證書正?，F(xiàn)象）。

密碼認證：

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

八、故障排查

8.1 反代后首次訪問的典型問題與處理順序

通過 Nginx 反代首次用瀏覽器訪問 https://YOUR_SERVER_IP/#token=... 時，常會依次遇到下面三類情況，按順序處理即可。

1）提示 "origin not allowed"

• 原因：瀏覽器請求的 Origin 為 https://YOUR_SERVER_IP（經(jīng) Nginx 訪問時的來源），未在網(wǎng)關白名單中。
• 處理：在 ~/.openclaw/openclaw.json 的 gateway.controlUi.allowedOrigins 中增加一項 https://YOUR_SERVER_IP（將 YOUR_SERVER_IP 換成實際 IP，無需寫 :443）。保存后重啟網(wǎng)關。

2）日志出現(xiàn) "Proxy headers detected from untrusted address"

• 原因：網(wǎng)關收到了 Nginx 轉(zhuǎn)發(fā)的 X-Forwarded-For 等代理頭，但未把 Nginx 所在地址視為可信代理。
• 處理：在 gateway 中增加 "trustedProxies": ["127.0.0.1"]（Nginx 與網(wǎng)關同機時）。保存后重啟網(wǎng)關。此步為可選，僅用于消除警告并改善"經(jīng)代理的本地連接"識別。

3）連接失敗：pairing required / not-paired（WebSocket code 1008）

• 原因：經(jīng)反代訪問時，瀏覽器設備會被視為"遠程設備"，需在網(wǎng)關上完成一次設備配對后才能建立 WebSocket。與 Nginx 配置無關。
• 處理：在運行網(wǎng)關的服務器上執(zhí)行：

openclaw devices list          # 查看 Pending 列表中的 Request ID
openclaw devices approve <Request ID>   # 批準該設備，例如 approve <Request ID>

• 批準后，刷新瀏覽器并再次訪問 https://YOUR_SERVER_IP/#token=你的令牌，Control UI 應能正常連接。地址欄從 / 跳轉(zhuǎn)到 /chat?session=main 是前端路由行為，屬正常。

8.2 常見現(xiàn)象速查表

九、參考鏈接

• OpenClaw 遠程訪問 (SSH / Tailscale / WSS)
• OpenClaw 網(wǎng)關認證
• OpenClaw 配置示例

到此這篇關于使用Nginx為OpenClaw反向代理的實現(xiàn)的文章就介紹到這了,更多相關Nginx OpenClaw反向代理內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！

最新評論