受信任的代理驗證

​

使用時機

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

​

不應使用的時機

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

​

運作方式

​

設定

{
  gateway: {
    // Trusted-proxy auth expects the proxy's source IP to be non-loopback 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: ["nick@example.com", "admin@company.org"],

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

​

設定參考

​

Control UI 配對行為

• 無裝置的 Control UI WebSocket 工作階段可以連線，但預設不會收到任何操作員範圍。OpenClaw 會將要求的範圍清單清空為 []，因此未繫結到已核准配對裝置／權杖的工作階段無法自行宣告權限。
• 如果 WebSocket 成功連線後方法因 missing scope 失敗，請使用 HTTPS，讓瀏覽器可以產生裝置身分並完成配對。請參閱 Control UI 不安全 HTTP。
• 只限緊急破窗：gateway.controlUi.dangerouslyDisableDeviceAuth=true 會在沒有裝置身分時仍保留要求的範圍。這是嚴重的安全性降級；請快速還原。請參閱 Control UI 不安全 HTTP。

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

​

操作員範圍標頭

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

• 當標頭存在時，OpenClaw 會採用宣告的範圍集合。
• 當標頭存在但為空時，請求會宣告沒有操作員範圍。
• 當標頭不存在時，標準承載身分的 HTTP API 會 fallback 到標準操作員預設範圍集合（operator.admin、operator.read、operator.write、operator.approvals、operator.pairing、operator.talk.secrets）。
• 閘道驗證的外掛 HTTP 路由預設更窄：當 x-openclaw-scopes 不存在時，其執行階段範圍只會 fallback 到 operator.write。
• 即使 trusted-proxy 驗證成功，瀏覽器來源的 HTTP 請求仍必須通過 gateway.controlUi.allowedOrigins（或刻意使用的 Host 標頭 fallback 模式）。

​

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: nick@example.com
    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",
      },
    },
  },
}

​

混合權杖設定

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

​

安全檢查清單

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

​

安全稽核

• 基本 gateway.trusted_proxy_auth 警告／嚴重提醒。
• 缺少 trustedProxies 設定。
• 缺少 userHeader 設定。
• 空的 allowUsers（允許任何已驗證使用者）。
• 為同主機代理來源啟用了 allowLoopback。

​

疑難排解

​

從權杖驗證遷移

​

相關

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