信頼済みプロキシ認証

使用する場合

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

使用しない場合

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

仕組み

設定

{  gateway: {    // 信頼できるプロキシによる認証では、デフォルトでプロキシの送信元 IP が loopback 以外であることが求められる    bind: "lan",     // 重要: ここにはプロキシの IP のみを追加する    trustedProxies: ["10.0.0.1", "172.17.0.1"],     auth: {      mode: "trusted-proxy",      trustedProxy: {        // 認証済みユーザー ID を含むヘッダー（必須）        userHeader: "x-forwarded-user",         // 任意: 必ず存在しなければならないヘッダー（プロキシ検証）        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],         // 任意: 特定のユーザーに制限する（空 = すべて許可）        allowUsers: ["nick@example.com", "admin@company.org"],         // 任意: 明示的にオプトインした場合、同一ホストの loopback プロキシを許可する        allowLoopback: false,         // 任意: 認証済みのプロキシユーザーが新しいブラウザーデバイスを登録できるようにする        deviceAutoApprove: {          enabled: false,          scopes: ["operator.read", "operator.write", "operator.approvals"],        },      },    },  },}

設定リファレンス

デバイスの自動承認

信頼できるプロキシによる認証では、必要に応じてプロキシ ID を新しいブラウザーデバイスの承認境界として使用できます。

{  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 は、空でないユーザー ID を使用して trusted-proxy メソッドによる認証を完了している必要があり、許可リストが設定されている場合は、その ID が allowUsers を満たしていなければなりません。トークン、パスワード、Tailscale、および未認証の接続には、このポリシーは適用されません。
2. 自動承認できるのは、新しい Control UI または WebChat のブラウザーデバイスだけです。スコープのアップグレードを含め、既存デバイスに対するリクエストはすべて、openclaw devices approve <requestId> による手動承認を待つ状態のままになります。
3. デバイスはロール operator で承認されます。接続リクエストにスコープが含まれる場合、付与されるスコープは、要求されたスコープと deviceAutoApprove.scopes の正確な共通部分です。リクエストでスコープが省略された場合は、設定されたリストが付与されます。そのリストも省略された場合、デフォルトで operator.read、operator.write、および operator.approvals になります。その後、接続に x-openclaw-scopes プロキシヘッダーが存在する場合、結果として得られる付与内容はさらにそのヘッダーによって制限されます。そのため、プロキシがユーザーのスコープを狭めると、セッションだけでなく 永続的な デバイス付与も制限されます。ヘッダーが存在していても空の場合、スコープは付与されません。この制限は、クライアント自身のスコープリストが省略された場合にも適用されます。
4. operator.admin は、deviceAutoApprove.scopes に明示的に指定した場合にのみ許可されます。指定すると、プロキシで認証されたすべてのユーザーが、新しいブラウザーデバイスで完全な管理者権限を要求し、自動的に取得できます。スコープのないリクエストには、完全な管理者権限が自動的に付与されます。openclaw security audit は CRITICAL の gateway.trusted_proxy_device_auto_approve_admin 検出事項を報告し、Gateway は起動時に一度警告を記録します。ID ごとのロールが利用可能になるまでは、openclaw devices approve または openclaw devices rotate を使用した管理者権限の手動承認を推奨します。

Control UI のペアリング動作

gateway.auth.mode = "trusted-proxy" が有効で、リクエストが信頼できるプロキシの確認に合格すると、Control UI の WebSocket セッションはデバイスペアリング ID なしで接続できます。

スコープへの影響:

• デバイスなしの Control UI WebSocket セッションは接続できますが、デフォルトではオペレータースコープを受け取りません。OpenClaw は要求されたスコープリストを [] にクリアするため、承認済みのペアリング済みデバイスまたはトークンに関連付けられていないセッションが権限を自己申告することはできません。
• WebSocket の接続に成功した後、メソッドが missing scope で失敗する場合は、ブラウザーがデバイス ID を生成してペアリングを完了できるように 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 の場合、プロキシ ID は新しいブラウザーデバイス登録の承認ゲートにもなります。
• リバースプロキシの認証ポリシーと allowUsers が、実質的なアクセス制御になります。
• Gateway の受信経路は、信頼できるプロキシ IP のみに制限してください（gateway.trustedProxies + ファイアウォール）。

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

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

Trusted-proxy 認証はアイデンティティを伴う HTTP モードであるため、呼び出し元は HTTP API リクエストで x-openclaw-scopes を使用してオペレータースコープを任意で宣言できます。

注: WebSocket スコープは、Gateway プロトコルのハンドシェイクとデバイスアイデンティティのバインディングによって決定されます。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）にフォールバックします。
• Gateway 認証を使用する Plugin HTTP ルートは、デフォルトではより制限されています。x-openclaw-scopes が存在しない場合、そのランタイムスコープは operator.write のみにフォールバックします。
• ブラウザーオリジンの HTTP リクエストは、trusted-proxy 認証に成功した後も、gateway.controlUi.allowedOrigins（または明示的に有効化した Host ヘッダーのフォールバックモード）を通過する必要があります。

実用上のルール: trusted-proxy リクエストをデフォルトより狭いスコープにする場合、または Gateway 認証を使用する Plugin ルートで書き込みスコープより強い権限が必要な場合は、x-openclaw-scopes を明示的に送信してください。

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 を使用します。
• ループバックのみを使用するローカル開発では、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 の起動時に trusted-proxy 認証は拒否されます。この 2 つは相互排他的です。共有トークンを使用すると、同じホスト上の呼び出し元が、このモードで強制することを意図したプロキシ検証済みアイデンティティとはまったく異なる経路で認証できてしまうためです。

gateway auth mode is trusted-proxy, but a shared token is also configured のようなエラーで起動に失敗する場合:

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

ループバックの trusted-proxy アイデンティティヘッダーもフェイルクローズになります。同じホスト上の呼び出し元が、暗黙的にプロキシユーザーとして認証されることはありません。プロキシを経由しない OpenClaw の内部呼び出し元は、代わりに gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD で認証できます。trusted-proxy モードでは、トークンへのフォールバックは意図的にサポートされていません。

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

trusted-proxy 認証を有効にする前に、以下を確認してください。

• [ ] プロキシが唯一の経路である: Gateway ポートへのアクセスを、使用するプロキシ以外のすべてからファイアウォールで遮断します。
• [ ] trustedProxies が最小限である: サブネット全体ではなく、実際に使用するプロキシの IP のみを指定します。
• [ ] ループバックのプロキシソースを意図的に使用している: 同じホスト上のプロキシ向けに gateway.auth.trustedProxy.allowLoopback を明示的に有効化しない限り、ループバックソースのリクエストに対する trusted-proxy 認証はフェイルクローズになります。
• [ ] プロキシがヘッダーを除去する: プロキシがクライアントからの x-forwarded-* ヘッダーを追記するのではなく、上書きするようにします。
• [ ] TLS 終端: プロキシが TLS を処理し、ユーザーが HTTPS 経由で接続するようにします。
• [ ] allowedOrigins が明示されている: local loopback 以外の Control UI では、gateway.controlUi.allowedOrigins を明示的に指定します。
• [ ] allowUsers が設定されている（推奨）: 認証されたすべてのユーザーを許可するのではなく、既知のユーザーに制限します。
• [ ] トークンを併用していない: gateway.auth.token と gateway.auth.mode: "trusted-proxy" の両方を設定しないでください。
• [ ] ローカルパスワードへのフォールバックが非公開である: 内部の直接呼び出し元向けに gateway.auth.password を設定する場合は、プロキシを経由しないリモートクライアントが Gateway ポートへ直接到達できないよう、ファイアウォールで遮断してください。
• [ ] デバイスの自動承認を意図的に使用している: deviceAutoApprove.enabled が true の場合は、リバースプロキシのアカウントセキュリティをデバイス登録の境界として扱い、付与するスコープ一覧を管理者権限なしの最小限に保ちます。

セキュリティ監査

openclaw security audit は trusted-proxy 認証を重大な深刻度の検出結果として報告します。これは意図された動作であり、セキュリティをプロキシ設定へ委任していることを注意喚起するものです。

監査では以下を確認します。

• 基本の gateway.trusted_proxy_auth 警告/重大リマインダー。
• trustedProxies 設定の欠如。
• userHeader 設定の欠如。
• 空の allowUsers（認証されたすべてのユーザーを許可します）。
• 同じホスト上のプロキシソースに対して allowLoopback が有効になっていること。
• ブラウザーデバイスの自動承認が有効になっていること（新しいデバイスのペアリングをプロキシアイデンティティへ委任します）。

Control UI が公開されている場合は、trusted-proxy に固有ではない別の検出結果も適用されます。これには、ワイルドカードまたは未設定の gateway.controlUi.allowedOrigins、および Host ヘッダーによるオリジンのフォールバックが含まれます。

トラブルシューティング

トークン認証からの移行

関連項目

• 設定 — 設定リファレンス
• オペレータースコープ — ロール、スコープ、承認チェック
• リモートアクセス — その他のリモートアクセスパターン
• セキュリティ — 完全なセキュリティガイド
• Tailscale — tailnet のみにアクセスする場合の、より簡単な代替手段