SpyBara
Go Premium

claude-apps-gateway-config.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 287 additions and 84 deletions.

2026
Wed 9 22:58 Fri 18 23:58

Claude apps gateway 設定

gateway.yaml のすべてのオプションのリファレンス：リスナーと TLS、OIDC、セッション、Postgres ストア、Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、Microsoft Foundry アップストリーム、モデルルーティング、マネージドポリシー、テレメトリー。

Claude apps gateway デプロイメントは、慣例的に gateway.yaml という 1 つの YAML ファイルで設定されます。このファイルは、ゲートウェイが行うすべてのことを定義します：どこでリッスンするか、開発者がどのようにサインインするか、推論がどこに行くか、どのポリシーとテレメトリーが適用されるかです。このページは、そのファイル内のすべてのオプションのリファレンスです。最初のファイルを作成するには、クイックスタートから始めてください。これは最小限の動作設定を構築して実行します。設定に満足したら、デプロイメントガイドで、Kubernetes、Cloud Run、または独自のプラットフォームでのコンテナ化とホスティングについて説明しています。

ゲートウェイは、claude gateway --config /path/to/gateway.yaml でスタートアップ時にファイルを 1 回読み込みます。すべてのオプションはブート時にスキーマに対して検証されるため、形式が正しくない設定は、最初の使用時ではなく、フィールドレベルのエラーで開始時に失敗します。

このページの最後にある完全な例は、すべてのセクションを実行します。

ファイル構造

5 つのセクションが必須です。他のすべてのセクションはオプションであり、省略されたセクションはデフォルトを使用します。不明なキーはブートに失敗するため、タイプミスは無視された設定ではなく、名前付きエラーとして表示されます。

必須セクション：

  • listen：バインドアドレス、パブリック URL、TLS 終了
  • oidc：ID プロバイダー（IdP）、発行者、クライアント、クレームマッピング、サインイン可能なユーザーを含む
  • session：ゲートウェイが発行するベアラートークン、シークレット、有効期間
  • store：デバイスグラント、レート制限カウンターの PostgreSQL
  • upstreams：推論がどこに行くか、Anthropic、Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、または Microsoft Foundry かどうか

オプションセクション：

  • admin：Admin API 認証、支出制限の保持
  • enforcement：支出制限のフェイルオープンまたはフェイルクローズ動作
  • pricing：契約レートと支出メーターの割引乗数
  • models と auto_include_builtin_models：管理者がキュレーションしたモデルリスト、アップストリームごとの ID
  • managed：IdP グループ別のマネージド設定ポリシー
  • telemetry：OTLP を観測可能性スタックに転送
  • access_control、limits、timeouts、rate_limits：IP 許可/拒否、リクエストサイズキャップ、アップストリーム初バイト時間、IP ごとのサインイン制限

シークレット展開

client_secret、jwt_secret、postgres_url などのシークレットを gateway.yaml に直接書き込まないでください。以下のいずれかの形式で参照すると、ゲートウェイはブート時に環境変数またはファイルから値を解決します：

形式 解決先 用途
${VAR} 環境変数 VAR。未定義の場合はブート失敗。 コンテナ環境変数、env インジェクション経由の AWS Secrets Manager
${file:/path} そのパスにあるファイルの内容、トリミング済み。参照はフィールド全体の値である必要があります：${VAR} とは異なり、より長い文字列内で展開されないため、データベースパスワードの場合は postgres_url に埋め込むのではなく store.password を設定してください。 Kubernetes Secret ボリュームマウント、Vault Agent、SOPS

必須セクション

`listen`

listen ブロックは、ゲートウェイがサービスを提供する場所を制御します：バインドアドレスとポート、外部から見えるオリジン、オプションの TLS 終了。

フィールド 必須 説明
host いいえ バインドアドレス。デフォルト 0.0.0.0。
port いいえ バインドポート。デフォルト 8080。
public_url host がループバックでない場合 外部から見える https:// オリジン。IdP redirect_uri と検出メタデータを構築するために使用されます。ALB、Ingress、Cloud Run などのプロキシで TLS が終了する場合、またはゲートウェイ自体が tls を通じて終了する場合に必須です。ゲートウェイは X-Forwarded-* ヘッダーから独自のオリジンを派生させることはないためです。これらはクライアントがスプーフ可能です。これなしではブートが失敗します。以下の trusted_proxies はクライアント IP 解決のみを管理します。また、テレメトリを有効にするためにも必須です。ゲートウェイはこの URL からクライアントにプッシュする OTLP エンドポイントを構築するためです。
tls.cert / tls.key いいえ ゲートウェイが TLS 自体を終了する場合の PEM パス
trusted_proxies いいえ ゲートウェイの前にあるロードバランサーの CIDR または IP。設定すると、ゲートウェイはこれらのピアからのみ X-Forwarded-For を信頼し、IP ごとのレート制限と監査のための実際のクライアント IP を記録します。nginx set_real_ip_from と同等。X-Forwarded-For エントリが ipv4:port または [ipv6]:port として書き込まれている場合（一部のロードバランサーがそうするように）、ポートを削除して読み込まれます。ポートが追加されたブラケットなしの IPv6 アドレスは、別のアドレスとして読み込まれるか、まったく読み込まれない可能性があるため、そのフォームを書き込むプロキシのポートオプションをオフにします。

`oidc`

oidc ブロックはゲートウェイを ID プロバイダーに接続し、サインイン可能なユーザーを決定します。発行者と OAuth クライアントに名前を付け、メールとグループを含むクレームをマップし、メールドメインまたはグループによるサインインを制限します。

OpenID Connect（OIDC）は、ゲートウェイが ID プロバイダーで使用する SSO プロトコルです。IdP 側で登録する内容については、ID プロバイダー設定を参照してください。

フィールド 必須 説明
issuer はい OIDC 検出ベース。/.well-known/openid-configuration で検出を提供する必要があります。本番環境では HTTPS を使用してください。ゲートウェイは http:// 発行者を受け入れます。http://localhost:8081 などのループバック発行者は、CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 がゲートウェイの環境に設定されていない限り、SSRF ガードによって拒否されます。
client_id / client_secret はい OAuth クライアント登録から
allowed_email_domains いいえ email クレームがこれらのドメインのいずれかにない id_token を拒否します。大文字小文字を区別しません。マルチテナント IdP の設定ミスに対する多層防御。この設定とは無関係に、email_verified クレームが明示的に false である id_token は常に拒否されます。
allowed_groups いいえ サインインを groups_claim に対してマッチしたこれらの IdP グループのメンバーに制限します。許可されたメールドメイン内にあるが、これらのグループのいずれにも属していないユーザーは拒否されます。IdP がグループクレームを発行する必要があります。マッチングは、そのクレーム内の値に対する正確で大文字小文字を区別する文字列比較であり、ゲートウェイはネストされたグループを展開しません：サブグループのメンバーを許可するには、ここにサブグループをリストするか、IdP を設定してフラット化されたメンバーシップを発行します。
groups_claim いいえ グループメンバーシップを含む id_token クレーム。デフォルト groups。Microsoft Entra はアプリロールを roles の下に発行します。フラットキーまたは /resource_access/gateway/roles などのネストされたクレーム用の RFC 6901 JSON ポインタを受け入れます。
google_groups いいえ Google Workspace Admin SDK Directory API を通じてサインインしたユーザーのグループを検索します。Google の id_token はグループクレームを含まないためです。service_account_json_path を https://www.googleapis.com/auth/admin.directory.group.readonly スコープでドメイン全体の委任を持つサービスアカウントキーファイルに設定し、admin_email をサービスアカウントが偽装する Workspace 管理者に設定します。Directory API は実際の管理者サブジェクトが必要です。各ユーザーのグループメールアドレスがグループクレームになるため、allowed_groups と managed.policies.match.groups はグループメールでマッチします。
email_claim いいえ ユーザーのメールを含む id_token クレーム。デフォルト email。ADFS や Entra B2C などの一部の IdP は、代わりに upn または preferred_username を発行します。フラットキー、JSON ポインタ、または最初に存在するキーが使用されるフォールバックキーのリストを受け入れます。
scopes いいえ ゲートウェイが要求する OIDC スコープの完全なオーバーライド。デフォルト [openid, profile, email, offline_access]。IdP が認識しないスコープを拒否する場合、またはグループまたはメールを発行するカスタムスコープが必要な場合に設定します。openid を含める必要があります。offline_access を削除するとリフレッシュトークンが無効になるため、開発者は session.ttl_hours ごとにブラウザログインを再実行します。Google のリフレッシュトークンフローなどの IdP ごとのスコープレシピについては、ID プロバイダー設定を参照してください。
scope_on_refresh いいえ リフレッシュトークンを交換する場合、サインインリクエストと同じリストで scope も送信します。デフォルト false：リフレッシュリクエストは scope を省略します。ほとんどの IdP はすべてのリフレッシュで id_token を返し、これを必要としません。IdP が openid を再度要求された場合にのみリフレッシュ時に id_token を返す場合、true に設定します。これは Okta がリフレッシュグラントについて文書化しています。id_token がない場合、すべてのリフレッシュは IdP の userinfo エンドポイントがリフレッシュされたアクセストークンを受け入れることに依存します。グループでサインインまたはポリシーマッチをゲートしており、IdP のリフレッシュ時 id_token がそれらを省略する場合、userinfo_fallback: true も設定して、ゲートウェイが userinfo エンドポイントからそれらを埋めるようにします。許可されたスコープが要求されたスコープより少ないことを付与した IdP は、これがオンの場合、invalid_scope でリフレッシュを拒否できます。これは、これがオンの場合、scopes にエントリを追加した後、既存のセッションを含みます。リフレッシュが設定後に token_endpoint で失敗し始めた場合、キーを設定解除します。Claude Code v2.1.260 以降がゲートウェイサーバーで必要です。
extra_auth_params いいえ IdP 認可リクエストに逐語的に追加される追加クエリパラメータ。これは、Google リフレッシュトークンの access_type: offline、一部の Entra テナントの domain_hint、またはステップアップフローの acr_values など、IdP 固有の動作のオーバーライドメカニズムです。ゲートウェイが管理するプロトコルパラメータはオーバーライドできません：state、nonce、redirect_uri、PKCE、scope、response_type、response_mode、client_id。
userinfo_fallback いいえ id_token がメールまたはグループを省略する場合、/userinfo から取得します。Keycloak 軽量アクセストークン、Okta org サーバー、ADFS 最小トークンに必要です。id_token は権威的なままです。userinfo はギャップのみを埋めます。デフォルト false。
use_pkce いいえ 認可リクエストで PKCE（S256）チャレンジを送信します。デフォルト true。IdP がこの機密クライアントの PKCE を拒否する場合のみ false に設定します。
clock_skew_seconds いいえ id_token 時間クレームを検証する際にクロックドリフトを許容します。デフォルト 0（厳密）。サインイン直後のホスト/IdP クロックスキューによる「トークン期限切れ/まだ有効でない」エラーが表示される場合は、増やします。
token_endpoint_auth_method いいえ トークンエンドポイント認証方法をオーバーライドします。client_secret_basic または client_secret_post を受け入れます。デフォルトで自動ネゴシエーション。
id_token_signed_response_alg いいえ 予想される id_token 署名アルゴリズム。デフォルト RS256。ES256、PS256、または EdDSA で署名する IdP に設定します。
additional_authorized_parties いいえ client_id を超えて受け入れる追加の azp 値。Keycloak ブローカーとトークン交換フロー用。
discovery_url いいえ issuer から派生させるのではなく、この URL から検出ドキュメントを取得します。プロキシの背後にある IdP の場合、発行者ホストを書き直します。パスは /.well-known/ を含む必要があります。
use_proxy いいえ ゲートウェイ自身の IdP リクエストを HTTPS_PROXY または HTTP_PROXY のフォワードプロキシを通じて送信し、NO_PROXY を尊重します。設定解除または false の場合、これらのリクエストは直接行きます。v2.1.227 以降が必要です。以下の IdP リクエストをフォワードプロキシを通じてを参照してください。
form_action_origins いいえ /device ページの Content-Security-Policy: form-action ディレクティブの追加オリジン。ゲートウェイはすでに 'self' と検出された authorization_endpoint オリジンを許可していますが、Chrome は全リダイレクトチェーンに対して form-action を強制します。IdP が Azure AD から ADFS へのフェデレーション、ハブスポーク Okta、または企業 SSO インターセプターなど、2 番目のホストを通じてリダイレクトする場合、認可リクエストがリダイレクトする可能性のあるすべてのオリジンをリストします。
ca_cert_pem いいえ PEM エンコードされた CA 証明書そのもの。ファイルへのパスではありません。IdP リクエストのみのシステムトラストストアを置き換えます。マウントされたファイルを読み込むには、${file:/etc/gateway/idp-ca.pem} と書き込みます。企業 PKI の背後にある Keycloak または Dex に使用します。

