受信任的代理驗證

# 何時使用

在以下情況使用 trusted-proxy 驗證模式：

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

# 何時不要使用

• 如果你的代理不會驗證使用者（只是 TLS 終止器或負載平衡器）。
• 如果有任何路徑可繞過代理存取 Gateway（防火牆漏洞、內部網路存取）。
• 如果你不確定代理是否正確移除或覆寫轉送標頭。
• 如果你只需要個人單一使用者存取（可考慮使用 Tailscale Serve + loopback 以簡化設定）。

# 運作方式

# Control UI 配對行為

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

影響：

• 在此模式中，配對不再是 Control UI 存取的主要閘門。
• 你的反向代理驗證政策與 allowUsers 會成為實際的存取控制。
• 僅讓 Gateway 入口鎖定為受信任的代理 IP（gateway.trustedProxies + 防火牆）。

# 設定

{
  gateway: {
    // Trusted-proxy auth expects requests from a non-loopback trusted proxy source by default
    bind: "lan",

    // CRITICAL: Only add your proxy's IP(s) here
    trustedProxies: ["10.0.0.1", "172.17.0.1"],

    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        // Header containing authenticated user identity (required)
        userHeader: "x-forwarded-user",

        // Optional: headers that MUST be present (proxy verification)
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],

        // Optional: restrict to specific users (empty = allow all)
        allowUsers: ["[email protected]", "[email protected]"],

        // Optional: allow a same-host loopback proxy after explicit opt-in
        allowLoopback: false,
      },
    },
  },
}

# 設定參考

# TLS 終止與 HSTS

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

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

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

# 推出指引

• 驗證流量時，先從較短的 max age 開始（例如 max-age=300）。
• 只有在信心足夠高後，才提高到長效值（例如 max-age=31536000）。
• 只有在每個子網域都已準備好 HTTPS 時，才加入 includeSubDomains。
• 只有在你有意為完整網域集合滿足 preload 要求時，才使用 preload。
• 僅限 loopback 的本機開發不會受益於 HSTS。

# 代理設定範例

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // Pomerium's 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: [email protected]
    pass_identity_headers: true

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"], // Caddy/sidecar proxy 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 container IP
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

# 混合 token 設定

OpenClaw 會拒絕同時啟用 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）與 trusted-proxy 模式的模糊設定。混合 token 設定可能導致 loopback 請求在錯誤的驗證路徑上悄悄通過驗證。

如果你在啟動時看到 mixed_trusted_proxy_token 錯誤：

• 使用 trusted-proxy 模式時，移除共享 token，或
• 如果你打算使用 token 型驗證，將 gateway.auth.mode 切換為 "token"。

Loopback trusted-proxy 身分標頭仍會失敗關閉：same-host 呼叫者不會被悄悄驗證為代理使用者。繞過代理的內部 OpenClaw 呼叫者可以改用 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD 驗證。Token fallback 在 trusted-proxy 模式中仍刻意不支援。

# 操作者範圍標頭

Trusted-proxy 驗證是一種帶有身分的 HTTP 模式，因此呼叫者可以選擇使用 x-openclaw-scopes 宣告操作者範圍。

範例：

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

行為：

• 當標頭存在時，OpenClaw 會採用宣告的 scope 集合。
• 當標頭存在但為空時，請求宣告沒有操作者範圍。
• 當標頭不存在時，一般帶有身分的 HTTP API 會回退到標準操作者預設 scope 集合。
• Gateway 驗證的 Plugin HTTP 路由預設較窄：當 x-openclaw-scopes 不存在時，其執行階段 scope 會回退到 operator.write。
• 來自瀏覽器來源的 HTTP 請求，即使 trusted-proxy 驗證成功，仍必須通過 gateway.controlUi.allowedOrigins（或刻意使用 Host-header fallback 模式）。

實務規則：當你希望 trusted-proxy 請求比預設值更窄，或 gateway-auth Plugin 路由需要比 write scope 更強的權限時，請明確傳送 x-openclaw-scopes。

# 安全檢查清單

啟用 trusted-proxy 驗證前，請確認：

• [ ] Proxy 是唯一路徑：除了你的 Proxy 之外，Gateway 連接埠已對所有來源封鎖。
• [ ] trustedProxies 最小化：只包含你的實際 Proxy IP，而不是整個子網路。
• [ ] Loopback Proxy 來源是刻意設定：除非為同主機 Proxy 明確啟用 gateway.auth.trustedProxy.allowLoopback，否則 trusted-proxy 驗證會對 loopback 來源請求安全失敗。
• [ ] Proxy 會移除標頭：你的 Proxy 會覆寫（而不是附加）來自用戶端的 x-forwarded-* 標頭。
• [ ] TLS 終止：你的 Proxy 會處理 TLS；使用者透過 HTTPS 連線。
• [ ] allowedOrigins 是明確的：非 loopback 控制 UI 使用明確的 gateway.controlUi.allowedOrigins。
• [ ] allowUsers 已設定（建議）：限制為已知使用者，而不是允許任何已驗證的人。
• [ ] 沒有混用 Token 設定：不要同時設定 gateway.auth.token 和 gateway.auth.mode: "trusted-proxy"。
• [ ] 本機密碼備援保持私密：如果你為內部直接呼叫者設定 gateway.auth.password，請保持 Gateway 連接埠受防火牆保護，讓非 Proxy 的遠端用戶端無法直接連到它。

# 安全性稽核

openclaw security audit 會將 trusted-proxy 驗證標記為 critical 嚴重性發現。這是刻意設計的，提醒你正在把安全性委派給你的 Proxy 設定。

稽核會檢查：

• 基礎 gateway.trusted_proxy_auth 警告/critical 提醒
• 缺少 trustedProxies 設定
• 缺少 userHeader 設定
• 空的 allowUsers（允許任何已驗證使用者）
• 為同主機 Proxy 來源啟用的 allowLoopback
• 暴露的控制 UI 表面上有萬用字元或缺少瀏覽器來源政策

# 疑難排解

# 從 Token 驗證遷移

如果你要從 Token 驗證移轉到 trusted-proxy：

# 相關

• 設定 — 設定參考
• 遠端存取 — 其他遠端存取模式
• 安全性 — 完整安全性指南
• Tailscale — 對於僅限 tailnet 存取的更簡單替代方案