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、AWS 上の Claude Platform、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 に直接書き込まないでください。以下のいずれかの形式で参照すると、ゲートウェイはブート時に環境変数またはファイルから値を解決します：

必須セクション

`listen`

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

`oidc`

oidc ブロックはゲートウェイをアイデンティティプロバイダーに接続し、誰がサインインできるかを決定します。発行者と OAuth クライアントに名前を付け、メールとグループを含むクレームをマップし、メールドメインまたはグループによるサインインを制限します。

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

フォワードプロキシを通じた 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 ブロックはサインイン後にゲートウェイが鋳造するベアラートークンを形成します。それらに署名するシークレットと、どのくらい長く生きるかです。

`store`

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

ローカル開発の場合、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 はそのアップストリームが要求されたモデルを提供しないことを意味するため、リスト内の後のアップストリームはまだそれを提供できます。

アップストリームで forward_user_identity: true を設定する場合、開発者のメールを含むリクエストに返す 429 はフェイルオーバーしません。per-user limit denial が開発者に到達する方法を参照してください。

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

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

Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、Microsoft Foundry クライアントはスタートアップ時に一度構築され、それらの 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}
    # OR an OAuth bearer (e.g. a Workload-Identity-Federation-exchanged token):
    #   oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
    # base_url: https://api.anthropic.com   # default; override for a forward proxy

2 つの認証情報フォームは送信するヘッダーが異なります。

• api_key。x-api-key を送信します。Claude Console でローテーションし、環境変数を更新します。
• oauth_token。Authorization: Bearer を送信します。組織が長期 API キーではなく短期トークンを発行する場合、ベアラーフォームを使用します。ベアラーはスタートアップ時に一度読み取られるため、シークレットを再マウントして再起動することでリフレッシュします。

静的キーまたはベアラーの代わりに、Workload Identity Federation を使用できます。Workload Identity Federation ガイドに従って 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_...       # required if the rule covers >1 workspace
      # service_account_id: svac_...   # optional expected-target check

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

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

プロキシが開発者のメールを含むリクエストに 429 で応答する場合、ゲートウェイはその応答を開発者にそのまま返し、次のアップストリームにフェイルオーバーしません。プロキシの per-user バジェットまたはレート制限が保持されます。プロキシの他の応答は通常のフェイルオーバールールに従います。開発者の IdP トークンがメールを含まない場合、ゲートウェイはメールヘッダーなしでリクエストを転送するため、そのようなリクエストへの 429 はアップストリーム容量としてカウントされ、フェイルオーバーします。ゲートウェイサーバーで v2.1.267 より前では、すべての 429 がフェイルオーバーしました。

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: {}                           # preferred: AWS default credential chain
    # OR explicit credentials:
    # auth:
    #   aws_access_key_id: ${AWS_AKID}
    #   aws_secret_access_key: ${AWS_SK}
    #   aws_session_token: ${AWS_ST}
    # OR a Bedrock API bearer token:
    # auth:
    #   aws_bearer_token: ${AWS_BEARER_TOKEN}
    # Override the bedrock-runtime endpoint for FIPS or VPC-endpoint deployments:
    # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

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

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

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}   # sent as x-api-key
    # OR SigV4 via the AWS default credential chain:
    # auth: {}
    # OR explicit SigV4 credentials:
    # auth:
    #   aws_access_key_id: ${AWS_ACCESS_KEY_ID}
    #   aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    # Override the derived endpoint:
    # 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 アップストリームが使用するのと同じチェーンです。

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

Google Cloud Agent Platform

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

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    auth: {}                           # preferred: Application Default Credentials
    # OR a service account key file:
    # auth: { service_account_json: /secrets/sa.json }
    # Override the aiplatform endpoint for Private Service Connect:
    # 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 を設定して、リージョナルエンドポイントの代わりに Google Cloud の Agent Platform のグローバルエンドポイントを使用します。Google はその後、各リクエストを利用可能なリージョンにルーティングするため、リージョンごとのモデル可用性を追跡しません。特定のリージョンを設定するとすべてのリクエストをそれにピンします。

Microsoft Foundry

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