IdP リクエストをフォワードプロキシを通じて

推論アップストリームはすべてのバージョンで HTTPS_PROXY と HTTP_PROXY を尊重します。ゲートウェイ自身の IdP、検出、JWKS、トークン、userinfo へのリクエストは、oidc.use_proxy: true を設定しない限り直接行きます。これには v2.1.227 以降が必要です。プロキシ変数が設定され、use_proxy が設定解除され、発行者が NO_PROXY でカバーされていない場合、ゲートウェイはこれらのリクエストを直接保ち、ブート時に選択するよう求める通知をログに記録します。use_proxy: false はそれらを直接保ち、通知を沈黙させます。

use_proxy: true の場合、ポッドは各 IdP エンドポイントのホスト名を自身で解決し、プロキシに解決された IP アドレスへの CONNECT を要求するため、プロキシは検出ドキュメントが名前を付けるすべてのホストの IP アドレスへの CONNECT を受け入れる必要があります。発行者だけではなく。http:// プロキシ URL を使用します。ca_cert_pem と SSRF ガードはプロキシされたパスにも適用されます。

`session`

session ブロックは、サインイン後にゲートウェイが発行するベアラートークンの形状を決定します：それらに署名するシークレットと、どのくらい長く生きるか。

フィールド 必須 説明
jwt_secret はい 少なくとも 32 バイトのエントロピー。例えば openssl rand -base64 32 から。ゲートウェイの HS256 ベアラートークンに署名します。単一の文字列または回転用の配列を受け入れます：インデックス 0 が署名し、すべてのエントリが検証します。回転するには、新しいシークレットを先頭に追加し、ttl_hours 待機してから古いものを削除します。
ttl_hours いいえ ゲートウェイベアラートークンの有効期間。デフォルト 1。CLI は IdP がリフレッシュトークンを発行する場合、有効期限前に無言でリフレッシュします。有効期間が短いほど、より速くプロビジョニング解除されます。長いほど、IdP ラウンドトリップが少なくなります。IdP が offline_access が利用できないため、リフレッシュトークンを発行できない場合、無言リフレッシュはないため、開発者が 1 時間ごとにブラウザログインに戻されるのを避けるために、これを 8 または 12 に上げます。

`store`

store ブロックは、ゲートウェイを PostgreSQL データベースに指します。このデータベースは、デバイスグラントとレート制限カウンターを保持します。

フィールド 必須 説明
postgres_url はい postgres:// または postgresql:// URL。必須：デバイスグラント集合場所。ブラウザコールバックが書き込み、ポーリング CLI が読み込む場所。レプリカ間の状態が必要です。ゲートウェイはブート時と アップグレード時に独自のスキーママイグレーションを実行するため、ロールはターゲットスキーマでテーブルを作成および変更する権限が必要です。アップグレードと Postgresを参照してください。
username いいえ postgres_url のユーザーをオーバーライド
password いいえ データベース認証情報。postgres_url ではなくここに設定して、認証情報を URL から外します。任意の文字を受け入れ、URL 認証情報よりも優先されます。
max_connections いいえ レプリカごとの Postgres 接続プール サイズ。デフォルト 5。共有データベースに対して保守的でフレンドリーです。支出制限が有効な場合、ホットパスは推論リクエストごとに数回の操作を実行するため、専用データベースの負荷の下で増やし、レプリカ × これをデータベースの max_connections 以下に保ちます。

ローカル開発の場合、postgres_url を使い捨て Postgres コンテナに指します。例えば docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres。

`upstreams`

upstreams は順序付きリストです。ゲートウェイは、要求されたモデルを解決する最初のアップストリームに推論を転送します。5xx、429、401、403、404、またはタイムアウト時に次にフェイルオーバーします。他の 4xx はしません。これらのエラーはリクエストではなくアップストリームに起因するためです。401 または 403 はゲートウェイ自身の認証情報がそのアップストリームに対して失敗したことを意味し、404 はそのアップストリームが要求されたモデルを提供していないことを意味するため、リスト内の後のアップストリームはまだ提供できます。

404 でのフェイルオーバーにはゲートウェイ v2.1.198 以降が必要です。以前のリリースは、リスト内の後のアップストリームがモデルを提供している場合でも、最初の 404 をクライアントに返しました。

同じプロバイダーの複数のアップストリームは、異なる name: を設定する必要があります。

Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、Microsoft Foundry クライアントはスタートアップ時に 1 回構築され、SDK は内部的に認証情報をリフレッシュするため、クラウド認証情報のローテーションは再起動を必要としません。静的 Anthropic API キーとベアラーはスタートアップ時に読み込まれます。Anthropic APIを参照してください。

アップストリームエラーメッセージ

ゲートウェイは、アップストリームがどのように応答したかに応じて、1 つのアップストリームのエラー応答またはそれ自身の 502 を返します：

  • ゲートウェイが フェイルオーバーしないステータスを返したアップストリーム：そのアップストリームの応答。ゲートウェイはさらなるアップストリームを試しません。
  • ゲートウェイが試したすべてのアップストリームが フェイルオーバーする方法で失敗した：最後の 429。どれも 429 を返さなかった場合、ゲートウェイは順番に、最後の 401 または 403、最後の 404、最後の 501 を優先します。どれもそれらのいずれかを返さなかった場合、ゲートウェイ自身の 502、all upstreams failed (N attempted)。N は upstreams のすべてのエントリをカウントします。ゲートウェイが要求されたモデルを提供しないため、スキップしたエントリを含みます。

