信頼済みプロキシ認証

使用する場合

次の場合は trusted-proxy 認証モードを使用します。

• OpenClaw を ID 認識プロキシ（Pomerium、Caddy + OAuth、nginx + oauth2-proxy、Traefik + forward auth）の背後で実行している。
• プロキシがすべての認証を処理し、ヘッダー経由でユーザー ID を渡す。
• Kubernetes またはコンテナ環境で、プロキシが Gateway への唯一の経路である。
• ブラウザーが WS ペイロードでトークンを渡せないため、WebSocket 1008 unauthorized エラーが発生している。

使用しない場合

• プロキシがユーザーを認証しない場合（単なる TLS ターミネーターやロードバランサー）。
• プロキシを迂回して Gateway に到達できる経路がある場合（ファイアウォールの穴、内部ネットワークアクセス）。
• プロキシが転送ヘッダーを正しく削除または上書きしているか不明な場合。
• 個人の単一ユーザーアクセスだけが必要な場合（より簡単な設定として Tailscale Serve + ループバックを検討してください）。

仕組み

Control UI のペアリング動作

gateway.auth.mode = "trusted-proxy" が有効で、リクエストが trusted-proxy チェックに合格した場合、Control UI WebSocket セッションはデバイスペアリング ID なしで接続できます。

スコープへの影響:

• デバイスなしの Control UI WebSocket セッションは接続できますが、デフォルトではオペレータースコープを受け取りません。OpenClaw は要求されたスコープリストを [] にクリアするため、承認済みのペアリング済みデバイスやトークンに紐づいていないセッションが権限を自己宣言することはできません。
• WebSocket 接続に成功した後にメソッドが missing scope で失敗する場合は、ブラウザーがデバイス ID を生成してペアリングを完了できるように HTTPS を使用してください。Control UI の安全でない HTTP を参照してください。
• 緊急時のみ: gateway.controlUi.dangerouslyDisableDeviceAuth=true は、デバイス ID がなくても要求されたスコープを保持します。これは深刻なセキュリティ低下です。速やかに元に戻してください。Control UI の安全でない HTTP を参照してください。

リバースプロキシによるスコープ制限:

• プロキシが Control UI WebSocket アップグレードリクエストで x-openclaw-scopes を送信する場合、OpenClaw はセッションスコープを、要求されたスコープと宣言されたスコープの共通部分に制限します。このヘッダーはスコープを付与しません。セッションが保持できる範囲を狭めるだけです。

影響:

• このモードでは、ペアリングは Control UI アクセスの主要なゲートではなくなります。
• リバースプロキシの認証ポリシーと allowUsers が実効的なアクセス制御になります。
• Gateway への入口は信頼済みプロキシ IP のみにロックしてください（gateway.trustedProxies + ファイアウォール）。

カスタム WebSocket クライアントは Control UI セッションではありません。gateway.controlUi.dangerouslyDisableDeviceAuth は、任意の client.mode: "backend" や CLI 形式のクライアントにスコープを付与しません。カスタム自動化では、デバイス ID/ペアリング、予約済みの直接ローカル client.id: "gateway-client" バックエンドヘルパーパス、または HTTP リクエスト/レスポンスのサーフェスがより適している場合は admin HTTP RPC Plugin を使用してください。

設定

