一、前提與約束

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

二、OpenClaw 網(wǎng)關(guān)配置（密碼認(rèn)證）

在配置 Nginx 之前，先讓 OpenClaw 使用密碼認(rèn)證，并允許來(lái)自 Nginx 的 Origin（即 https://<你的IP>）。

2.1 編輯~/.openclaw/openclaw.json

在 gateway 段中設(shè)置：

"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": "你的訪問(wèn)令牌"
  },
  "trustedProxies": ["127.0.0.1"]
}

說(shuō)明：

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

2.2 重啟網(wǎng)關(guān)

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. 驗(yàn)證安裝
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. 驗(yàn)證安裝
nginx -v

3. Ubuntu / Debian

# 1. 更新系統(tǒng)包
sudo apt update && sudo apt upgrade -y
# 2. 安裝
 Nginxsudo apt install -y nginx
# 3. 驗(yàn)證安裝
nginx -v

四、生成自簽名證書（僅 IP、無(wú)域名）

無(wú)域名時(shí)無(wú)法使用 Let's Encrypt，需自簽名證書。將 YOUR_SERVER_IP 換成實(shí)際 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，請(qǐng)?zhí)罟W(wǎng) IP；若僅內(nèi)網(wǎng)訪問(wèn)，填內(nèi)網(wǎng) IP。瀏覽器訪問(wèn)會(huì)提示"連接不是私密連接"，需手動(dòng)接受或繼續(xù)訪問(wèn)方可使用。

五、Nginx 反向代理配置

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

找到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 替換為實(shí)際 IP）：

# OpenClaw 反向代理（僅 IP、無(wú)域名，HTTPS + WSS）
# 上游：OpenClaw 網(wǎng)關(guān)默認(rèn)端口 18789，僅監(jiān)聽本機(jī)
upstream openclaw_backend {
    server 127.0.0.1:18789;
    keepalive 64;
}
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    # 無(wú)域名時(shí)用 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;
    }
}

要點(diǎn)：

• Upgrade 與 Connection "upgrade" 用于 WebSocket 升級(jí)，否則 Control UI 與 wss 無(wú)法正常工作。
• proxy_read_timeout / proxy_send_timeout 拉長(zhǎng)，避免長(zhǎng)連接被 Nginx 斷開。

5.2 啟用站點(diǎn)并檢查配置

nginx -t   # 測(cè)試配置是否正確
systemctl restart nginx  # 重啟生效

六、防火墻與安全組

• 放行 443（HTTPS）。
• 若希望 HTTP 自動(dòng)跳轉(zhuǎn) HTTPS，可加 80 并做 redirect（見下節(jié)）。
• 不要對(duì)公網(wǎng)開放 18789，網(wǎng)關(guān)僅對(duì)本機(jī)監(jiān)聽。

七、訪問(wèn)方式

7.1 瀏覽器訪問(wèn) Control UI

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

密碼認(rèn)證：

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

八、故障排查

8.1 反代后首次訪問(wèn)的典型問(wèn)題與處理順序

通過(guò) Nginx 反代首次用瀏覽器訪問(wèn) https://YOUR_SERVER_IP/#token=... 時(shí)，常會(huì)依次遇到下面三類情況，按順序處理即可。

1）提示 "origin not allowed"

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

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

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

3）連接失?。簆airing required / not-paired（WebSocket code 1008）

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

openclaw devices list          # 查看 Pending 列表中的 Request ID
openclaw devices approve <Request ID>   # 批準(zhǔn)該設(shè)備，例如 approve <Request ID>

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

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

九、參考鏈接

• OpenClaw 遠(yuǎn)程訪問(wèn) (SSH / Tailscale / WSS)
• OpenClaw 網(wǎng)關(guān)認(rèn)證
• OpenClaw 配置示例

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

最新評(píng)論