ゲートウェイがアップストリームの応答を返す場合、アップストリームのステータスコードを保持します。アップストリームのメッセージを保持するかどうかはプロバイダーに依存します。Anthropic API アップストリームのエラー本体は開発者に変更されずに到達します。

Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、Microsoft Foundry アップストリームは、エラーテキストでアカウント ID、ロール ARN、プロジェクト ID に名前を付けることができます。ゲートウェイはその完全なテキストを 操作ログに記録します。開発者がこれらのアップストリームから見るものは、拒否に依存します：

  • Anthropic の標準エラーエンベロープの 400 または 413：prompt is too long などのアップストリーム自身のメッセージ。Claude Platform on AWS、Agent Platform、Microsoft Foundry はモデル API 拒否のためこのエンベロープを返します。
  • プロバイダー自身の形状の 400 または 413：capability_rejected: トークン。ゲートウェイが拒否を分類できない場合、400 で upstream rejected the request または 413 で request too large for this upstream。
  • その他のステータス：429 で upstream rate limit exceeded などのステータスごとの汎用コピー。

例えば、ゲートウェイは Amazon Bedrock の Input is too long for requested model. を capability_rejected: prompt_too_long に置き換えます。Claude Code は prompt is too long と同様に、そのトークンで 自動的にコンパクトにします。

クラウドアップストリームの 400 または 413 メッセージを保持するか、capability_rejected: トークンで置き換えるには、ゲートウェイ v2.1.233 以降が必要です。

Anthropic API

最小限の Anthropic アップストリームは、Claude Console からの API キーです：

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}
    # または OAuth ベアラー（例：Workload-Identity-Federation 交換トークン）：
    #   oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
    # base_url: https://api.anthropic.com   # デフォルト；フォワードプロキシの場合はオーバーライド

2 つの認証情報形式は、送信するヘッダーが異なります：

  • api_key：x-api-key を送信します。Claude Console でローテーションし、env var を更新します。
  • oauth_token：Authorization: Bearer を送信します。組織が長期 API キーではなく短期トークンを発行する場合、ベアラー形式を使用します。ベアラーはスタートアップ時に 1 回読み込まれるため、シークレットを再マウントして再起動することで更新します。

静的キーまたはベアラーの代わりに、Workload Identity Federation を使用できます。Workload Identity Federation ガイドに従って、フェデレーションルールを作成し、ワークロードの OIDC JWT をファイルとしてマウントします。例えば、Kubernetes プロジェクトサービスアカウントトークンまたは CI プラットフォームの id-token。ゲートウェイは JWT を短期ベアラーと交換し、自動的にリフレッシュします。トークンファイルはすべての交換で再読み込みされるため、ローテーションされたプロジェクトトークンは再起動なしで取得されます。

upstreams:
  - provider: anthropic
    auth:
      federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
      organization_id: ${ANTHROPIC_ORGANIZATION_ID}
      identity_token_file: /var/run/secrets/anthropic/id-token
      # workspace_id: wrkspc_...       # ルールが 1 つ以上のワークスペースをカバーする場合は必須
      # service_account_id: svac_...   # オプションの予想ターゲットチェック
あなたが実行するプロキシのユーザーごとのアイデンティティヘッダー

provider: anthropic アップストリームの base_url を、Anthropic API ではなく、あなたが実行するプロキシに指すことができます。各リクエストを送信した開発者をそのプロキシに伝えるには、そのアップストリームで forward_user_identity: true を設定します。プロキシはその後、開発者ごとに支出を属性付けることができます。Claude Code v2.1.233 以降がゲートウェイサーバーで実行されている必要があります。

例えば、upstream-gateway.internal.example.com のプロキシの場合：

upstreams:
  - provider: anthropic
    base_url: https://upstream-gateway.internal.example.com
    auth:
      api_key: ${PROXY_KEY}
    forward_user_identity: true        # デフォルト false

ゲートウェイはそのアップストリームに転送するすべてのリクエストにこれらのヘッダーを追加します。

ヘッダー 値
x-litellm-end-user-id IdP が提供した場合、開発者のメール。
x-claude-gateway-user-id トークンの sub クレームからの開発者の IdP サブジェクト。
x-claude-gateway-user-email IdP が提供した場合、開発者のメール。

IdP トークンがメールを含まない場合、ゲートウェイは x-claude-gateway-user-id のみを送信し、2 つのメールヘッダーを省略します。IdP がメールを別のクレームに入れる場合、oidc.email_claimをそのクレームに設定します。

forward_user_identity は、base_url があなたが操作するプロキシであるアップストリームにのみ設定します。ゲートウェイは開発者メールを、その base_url が名前を付けるサーバーに送信します。base_url が Anthropic API（デフォルト）の場合、ゲートウェイは起動を拒否します。

Amazon Bedrock

ゲートウェイが置き換えるまたはフロントする、クライアント側の Amazon Bedrock デプロイメントについては、Amazon Bedrock の Claude Codeを参照してください。ゲートウェイ側のアップストリーム：

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # 推奨：AWS デフォルト認証情報チェーン
    # または明示的な認証情報：
    # auth:
    #   aws_access_key_id: ${AWS_AKID}
    #   aws_secret_access_key: ${AWS_SK}
    #   aws_session_token: ${AWS_ST}
    # または Bedrock API ベアラートークン：
    # auth:
    #   aws_bearer_token: ${AWS_BEARER_TOKEN}
    # FIPS または VPC エンドポイントデプロイメント用に bedrock-runtime エンドポイントをオーバーライド：
    # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

空の auth ブロックは AWS SDK のデフォルト認証情報チェーンを使用します：env vars、~/.aws/credentials、ECS タスクロール、EC2 インスタンスメタデータ、または EKS の IRSA。本番環境では、コンテナイメージに静的キーを埋め込むのではなく、ゲートウェイポッドに IAM ロールを付与します。

明示的な認証情報は完全である必要があります：aws_access_key_id と aws_secret_access_key が一緒に設定されていない場合、または aws_session_token が設定されていない場合、ゲートウェイはブート時に失敗します。v2.1.207 より前では、部分的な auth: ブロックは検証に合格しました。

セットアップ 方法
IAM 権限 ゲートウェイのプリンシパルに bedrock:InvokeModel と bedrock:InvokeModelWithResponseStream を推論プロファイル ARN と基盤モデル ARN の両方に付与します。US リージョンの組み込みカタログの場合：arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.* と arn:aws:bedrock:*::foundation-model/anthropic.*。また、基盤モデル ARN に bedrock:CountTokens を付与します。ゲートウェイはそれを使用して、クライアントが放棄したリクエストの入力トークンをカウントするため、支出制限は正確なままです。これなしでは、ゲートウェイはそのカウントのために 1 トークン Bedrock リクエストにフォールバックします。
モデルアクセス Amazon Bedrock は商用リージョンでデフォルトでモデルアクセスを有効にします。残りのアカウントレベルゲートは Anthropic のワンタイムユースケースフォームです：AWS アカウント内の誰もそれを送信していない場合、Amazon Bedrock コンソールを開き、モデルカタログから Anthropic モデルを選択し、フォームを完成させます。ユースケース詳細を送信を参照してください。AWS Organizations フォームと送信者が必要とする権限。
EKS（IRSA） 上記のポリシーと、クラスターの OIDC プロバイダーのトラストポリシーを持つ IAM ロールを作成します。ゲートウェイのサービスアカウントにスコープされます。サービスアカウントに eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway でアノテーションを付けます。auth: {} がそれを取得します。
ECS / EC2 IAM ロールをタスク定義またはインスタンスプロファイルにアタッチします。auth: {} がそれを取得します。
その他の場所 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN env vars を通じて認証情報を渡すか、auth: で ${VAR} 展開を使用して明示的に設定します。
リージョン region: は API エンドポイントリージョンです。クロスリージョン推論プロファイルは、どれを選択するかに関わらず、地域（US、EU、APAC）全体でルーティングします。US 以外のリージョンまたはプロビジョニングスループット ARN の場合、正しいアップストリームごとの ID を持つ models: ブロックを追加します。

Claude Platform on AWS

Claude Platform on AWS は、aws-external-anthropic.<region>.api.aws で AWS インフラストラクチャ上の第一者 Anthropic API を提供します。第一者モデル ID を使用し、送信された anthropic-beta ヘッダーを尊重し、count_tokens を提供するため、Bedrock 固有の変換は適用されません。anthropicAws プロバイダーには Claude Code v2.1.198 以降が必要です。以前のゲートウェイリリースはブート時にそれを拒否します。

同じプラットフォームのクライアント側デプロイメントについては、Claude Platform on AWS の Claude Codeを参照してください。ゲートウェイ側のアップストリーム：

upstreams:
  - provider: anthropicAws
    region: us-east-1
    workspace_id: wrkspc_...
    auth:
      api_key: ${ANTHROPIC_AWS_API_KEY}   # x-api-key として送信
    # または AWS デフォルト認証情報チェーン経由の SigV4：
    # auth: {}
    # または明示的な SigV4 認証情報：
    # auth:
    #   aws_access_key_id: ${AWS_ACCESS_KEY_ID}
    #   aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    # 派生エンドポイントをオーバーライド：
    # base_url: https://aws-external-anthropic.us-east-1.api.aws

プラットフォームは Amazon Bedrock とは別の AWS アカウントで実行され、独自のサービス名 aws-external-anthropic の SigV4 リクエストに署名するため、Bedrock スコープの IAM ロールはそれを認可しません。auth.api_key の API キーは、SigV4 認証情報も設定されている場合、優先されます。空の auth ブロックは AWS SDK のデフォルト認証情報チェーンを使用します。これは Amazon Bedrock アップストリームが使用するのと同じチェーンです。

