Claude apps gateway設定の全項目 — gateway.yamlリファレンス

gateway.yamlは1ファイルで何を決めるか

Claude apps gatewayはgateway.yamlという1つのYAMLファイルだけで動作が決まります。どこでリッスンするか、開発者がどうサインインするか、推論がどこへ流れるか、どのポリシーとテレメトリを適用するかのすべてがこのファイルに書かれます。基本の使い方では最小構成の5セクションを組み立てましたが、実際の運用ではadminやmanagedのような任意セクションまで含めた全項目を把握しておく必要があります。本記事はその全項目のリファレンスです。

ゲートウェイは起動時に一度だけこのファイルを読み込み、claude gateway --config /path/to/gateway.yamlで起動します。すべての項目はスキーマに対して起動時に検証されるため、記述ミスがあると起動失敗時にフィールド単位のエラーが出ます。曖昧な設定のまま起動してリクエスト到達後に失敗する、という事故は起きません。未知のキーを書くと起動が失敗するので、タイポも黙って無視されずエラー名で表面化します。

必須セクションと任意セクションの構成

必須は5つ、それ以外はすべて任意で、省略したセクションは既定値で動きます。

シークレットはclient_secret・jwt_secret・postgres_urlのようにファイルへ直書きせず、${VAR}(環境変数)または${file:/path}(ファイル内容、末尾トリム済み)で展開します。

oidc:
  client_secret: ${OIDC_CLIENT_SECRET}          # 環境変数から展開
session:
  jwt_secret: ${file:/var/run/secrets/jwt}       # マウントされたファイルから展開

${file:/path}はフィールドの値全体を置き換える形でしか使えず、${VAR}のように長い文字列の中に埋め込むことはできません。データベースのパスワードをpostgres_urlに埋め込まずstore.passwordに分離するのはこの制約が理由です。

listen — バインドとTLS終端

public_urlはALB・Ingress・Cloud Runのような前段プロキシでTLS終端する場合でも省略できません。ゲートウェイはX-Forwarded-*ヘッダーから自分のオリジンを推測しないためです。クライアントが偽装できるヘッダーを信頼のルーツにしないという設計で、trusted_proxiesはクライアントIPの解決だけに使われ、オリジンの決定には関与しません。telemetryを有効にする場合もこの値からOTLPエンドポイントを組み立てるため必須になります。

oidc — IdP接続とサインインの許可条件

oidcブロックはIdPの発行者・OAuthクライアント・誰がサインインできるかを決めます。主要フィールドは次の通りです。

