OpenClaw 安全稽核：反向代理、Trusted Proxies 與 Gateway 安全強化 [2026]

如果你執行 openclaw security audit 後看到 「reverse proxy headers are not trusted」 警告以及錯誤代碼 gateway.trusted_proxies_missing，這是 OpenClaw 部署中最常見、也最重要的安全發現之一。本指南會詳細說明這個警告的意義、為什麼不能忽略它，以及如何在各大反向代理上修復它。

安全稽核告訴你什麼

執行 openclaw security audit 會對你的 gateway 設定進行一系列檢查。當 OpenClaw 偵測到它收到了轉發標頭（例如 X-Forwarded-For），但沒有設定 gateway.trustedProxies 清單時，就會產生以下輸出：

WARN  gateway.trusted_proxies_missing
      Reverse proxy headers are not trusted.
      Configure gateway.trustedProxies in openclaw.json

這表示 OpenClaw 位於反向代理後方，但無法驗證哪些轉發標頭是可信的。每個請求到達時的來源 IP 都是 127.0.0.1（代理伺服器），OpenClaw 無法判斷真正的客戶端 IP。

為什麼這很重要：IP 偽造與標頭注入

X-Forwarded-For 標頭是反向代理將原始客戶端 IP 傳遞給後端服務的方式。問題在於這個標頭可以被任何人設定——包括攻擊者。如果沒有 trusted proxies 設定，會發生兩個問題：

1. 客戶端 IP 偽造。 攻擊者可以發送帶有偽造 X-Forwarded-For: 192.168.1.1 標頭的請求。如果 OpenClaw 盲目信任該標頭，就會記錄錯誤的 IP、套用錯誤的存取控制，而且每個客戶端的速率限制也會失效。[^1]

2. 存取控制繞過。 OpenClaw 使用客戶端 IP 來區分本地連線和遠端連線。本地連線擁有更高的權限（例如裝置配對和管理操作）。如果代理 IP 不在信任清單中，OpenClaw 會將所有連線視為本地連線（因為它們都來自 127.0.0.1），或者完全拒絕信任轉發標頭——兩種結果都會破壞安全性。

gateway.trustedProxies 設定告訴 OpenClaw：「只從這些特定 IP 接受並信任 X-Forwarded-For 標頭。」其他來源的標頭都會被丟棄。

修復方式：設定 gateway.trustedProxies

無論你使用哪種反向代理，核心修復方式都一樣：

openclaw config set gateway.trustedProxies '["127.0.0.1"]'
openclaw restart

這告訴 gateway 只在請求來自 127.0.0.1（你的本地反向代理）時才信任轉發標頭。如果你的代理在另一台機器上，請改用該機器的 IP。

你也可以直接編輯 openclaw.json：

{
  "gateway": {
    "mode": "local",
    "trustedProxies": ["127.0.0.1"]
  }
}

修改後，重新啟動 gateway 並再次執行稽核：

openclaw restart
openclaw security audit

你應該會看到：

OK  gateway.trusted_proxies — reverse proxy headers are trusted

各伺服器的反向代理設定

OpenClaw 端只是修復的一半。你的反向代理也必須設定正確的轉發標頭。

Caddy

Caddy 會自動處理轉發標頭。只需要一個最簡單的 Caddyfile：[^2]

openclaw.yourdomain.com {
    reverse_proxy localhost:3001
}

Caddy 預設就會設定 X-Forwarded-For、X-Forwarded-Proto 和 X-Forwarded-Host。不需要額外的標頭設定。

修改後重新載入：

caddy reload --adapter caddyfile --config /etc/caddy/Caddyfile

Nginx

Nginx 需要明確的標頭指令。沒有這些指令，OpenClaw 完全收不到轉發資訊：[^3]

server {
    listen 443 ssl;
    server_name openclaw.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        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_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

關鍵的一行是 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for。這會將真實客戶端 IP 附加到現有的 X-Forwarded-For 鏈中，而不是取代它——這在多重代理的環境中很重要。

編輯後，測試並重新載入：

nginx -t && systemctl reload nginx

Apache

對於使用 mod_proxy 的 Apache，啟用 mod_headers 並設定轉發：

<VirtualHost *:443>
    ServerName openclaw.yourdomain.com

    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:3001/
    ProxyPassReverse / http://127.0.0.1:3001/

    RequestHeader set X-Forwarded-Proto "https"
    RequestHeader set X-Forwarded-For "%{REMOTE_ADDR}e"

    # WebSocket support
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteRule /(.*) ws://127.0.0.1:3001/$1 [P,L]
</VirtualHost>

啟用必要的模組：

a2enmod proxy proxy_http proxy_wstunnel headers rewrite
systemctl restart apache2

了解完整的安全稽核輸出

trusted_proxies_missing 檢查只是安全稽核評估的其中一項。完整的 openclaw security audit 涵蓋：

OK   gateway.token_set — gateway token is configured
WARN gateway.trusted_proxies_missing — reverse proxy headers are not trusted
OK   gateway.port_restricted — gateway port is not publicly exposed
OK   security.device_pairing — device pairing is enabled
OK   security.webhook_auth — webhook endpoints require authentication

--deep 參數會執行額外的檢查：

openclaw security audit --deep

這會增加開放連接埠、已啟用的瀏覽器控制工具、檔案權限暴露和 skill sandbox 完整性等檢查項目。

多層代理跳轉

如果流量經過多個代理（例如 Cloudflare → Nginx → OpenClaw），你需要信任每一個跳轉點：

openclaw config set gateway.trustedProxies '["127.0.0.1", "172.17.0.1"]'

列出每個會設定轉發標頭的代理 IP。OpenClaw 會從右到左遍歷 X-Forwarded-For 鏈，逐一剝離信任的 IP，直到找到第一個不受信任的 IP——那就是真正的客戶端 IP。

不要使用 ["0.0.0.0/0"] 或萬用字元 CIDR。信任所有 IP 會完全抵消這個設定的作用，讓你暴露在稽核警告所提醒的相同偽造攻擊風險中。

驗證修復結果

設定好兩端後，進行端對端驗證：

# 1. 重新執行安全稽核
openclaw security audit

# 2. 檢查 gateway 日誌中的真實客戶端 IP
openclaw logs --follow

# 3. 執行 doctor 進行整體健康檢查
openclaw doctor

如果稽核現在對 gateway.trusted_proxies 回報 OK，表示你的轉發標頭已正確驗證。

完全跳過設定

ClawTank 會為每個實例自動處理反向代理設定、TLS 憑證和 trusted proxy 設定。安全稽核開箱即通過——不需要手動進行 gateway 安全強化。

[^1]: OWASP Web Security Testing Guide — covers X-Forwarded-For header abuse and IP-based access control testing. [^2]: Caddy reverse_proxy directive documentation — details automatic header handling and upstream configuration. [^3]: Nginx ngx_http_proxy_module documentation — reference for proxy_set_header and forwarded header configuration.