フィールド 必須 説明
region はい AWS リージョン。小文字、数字、ハイフン。ゲートウェイは https://aws-external-anthropic.<region>.api.aws としてエンドポイントを派生させます。
workspace_id はい すべてのリクエストでヘッダーとして送信されます。プラットフォームはそれを必要とします。
auth.api_key いいえ プラットフォームの API キー。x-api-key として送信されます。ベアラートークンではありません：2 つの認証モードは API キーまたは SigV4 です。
auth.aws_access_key_id / auth.aws_secret_access_key いいえ 明示的な SigV4 認証情報。一方を他方なしで設定するとブート時に失敗します。auth.aws_session_token はそれらと一緒に受け入れられます。
base_url いいえ 派生エンドポイントをオーバーライド

プラットフォームは第一者モデル ID を解決するため、組み込みカタログは models: ブロックなしでそれにルーティングします。models: リストをキュレートする場合、エントリを anthropicAws: でキーイングし、第一者 ID を使用します。

Google Cloud Agent Platform

同等のクライアント側セットアップについては、Google Cloud の Claude Codeを参照してください。ゲートウェイ側のアップストリーム：

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    auth: {}                           # 推奨：Application Default Credentials
    # またはサービスアカウントキーファイル：
    # auth: { service_account_json: /secrets/sa.json }
    # Private Service Connect 用に aiplatform エンドポイントをオーバーライド：
    # base_url: https://us-east5-aiplatform.p.googleapis.com

空の auth ブロックは Application Default Credentials を使用します：GOOGLE_APPLICATION_CREDENTIALS、GCE メタデータ、または GKE Workload Identity。サービスアカウント JSON キーファイルはサポートされていますが、推奨されません。Workload Identity を使用するか、GCE または Cloud Run インスタンスにサービスアカウントをアタッチします。

region: global を設定して、地域のエンドポイントの代わりに Agent Platform のグローバルエンドポイントを使用します。Google は各リクエストを利用可能なリージョンにルーティングするため、リージョンごとのモデル可用性を追跡する必要はありません。特定のリージョンを設定すると、すべてのリクエストがそれにピンされます。

セットアップ 方法
IAM 権限 ゲートウェイのサービスアカウントに roles/aiplatform.user をプロジェクトに付与するか、aiplatform.endpoints.predict を持つカスタムロール。Agent Platform API（aiplatform.googleapis.com）を有効にします。
モデルアクセス Model Garden で、プロジェクトの Claude モデルを有効にします。特定のリージョンに公開されます。サポートされているリージョンについてはモデルカードを確認してください。
GKE（Workload Identity） GCP サービスアカウントをゲートウェイの Kubernetes サービスアカウントにバインドし、KSA に iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com でアノテーションを付けます。auth: {} がそれを取得します。
Cloud Run / GCE サービスのサービスアカウントを roles/aiplatform.user を持つものに設定します。auth: {} がそれを取得します。
その他の場所 auth: { service_account_json: /secrets/sa.json }。JSON キーファイルへのパス。シークレットとしてマウントされます。フィールドはキーの内容ではなくファイルパスを取得するため、${file:…} 展開は関係ありません。

Microsoft Foundry

クライアント側の Foundry デプロイメントについては、Microsoft Foundry の Claude Codeを参照してください。ゲートウェイ側のアップストリーム：

upstreams:
  - provider: foundry
    resource: example-foundry              # https://example-foundry.services.ai.azure.com
    auth: { use_azure_ad: true }        # 推奨：DefaultAzureCredential / Managed Identity
    # または API キー：
    # auth:
    #   api_key: ${FOUNDRY_API_KEY}

use_azure_ad: true は DefaultAzureCredential を通じて解決します：AKS、ACI、または App Service の Managed Identity、Azure CLI、または環境認証情報。API キーは機能しますが、プロジェクト全体であり、自動的にローテーションされません。Foundry のエンドポイントは resource: から派生します。Azure Government などのソブリンクラウドの場合、オプションの base_url を設定してオーバーライドします。

セットアップ 方法
RBAC ゲートウェイのアイデンティティに Azure AI User または Cognitive Services User を Foundry リソースに付与
デプロイメント Foundry は正規モデル ID ではなく、管理者が選択したデプロイメント名を使用します。各正規 ID をデプロイメント名にマップする models:ブロックを追加します。
AKS（ワークロードアイデンティティ） User-Assigned Managed Identity をクラスターの OIDC 発行者とフェデレーションし、ゲートウェイのサービスアカウントにバインドします。use_azure_ad: true は WorkloadIdentityCredential を通じてそれを取得します。
ACI / App Service リソースでシステム割り当てまたはユーザー割り当てマネージドアイデンティティを有効にします。use_azure_ad: true がそれを取得します。
その他の場所 auth: { api_key: "${FOUNDRY_API_KEY}" }。{ } 内の ${…} をクォートします。

複数のアップストリーム

同じプロバイダーは、異なる name: で複数回表示できます。これは異なるリージョン、異なる認証情報チェーン経由の異なるアカウント、プロビジョニングスループット対オンデマンド、クロスプロバイダーフェイルオーバーをカバーします。

ゲートウェイはアップストリームを順番に試します。5xx、429、401、403、404、タイムアウト、および欠落エンドポイント（501）はフェイルオーバーします。他の 4xx はしません。

429 はアップストリーム容量ごとです。プロビジョニングスループット（PT）枯渇はオンデマンドにフェイルオーバーします。404 はアップストリームモデル可用性ごとです。モデルを有効にしていないアップストリームは、後のアップストリームがそれを提供するのをブロックしません。要求されたモデルを解決できないアップストリームはネットワークラウンドトリップなしでスキップされます。

この例は、プロビジョニングスループット Amazon Bedrock 割り当てを最初にルーティングし、オンデマンドと 2 番目のアカウントにオーバーフロー、最後に Anthropic API にフォールバックします：

upstreams:
  # プライマリ：ホームリージョンのプロビジョニングスループット。
  - name: bedrock-pt
    provider: bedrock
    region: us-east-1
    auth: {}
  # オーバーフロー：オンデマンドクロスリージョン。
  - name: bedrock-od
    provider: bedrock
    region: us-west-2
    auth: {}
  # 異なるアカウント：想定ロール認証情報経由の別の Bedrock 割り当て。
  - name: bedrock-acct2
    provider: bedrock
    region: us-east-1
    auth:
      aws_access_key_id: ${ACCT2_AKID}
      aws_secret_access_key: ${ACCT2_SK}
  # 最後の手段：直接 Anthropic API。
  - name: anthropic-fallback
    provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

# アップストリームごとのモデル ID はアップストリームの `name:` でキーイングされます。
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef
      bedrock-od: us.anthropic.claude-opus-4-8
      bedrock-acct2: us.anthropic.claude-opus-4-8
      anthropic-fallback: claude-opus-4-8
レバー 方法
異なるリージョン リージョンごとに 1 つの Amazon Bedrock アップストリーム。それぞれ独自の region: を持ちます。auto_include_builtin_models: trueを使用すると、クロスリージョン推論プロファイルは自動的にルーティングされます。リージョンピンデプロイメントの場合、models: ブロックを使用します。
異なるアカウント アカウントごとに 1 つの Amazon Bedrock アップストリーム。それぞれ auth: で独自の認証情報を持ちます。デフォルトチェーン（auth: {}）はポッドのアイデンティティを使用します。2 番目のアカウントの場合、明示的な認証情報またはベアラートークンを設定します。
プロビジョニングスループット そのアップストリームの名前の models: でプロビジョニングスループット ARN にモデルをマップします。他のアップストリームはオンデマンド ID を保持するため、PT 容量はフェイルオーバー前に枯渇します。
VPC / FIPS エンドポイント アップストリームで base_url: を VPC エンドポイントまたは FIPS エンドポイント URL に設定します。
モデルスコープルーティング 唯一のカスタムモデル id（組み込み Claude モデルではないもの）は、その upstream_model: マップから欠落しているアップストリームをスキップします。ゲートウェイは組み込みモデルをすべてのアップストリームで順番に試し、マップにエントリがない場所でプロバイダーのデフォルト ID を使用するため、組み込みモデルの場合、マップはアップストリームが試されるかどうかではなく、アップストリームが受け取る ID を変更します。ID を拒否するアップストリームは、他のアップストリームエラーと同じ フェイルオーバールールに従います。

クラウドプロバイダー間、または直接 Anthropic API へのフェイルオーバーは、リクエストを管理する契約、地域、その他の条件を変更します。

CLI は、どのアップストリームが特定のリクエストを提供するかに関わらず、ゲートウェイに同じ機能ゲーティングを適用するため、フェイルオーバーはアップストリームが拒否するボディフィールドを送信しません。

オプションセクション

`admin`

オプション。/v1/organizations/spend_limits を有効にします。これは Anthropic のパブリック Admin API をミラーリングし、/v1/messages で開発者ごとの支出強制を行います。支出制限で、キャップがどのように設定および強制されるかを参照してください。このセクションは、機能をオンにしてチューニングする gateway.yaml キーをカバーします。