Okta・Microsoft Entra ID・Google Workspaceはそれぞれクレームの出方に癖があります。Oktaの組織認可サーバー(https://example.okta.com)はid_tokenが薄く、userinfo_fallback: trueが必須です。カスタム認可サーバー(.../oauth2/default)ならid_tokenに直接含まれるため不要になります。EntraはグループをオブジェクトID(GUID)で返すため、managed.policies.match.groupsにはこのGUIDを書くか、可読な名前が欲しい場合はApp Rolesを使います。Googleのid_tokenにはグループクレームが無く、google_groupsを設定しない場合はallowed_email_domainsとメールドメインベースのポリシーに頼ることになります。

sessionとstore — トークン寿命とPostgres接続

session.jwt_secretはゲートウェイが発行するHS256ベアラートークンの署名鍵で、32バイト以上のエントロピーが必要です(openssl rand -base64 32で生成)。単一文字列だけでなく配列も受け付け、インデックス0が署名に使われ、配列内の全エントリが検証に使われます。新しい鍵を先頭に追加し、ttl_hours経過後に古い鍵を外すことでローテーションできます。ttl_hoursの既定は1で、IdPがリフレッシュトークンを発行できる場合はCLIが期限前に自動更新します。リフレッシュトークンが使えないIdPでは、毎時ブラウザに戻されるのを避けるため8や12に伸ばすのが実務的です。

store.postgres_urlはデバイスサインインフローの状態(ブラウザコールバックが書き込み、ポーリング中のCLIが読み取る)とレート制限カウンターを保持します。ゲートウェイは起動時と更新時に自分のスキーママイグレーションを実行するため、指定するロールにはテーブルの作成・変更権限が必要です。store.max_connectionsはレプリカ1台あたりのコネクションプールサイズで、既定は5と控えめです。支出上限を有効にすると推論リクエストごとにPostgresへの操作が増えるため、専用データベースで負荷がかかる場合はこの値を引き上げますが、その際は「レプリカ数 × この値」をデータベース側のmax_connections未満に収める必要があります。ゲートウェイを複数レプリカで動かしている場合、各レプリカがこの上限までコネクションを張るためです。

upstreams — 推論の転送先とフェイルオーバー

upstreamsは順序付きリストで、ゲートウェイは要求されたモデルを解決できる最初のupstreamへ転送します。5xx・429・401・403・404・タイムアウトでは次のupstreamへフェイルオーバーし、それ以外の4xxはリクエスト側の問題とみなしフェイルオーバーしません。404でのフェイルオーバーはv2.1.198以降が必要で、それより古いリリースは後続のupstreamがモデルを提供できても最初の404をそのままクライアントへ返していました。

対応する4つのクラウドupstream(Amazon Bedrock・Claude Platform on AWS・Google Cloud's Agent Platform・Microsoft Foundry)は起動時に1度だけクライアントが構築され、各SDKが内部でクレデンシャルを更新するため、クラウド認証情報のローテーションに再起動は不要です。一方Anthropic APIの静的APIキーやbearerは起動時に読み込まれる点が異なります。

Anthropic API upstreamの最小構成はapi_keyかoauth_tokenのどちらかです。api_keyはx-api-keyヘッダーを送り、Claude Consoleでのローテーションが必要です。oauth_tokenはAuthorization: Bearerを送る形式で、組織が長期キーではなく短命トークンを発行する場合に使います。この2つの代わりにWorkload Identity Federationも使え、ワークロードのOIDC JWTをファイルとしてマウントすると、ゲートウェイが短命bearerに自動交換します。

複数のupstreamでプロバイダーが重複する場合は、nameフィールドで区別する必要があります。全upstreamを試した末のエラー応答は、次の優先順位で決まります。

• フェイルオーバー対象外のステータスで失敗したupstreamがあれば、そのupstreamの応答をそのまま返す
• 全upstreamがフェイルオーバー対象のステータスで失敗した場合は、最後に見た429を優先して返す
• 429が無ければ401/403→404→501の順で優先して返す
• どれも無ければゲートウェイ自身の502(all upstreams failed (N attempted))を返す

admin・enforcement・pricing — 支出上限まわりの設定キー

adminブロックを設定すると/v1/organizations/spend_limitsのAdmin APIと/v1/messagesでのリアルタイム支出上限強制が有効になります。上限の設定方法そのものはAdmin API側の話題になるため、ここではgateway.yaml側の鍵に絞ります。

enforcement.fail_closed_on_errorは既定falseで、Postgresが落ちた場合は支出上限チェックがフェイルオープンし推論は止まりません。trueにするとフェイルクローズになり、上限超過者だけでなくストアに到達できない全開発者がブロックされます。この鍵はadminブロックが設定されている場合のみ有効で、設定なしにtrueにするとゲートウェイは起動を拒否します。

pricingは契約レートを反映するための上書きで、adminブロックが無いと起動を拒否します。multiplier(既定1、0より大きく1以下)は算出額全体に掛かり、overridesは{upstream, model, input, output, cache_read, cache_write}をトークン100万あたりのUSDで指定します。マッチングはupstream名とモデルの両方が一致する行を優先し、同じupstreamに対して同じモデルを指す行が2つあると起動が失敗します。

models — モデルIDカタログ

modelsブロックは/v1/modelsで配信され、upstreamごとにモデルIDを変換する管理者キュレーションのカタログです。非米国リージョンのAmazon Bedrock、Bedrockのprovisioned-throughput ARN、Microsoft Foundryのデプロイ名を使う場合は必須になります。auto_include_builtin_models: falseを設定すると、ここに列挙したモデルだけが公開されます。各エントリのupstream_model配下のキーは設定済みupstreamのname(既定はプロバイダー名)と一致する必要があり、一致しないキーは起動を失敗させます。

managed — IdPグループ別のポリシー

managed.policiesはIdPグループやメールドメインをキーにしたロールベースのアクセスポリシーで、順に評価され最初に一致したものが選ばれ、match: {}のキャッチオールへマージされます。マージ規則はキーの種類で異なります。

availableModelsは/v1/messagesでもサーバー側で強制されるため、改造されたクライアントが送るモデル名を許可リストで迂回することはできません。マッチャーは次の4パターンです。

• match: {} — 全認証済みユーザーに一致
• match: { groups: [a, b] } — 大文字小文字を区別する完全一致
• match: { email_domain: example.com } — @より後ろの部分、大文字小文字を無視
• match: { groups: [a], email_domain: example.com } — 両方の条件を満たす場合のみ一致

managed:
  policies:
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
    - match: {}   # キャッチオール(最後に置く)
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

空のgroupsエントリや@・空白・カンマを含むemail_domainは起動時にエラー名付きで停止します(v2.1.232以降。それ以前はサイレントに全員へマッチする等の挙動でした)。

cliキーの中身はClaude Codeのmanaged-settings.jsonそのもので、CLIはこれをmanagedティアで適用しサーバー管理設定の代わりに使います。よく使われるキーは次の通りです。

hooks・承認が必要なenv変数・シェル実行系の設定は、配信されるたびに開発者へセキュリティ承認ダイアログが表示されます。

Claude Desktopも同じゲートウェイに接続する場合はdesktopブロックをcliと並べて設定します。空のdesktop: {}だけでオプトインになり、モデル一覧や無効化ツールリストはcliブロックから自動導出されます。desktopブロックを持たないポリシーにマッチした開発者は/user/bootstrapが404を返し、Desktopの接続設定が完了しません。

telemetry — OTLPの信号別opt-in

telemetry.forward_toは転送先のリストで、各宛先はmetrics・logs・tracesを個別にopt-inでき、既定はmetricsのみです。メトリクスはトークン数・リクエスト数・レイテンシーの集計値ですが、ログとトレースは開発者のマシンで実行されたbashコマンドやツール入力、ファイルパスまで含みうるため、アクセス制御と保持ポリシーが要件を満たす宛先だけで有効にします。CLIは認証済みユーザーのuser.id・user.email・user.groupsをエクスポートに自動でスタンプするため、開発者側の追加設定なしに利用者単位の帰属が取れます。

forward_toのURLはhttps://が必須で、ゲートウェイ自身のループバック上のコレクターだけが例外です(CLAUDE_GATEWAY_ALLOW_LOOPBACK=1が必要)。telemetry.forward_toとlisten.public_urlを両方設定すると、ゲートウェイはCLAUDE_CODE_ENABLE_TELEMETRY=1を含む6つの環境変数を接続済みクライアントへ自動プッシュし、開発者側でのOTEL設定は不要になります。トレースを追加で有効化するには、CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1をmanaged policyのenvブロック経由で配信する必要があります。

HTTPチューニングの4ブロック

access_control・limits・timeouts・rate_limitsはHTTPサーフェスを微調整する任意ブロックで、既定値のままでほとんどのデプロイに対応できます。

/healthzと/readyzはallow_cidrsの対象外で、アクセスを絞ったリスナーでもヘルスチェックは動き続けます。

managedのマージ規則はなぜキーの種類で挙動を変えるのか

許可リストは置き換え、拒否リストは和集合、レコード型はシャローマージという3種類の異なる規則は、一見複雑に見えますが安全側に倒す設計です。もし全キーが単純な置き換えだった場合、個別グループ向けのポリシーを書いた担当者が組織全体のpermissions.denyを意図せず上書きし、監査フックが特定のグループだけ効かなくなるという事故が起きます。拒否リストとフック配列だけを和集合にすることで、個別ポリシーは「制限を追加できるが、組織のベースラインを緩められない」という一方向の権限になります。

一方でavailableModelsのような許可リストを和集合にしてしまうと逆の問題が起きます。契約者グループにclaude-sonnet-4-6だけを許可したつもりが、ベースのmatch: {}が持つ全モデル許可リストと合算され、意図した制限が効かなくなるからです。許可リストは制限を狭める用途、拒否リストとフックは制限を広げない用途と考えると、置き換えと和集合の使い分けが一貫していることが分かります。

matcher(groups・email_domain)の空値やフォーマット違反をv2.1.232からboot時エラーに変えたのも同じ方向の設計判断です。それ以前は空のemail_domainが「全員にマッチする」という意図しない挙動を引き起こしていましたが、これは設定ミスをサイレントな過剰許可として処理していたことになります。boot失敗に変えたことで、設定ミスは「動くが間違っている」状態から「動かない」状態に変わり、運用担当者が気づかないまま過剰な権限を配布するリスクを構造的に減らしています。

まとめ

gateway.yamlは5つの必須セクションだけで最小構成が動きますが、実運用ではadminでの支出上限有効化、managedでのグループ別ポリシー、telemetryでの信号別opt-inまで組み合わせることになります。secret展開のルール、upstreamのフェイルオーバー条件、managed policyのマージ規則はいずれもドキュメントの表を読むだけでは見落としやすい箇所なので、設定を書き換える前に該当セクションの表を都度確認するのが安全です。導入自体の手順は基本の使い方の記事、支出上限の運用はAdmin APIでの設定方法の記事がそれぞれ扱っており、本番デプロイの具体的な手順はデプロイと運用にまとめています。