upstreams:
  - provider: foundry
    resource: example-foundry              # https://example-foundry.services.ai.azure.com
    auth: { use_azure_ad: true }        # preferred: DefaultAzureCredential / Managed Identity
    # OR an API key:
    # auth:
    #   api_key: ${FOUNDRY_API_KEY}

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

複数のアップストリーム

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

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

429 はアップストリーム容量ごとであるため、プロビジョニングされたスループット（PT）枯渇はオンデマンドにフェイルオーバーします。アップストリームで forward_user_identity: true を設定する場合、開発者のメールを含むリクエストへの 429 は per-user 拒否であり、フェイルオーバーしません。

404 はアップストリームモデル可用性ごとであるため、モデルを有効にしていないアップストリームは、それを提供する後のアップストリームをブロックしません。要求されたモデルを解決できないアップストリームはネットワークラウンドトリップなしでスキップされます。

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

upstreams:
  # Primary: provisioned throughput in your home region.
  - name: bedrock-pt
    provider: bedrock
    region: us-east-1
    auth: {}
  # Overflow: on-demand cross-region.
  - name: bedrock-od
    provider: bedrock
    region: us-west-2
    auth: {}
  # Different account: a separate Bedrock allotment via assumed-role creds.
  - name: bedrock-acct2
    provider: bedrock
    region: us-east-1
    auth:
      aws_access_key_id: ${ACCT2_AKID}
      aws_secret_access_key: ${ACCT2_SK}
  # Last resort: direct Anthropic API.
  - name: anthropic-fallback
    provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

# Per-upstream model IDs are keyed on the upstream's `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

クラウドプロバイダー間、または直接 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

`enforcement`

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

`pricing`

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

• ゲートウェイサーバー上の Claude Code v2.1.227 以降。以前のバージョンはブート時に不明なキーを拒否します。
• admin: ブロック、または v2.1.268 以降では、少なくとも 1 つのポリシーを持つ managed: ブロック。支出メーターのみが pricing を読み込むためです。ゲートウェイは pricing が設定されていて両方のブロックがない場合、起動を拒否します。

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

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

• 行は、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 つの行を指定します。

価格をマークアップする

ゲートウェイサーバー上で v2.1.271 以降を使用すると、multiplier を 1 より上に設定でき、最大 10 まで、プロバイダーが請求するより多くをメーターするため、例えば内部チャージバックレート。この例は、すべてのリクエストを価格の 120% でメーターします：

pricing:
  multiplier: 1.2

admin: ブロックを使用すると、マークアップは支出制限にも適用されます。メーターは価格の 120% をカウントするため、開発者はキャップに早く到達します。ゲートウェイはブート時に、そのことを示す警告をログします。

乗算器は、アップストリームプロバイダーがリクエストに請求する内容を変更しません。

ゲートウェイが 署名されたクライアントにレートを送信する場合、開発者はマークアップを見るために Claude Code v2.1.271 以降が必要です。以前のクライアントは 1 より上の multiplier を無視し、それなしでコストを表示します。

v2.1.271 より前のゲートウェイサーバーは、1 より上の multiplier を設定した場合、起動を拒否します。

署名されたクライアントにレートを送信する

ゲートウェイサーバー上で v2.1.268 以降を使用すると、ゲートウェイは pricing からのレートを提供する managed ポリシーに入れます。modelPricing マネージド設定として。ポリシーにマッチした開発者は、/usage、ステータス行、OpenTelemetry で各モデル ID を提供する最初のアップストリームの pricing レートを見ます。ポリシーにマッチしない開発者はマネージド設定を受け取らないため、彼らの数字はリスト価格のままです。クライアントは Claude Code v2.1.242 以降で設定を適用します。

• ゲートウェイが追加するもの：ポリシーの cli ブロックが既に modelPricing を設定していない限り、ゲートウェイは multiplier を追加し、クライアントがリクエストできるすべてのモデル ID について、そのモデル ID を提供する最初のアップストリームのオーバーライド行を追加します。フェイルオーバーアップストリームのみが請求するレートはゲートウェイに留まります。
• 1 つのポリシーをオプトアウト：ポリシーの cli ブロックで modelPricing を {} に設定し、その開発者はリスト価格のままです。
• ポリシー独自のレートを保持：cli ブロックが独自の multiplier または overrides で modelPricing を設定するポリシーは、その modelPricing 全体を保持し、ゲートウェイはそれに独自のレートを追加しません。