admin:
  # 管理エンドポイント用の名前付き静的 API キー。x-api-key として送信されます。
  # ID は監査ログに admin-key:<id> として表示されるため、各キーは
  # 属性可能です。回転用の配列：新しいキーを追加し、クライアントをロール、
  # 古いものを削除します。
  write_keys:
    - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
    - { id: ci,        key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
  read_keys:
    - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
  # 通常のゲートウェイ JWT（API キーなし）経由で完全な管理者を付与された IdP グループ。
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits
フィールド 必須 説明
write_keys いいえ {id, key} の配列。これらのいずれかと一致する x-api-key は、支出制限をリスト、設定、削除できます。キー値は少なくとも 32 文字である必要があります。id は read_keys と write_keys 全体で一意である必要があります。
read_keys いいえ {id, key} の配列。読み取り専用：すべての GET エンドポイント。キャップのリスト、ID による 1 つの取得、/effective と /audit の読み取りを含みます。
admin_groups いいえ IdP グループ名。groups クレームがこれらのいずれかを含むゲートウェイ JWT は、完全な管理者アクセス、読み取りと書き込みを持ち、oidc:<sub> として監査されます。人間の管理者に使用します。マシンに API キーを使用します。このリストの空のエントリはゲートウェイをブート時に停止します。ゲートウェイをブート時に停止するマッチャー値を参照してください。
blocked_message いいえ ブロックされた開発者が見る 429 billing_error に逐語的に追加されます。URL または Slack チャネルなど、完全な指示を書きます。未設定の場合、ゲートウェイはデフォルトメッセージのみを送信します。強制がどのように機能するかを参照してください。
audit_retention_days いいえ デフォルト 365。古い admin_audit 行はスイープされます。
spend_retention_months いいえ デフォルト 13。この期間より古い spend カウンター行はスイープされます。デフォルトは、年間比較レポート用に完全な年と現在の部分月を保持します。
identity_retention_days いいえ デフォルト 90。principal_emails 行の最後に見た TTL。各開発者のメール、表示名、グループ（PII）を保持します。意図的に支出保持より短いため、プロビジョニング解除されたアイデンティティは、その匿名支出カウンターが残っている間に期限切れになります。
group_limit_mode いいえ min（デフォルト）または max。開発者が複数のグループにキャップがある場合、min は最も制限的なものを強制し、max は最も制限的でないものを強制します。強制と /effective の両方で使用されます。

`enforcement`

enforcement ブロックは、ストアが利用できない場合の支出制限チェックの動作を制御します。

フィールド 必須 説明
fail_closed_on_error いいえ デフォルト false。支出強制は Postgres 停止時にオープンで失敗するため、推論は稼働したままです。true に設定してクローズで失敗：上限を超えた開発者はブロックされますが、ストアに到達できない場合は他のすべてもブロックされます。admin: ブロックが必要です：支出強制は admin が設定されている場合にのみ実行され、これを true に設定して admin ブロックなしでゲートウェイは起動を拒否します。

`pricing`

pricing ブロックは、支出メーターに USD リスト価格の代わりに請求する内容を指示するため、キャップと /effective は契約レートを反映します。金額は USD のままで、請求書ではなく見積もりのままです。2 つの前提条件：

  • ゲートウェイサーバー上の Claude Code v2.1.227 以降。以前のバージョンはブート時に不明なキーを拒否します。
  • admin: ブロック。支出メーターのみが pricing を読み込むためです。ゲートウェイは pricing が設定されていて admin がない場合、起動を拒否します。
pricing:
  multiplier: 0.85
  overrides:
    - upstream: bedrock-eu
      model: claude-sonnet-4-6
      input: 3.30
      output: 16.50
      cache_read: 0.33
      cache_write: 4.125
フィールド 必須 説明
multiplier いいえ デフォルト 1。メーターはリスト価格またはオーバーライドされたかどうかに関わらず、すべてのメーター量にこれを乗算するため、0.85 は価格の 85% を請求します。0 より大きく、最大 1 である必要があります。
overrides いいえ {upstream, model, input, output, cache_read, cache_write} の行。USD/百万トークン。4 つのレートすべてが必須で、正の値である必要があります。

メーターがオーバーライド行をマッチする方法：

  • 行は、upstream（upstreams[].name）が model に対して提供するリクエストのリスト価格を置き換えます。これには、より高い 高速モード レートが含まれるため、高速と標準リクエストは同じ 4 つのレートでメーターされます。
  • claude-sonnet-4-6 などの組み込み ID（models[].id のようにマッチ）は、メーターがそのモデルとして価格設定するすべての日付形式、地域 Amazon Bedrock 形式、または Google Cloud の Agent Platform 形式をカバーします。エイリアスまたは推論プロファイル ARN などの他の文字列は、クライアントが送信した ID またはアップストリームに送信された文字列と大文字小文字を区別せずにマッチします。
  • 行が重複する場合、メーターは最初の行ではなく最も具体的な行を選択します：アップストリームに送信された正確なモデル文字列である model を持つ行、次にクライアントが送信した正確な ID にマッチする行、次に組み込みモデルに名前を付ける行。
  • 不明なアップストリーム名はブートに失敗し、1 つのアップストリームに対して同じモデルに名前を付ける 2 つの行も失敗します。これには、組み込みモデルの 2 つのスペルが含まれます。ゲートウェイはブート時に、リクエスト可能なモデルが使用できない行について警告します。
  • Web 検索リクエストは $0.01 リスト価格のままです。乗算器はそれらにも適用されます。

地域ごとのレートについては、各地域に独自の名前付きアップストリームを指定し、アップストリームごとに 1 つの行を指定します。

`models`

models ブロックはオプションの管理者がキュレーションしたモデルリストで、/v1/models で提供され、アップストリームごとのモデル ID を変換するために使用されます。US 以外の Amazon Bedrock リージョン、Amazon Bedrock プロビジョニングスループット ARN、Microsoft Foundry デプロイメント名に必須です。

auto_include_builtin_models: true   # false：以下のリストのみを公開
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    # description：オプションのテキスト。クライアントに表示される場合がある
    upstream_model:
      anthropic: claude-opus-4-8
      bedrock: us.anthropic.claude-opus-4-8   # または推論プロファイル ARN
      foundry: your-opus-deployment-name

upstream_model の下の各キーは、設定されたアップストリームの name と一致する必要があります。デフォルトはプロバイダー名です。アップストリームと一致しないキーはブートに失敗するため、使用しないプロバイダーの行は省略します。

`managed`

managed ブロックは、IdP グループまたはメールドメインでキーイングされた、ロールベースのアクセスポリシーを定義します。ポリシーは順番に評価されます。最初のマッチが選択され、以下で説明する match: {} キャッチオール基盤にマージされます。ユーザーごとに GET /managed/settings で ETag/304 キャッシング付きで提供されます。

managed:
  policies:
    # 特定のグループを最初に。
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        permissions: { deny: ["WebFetch", "WebSearch"] }
    # デフォルトキャッチオール最後：認証されたすべてのユーザーにマッチします。
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

match: {} キャッチオール。慣例的に最後にリストされます。基盤層として扱われます。他のすべてのポリシーは、設定しないキーについてキャッチオールから継承するため、ロール別エントリは組織デフォルトから異なるものだけをリストする必要があります。マージルールはキータイプに依存します：

  • 許可リスト：availableModels と permissions.allow。特定のポリシーのリストは基盤のリストを完全に置き換えます。
  • 拒否リストとフックアレイ：permissions.deny、permissions.ask、disabledMcpjsonServers、deniedMcpServers、blockedMarketplaces、およびすべての hooks イベントタイプアレイ。これらは基盤とポリシーの和集合を取得するため、組織全体の拒否または監査フックは、ロール別オーバーライドによって誤ってドロップされることはできません。
  • レコードタイプキー：env、modelOverrides、skillOverrides。これらは浅くマージするため、ロール別 env ブロックは設定するキーをオーバーライドし、基盤から残りを継承します。

availableModels は /v1/messages でサーバー側でも強制されるため、拒否されたモデルはクライアントが送信するものに関わらず 400 を返します。

ゲートウェイはリクエストをリレーする前に model 値自体を検証するため、形式が正しくない値がアップストリームに到達することはありません。2 つのケースで 400 でリクエストを拒否します：

  • 値が欠落しているか空の場合、ゲートウェイはメッセージ model is required でリクエストを拒否します。このチェックには Claude Code v2.1.228 以降を実行しているゲートウェイが必要です。
  • 値が存在しているが文字列ではない場合、ゲートウェイはメッセージ model must be a string でリクエストを拒否します。Claude Code v2.1.221 以降を実行しているゲートウェイが必要です。
マッチャー 動作
match: {} 認証されたすべてのユーザーにマッチします。これで開始し、後で上にグループスコープポリシーを追加します。
match: { groups: [a, b] } JWT の groups クレームがリストされたグループのいずれかを含む場合にマッチします。大文字小文字を区別します：グループは IdP の正確な大文字小文字と一致する必要があります。
match: { email_domain: example.com } JWT の email クレームの最後の @ の後の部分にマッチします。大文字小文字を区別しません。ポリシーごとに 1 つのドメインを受け入れます。
match: { groups: [a], email_domain: example.com } 両方の条件がマッチする必要があります。

ポリシーにマッチしない認証されたユーザーは、ゲートウェイのデフォルトを取得します。これは、カタログ内のすべてのモデルと管理設定なしを意味します。最後に match: {} キャッチオールを追加して、保証されたデフォルトポリシーが必要な場合。

ゲートウェイをブート時に停止するマッチャー値

ブート時に、ゲートウェイはすべてのポリシーの match ブロックと admin_groups リストをチェックします。これらの値のいずれかがゲートウェイをフィールドに名前を付けるエラーで停止します：

  • 空の groups リスト
  • groups または admin_groups の空のエントリ
  • 空の email_domain
  • @、空白、またはコンマを含む email_domain。ゲートウェイはこのチェック前に値をトリムし、1 つの先頭 @ を削除します。example.com などの 1 つの裸のドメインを書きます。

v2.1.232 より前では、ゲートウェイはこれらの値で起動しました。各値はこの効果を持っていました：

  • 空の email_domain：ゲートウェイはドメインチェックをスキップしたため、空の email_domain と groups リストなしのポリシーはすべての認証されたユーザーにマッチしました。
  • 空の groups リスト：ポリシーは誰にもマッチしませんでした。
  • @、空白、またはコンマを含む email_domain：ポリシーは誰にもマッチしませんでした。
  • groups または admin_groups の空のエントリ：エントリはそのユーザーの IdP groups クレームも空のエントリを含む場合にのみユーザーにマッチしました。admin_groups では、そのマッチは管理者アクセスを付与しました。admin_groups リストに空のエントリが含まれていない場合、誰もこの方法で管理者アクセスを取得しませんでした。

`cli` に何が入るか

各 cli 値は、完全な Claude Code managed-settings.json ドキュメント。MDM または /etc/claude-code/managed-settings.json を通じてデプロイするのと同じスキーマ。ここでは YAML として表現されます。CLI は、マネージド層で配信されたドキュメントを適用します。ユーザーとプロジェクト設定の上。サーバー管理設定の代わりに。したがって、OS レベルのポリシーソースに制限されている設定（policyHelper と wslInheritsWindowsSettings など）を無視します。

ゲートウェイは、ブート時に CLI の設定スキーマに対して各ドキュメントを検証するため、認識されないトップレベルキーはすべての違反キーに名前を付けるエラーでブートに失敗します。スキーマの意図的にオープンな部分は、新しいクライアントがゲートウェイのスキーマが認識しないエントリを認識する可能性があるため、任意の値を受け入れます。これらのオープンキーは env、pluginConfigs、permissions の下にネストされたキーです。

検証はゲートウェイのインストール済みバージョンにバンドルされたスキーマを使用するため、新しい Claude Code リリースで導入されたトップレベル設定キーをマネージド設定に入れるには、最初にゲートウェイをアップグレードする必要があります。新しいポリシーを 1 つのクライアントでスモークテストしてから、ロールアウトします。

完全なキーリファレンスは Claude Code 設定 にあります。オペレーターが最初に到達するキー：

managed:
  policies:
    - match: {}
      cli:
        # モデルアクセス（/v1/messages でサーバー側でも強制）
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

        # 権限ポリシー
        permissions:
          deny:
            - "WebFetch"
            - "Read(./.env)"
            - "Read(./secrets/**)"
          disableBypassPermissionsMode: disable   # --dangerously-skip-permissions をブロック
        allowManagedPermissionRulesOnly: true     # ユーザー/プロジェクト権限ルールを無視

        # CLI プロセスにプッシュされた環境。DISABLE_UPDATES はバックグラウンドと手動更新をブロック；DISABLE_AUTOUPDATER はバックグラウンド更新のみを停止。
        env:
          DISABLE_UPDATES: "1"                    # 独自の配布経由でバージョンをピン

        # 組織全体のフック。フックコマンドはゲートウェイではなく開発者マシンで実行されるため、パスはポリシー内のすべてのクライアント OS に存在する必要があります。
        hooks:
          PostToolUse:
            - matcher: "Edit|Write"
              hooks:
                - { type: command, command: /usr/local/bin/audit-edit.sh }
キー 強制者 効果
availableModels ゲートウェイ + CLI モデル許可リスト。/v1/messages でもチェックされるため、パッチされたクライアントはバイパスできません。
permissions.allow / .deny CLI ツールとコマンドルール。権限を参照してください。
permissions.disableBypassPermissionsMode CLI disable に設定して bypassPermissions をブロック。すべてのツール呼び出しを自動承認するモード、および --dangerously-skip-permissions フラグ。
allowManagedPermissionRulesOnly CLI true の場合、マネージド設定は権限ルールの唯一の設定ソースになります。allowManagedPermissionRulesOnly エントリは Claude Code がその後無視するすべてのソースをリストします。
env CLI CLI プロセスにマージされた環境変数。テレメトリ、自動更新、モデル名オーバーライドに使用します。
hooks CLI 組織全体の フック。
managedMcpServers CLI リモート MCP サーバー マッチする開発者ごとに提供。彼らが自分で追加するサーバーの横に、http と sse のみ。ポリシー内の MCP サーバーを参照してください。ゲートウェイサーバーとクライアント上で Claude Code v2.1.259 以降が必要です。以前のクライアントはキーを無視します。

これらの設定はネットワーク経由で到着するため、CLI は以下にリストされた設定を適用する前に、各開発者にセキュリティ承認ダイアログを表示します：

  • hooks
  • プロキシとベース URL 変数など、開発者の承認が必要な env 変数
  • apiKeyHelper と statusLine などのシェル実行設定
  • サンドボックスバイナリ設定 sandbox.bwrapPath、sandbox.socatPath、sandbox.ripgrep
  • sandbox.network.tlsTerminate とプロキシポート設定など、トラフィックをインターセプト、認証情報を注入、または分離を弱める Sandbox 設定。セキュリティ承認ダイアログはすべてをリストします。

承認メモリは、承認がどのくらい続くか、およびダイアログが再度表示されるときをカバーします。

Claude Code は、モデル選択設定や数値制限など、開発者の承認ダイアログを表示せずに配信された env 変数の一部を適用します。他の配信変数は、開発者の承認が必要な場合があります。空でないプロキシ、ベース URL、または OTEL_EXPORTER_OTLP_ENDPOINT 値は常にそうです。配信変数が承認を必要とする場合、ダイアログはそれに名前を付けます。

環境変数と承認ダイアログには詳細があります。配信値が承認を必要とするかどうかを決定する 4 つのプライバシートグルを含みます。v2.1.218 より前では、Claude Code はより少ない変数を開発者に尋ねずに適用したため、より多くの配信変数がダイアログをトリガーしました。

ゲートウェイの テレメトリ 設定は OTEL_EXPORTER_OTLP_ENDPOINT をプッシュするため、telemetry.forward_to を設定すると、各インタラクティブクライアントで承認ダイアログがトリガーされます。ダイアログは、組織から開発者を保護するのではなく、開発者のマシンを侵害または敵対的なゲートウェイから保護します。

-p フラグを使用した非インタラクティブ実行はダイアログを表示できません。その実行のみのためにプッシュされた設定を適用し、それらを承認済みとして記録しないため、開発者の次のインタラクティブセッションはまだダイアログを表示します。v2.1.207 より前では、非インタラクティブ実行は設定を承認済みとして保存し、後のインタラクティブセッションはそれらのダイアログを表示しませんでした。

開発者が拒否した場合、Claude Code はポリシーを適用せずにそのセッションを終了します。新しいフックまたはダイアログをトリガーする env var を広いポリシーにプッシュすることは、Claude Code がマッチする開発者に次の起動時にダイアログを表示することを意味します。ダイアログは実行中のセッションで次の時間ごとのポーリング時に表示され、そうでなければ開発者の次の起動時に表示されます。

cli キーは以前のリリースで settings という名前でした。その綴りはまだエイリアスとして受け入れられていますが、新しいデプロイメントは cli を使用する必要があります。

ポリシー内の MCP サーバー

ポリシーが一致する Claude Code クライアントに MCP サーバーを提供するには、そのポリシーの cli ブロックで managedMcpServers を設定します。ゲートウェイサーバーとクライアント上で Claude Code v2.1.259 以降が必要です。

ゲートウェイは Claude Code がクライアントで適用するのと同じルールで各エントリをブート時にチェックし、エントリがチェックに失敗した場合、ゲートウェイは起動を拒否してエントリに名前を付けます。

gateway.yaml に ${VAR} 参照を書く場合、ゲートウェイはブート時に シークレット展開 を通じてその環境から解決するため、マッチする各クライアントはリテラル値を受け取り、それを読み込むことができます。提供されたサーバーのヘッダーガイダンスは展開された値に適用されます。

ゲートウェイは cli ブロック内の .mcp.json スペル mcpServers を拒否し、ブートエラーは使用するキーとして managedMcpServers に名前を付けます。v2.1.259 より前では、ゲートウェイは cli ブロック内の MCP サーバー定義を拒否しました。

Claude Desktop オーバーレイ

組織が Claude Desktop もデプロイする場合、同じゲートウェイが両方のクライアントに提供します。Claude Desktop の マネージド設定 で bootstrapUrl を <listen.public_url>/user/bootstrap にポイントします。Claude Desktop はその URL から OAuth 発行者を導出し、このゲートウェイに対して同じデバイスコード サインインを実行し、レスポンスから設定を取得します。

ゲートウェイはレスポンスの多くをマッチしたポリシーの cli ブロックとトップレベルゲートウェイ設定から導出します：

  • モデルリスト。availableModels から

  • 無効なツール。裸のツール名 permissions.deny エントリから。ポリシーの desktop ブロックで disabledBuiltinTools を設定する場合、ゲートウェイはあなたの値と導出されたリストの和集合を提供するため、この方法でより多くのツールを無効にできますが、permissions.deny を通じて無効にしたものを再度有効にすることはできません。

  • エグレス許可リスト。sandbox.network.allowedDomains から。ポリシーの desktop ブロックで coworkEgressAllowedHosts を設定する場合、ゲートウェイは導出されたリストの代わりにその値を使用します。

  • ゲートウェイ自体をポイントする OTLP エンドポイント。これは宛先にファンアウトします。telemetry フォワーディングが設定されている場合に含まれます。

    Claude Desktop はすべてのシグナルを 1 つのエンコーディングでエクスポートします：http/protobuf、またはポリシーの env で OTEL_EXPORTER_OTLP_PROTOCOL またはそのシグナルごとのバリアントを http/json に設定する場合は http/json。ゲートウェイサーバー上の Claude Code v2.1.261 より前では、レスポンスは関係なく http/json を設定したため、protobuf のみを受け入れるコレクターは Claude Desktop のエクスポートを拒否しました。

ポリシーの desktop ブロックで disabledBuiltinTools、coworkEgressAllowedHosts、または Claude Desktop 独自の managedMcpServers 設定を設定するには、ゲートウェイサーバー上で Claude Code v2.1.232 以降が必要です。Claude Desktop の managedMcpServers はオブジェクトではなく配列値を取ります。

ゲートウェイは Claude Desktop 相当がないキー（hooks やスコープ権限ルール（Bash(npm *) など））をブートストラップレスポンスから省略します。

cli の横にオプションの desktop ブロックを追加して、Claude Desktop 設定を直接設定します。Claude Desktop の マネージド設定リファレンス からの設定を平坦なキー名として書きます。ゲートウェイが読み込むのみのキー（bootstrapUrl など）を省略します。MDM またはローカルファイルから。ゲートウェイはブート時にそれらを拒否します。v2.1.232 より前では、ゲートウェイは chatTabEnabled と disableAutoUpdates などの固定リストの 11 個の機能ゲートキーを受け入れ、他のすべてのキーをブート時に拒否しました。v2.1.227 より前では、ゲートウェイは chatTabEnabled と chatAdvancedFileAnalysisEnabled もブート時に拒否しました。

managed:
  policies:
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
      desktop:
        isLocalDevMcpEnabled: false
        disableAutoUpdates: true
        banner: { text: "Contractor build: internal use only" }

すべてのキーはオプションです。Claude Desktop は省略したキーに対して独自のデフォルトを適用します。ゲートウェイは各 desktop ブロックをブート時に Claude Desktop 自体が使用する設定スキーマに対して検証するため、間違いはゲートウェイ起動時にキーに名前を付けるエラーとして表示され、接続されたすべてのデスクトップに到達しません。ゲートウェイはブロックに以下が含まれる場合に失敗します：

  • 不明なキー
  • Claude Desktop が拒否または無言でドロップするであろう認識されたキー。空の値やネストされたエントリ内のスペルミスされたサブキーなど。v2.1.260 より前では、ゲートウェイは managedMcpServers または orgPluginSettings エントリのネストされたオブジェクト内のスペルミスされたフィールドを無言でドロップしました。ブート時に失敗する代わりに。
  • ゲートウェイが自身で計算するキー：推論接続、モデルリスト、OTLP リレー。upstreams、models、telemetry セクションの forward_to を通じてそれらを設定します。
  • 現在のキーのレガシーエイリアス。ブートエラーで、ゲートウェイは書くべき正規キーに名前を付けます。

非推奨の値またはエントリ形状（transport なしの managedMcpServers エントリなど）を使用する場合、ゲートウェイは起動し、置き換えに名前を付ける警告をログします。

ゲートウェイは desktop ブロックを cli ブロックと同様にインストール済みバージョンにバンドルされたスキーマに対して検証します。新しい Claude Desktop リリースで導入された設定を配信するには、最初にゲートウェイをアップグレードします。例えば、userPluginMarketplacesEnabled と userPluginUploadsEnabled はゲートウェイサーバー上で Claude Code v2.1.260 以降と Claude Desktop 1.37937.0 以降が必要です。メンバーのマシン上で。

ポリシーの desktop ブロックで orgPluginSettings を設定する場合、ゲートウェイは Claude Desktop 1.15200.0 以降が読み込む配列形式で提供します。古いデスクトップは配列を無視し、プラグインツールポリシーを強制しないため、それに依存する前にメンバーを 1.15200.0 以降に更新します。

ゲートウェイはポリシーの desktop ブロックが設定しないキーを match: {} キャッチオールの desktop ブロックから埋めます。ポリシーの cli ブロックを基盤から埋めるのと同じ方法で。ベースとロールポリシーの両方で disabledBuiltinTools または builtinToolPolicy を設定する場合、ゲートウェイはベースの制限を保持します：

  • disabledBuiltinTools：ゲートウェイはベースのリストとポリシーのリストの和集合を使用します。
  • builtinToolPolicy：ベースでツールを allow 以外の値に設定する場合、ゲートウェイはロールポリシーで同じツールに対して allow を設定しても、その値を保持します。

他のすべてのキーについて、ロールポリシーで設定する場合、ゲートウェイはロールポリシーの値を使用します。ゲートウェイは配列またはネストされたオブジェクト（banner など）を全体で置き換えるため、ロールポリシーで banner.text を設定する場合、ゲートウェイはベースの banner.backgroundColor をドロップします。

Claude Desktop をデプロイしない場合、ポリシーから desktop を完全に省略します。ゲートウェイはその後、すべてのユーザーに対して /user/bootstrap から 404 を返します。

他のマネージドソースとの優先順位

デバイスに MDM 配信ポリシーまたはローカル managed-settings.json もある場合、ゲートウェイ配信設定がランク付けされます。最初。マネージド層内の優先順位はマネージド設定ページで、ローカルソースが適用される場合を説明し、すべての管理ソースから読み込まれる Claude Code キーを持っています。サンドボックスロックキー、forceRemoteSettingsRefresh、変数ごとの env マージなど、どのソースを選択したかに関わらず。policyHelper は MDM プロファイルまたはマネージド設定ファイルで設定され、ゲートウェイが設定を配信しない場合にのみ実行されます。エントリは出力が置き換えるものを説明します。

Claude Desktop などの埋め込みホストは SDK managedSettings オプションを通じてポリシーを提供できます。埋め込みホストからの親設定は Claude Code がそれを適用する場合を説明し、親設定を制限は allowManaged*Only ロックなしでもまだ適用される許可方向設定をリストします。

ゲートウェイポリシーはマシン上のすべての Claude Code 呼び出しに適用されます。非インタラクティブ claude -p 実行と Agent SDK によって生成されたセッションを含みます。ゲートウェイがスタートアップ時に到達不可能な場合、署名されたセッションはポリシーなしで実行するのではなく、エラーで終了します。

`telemetry`

CLI は OpenTelemetry Protocol（OTLP）を HTTP メトリクス、ログ、有効な場合はトレースでゲートウェイに送信します。ゲートウェイはそれらを逐語的に各設定先にリレーします。使用状況の監視で、CLI が発行するメトリクスとイベントを参照してください。

CLI は、ゲートウェイ発行 JWT から読み込まれた認証されたユーザーのアイデンティティで各エクスポートにスタンプを付けます：user.id、user.email、user.groups 属性。開発者ごとのコストと使用状況の属性は、開発者側の設定なしで機能します。

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      # シグナルごとのオプトイン。デフォルト：メトリクスのみ。
      metrics: true
      logs: false
      traces: false
    - url: https://api.datadoghq.com/api/v2/otlp
      headers:
        DD-API-KEY: ${DD_API_KEY}

各 forward_to URL は https:// を使用する必要があります。ゲートウェイ独自のループバックインターフェース上のコレクターの場合は 1 つの例外：

  • http://localhost:<port> は設定検証を通過しますが、SSRF ガードは ECONNREFUSED_SSRF ですべてのエクスポートをブロックします。CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 をゲートウェイの環境に設定しない限り。
  • http://127.0.0.1:<port> または http://[::1]:<port> はその変数が設定されていない限りブートに失敗します。

クラスター内コレクターの場合、HTTPS で独自の内部アドレスで公開するか、変数が設定されたサイドカーとして実行します。

テレメトリは CLI でデフォルトでオフです。telemetry.forward_to を listen.public_url と一緒に設定するとオンになります。ゲートウェイは 6 つの env var を /managed/settings を通じてすべての接続されたクライアントにプッシュします：

  • CLAUDE_CODE_ENABLE_TELEMETRY=1
  • OTEL_METRICS_EXPORTER=otlp
  • OTEL_LOGS_EXPORTER=otlp
  • OTEL_TRACES_EXPORTER=otlp
  • OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
  • OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

プッシュされたエンドポイントはパブリック URL から構築されるため、メトリクスとログは開発者またはポリシーからの OTEL 設定を必要としません。プッシュされた設定はマネージド層で適用され、開発者がローカルで設定する OTEL_* 変数をオーバーライドします。ゲートウェイがこれらの変数をプッシュするかどうかに関わらず、/login を通じてサインインした CLI が OTLP/HTTP エクスポート有効にしたものは、ローカルに設定されたエンドポイントではなく、ゲートウェイにエクスポートを送信し、シグナルの forward_to 宛先がない場合、ゲートウェイはそれを受け入れて破棄します。Claude Code テレメトリを直接収集する場合は、コレクターを forward_to 宛先として追加します。

トレースはさらに各クライアントで CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 を必要とします。ゲートウェイはその変数をプッシュしないため、マネージドポリシーの env ブロックを通じて設定します。これは Claude Code が開発者の承認なしで適用する変数の中にはないため、ポリシーを通じてそれを配信することは、プッシュされた OTLP エンドポイントがすでてトリガーする同じ セキュリティ承認ダイアログでカバーされます。

protobuf と JSON OTLP エンコーディングの両方がリレーされ、OpenTelemetry 互換バックエンドは宛先として機能します。

HTTP チューニング

4 つのオプションのトップレベルブロック、access_control、limits、timeouts、rate_limits。HTTP サーフェスをチューニングします。デフォルトはほとんどのデプロイメントに適しています。

ブロック キー デフォルト 説明
access_control allow_cidrs / deny_cidrs 空 trusted_proxies 解決後のクライアントアドレスによるインバウンド IP 許可/拒否。deny_cidrs が最初にチェックされます。クライアントがマッチする場合、allow_cidrs もマッチしても拒否されます。allow_cidrs が空でない場合、ゲートウェイはデフォルト拒否です。/healthz と /readyz は allow_cidrs から除外されます。信頼できるプロキシが X-Forwarded-For エントリを送信し、それが IP アドレスではない場合、実際のクライアントは不明で、ゲートウェイは何をチェックするかに名前を付ける警告を 1 回ログします。どちらかのリストがリクエストに適用される場合、それはリクエストを拒否し、403 と監査理由 xff_unparseable を返します。どちらでもない場合、リクエストを提供し、プロキシ独自のアドレスを IP ごとのレート制限と監査のクライアント IP として使用します。
limits max_request_bytes 32 MiB 最大インバウンドリクエストボディ。サイズを超えるリクエストはボディがバッファリングされる前に 413 を取得します。大きなファイルまたは画像リクエストの場合は増やします。
limits max_request_header_bytes 未設定 設定すると、サイズを超えるヘッダーは 431 を返します。
limits max_url_length 未設定 設定すると、長すぎる URL は 414 を返します。
timeouts upstream_ttfb_ms 120000 アップストリームのレスポンスヘッダー（初バイト時間）を待つ最大時間。レスポンスボディはその後、ウォールクロックキャップなしでストリーミングされます。直接 Anthropic アップストリームパスに適用されます。他のすべてのプロバイダーはプロバイダー SDK 独自のタイムアウトで制限されます。
rate_limits device_authorization.max / .window_seconds 30 / 600 認証されていないデバイス認可エンドポイントの IP ごとのレート制限。共有エグレス IP または NAT の背後にある大規模な組織の場合は増やします。これらの制限は、デバイスグラント サインインフローにのみ適用され、/v1/messages 推論には適用されません。ユーザーコードブルートフォース耐性を参照してください。
rate_limits device_verify.max / .window_seconds 10 / 600 /device での user_code 送信の IP ごとのレート制限。

完全な例

この完全なリファレンス設定はすべてのコアセクションを実行します。HTTP チューニングブロックはデフォルトを保持します。コピーして、不要なものを削除し、値を入力します。クイックスタートの設定はこれの最小バージョンです。

# 実行：
#   claude gateway --config gateway.yaml
#
# 運用ログの詳細度は CLAUDE_GATEWAY_LOG_LEVEL
# 環境変数で制御されます（debug | info | warn | error；デフォルト info）。debug
# は各 id_token のクレーム名もログに記録します。groups_claim 診断用です。
# 監査イベントには影響しません。常に発行されます。

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com
  # TLS 終了 ingress の背後で実行する場合は tls ブロックを省略します。
  # tls:
  #   cert: /certs/gateway.crt
  #   key: /certs/gateway.key
  # trusted_proxies:
  #   - 10.0.0.0/8

oidc:
  issuer: https://example.okta.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains:
    - example.com
  # Okta org サーバーが発行者の場合は必須。id_token はメールとグループを省略できます。ゲートウェイは /userinfo から埋めます。
  userinfo_fallback: true
  # allowed_groups: [claude-code-users]
  # Okta はグループスコープがリクエストされ、アプリのグループクレームフィルターが許可する場合のみグループを発行します。以下のコントラクターポリシーはグループでマッチするため、スコープはここでリクエストされます。
  scopes: [openid, profile, email, offline_access, groups]
  # extra_auth_params: { access_type: offline, prompt: consent }  # Google
  # groups_claim: groups          # Entra アプリロール：`roles` を使用
  # email_claim: email

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}   # openssl rand -base64 32
  # ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}
  # max_connections: 5

