gateway.yaml という 1 つの YAML ファイルで設定されます。このファイルは、ゲートウェイが行うすべてのことを定義します:どこでリッスンするか、開発者がどのようにサインインするか、推論がどこに行くか、どのポリシーとテレメトリーが適用されるかです。このページは、そのファイル内のすべてのオプションのリファレンスです。最初のファイルを作成するには、クイックスタートから始めてください。これは最小限の動作設定を構築して実行します。設定に満足したら、デプロイメントガイドで、Kubernetes、Cloud Run、または独自のプラットフォームでのコンテナ化とホスティングについて説明しています。
ゲートウェイは、claude gateway --config /path/to/gateway.yaml でスタートアップ時にファイルを 1 回読み込みます。すべてのオプションはブート時にスキーマに対して検証されるため、形式が正しくない設定は、最初の使用時ではなく、フィールドレベルのエラーで開始時に失敗します。
このページの最後にある完全な例は、すべてのセクションを実行します。
ファイル構造
5 つのセクションが必須です。他のすべてのセクションはオプションであり、省略されたセクションはデフォルトを使用します。不明なキーはブートに失敗するため、タイプミスは無視された設定ではなく、名前付きエラーとして表示されます。 必須セクション:listen:バインドアドレス、パブリック URL、TLS 終了oidc:ID プロバイダー(IdP)、発行者、クライアント、クレームマッピング、サインイン可能なユーザーを含むsession:ゲートウェイが発行するベアラートークン、シークレット、有効期間store:デバイスグラント、レート制限カウンターの PostgreSQLupstreams:推論がどこに行くか、Anthropic、Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、または Microsoft Foundry かどうか
admin:Admin API 認証、支出制限の保持enforcement:支出制限のフェイルオープンまたはフェイルクローズ動作modelsとauto_include_builtin_models:管理者がキュレーションしたモデルリスト、アップストリームごとの IDmanaged:IdP グループ別のマネージド設定ポリシーtelemetry:OTLP を観測可能性スタックに転送access_control、limits、timeouts、rate_limits:IP 許可/拒否、リクエストサイズキャップ、アップストリーム初バイト時間、IP ごとのサインイン制限
シークレット展開
client_secret、jwt_secret、postgres_url などのシークレットを gateway.yaml に直接書き込まないでください。以下のいずれかの形式で参照すると、ゲートウェイはブート時に環境変数またはファイルから値を解決します:
必須セクション
listen
listen ブロックは、ゲートウェイがサービスを提供する場所を制御します:バインドアドレスとポート、外部から見えるオリジン、オプションの TLS 終了。
oidc
oidc ブロックはゲートウェイを ID プロバイダーに接続し、サインイン可能なユーザーを決定します。発行者と OAuth クライアントに名前を付け、メールとグループを含むクレームをマップし、メールドメインまたはグループによるサインインを制限します。
OpenID Connect(OIDC)は、ゲートウェイが ID プロバイダーで使用する SSO プロトコルです。IdP 側で登録する内容については、ID プロバイダー設定を参照してください。
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 はそのアップストリームが要求されたモデルを提供していないことを意味するため、リスト内の後のアップストリームはまだ提供できます。
404 でのフェイルオーバーにはゲートウェイ v2.1.198 以降が必要です。以前のリリースは、リスト内の後のアップストリームがモデルを提供している場合でも、最初の 404 をクライアントに返しました。
同じプロバイダーの複数のアップストリームは、異なる name: を設定する必要があります。
Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、Microsoft Foundry クライアントはスタートアップ時に 1 回構築され、SDK は内部的に認証情報をリフレッシュするため、クラウド認証情報のローテーションは再起動を必要としません。静的 Anthropic API キーとベアラーはスタートアップ時に読み込まれます。Anthropic APIを参照してください。
Anthropic API
最小限の Anthropic アップストリームは、Claude Console からの API キーです:api_key:x-api-keyを送信します。Claude Console でローテーションし、env var を更新します。oauth_token:Authorization: Bearerを送信します。組織が長期 API キーではなく短期トークンを発行する場合、ベアラー形式を使用します。ベアラーはスタートアップ時に 1 回読み込まれるため、シークレットを再マウントして再起動することで更新します。
Amazon Bedrock
ゲートウェイが置き換えるまたはフロントする、クライアント側の Amazon Bedrock デプロイメントについては、Amazon Bedrock の Claude Codeを参照してください。ゲートウェイ側のアップストリーム: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: ブロックは検証に合格しました。
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 を参照してください。ゲートウェイ側のアップストリーム:
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 を参照してください。ゲートウェイ側のアップストリーム:auth ブロックは Application Default Credentials を使用します:GOOGLE_APPLICATION_CREDENTIALS、GCE メタデータ、または GKE Workload Identity。サービスアカウント JSON キーファイルはサポートされていますが、推奨されません。Workload Identity を使用するか、GCE または Cloud Run インスタンスにサービスアカウントをアタッチします。
region: global を設定して、地域のエンドポイントの代わりに Agent Platform のグローバルエンドポイントを使用します。Google は各リクエストを利用可能なリージョンにルーティングするため、リージョンごとのモデル可用性を追跡する必要はありません。特定のリージョンを設定すると、すべてのリクエストがそれにピンされます。
Microsoft Foundry
クライアント側の Foundry デプロイメントについては、Microsoft Foundry の Claude Codeを参照してください。ゲートウェイ側のアップストリーム:use_azure_ad: true は DefaultAzureCredential を通じて解決します:AKS、ACI、または App Service の Managed Identity、Azure CLI、または環境認証情報。API キーは機能しますが、プロジェクト全体であり、自動的にローテーションされません。Foundry のエンドポイントは resource: から派生します。Azure Government などのソブリンクラウドの場合、オプションの base_url を設定してオーバーライドします。
複数のアップストリーム
同じプロバイダーは、異なるname: で複数回表示できます。これは異なるリージョン、異なる認証情報チェーン経由の異なるアカウント、プロビジョニングスループット対オンデマンド、クロスプロバイダーフェイルオーバーをカバーします。
ゲートウェイはアップストリームを順番に試します。5xx、429、401、403、404、タイムアウト、および欠落エンドポイント(501)はフェイルオーバーします。他の 4xx はしません。
429 はアップストリーム容量ごとです。プロビジョニングスループット(PT)枯渇はオンデマンドにフェイルオーバーします。404 はアップストリームモデル可用性ごとです。モデルを有効にしていないアップストリームは、後のアップストリームがそれを提供するのをブロックしません。要求されたモデルを解決できないアップストリームはネットワークラウンドトリップなしでスキップされます。
この例は、プロビジョニングスループット Amazon Bedrock 割り当てを最初にルーティングし、オンデマンドと 2 番目のアカウントにオーバーフロー、最後に Anthropic API にフォールバックします:
クラウドプロバイダー間、または直接 Anthropic API へのフェイルオーバーは、リクエストを管理する契約、地域、その他の条件を変更します。
CLI は、どのアップストリームが特定のリクエストを提供するかに関わらず、ゲートウェイに同じ機能ゲーティングを適用するため、フェイルオーバーはアップストリームが拒否するボディフィールドを送信しません。
オプションセクション
admin
オプション。/v1/organizations/spend_limits を有効にします。これは Anthropic のパブリック Admin API をミラーリングし、/v1/messages で開発者ごとの支出強制を行います。支出制限で、キャップがどのように設定および強制されるかを参照してください。このセクションは、機能をオンにしてチューニングする gateway.yaml キーをカバーします。
enforcement
enforcement ブロックは、ストアが利用できない場合の支出制限チェックの動作を制御します。
models
models ブロックはオプションの管理者がキュレーションしたモデルリストで、/v1/models で提供され、アップストリームごとのモデル ID を変換するために使用されます。US 以外の Amazon Bedrock リージョン、Amazon Bedrock プロビジョニングスループット ARN、Microsoft Foundry デプロイメント名に必須です。
managed
managed ブロックは、IdP グループまたはメールドメインでキーイングされた、ロールベースのアクセスポリシーを定義します。ポリシーは順番に評価されます。最初のマッチが選択され、以下で説明する match: {} キャッチオール基盤にマージされます。ユーザーごとに GET /managed/settings で ETag/304 キャッシング付きで提供されます。
match: {} キャッチオール。慣例的に最後にリストされます。基盤層として扱われます。他のすべてのポリシーは、設定しないキーについてキャッチオールから継承するため、ロール別エントリは組織デフォルトから異なるものだけをリストする必要があります。マージルールはキータイプに依存します:
- 許可リスト:
availableModelsとpermissions.allow。特定のポリシーのリストは基盤のリストを完全に置き換えます。 - 拒否リストとフックアレイ:
permissions.deny、permissions.ask、disabledMcpjsonServers、deniedMcpServers、blockedMarketplaces、およびすべてのhooksイベントタイプアレイ。これらは基盤とポリシーの和集合を取得するため、組織全体の拒否または監査フックは、ロール別オーバーライドによって誤ってドロップされることはできません。 - レコードタイプキー:
env、modelOverrides、skillOverrides。これらは浅くマージするため、ロール別envブロックは設定するキーをオーバーライドし、基盤から残りを継承します。
availableModels は /v1/messages でサーバー側でも強制されるため、拒否されたモデルはクライアントが送信するものに関わらず 400 を返します。
ポリシーにマッチしない認証されたユーザーは、ゲートウェイのデフォルトを取得します。これは、カタログ内のすべてのモデルと管理設定なしを意味します。最後に
match: {} キャッチオールを追加して、保証されたデフォルトポリシーが必要な場合。
ゲートウェイは独自のユーザーディレクトリを保持しません。ユーザーの IdP トークンから各リクエストを認可し、トークンの
groups クレームからグループメンバーシップを読み込み、それに対してポリシーを評価します。列挙するロスターはなく、事前作成するアカウントもありません。したがって、SCIM エンドポイントはありません。SCIM が同期するものがないためです。ユーザーとグループのライフサイクル管理を、真実の源である IdP のネイティブ SCIM プロビジョニングまたは専用アイデンティティガバナンスプラットフォームで実行します。メンバーシップとプロビジョニング解除はそこで管理され、トークンを通じてゲートウェイに自動的に流れます。Claude アカウント自体の SCIM プロビジョニングが必要な場合、それは Claude for Enterprise 機能です。2 つの伝播クロックが適用されます:- ポリシーコンテンツ:ポリシーを編集して再デプロイすると、接続されたクライアントの次のマネージド設定ポーリング時に到達します。1 時間以内。
- グループメンバーシップ:ユーザーのグループメンバーシップを変更すると、どのポリシーが彼らにマッチするかが変わります。これは次のセッション再発行時に有効になります。つまり、次の無言リフレッシュ。
session.ttl_hoursで制限されます。
cli に何が入るか
各 cli 値は、完全な Claude Code managed-settings.json ドキュメントです。MDM または /etc/claude-code/managed-settings.json を通じてデプロイするのと同じスキーマ。ここでは YAML として表現されます。CLI は、マネージド層で配信されたドキュメントを適用します。ユーザーとプロジェクト設定の上。
ゲートウェイは、ブート時に CLI の設定スキーマに対して各ドキュメントを検証するため、認識されないトップレベルキーまたは認識されたキーで形式が正しくない値は、すべての違反キーに名前を付けるエラーでブートに失敗します。スキーマの意図的にオープンな部分は、新しいクライアントがゲートウェイのスキーマが認識しないエントリを認識する可能性があるため、任意の値を受け入れます。これらのオープンキーは env、pluginConfigs、permissions の下にネストされたキーです。
検証はゲートウェイのインストール済みバージョンにバンドルされたスキーマを使用するため、新しい Claude Code リリースで導入されたトップレベル設定キーをマネージド設定に入れるには、最初にゲートウェイをアップグレードする必要があります。新しいポリシーを 1 つのクライアントでスモークテストしてから、ロールアウトします。
完全なキーリファレンスは Claude Code 設定 にあります。オペレーターが最初に到達するキー:
これらの設定はネットワーク経由で到着するため、CLI は、シェルコマンドを実行したり、トラフィックがどこに行くかを変更したりできるものを適用する前に、各開発者に 1 回限りのセキュリティ承認ダイアログを表示します。ダイアログは以下をカバーします:
hooksenv変数。CLI の組み込みセーフリストにないapiKeyHelperとstatusLineなどのシェル実行設定- マネージド CLAUDE.md コンテンツ
env 変数が承認なしで適用されるかを決定します:
- セーフリスト上:自動更新とモデル名変数
- セーフリストにない:プロキシ変数、ベース URL 変数、
OTEL_EXPORTER_OTLP_ENDPOINT
OTEL_EXPORTER_OTLP_ENDPOINT をプッシュするため、telemetry.forward_to を設定すると、各インタラクティブクライアントで承認ダイアログがトリガーされます。ダイアログは、組織から開発者を保護するのではなく、開発者のマシンを侵害または敵対的なゲートウェイから保護します。
-p フラグを使用した非インタラクティブ実行はダイアログを表示できません。その実行のみのためにプッシュされた設定を適用し、それらを承認済みとして記録しないため、開発者の次のインタラクティブセッションはまだダイアログを表示します。v2.1.207 より前では、非インタラクティブ実行は設定を承認済みとして保存し、後のインタラクティブセッションはそれらのダイアログを表示しませんでした。
開発者が拒否した場合、Claude Code は設定を適用せずに終了します。新しいフックまたは非セーフ env var を広いポリシーにプッシュすることは、マッチする開発者の次の起動時に承認プロンプトを意味します。
cli キーは以前のリリースで settings という名前でした。その綴りはまだエイリアスとして受け入れられていますが、新しいデプロイメントは cli を使用する必要があります。
他のマネージドソースとの優先順位
デバイスにローカルmanaged-settings.json または MDM 配信ポリシーもある場合、マネージドソースはマージされません。最優先ソースはすべてのポリシー設定を提供します。この順序でランク付けされます。最優先順位が最初:
- ポリシーヘルパー
- ゲートウェイ配信設定
- MDM。Windows の HKLM レジストリまたは macOS の plist 経由
managed-settings.jsonファイル- HKCU レジストリ。Windows のみ
managedSettings オプションを通じてポリシーを提供できます。デフォルトでは無視され、マネージドソースが parentSettingsBehavior: "merge" でオプトインした場合のみ適用されます。ポリシーを厳しくできますが、緩くすることはできません。
例外は、管理者ソースが設定する場合に尊重される小さなキーセットです。ユーザー書き込み可能な HKCU 層は除外されます:
sandbox.network.allowManagedDomainsOnlyとsandbox.filesystem.allowManagedReadPathsOnly:ロックされている場合、対応する許可リストはソース全体で和集合されます。allowAllClaudeAiMcps:claude.ai MCP サーバー許可リストの許可のみオーバーライドsandbox.bwrapPathとsandbox.socatPath:サンドボックスヘルパーバイナリへのファイルシステムパスforceRemoteSettingsRefresh:スタートアップをブロックして、リモートマネージド設定を新しく取得するため、キーが不足しているキャッシュされたリモートペイロードが最優先ソースである場合でも、MDM またはファイルポリシーがそれを設定することが尊重されます。
allowManagedPermissionRulesOnly と disableBypassPermissionsMode を含むすべての他のキーは、最優先ソースのみから来ます。設定の優先順位で、設定ページの同じルールを参照してください。
ゲートウェイポリシーはマシン上のすべての Claude Code 呼び出しに適用されます。非インタラクティブ claude -p 実行と Agent SDK によって生成されたセッションを含みます。ゲートウェイがスタートアップ時に到達不可能な場合、署名されたセッションはポリシーなしで実行するのではなく、エラーで終了します。
telemetry
CLI は OpenTelemetry Protocol(OTLP)を HTTP メトリクス、ログ、有効な場合はトレースでゲートウェイに送信します。ゲートウェイはそれらを逐語的に各設定先にリレーします。使用状況の監視で、CLI が発行するメトリクスとイベントを参照してください。
CLI は、ゲートウェイ発行 JWT から読み込まれた認証されたユーザーのアイデンティティで各エクスポートにスタンプを付けます:user.id、user.email、user.groups 属性。開発者ごとのコストと使用状況の属性は、開発者側の設定なしで機能します。
telemetry.forward_to を listen.public_url と一緒に設定するとオンになります。ゲートウェイは 5 つの env var を /managed/settings を通じてすべての接続されたクライアントにプッシュします:
CLAUDE_CODE_ENABLE_TELEMETRY=1OTEL_METRICS_EXPORTER=otlpOTEL_LOGS_EXPORTER=otlpOTEL_TRACES_EXPORTER=otlpOTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
OTEL_* 変数をオーバーライドします。
トレースはさらに各クライアントで CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 を必要とします。ゲートウェイはその変数をプッシュしないため、マネージドポリシーの env ブロックを通じて設定します。CLI のセーフリストにはないため、ポリシーを通じてそれを配信することは、プッシュされた OTLP エンドポイントがすでにトリガーする同じ セキュリティ承認ダイアログでカバーされます。
protobuf と JSON OTLP エンコーディングの両方がリレーされ、OpenTelemetry 互換バックエンドは宛先として機能します。
HTTP チューニング
4 つのオプションのトップレベルブロック、access_control、limits、timeouts、rate_limits。HTTP サーフェスをチューニングします。デフォルトはほとんどのデプロイメントに適しています。
完全な例
この完全なリファレンス設定はすべてのコアセクションを実行します。HTTP チューニングブロックはデフォルトを保持します。コピーして、不要なものを削除し、値を入力します。クイックスタートの設定はこれの最小バージョンです。gateway.yaml
クライアント側マネージド設定
上記のすべてはゲートウェイサーバーを設定します。開発者マシンをそれに指すことは、各デバイスで別々に設定されます。Claude Code の マネージド設定 を通じて。ゲートウェイはこれらのキーをプッシュできません。ゲートウェイがどこにあるかをクライアントに伝えるものだからです。 CLI の場合、OS ごとのmanaged-settings.json に両方のキーを設定します:
forceLoginGatewayUrl と forceLoginMethod の "gateway" 値は、管理者制御マネージド層からのみ尊重されます。開発者が独自の ~/.claude/settings.json で設定しても効果がありません。
関連
- Claude apps gateway 概要:クイックスタートと開発者接続
- デプロイメントガイド:IdP セットアップ、コンテナイメージ、Kubernetes と Cloud Run、運用
- 支出制限:開発者ごとのキャップと Admin API