`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 ブロックと 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 }

これらの設定はネットワーク経由で到着するため、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 メトリクス、ログ、有効な場合はトレースでゲートウェイに送信します。ゲートウェイはそれらを逐語的に各設定先にリレーします。エクスポートは OpenTelemetry Protocol（OTLP）を HTTP 経由で使用します。リレーをスキップして、セッションが直接コレクターにエクスポートするには、ポリシーでコレクターに名前を付けます。使用状況の監視で、CLI が発行するメトリクスとイベントを参照してください。

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

Claude Desktop と Cowork セッションがゲートウェイ経由でサインインすると、user.email と user.groups を enduser.id と一緒にテレメトリにスタンプを付けるため、1 つのクエリで user.email または user.groups でターミナル、Desktop、Cowork 使用状況をカバーできます。user.groups はコンマ区切りの IdP グループリストです。

Claude Code からのすべての OpenTelemetry データと同様に、これらの属性は組織が設定する宛先にのみ移動し、Anthropic には移動しません。

ユーザーのグループリストがパーセントエンコード後に 255 文字より長い場合、またはグループ名にコンマまたは等号が含まれている場合、ゲートウェイはそのユーザーの Desktop と Cowork テレメトリから user.groups を省略します。そのユーザーのターミナルセッションは完全なリストを引き続き実行します。

ゲートウェイサーバー上で Claude Code v2.1.265 以降が必要で、Desktop と Cowork テレメトリで user.email と user.groups が必要です。各開発者のマシン上で Claude Desktop 1.24012 以降が 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 の両方を設定すると、ゲートウェイはそれをオンにします。接続されたクライアント用に /managed/settings を通じて 6 つの環境変数をプッシュします：

• CLAUDE_CODE_ENABLE_TELEMETRY=1
• OTEL_METRICS_EXPORTER、OTEL_LOGS_EXPORTER、OTEL_TRACES_EXPORTER。少なくとも 1 つの forward_to 宛先がそのシグナルを有効にする場合は otlp に設定され、そうでない場合は none に設定されます。
• OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
• OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

ゲートウェイサーバー上の Claude Code v2.1.265 より前では、ゲートウェイはすべての 3 つのエクスポーターセレクターを otlp としてプッシュしました。宛先がオプトインしなかったシグナルを含みます。

プッシュされたエンドポイントはパブリック URL から構築されるため、メトリクスとログは開発者またはポリシーからの OTEL 設定を必要としません。

/login を通じてサインインした開発者は、独自の OTEL 設定でエクスポートをリダイレクトできません：

• ローカルに設定された変数：Claude Code はプッシュされた変数をマネージド層で適用するため、各変数はローカルで設定する値をオーバーライドします。
• ローカルに設定されたエンドポイント：OTLP/HTTP エクスポート有効にすると、CLI はローカルに設定されたエンドポイントを無視します。ゲートウェイがプッシュしたテレメトリ変数があるかどうかに関わらず。エクスポートはゲートウェイに移動します。ポリシーが コレクターをエンドポイントとして名前を付けない限り。

forward_to 宛先がシグナルにない場合、ゲートウェイはそれを受け入れて破棄します。開発者が既に Claude Code テレメトリを 1 つのコレクターにエクスポートしている場合、それを forward_to 宛先として追加します。ログまたはトレースをエクスポートする場合は、それらを有効にして、サインイン後もデータを受け取り続けるようにします。リレーをスキップするには、代わりに ポリシーでコレクターに名前を付けます。

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

それを 1 に設定するのは、トレースしたいグループのポリシーのみです。ポリシーが設定しない場合、match: {} キャッチオールポリシーが設定する場合、その値を継承します。マージルールに従って。グループのクライアントが開発者がローカルで変数を設定しても、トレースを送信しないようにするには、そのグループのポリシーで 0 に設定します。

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

コレクターに直接エクスポートする

/login を通じてサインインしたセッションがリレーを通じてではなく、コレクターに直接テレメトリを送信するには、マネージドポリシーの env ブロックでコレクターの https:// ベース URL に OTEL_EXPORTER_OTLP_ENDPOINT を設定します。Claude Code は /v1/metrics、/v1/logs、/v1/traces を URL に追加します。例えば https://otel-collector.example.com:4318。各シグナルをそこに OTLP/HTTP 経由でエクスポートします。各開発者のマシン上で Claude Code v2.1.265 以降が必要です。以前のクライアントはリレーを通じてエクスポートします。

コレクターに認証するには、同じ env ブロックで OTEL_EXPORTER_OTLP_HEADERS を設定します。セッションはこの方法で名前を付けられたコレクターに開発者のゲートウェイセッショントークンを送信しません。

ポリシーでこのエンドポイントを追加または変更すると、Claude Code は セキュリティ承認ダイアログでそれを適用する前に各開発者に承認を求めます。

Claude Code はシグナルを直接エクスポートする前にエンドポイントをチェックし、チェックが失敗するとそのシグナルをリレーに保持します。チェックには以下が含まれます：

• エンドポイントはゲートウェイ自体から来ます。MDM プロファイルまたはローカル managed-settings.json で同じ変数を設定する場合、エクスポートはリレーに留まります。
• URL は https:// を使用するか、ループバックアドレスに http:// を使用します。
• URL は /v1/<signal> で終わるパスに解決され、クエリまたはフラグメントはありません。Claude Code はジェネリック変数からそのパスを自身で構築します。OTEL_EXPORTER_OTLP_METRICS_ENDPOINT などのシグナルごとの変数を使用する場合は、完全なパスをそこに含めます。
• URL はゲートウェイ独自のホストではありません。ゲートウェイに対処されたエンドポイントはリレーパスとセッショントークンを保持します。
• あなたも開発者も otelHeadersHelper を設定していません。任意の設定ソースで。ヘルパーが設定されている場合、すべてのシグナルはリレーに留まります。

名前を付けるエンドポイントはエクスポートがどこに移動するかのみを変更します。どのシグナルがエクスポートするかは、OTEL_*_EXPORTER セレクターで選択します。

エンドポイント単独ではエクスポートをオンにしないため、ゲートウェイが既にプッシュしていない限り、それをオンにする変数も設定します：

• ゲートウェイが既に テレメトリ変数をプッシュする場合、それらは有効化、セレクター、プロトコルをカバーし、プッシュされた <public_url> 値をオーバーライドします。forward_to 宛先が有効にしないシグナルについてのみ、OTEL_*_EXPORTER セレクターを otlp に自身で設定します。
• そうでない場合、CLAUDE_CODE_ENABLE_TELEMETRY=1、OTEL_*_EXPORTER セレクター、OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf も設定します。

開発者がサインアウトするか、別のゲートウェイにサインインすると、コレクターへのエクスポートは停止し、Claude Code は各残りのバッチをドロップします。

宛先が失敗する場合

ゲートウェイはバッファリング、再試行、またはテレメトリを保存しないため、宛先に到達しないエクスポートは遅く配信するのではなくドロップされます。各宛先は独立して成功または失敗し、エクスポートクライアントはどちらの方法でも成功レスポンスを受け取るため、失敗した配信はゲートウェイのログにのみ表示されます。

5 つの連続した失敗した配信の後、ゲートウェイは 30 秒のストレッチで宛先へのフォワーディングを一時停止し、各一時停止をログします。配信が成功するまで。エラーレスポンス、タイムアウト、接続エラーはすべて失敗した配信としてカウントされます。400、413、415、422、431 を除き、コレクターがそのエクスポートのペイロードを形式が正しくないか大きすぎるとして拒否したことを意味します。

拒否されたペイロードは失敗カウントを進めたり、リセットしたりしません：ゲートウェイは宛先へのフォワーディングを続け、最初の拒否と 100 番目ごとに、宛先に名前を付けるステータスを警告します。

HTTP チューニング

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

access_control リストを両方とも空のままにする場合、これはデフォルトで、ゲートウェイはすべてのクライアントアドレスに提供するため、ネットワークのみがそれに到達できるユーザーを制限します。これは重要です。ゲートウェイは マネージド設定をプッシュできるため、開発者マシンでコマンドを実行します。

allow_cidrs が空の間、ゲートウェイは 2 つの場所で警告します。リクエストへの回答方法を変更することなく：

• ブート時：運用ログの警告は、プライベート範囲 10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、100.64.0.0/10、127.0.0.0/8、::1/128、fc00::/7 のみを許可することを推奨します。開発者が接続する他の内部範囲を加えます。ゲートウェイをループバックアドレスにバインドし、trusted_proxies も public_url も設定しない場合、ローカル開発のように、警告は表示されません。
• 実行時：リクエストが最初にこれらのプライベート範囲外のアドレスから到着すると、ゲートウェイは警告をログし、access.public_client 監査イベントをクライアント IP で発行します。両方とも 1 回プロセスごとに発火します。リンクローカルアドレス、169.254.0.0/16 と fe80::/10 は、パブリックとしてカウントされません。ゲートウェイは /healthz と /readyz をこのチェック実行前に回答するため、パブリック範囲からのヘルスプローブはそれをトリガーしません。

両方のシグナルはゲートウェイが解決するクライアントアドレスを使用します。ロードバランサー、ポートフォワード、またはトンネルがトラフィックをリレーし、listen.trusted_proxies にリストされていない場合、ゲートウェイはリレーのアドレスを見ます。通常はプライベートです。したがって、実行時警告もプライベート許可リストもそれをキャッチしません。

そのようなフロントエンドの背後で、listen.trusted_proxiesを最初に設定して、ゲートウェイが実際のクライアントアドレスを見るようにし、ゲートウェイとその前のすべてをパブリックインターネットから到達不可能に保ちます。

完全な例

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

# Run with:
#   claude gateway --config gateway.yaml
#
# Operational log verbosity is controlled by the CLAUDE_GATEWAY_LOG_LEVEL
# environment variable (debug | info | warn | error; default info). debug
# also logs the claim names in each id_token, for groups_claim diagnosis.
# It does not affect audit events, which are always emitted.

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com
  # Omit the tls block when running behind a TLS-terminating ingress.
  # 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
  # Required when the issuer is the Okta org server, whose id_tokens
  # can omit email and groups; the gateway fills them from /userinfo.
  userinfo_fallback: true
  # allowed_groups: [claude-code-users]
  # Okta emits groups only when the `groups` scope is requested and the
  # app's groups claim filter allows them. The contractors policy below
  # matches on groups, so the scope is requested here.
  scopes: [openid, profile, email, offline_access, groups]
  # extra_auth_params: { access_type: offline, prompt: consent }  # Google
  # groups_claim: groups          # Entra app roles: use `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