# /v1/organizations/spend_limits を有効にします（Anthropic Admin API をミラーリング）
# および /v1/messages での開発者ごとの支出強制。無効にするには省略します。
# キャップ自体は admin API 経由で設定されます。ここではありません。
# admin:
#   write_keys:
#     - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
#   read_keys:
#     - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
#   admin_groups: [platform-finops]
#   blocked_message: request an increase at https://go.example.com/claude-limits
#   # audit_retention_days: 365
#   # spend_retention_months: 13
#   # identity_retention_days: 90
#   # group_limit_mode: min

# enforcement:
#   fail_closed_on_error: false

# 契約レートで USD リスト価格の代わりにメーターします。admin: が必要です。
# 以下のレートはプレースホルダーであり、実際の契約価格ではありません。
# pricing:
#   multiplier: 0.85
#   overrides:
#     - { upstream: anthropic, model: claude-sonnet-4-6, input: 3.30, output: 16.50, cache_read: 0.33, cache_write: 4.125 }

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

  # - provider: bedrock
  #   region: us-east-1
  #   auth: {}

  # - provider: anthropicAws
  #   region: us-east-1
  #   workspace_id: wrkspc_...
  #   auth:
  #     api_key: ${ANTHROPIC_AWS_API_KEY}

  # - provider: vertex
  #   region: us-east5
  #   project_id: example-prod
  #   auth: {}

  # - provider: foundry
  #   resource: example-foundry
  #   auth: { use_azure_ad: true }

