信頼済みプロキシ認証

使用する場合

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

使用しない場合

• プロキシがユーザーを認証しない（単なる TLS 終端またはロードバランサーである）。
• プロキシを迂回して Gateway に到達できる経路がある（ファイアウォールの穴、内部ネットワークからのアクセスなど）。
• プロキシが転送ヘッダーを正しく削除または上書きするか確信がない。
• 個人用の単一ユーザーアクセスだけが必要である（代わりに 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 のペアリング動作

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 を指定すると、デバイス 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 のリクエスト／レスポンス形式が適している場合は 管理 HTTP RPC pluginを使用してください。

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

信頼済みプロキシ認証は ID を伴う HTTP モードであるため、呼び出し元は必要に応じて、HTTP API リクエストの x-openclaw-scopes でオペレータースコープを宣言できます。

注: WebSocket のスコープは、Gateway プロトコルのハンドシェイクとデバイス ID の関連付けによって決まります。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 は宣言されたスコープセットを適用します。
• ヘッダーが存在していても空の場合、リクエストはオペレータースコープを 一切 宣言しません。
• ヘッダーが存在しない場合、通常の ID を伴う HTTP API は、標準のオペレーターデフォルトスコープセット（operator.admin、operator.read、operator.write、operator.approvals、operator.pairing、operator.talk.secrets）にフォールバックします。
• Gateway 認証を使用する plugin HTTP ルート のデフォルトは、より限定的です。x-openclaw-scopes が存在しない場合、そのランタイムスコープは operator.write のみにフォールバックします。
• ブラウザーオリジンからの HTTP リクエストは、信頼済みプロキシ認証に成功した後も、gateway.controlUi.allowedOrigins（または意図的に設定された Host ヘッダーフォールバックモード）の検査に合格する必要があります。

実用上の規則: 信頼済みプロキシからのリクエストをデフォルトより狭いスコープにしたい場合、または 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 を追加してください。
• ドメイン全体が意図的にプリロード要件を満たしている場合にのみ、プリロードを使用してください。
• 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/サイドカープロキシの 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 ポートへ直接アクセスできないよう、ファイアウォールで遮断する。

セキュリティ監査

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

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

• 基本となる gateway.trusted_proxy_auth の警告／重大リマインダー。
• trustedProxies 設定の欠落。
• userHeader 設定の欠落。
• 空の allowUsers（認証されたすべてのユーザーを許可）。
• 同一ホストのプロキシ送信元に対して有効化された allowLoopback。

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

トラブルシューティング

トークン認証からの移行

関連項目

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