# Enables /v1/organizations/spend_limits (mirrors the Anthropic Admin API)
# and per-developer spend enforcement on /v1/messages. Omit to disable.
# Caps themselves are set via the admin API, not here.
# 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

# Meter at contracted rates instead of USD list price. Requires admin: or a
# managed: policy. With managed:, the same rates also go to signed-in clients.
# Rates below are placeholders, not real contract prices.
# 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]
        # Constrain the Default picker option to availableModels instead of
        # the tier default, so contractors don't get a 400 on the default.
        enforceAvailableModels: true
        # allow auto-approves these tools; it does not block the rest.
        # Add deny rules to restrict tools.
        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 セッションにポリシーを配信するはメカニズムと opt-in が配置される場所を説明しています。

managed-settings.json ファイルを各デバイスにデプロイします。通常は MDM プラットフォーム経由です。ファイルパスはプラットフォームによって異なります。各メカニズムがポリシーを保存する場所を参照してください。

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

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

Claude Code は forceLoginGatewayUrl、gatewayInternalNetworks、および forceLoginMethod の "gateway" 値をマシン上のマネージドソースからのみ認識します。managed-settings.json、macOS plist または Windows HKLM レジストリ、またはポリシーヘルパーです。開発者が独自の ~/.claude/settings.json でこれらを設定しても効果がなく、ゲートウェイペイロードで設定しても同様です。

関連

• Claude apps gateway 概要：クイックスタートと開発者接続
• デプロイメントガイド：IdP セットアップ、コンテナイメージ、Kubernetes と Cloud Run、運用
• 支出制限：開発者ごとのキャップと Admin API