auto_include_builtin_models: true
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      anthropic: claude-opus-4-8
      # bedrock: us.anthropic.claude-opus-4-8
      # anthropicAws: claude-opus-4-8
      # vertex: claude-opus-4-8
      # foundry: <your-opus-deployment-name>
  - id: claude-sonnet-4-6
    label: Claude Sonnet 4.6
    upstream_model:
      anthropic: claude-sonnet-4-6
  - id: claude-haiku-4-5
    label: Claude Haiku 4.5
    upstream_model:
      anthropic: claude-haiku-4-5

managed:
  policies:
    - match: { groups: [contractors] }
      cli:
        availableModels: [claude-haiku-4-5]
        # Default ピッカーオプションを availableModels に制限します。デフォルトの代わりに、コントラクターが default で 400 を取得しないようにします。
        enforceAvailableModels: true
        # allow はこれらのツールを自動承認します。残りをブロックしません。
        # ツールを制限するには deny ルールを追加します。
        permissions: { allow: [Read, Grep] }
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        permissions:
          allow: [Read, Grep, Bash, Edit]
          deny: ["WebFetch"]
        env: { HTTP_PROXY: http://proxy.example.com:8080 }

telemetry:
  forward_to:
    - url: https://otel.internal.example.com:4318
      headers:
        Authorization: Bearer ${OTEL_TOKEN}

クライアント側マネージド設定

上記のすべてはゲートウェイサーバーを設定します。開発者マシンをそれに指すことは、各デバイスで別々に設定されます。Claude Code の マネージド設定 を通じて。ゲートウェイはログインキーをプッシュできません。これらのキーがクライアントにゲートウェイがどこにあるかを伝えるものだからです。

CLI の場合、OS ごとの managed-settings.json にこれら 2 つのログインキーを設定します。各開発者の /login をゲートウェイにルーティングします：

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge"
}