{  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: ["nick@example.com", "admin@company.org"],         // Optional: allow a same-host loopback proxy after explicit opt-in        allowLoopback: false,      },    },  },}

設定リファレンス

TLS 終端と HSTS

TLS 終端点は 1 つにし、そこで 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 を追加します。
• ドメインセット全体について preload 要件を意図的に満たしている場合にのみ、preload を使用します。
• ループバックのみのローカル開発では、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",      },    },  },}

混在トークン設定

OpenClaw は、gateway.auth.token（または OPENCLAW_GATEWAY_TOKEN）と trusted-proxy モードの両方が同時に有効な曖昧な設定を拒否します。混在トークン設定では、ループバックリクエストが誤った認証パスで暗黙的に認証される可能性があります。

起動時に mixed_trusted_proxy_token エラーが表示された場合:

• trusted-proxy モードを使用する場合は共有トークンを削除する、または
• トークンベース認証を意図している場合は gateway.auth.mode を "token" に切り替えます。

Loopback の信頼済みプロキシ identity ヘッダーは引き続き fail closed します。同一ホストの呼び出し元が、プロキシユーザーとして暗黙に認証されることはありません。プロキシをバイパスする内部 OpenClaw 呼び出し元は、代わりに gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD で認証できます。信頼済みプロキシモードでは、トークンフォールバックは意図的にサポートされていません。

オペレータースコープヘッダー

信頼済みプロキシ認証は identity を伴う HTTP モードのため、呼び出し元は HTTP API リクエストで x-openclaw-scopes を使って、オペレータースコープを任意で宣言できます。

注: WebSocket スコープは、Gateway プロトコルのハンドシェイクとデバイス identity バインディングによって決まります。Control UI の WebSocket アップグレードリクエストでは、x-openclaw-scopes はネゴシエートされたセッションスコープの上限にすぎず、付与ではありません。信頼済みプロキシでの WebSocket スコープの挙動については、Control UI ペアリングの挙動を参照してください。

例:

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

挙動:

• ヘッダーが存在する場合、OpenClaw は宣言されたスコープセットを尊重します。
• ヘッダーが存在するが空の場合、リクエストはオペレータースコープが ない ことを宣言します。
• ヘッダーがない場合、通常の identity を伴う HTTP API は標準のオペレーター既定スコープセットにフォールバックします。
• Gateway 認証のプラグイン HTTP ルートは、既定でより狭くなります。x-openclaw-scopes がない場合、それらのランタイムスコープは operator.write にフォールバックします。
• ブラウザー由来の HTTP リクエストは、信頼済みプロキシ認証が成功した後でも、gateway.controlUi.allowedOrigins（または意図的な Host ヘッダーフォールバックモード）を通過する必要があります。
• Control UI WebSocket セッションでは、アップグレードリクエストに x-openclaw-scopes が存在する場合、それはスコープの上限です。空の値はスコープなしになります。

実用上のルール: 信頼済みプロキシリクエストを既定より狭くしたい場合、または Gateway 認証プラグインルートが write スコープより強いものを必要とする場合は、x-openclaw-scopes を明示的に送信してください。

セキュリティチェックリスト

信頼済みプロキシ認証を有効にする前に、次を確認してください。

• [ ] プロキシが唯一の経路: Gateway ポートは、プロキシ以外のすべてからファイアウォールで遮断されています。
• [ ] trustedProxies は最小限: サブネット全体ではなく、実際のプロキシ IP のみです。
• [ ] Loopback プロキシ送信元が意図的: 同一ホストプロキシ用に gateway.auth.trustedProxy.allowLoopback が明示的に有効化されていない限り、loopback 送信元リクエストに対する信頼済みプロキシ認証は fail closed します。
• [ ] プロキシがヘッダーを除去する: プロキシはクライアントからの x-forwarded-* ヘッダーを追記ではなく上書きします。
• [ ] TLS 終端: プロキシが TLS を処理し、ユーザーは HTTPS 経由で接続します。
• [ ] allowedOrigins が明示的: 非 loopback の Control UI は明示的な gateway.controlUi.allowedOrigins を使います。
• [ ] allowUsers が設定されている（推奨）: 認証された誰でも許可するのではなく、既知のユーザーに制限します。
• [ ] トークン設定が混在していない: gateway.auth.token と gateway.auth.mode: "trusted-proxy" の両方を設定しないでください。
• [ ] ローカルパスワードフォールバックがプライベート: 内部の直接呼び出し元向けに gateway.auth.password を設定する場合は、プロキシではないリモートクライアントが Gateway ポートへ直接到達できないよう、ファイアウォールで遮断してください。

セキュリティ監査

openclaw security audit は、信頼済みプロキシ認証を critical 重大度の検出としてフラグします。これは意図的なもので、セキュリティをプロキシ設定に委任していることを思い出させるためです。

監査では次を確認します。

• 基本の gateway.trusted_proxy_auth 警告/critical リマインダー
• trustedProxies 設定の欠落
• userHeader 設定の欠落
• 空の allowUsers（認証済みユーザーなら誰でも許可）
• 同一ホストプロキシ送信元向けに有効化された allowLoopback
• 公開された Control UI サーフェスでのワイルドカードまたは欠落したブラウザー origin ポリシー

トラブルシューティング

トークン認証からの移行

トークン認証から信頼済みプロキシへ移行する場合:

関連

• 設定 — 設定リファレンス
• リモートアクセス — その他のリモートアクセスパターン
• セキュリティ — 完全なセキュリティガイド
• Tailscale — tailnet 専用アクセス向けのより簡単な代替手段