信頼済みプロキシ認証

​

使用する場合

• 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"],
        },
      },
    },
  },
}

​

設定リファレンス

​

デバイスの自動承認

{
  gateway: {
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
        allowUsers: ["operator@example.com"],
        deviceAutoApprove: {
          enabled: true,
          scopes: ["operator.read", "operator.write", "operator.approvals"],
        },
      },
    },
  },
}

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 のペアリング動作

• デバイスなしの Control UI WebSocket セッションは接続できますが、デフォルトではオペレータースコープを受け取りません。OpenClaw は要求されたスコープリストを [] にクリアするため、承認済みのペアリング済みデバイスまたはトークンに関連付けられていないセッションが権限を自己申告することはできません。
• WebSocket の接続に成功した後、メソッドが missing scope で失敗する場合は、ブラウザーがデバイス ID を生成してペアリングを完了できるように HTTPS を使用してください。Control UI の安全でない HTTP を参照してください。
• 廃止された gateway.controlUi.dangerouslyDisableDeviceAuth=true キーがまだ含まれている古い設定には、限定的な Control UI アップグレード移行が適用されます。

• ペアリングは、デバイスなしの Control UI アクセスに対する主要なゲートではなくなります。deviceAutoApprove.enabled が true の場合、プロキシ ID は新しいブラウザーデバイス登録の承認ゲートにもなります。
• リバースプロキシの認証ポリシーと allowUsers が、実質的なアクセス制御になります。
• Gateway の受信経路は、信頼できるプロキシ 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 は、標準のオペレーター用デフォルトスコープセット（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 ヘッダーのフォールバックモード）を通過する必要があります。

​

TLS 終端と 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",
      },
    },
  },
}

​

トークンを併用した設定

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

​

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

• プロキシが唯一の経路である: 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 の場合は、リバースプロキシのアカウントセキュリティをデバイス登録の境界として扱い、付与するスコープ一覧を管理者権限なしの最小限に保ちます。

​

セキュリティ監査

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

​

トラブルシューティング

​

トークン認証からの移行

​

関連項目

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