parentSettingsBehavior: "merge" は Claude Desktop の出力許可リストの配信をその埋め込み Claude Code セッションに対して機能させ続けます。Claude Desktop セッションにポリシーを配信する はメカニズムとオプトインが必要な場所を説明しています。

managed-settings.json ファイルを各デバイスにデプロイします。通常は MDM プラットフォーム経由。ファイルパスはプラットフォームによって異なります：

プラットフォーム パス
macOS /Library/Application Support/ClaudeCode/managed-settings.json、または com.anthropic.claudecode マネージド設定ドメイン
Linux と WSL /etc/claude-code/managed-settings.json
Windows C:\Program Files\ClaudeCode\managed-settings.json、または HKLM レジストリ経由のグループポリシー

デフォルトでは、Windows のレジストリポリシーまたは macOS のマネージド設定 plist は、上記の例外キーとクロスソースチェック を除き、managed-settings.json ファイルを置き換えるのではなくマージします。このスニペットの 3 つのキーはすべて最優先ソースルールに従うため、グループポリシーまたは設定プロファイルを通じてポリシーを配信するフリートは、代わりにそのメカニズムにすべて 3 つを配置する必要があります。

Claude Desktop の場合、Claude Desktop 独自の マネージド設定 で bootstrapUrl キーを <listen.public_url>/user/bootstrap に設定します。サインインフローとグループごとのポリシーは、ポリシーが desktop キーでサーバー側でオプトインされると CLI のものと一致します。オプトインなしでは、/user/bootstrap は 404 を返します。Claude Desktop オーバーレイ を参照してサーバー側の部分を確認してください。

forceLoginGatewayUrl と forceLoginMethod の "gateway" 値は、マシン上のマネージドソースからのみ尊重されます：managed-settings.json、macOS plist または Windows HKLM レジストリ、またはポリシーヘルパー。開発者が独自の ~/.claude/settings.json で設定しても効果がありません。ゲートウェイペイロードで設定しても同様です。