信頼済みプロキシ認証

​

使用する場合

• OpenClaw を ID 認識プロキシ（Pomerium、Caddy + OAuth、nginx + oauth2-proxy、Traefik + forward auth）の背後で実行している。
• プロキシがすべての認証を処理し、ヘッダー経由でユーザー ID を渡す。
• Kubernetes またはコンテナ環境で、プロキシが Gateway への唯一の経路になっている。
• ブラウザーが 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 ペアリング動作

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

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

​

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

• 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 リクエストは、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（例: max-age=300）から始めます。
• 十分な確信が得られた後でのみ、長期間の値（例: max-age=31536000）へ増やします。
• すべてのサブドメインが HTTPS 対応済みの場合にのみ、includeSubDomains を追加します。
• ドメインセット全体について preload 要件を意図的に満たす場合にのみ、preload を使用します。
• 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/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",
      },
    },
  },
}

​

混在トークン設定

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

​

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

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

​

セキュリティ監査

• 基本の gateway.trusted_proxy_auth 警告/critical リマインダー。
• trustedProxies 設定の欠落。
• userHeader 設定の欠落。
• 空の allowUsers（認証済みユーザーを誰でも許可）。
• 同一ホストプロキシ送信元に対する allowLoopback の有効化。

​

トラブルシューティング

​

トークン認証からの移行

​

関連

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