​

Trusted Proxy 認証

⚠️ セキュリティ上重要な機能です。 このモードでは、認証を完全にリバースプロキシに委任します。設定を誤ると、Gateway が未承認アクセスにさらされる可能性があります。有効にする前に、このページを注意深く読んでください。

​

使用するべき場合

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

​

使用してはいけない場合

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

​

仕組み

1. リバースプロキシがユーザーを認証する（OAuth、OIDC、SAML など）
2. プロキシが認証済みユーザー ID を含むヘッダーを追加する（例: x-forwarded-user: nick@example.com）
3. OpenClaw が、そのリクエストが信頼されたプロキシ IP（gateway.trustedProxies で設定）から来たことを確認する
4. OpenClaw が設定されたヘッダーからユーザー ID を抽出する
5. すべての条件が満たされれば、リクエストは認可される

​

Control UI のペアリング動作

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

​

設定

{
  gateway: {
    // Trusted-proxy auth は、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"],
      },
    },
  },
}

• trusted-proxy 認証は、loopback 送信元のリクエスト（127.0.0.1、::1、loopback CIDR）を拒否します。
• 同一ホストの loopback リバースプロキシは trusted-proxy 認証を満たしません。
• 同一ホストの loopback プロキシ構成では、代わりに token / password 認証を使用するか、OpenClaw が検証できる loopback 以外の trusted proxy アドレス経由にしてください。
• loopback 以外の Control UI デプロイでは、明示的な gateway.controlUi.allowedOrigins も必要です。

​

設定リファレンス

​

TLS 終端と HSTS

​

推奨パターン: プロキシで TLS 終端

• インターネット公開のデプロイに適しています。
• 証明書と HTTP ハードニングポリシーを 1 か所で管理できます。
• OpenClaw はプロキシ背後の loopback HTTP のままにできます。

Strict-Transport-Security: max-age=31536000; includeSubDomains

​

Gateway で TLS 終端

{
  gateway: {
    tls: { enabled: true },
    http: {
      securityHeaders: {
        strictTransportSecurity: "max-age=31536000; includeSubDomains",
      },
    },
  },
}

​

ロールアウト指針

• まずは短い max age（例: max-age=300）から始めて、トラフィックを検証してください。
• 十分な確信が持ててから、長期間の値（例: max-age=31536000）に引き上げてください。
• includeSubDomains は、すべてのサブドメインが HTTPS 対応済みの場合にのみ追加してください。
• preload は、ドメイン全体が preload 要件を満たすよう意図的に整えている場合にのみ使用してください。
• loopback 専用のローカル開発では HSTS の恩恵はありません。

​

プロキシ設定例

​

Pomerium

{
  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

​

OAuth 付き Caddy

{
  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}
    }
}

​

nginx + oauth2-proxy

{
  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";
}

​

Forward Auth 付き Traefik

{
  gateway: {
    bind: "lan",
    trustedProxies: ["172.17.0.1"], // Traefik コンテナーの IP
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
      },
    },
  },
}

​

混在した token 設定

• trusted-proxy モードを使うなら shared token を削除する、または
• token ベース認証を意図しているなら gateway.auth.mode を "token" に切り替える

​

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

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

• ヘッダーが存在する場合、OpenClaw は宣言されたスコープ集合を尊重します。
• ヘッダーが存在していて空の場合、そのリクエストはオペレータースコープなしを宣言します。
• ヘッダーが存在しない場合、通常の ID 付き HTTP API は標準のオペレーターデフォルトスコープ集合にフォールバックします。
• Gateway-auth plugin HTTP ルートはデフォルトでより狭く、x-openclaw-scopes が存在しない場合、そのランタイムスコープは operator.write にフォールバックします。
• ブラウザー起点の HTTP リクエストは、trusted-proxy 認証が成功した後でも、gateway.controlUi.allowedOrigins（または意図的な Host-header フォールバックモード）を通過する必要があります。

• trusted-proxy リクエストをデフォルトより狭くしたい場合、または gateway-auth plugin ルートで write スコープより強い権限が必要な場合は、x-openclaw-scopes を明示的に送ってください。

​

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

• プロキシが唯一の経路である: Gateway ポートは、あなたのプロキシ以外からはファイアウォールで遮断されている
• trustedProxies が最小限である: サブネット全体ではなく、実際のプロキシ IP のみ
• loopback プロキシ送信元がない: trusted-proxy 認証は loopback 送信元リクエストでフェイルクローズする
• プロキシがヘッダーを除去する: プロキシはクライアントからの x-forwarded-* ヘッダーを追記ではなく上書きする
• TLS 終端: プロキシが TLS を処理し、ユーザーは HTTPS 経由で接続する
• allowedOrigins が明示的である: loopback 以外の Control UI では明示的な gateway.controlUi.allowedOrigins を使う
• allowUsers が設定されている（推奨）: 認証済みなら誰でもではなく、既知のユーザーに制限する
• 混在した token 設定がない: gateway.auth.token と gateway.auth.mode: "trusted-proxy" を同時に設定しない

​

セキュリティ監査

• ベースとなる gateway.trusted_proxy_auth の warning / critical リマインダー
• trustedProxies 設定の欠落
• userHeader 設定の欠落
• 空の allowUsers（認証済みなら誰でも許可）
• 公開された Control UI サーフェスにおけるワイルドカードまたは欠落した browser-origin ポリシー

​

トラブルシューティング

​

「trusted_proxy_untrusted_source」

• プロキシ IP は正しいですか？（Docker コンテナー IP は変わることがあります）
• プロキシの前段にロードバランサーはありますか？
• 実際の IP を確認するには docker inspect または kubectl get pods -o wide を使ってください

​

「trusted_proxy_loopback_source」

• プロキシは 127.0.0.1 / ::1 から接続していますか？
• 同一ホストの loopback リバースプロキシで trusted-proxy 認証を使おうとしていませんか？

• 同一ホストの loopback プロキシ構成では token / password 認証を使う、または
• loopback 以外の trusted proxy アドレスを経由し、その IP を gateway.trustedProxies に含める

​

「trusted_proxy_user_missing」

• プロキシは ID ヘッダーを渡すように設定されていますか？
• ヘッダー名は正しいですか？（大文字小文字は区別しませんが、綴りは重要です）
• ユーザーは本当にプロキシで認証されていますか？

​

「trustedproxy_missing_header*」

• それらの特定ヘッダーに対するプロキシ設定
• 経路のどこかでヘッダーが除去されていないか

​

「trusted_proxy_user_not_allowed」

​

「trusted_proxy_origin_not_allowed」

• gateway.controlUi.allowedOrigins に正確なブラウザー origin が含まれている
• 意図的に全許可したい場合を除いて、ワイルドカード origin に依存していない
• Host-header フォールバックモードを意図的に使う場合、gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true を明示的に設定している

​

WebSocket がまだ失敗する

• WebSocket アップグレードをサポートしている（Upgrade: websocket、Connection: upgrade）
• ID ヘッダーを WebSocket アップグレードリクエストでも渡している（HTTP だけではない）
• WebSocket 接続に別の認証経路が存在しない

​

token 認証からの移行

1. プロキシがユーザーを認証し、ヘッダーを渡すよう設定する
2. プロキシ構成を独立してテストする（ヘッダー付き curl）
3. OpenClaw の設定を trusted-proxy 認証に更新する
4. Gateway を再起動する
5. Control UI からの WebSocket 接続をテストする
6. openclaw security audit を実行して、検出結果を確認する

​

関連

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