受信任的代理伺服器驗證

使用時機

• 你在具備身分感知功能的代理（Pomerium、Caddy + OAuth、nginx + oauth2-proxy、Traefik + forward auth）後方執行 OpenClaw。
• 你的代理會處理所有驗證，並透過標頭傳遞使用者身分。
• 你位於 Kubernetes 或容器環境中，且代理是通往閘道的唯一路徑。
• 你遇到 WebSocket 1008 unauthorized 錯誤，因為瀏覽器無法在 WS 承載資料中傳遞權杖。

不應使用的時機

• 你的代理不會驗證使用者（僅作為 TLS 終結器或負載平衡器）。
• 存在任何可略過代理而存取閘道的路徑（防火牆漏洞、內部網路存取）。
• 你不確定代理是否會正確移除或覆寫轉送標頭。
• 你只需要個人單一使用者存取（請改用 Tailscale Serve + 回送位址）。

運作方式

設定

{  gateway: {    // 可信任代理驗證預設要求代理的來源 IP 不是回送位址    bind: "lan",     // 重要：此處僅加入你的代理 IP    trustedProxies: ["10.0.0.1", "172.17.0.1"],     auth: {      mode: "trusted-proxy",      trustedProxy: {        // 包含已驗證使用者身分的標頭（必要）        userHeader: "x-forwarded-user",         // 選用：必須存在的標頭（代理驗證）        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],         // 選用：限制為特定使用者（空白 = 允許所有使用者）        allowUsers: ["nick@example.com", "admin@company.org"],         // 選用：明確選擇啟用後，允許同一主機上的回送代理        allowLoopback: false,         // 選用：允許已透過代理驗證的使用者註冊新的瀏覽器裝置        deviceAutoApprove: {          enabled: false,          scopes: ["operator.read", "operator.write", "operator.approvals"],        },      },    },  },}

設定參考

自動裝置核准

可信任代理驗證可選擇使用代理身分作為新瀏覽器裝置的核准邊界：

{  gateway: {    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",        allowUsers: ["operator@example.com"],        deviceAutoApprove: {          enabled: true,          scopes: ["operator.read", "operator.write", "operator.approvals"],        },      },    },  },}

預設值為 enabled: false。啟用後，以下規則全數適用：

1. WebSocket 必須已透過 trusted-proxy 方法完成驗證，具有非空白的使用者身分，且在設定允許清單時已通過 allowUsers。權杖、密碼、Tailscale 及未驗證連線絕不會使用此原則。
2. 只有新的 Control UI 或 WebChat 瀏覽器裝置能獲得自動核准。針對既有裝置的任何要求（包括提升範圍）都會維持待處理狀態，等候使用 openclaw devices approve <requestId> 手動核准。
3. 裝置會以 operator 角色獲得核准。如果連線要求包含範圍，授權內容會是要求範圍與 deviceAutoApprove.scopes 的精確交集。如果要求省略範圍，則會授予已設定的清單；若省略該清單，預設為 operator.read、operator.write 和 operator.approvals。若連線中存在 x-openclaw-scopes 代理標頭，最終授權還會受其限制，因此縮減使用者範圍的代理也會限制持久性裝置授權，而不只是工作階段；存在但為空白的標頭不會產生任何範圍。即使用戶端省略自己的範圍清單，此限制仍會套用。
4. 只有明確列於 deviceAutoApprove.scopes 中時，才允許 operator.admin。列出後，每位透過代理驗證的使用者都能為新的瀏覽器裝置要求並自動獲得完整管理員權限；未指定範圍的要求會自動獲得完整管理員權限。openclaw security audit 會回報嚴重的 gateway.trusted_proxy_device_auto_approve_admin 發現，且閘道會在啟動時記錄一次警告。在個別身分角色可用之前，請優先使用 openclaw devices approve 或 openclaw devices rotate 手動核准管理員權限。

Control UI 配對行為

當 gateway.auth.mode = "trusted-proxy" 啟用且要求通過可信任代理檢查時，Control UI WebSocket 工作階段可在沒有裝置配對身分的情況下連線。

範圍影響：

• 沒有裝置的 Control UI WebSocket 工作階段可以連線，但預設不會獲得任何操作員範圍。OpenClaw 會將要求的範圍清單清除為 []，因此未繫結至已核准配對裝置／權杖的工作階段無法自行宣告權限。
• 如果 WebSocket 成功連線後，方法因 missing scope 而失敗，請使用 HTTPS，讓瀏覽器可以產生裝置身分並完成配對。請參閱 Control UI 不安全的 HTTP。
• 仍包含已淘汰 gateway.controlUi.dangerouslyDisableDeviceAuth=true 金鑰的舊版設定會使用受限的 Control UI 升級遷移。

反向代理範圍限制：如果你的代理在 Control UI WebSocket 升級要求中傳送 x-openclaw-scopes，OpenClaw 會將工作階段範圍限制為要求範圍與宣告範圍的交集。此標頭不會授予範圍，只會縮減工作階段可持有的範圍。當 deviceAutoApprove.enabled 為 true 時，相同限制也會套用至由自動裝置核准寫入的持久性裝置授權，因此自動核准的裝置絕不會持有超出代理所宣告的範圍。

影響：

• 配對不再是無裝置 Control UI 存取的主要閘門。當 deviceAutoApprove.enabled 為 true 時，代理身分也會成為新瀏覽器裝置註冊的核准閘門。
• 你的反向代理驗證原則和 allowUsers 會成為實際的存取控制。
• 請將閘道輸入流量限制為僅允許可信任的代理 IP（gateway.trustedProxies + 防火牆）。

自訂 WebSocket 用戶端並非 Control UI 工作階段。已淘汰的 Control UI 升級輸入不會向任意 client.mode: "backend" 或命令列介面形式的用戶端授予暫時存取權。自訂自動化應使用 裝置身分／配對、保留供本機直接使用的 client.id: "gateway-client" 後端輔助程式路徑，或在 HTTP 要求／回應介面更合適時使用管理員 HTTP RPC 外掛。

操作員範圍標頭

受信任代理驗證是一種帶有身分資訊的 HTTP 模式，因此呼叫端可選擇在 HTTP API 請求中使用 x-openclaw-scopes 宣告操作者範圍。

注意：WebSocket 範圍由閘道通訊協定交握與裝置身分繫結決定。在 Control UI WebSocket 升級請求中，x-openclaw-scopes 只會限制協商後的工作階段範圍，並不會授予範圍。請參閱 Control UI 配對行為。

範例：

• x-openclaw-scopes: operator.read
• x-openclaw-scopes: operator.read,operator.write
• x-openclaw-scopes: operator.admin,operator.write

行為：

• 標頭存在時，OpenClaw 會採用所宣告的範圍集合。
• 標頭存在但為空時，請求會宣告沒有操作者範圍。
• 標頭不存在時，一般帶有身分資訊的 HTTP API 會退回使用標準操作者預設範圍集合（operator.admin、operator.read、operator.write、operator.approvals、operator.pairing、operator.talk.secrets）。
• 閘道驗證的外掛 HTTP 路由預設範圍較窄：當 x-openclaw-scopes 不存在時，其執行階段範圍僅退回使用 operator.write。
• 即使受信任代理驗證成功，來自瀏覽器來源的 HTTP 請求仍必須通過 gateway.controlUi.allowedOrigins（或刻意啟用的 Host 標頭備援模式）。

實用規則：若要讓受信任代理請求的範圍比預設值更窄，或閘道驗證的外掛路由需要比寫入範圍更強的權限，請明確傳送 x-openclaw-scopes。

TLS 終止與 HSTS

使用單一 TLS 終止點，並在該處套用 HSTS。

Strict-Transport-Security: max-age=31536000; includeSubDomains

{  gateway: {    tls: { enabled: true },    http: {      securityHeaders: {        strictTransportSecurity: "max-age=31536000; includeSubDomains",      },    },  },}

推出指引

• 驗證流量時，先從較短的最大存留時間開始（例如 max-age=300）。
• 只有在充分確認後，才提高為長期值（例如 max-age=31536000）。
• 只有在每個子網域都已準備好使用 HTTPS 時，才新增 includeSubDomains。
• 只有在你刻意符合完整網域集合的預載要求時，才使用預載。
• 僅限迴路的本機開發無法從 HSTS 獲益。

代理設定範例

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // Pomerium 的 IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-pomerium-claim-email",        requiredHeaders: ["x-pomerium-jwt-assertion"],      },    },  },}

routes:  - from: https://openclaw.example.com    to: http://openclaw-gateway:18789    policy:      - allow:          or:            - email:                is: nick@example.com    pass_identity_headers: true

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // Caddy/附屬代理 IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

openclaw.example.com {    authenticate with oauth2_provider    authorize with policy1     reverse_proxy openclaw:18789 {        header_up X-Forwarded-User {http.auth.user.email}    }}

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // nginx/oauth2-proxy IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-auth-request-email",      },    },  },}

location / {    auth_request /oauth2/auth;    auth_request_set $user $upstream_http_x_auth_request_email;     proxy_pass http://openclaw:18789;    proxy_set_header X-Auth-Request-Email $user;    proxy_http_version 1.1;    proxy_set_header Upgrade $http_upgrade;    proxy_set_header Connection "upgrade";}

{  gateway: {    bind: "lan",    trustedProxies: ["172.17.0.1"], // Traefik 容器 IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

混合權杖設定

如果同時設定了共用權杖（gateway.auth.token 或 OPENCLAW_GATEWAY_TOKEN），閘道啟動時會拒絕受信任代理驗證。兩者互斥，因為共用權杖會讓同一主機上的呼叫端，透過與此模式原本要強制執行的代理驗證身分完全不同的路徑進行驗證。

如果啟動失敗，並顯示類似 gateway auth mode is trusted-proxy, but a shared token is also configured 的錯誤：

• 使用受信任代理模式時移除共用權杖，或
• 如果你想使用權杖式驗證，請將 gateway.auth.mode 切換為 "token"。

迴路受信任代理身分標頭仍會採取封閉式失敗：同一主機上的呼叫端不會被默默驗證為代理使用者。繞過代理的 OpenClaw 內部呼叫端可改用 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD 進行驗證。受信任代理模式刻意不支援權杖備援。

安全性檢查清單

啟用受信任代理驗證前，請確認：

• [ ] 代理是唯一路徑：閘道連接埠的防火牆只允許你的代理存取。
• [ ] trustedProxies 維持最小範圍：僅包含實際代理 IP，而非整個子網路。
• [ ] 迴路代理來源是刻意設定的：除非為同一主機代理明確啟用 gateway.auth.trustedProxy.allowLoopback，否則來自迴路來源的請求會使受信任代理驗證採取封閉式失敗。
• [ ] 代理會移除標頭：你的代理會覆寫（而非附加）來自用戶端的 x-forwarded-* 標頭。
• [ ] TLS 終止：你的代理處理 TLS；使用者透過 HTTPS 連線。
• [ ] 明確設定 allowedOrigins：非迴路的 Control UI 使用明確的 gateway.controlUi.allowedOrigins。
• [ ] 已設定 allowUsers（建議）：限制為已知使用者，而非允許任何通過驗證的人。
• [ ] 沒有混合權杖設定：不要同時設定 gateway.auth.token 與 gateway.auth.mode: "trusted-proxy"。
• [ ] 本機密碼備援保持私密：如果為內部直接呼叫端設定 gateway.auth.password，請以防火牆保護閘道連接埠，避免非代理遠端用戶端直接存取。
• [ ] 裝置自動核准是刻意啟用的：如果 deviceAutoApprove.enabled 為 true，請將反向代理帳號安全性視為裝置註冊邊界，並將授予的範圍清單維持為非管理員且最小化。

安全性稽核

openclaw security audit 會以重大嚴重性發現標記受信任代理驗證。這是刻意設計的；用來提醒你已將安全性委派給代理設定。

稽核會檢查：

• 基本 gateway.trusted_proxy_auth 警告／重大提醒。
• 缺少 trustedProxies 設定。
• 缺少 userHeader 設定。
• allowUsers 為空（允許任何通過驗證的使用者）。
• 為同一主機代理來源啟用了 allowLoopback。
• 啟用了瀏覽器裝置自動核准（將新裝置配對委派給代理身分）。

只要 Control UI 對外公開，其他不專屬於受信任代理的發現也同樣適用：萬用字元或缺少 gateway.controlUi.allowedOrigins，以及 Host 標頭來源備援。

疑難排解

從權杖驗證遷移

相關內容

• 設定 — 設定參考
• 操作員範圍 — 角色、範圍與核准檢查
• 遠端存取 — 其他遠端存取模式
• 安全性 — 完整的安全性指南
• Tailscale — 僅限 tailnet 存取的較簡單替代方案