1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Claude apps gateway 設定
6
7> gateway.yaml のすべてのオプションのリファレンス：リスナーと TLS、OIDC、セッション、Postgres ストア、Bedrock/Agent Platform/Foundry アップストリーム、モデルルーティング、マネージドポリシー、テレメトリー。
8
9Claude apps gateway デプロイメントは、慣例的に `gateway.yaml` という 1 つの YAML ファイルで設定されます。このファイルは、ゲートウェイが行うすべてのことを定義します：どこでリッスンするか、開発者がどのようにサインインするか、推論がどこに行くか、どのポリシーとテレメトリーが適用されるかです。このページは、そのファイル内のすべてのオプションのリファレンスです。最初のファイルを作成するには、[クイックスタート](/ja/claude-apps-gateway#quickstart)から始めてください。これは最小限の動作設定を構築して実行します。設定に満足したら、[デプロイメントガイド](/ja/claude-apps-gateway-deploy)で、Kubernetes、Cloud Run、または独自のプラットフォームでのコンテナ化とホスティングについて説明しています。
10
11ゲートウェイは、`claude gateway --config /path/to/gateway.yaml` でスタートアップ時にファイルを 1 回読み込みます。すべてのオプションはブート時にスキーマに対して検証されるため、形式が正しくない設定は、最初の使用時ではなく、フィールドレベルのエラーで開始時に失敗します。
12
13このページの最後にある[完全な例](#complete-example)は、すべてのセクションを実行します。
14
15<h2 id="file-structure">
16 ファイル構造
17</h2>
18
195 つのセクションが[必須](#required-sections)です。他のすべてのセクションは[オプション](#optional-sections)であり、省略されたセクションはデフォルトを使用します。不明なキーはブートに失敗するため、タイプミスは無視された設定ではなく、名前付きエラーとして表示されます。
20
21**必須セクション：**
22
23* [`listen`](#listen)：バインドアドレス、パブリック URL、TLS 終了
24* [`oidc`](#oidc)：ID プロバイダー（IdP）、発行者、クライアント、クレームマッピング、サインイン可能なユーザーを含む
25* [`session`](#session)：ゲートウェイが発行するベアラートークン、シークレット、有効期間
26* [`store`](#store)：デバイスグラント、レート制限カウンターの PostgreSQL
27* [`upstreams`](#upstreams)：推論がどこに行くか、Anthropic、Bedrock、Agent Platform、または Foundry かどうか
28
29**オプションセクション：**
30
31* [`admin`](#admin)：Admin API 認証、支出制限の保持
32* [`enforcement`](#enforcement)：支出制限のフェイルオープンまたはフェイルクローズ動作
33* [`models`](#models) と `auto_include_builtin_models`：管理者がキュレーションしたモデルリスト、アップストリームごとの ID
34* [`managed`](#managed)：IdP グループ別のマネージド設定ポリシー
35* [`telemetry`](#telemetry)：OTLP を観測可能性スタックに転送
36* [`access_control`、`limits`、`timeouts`、`rate_limits`](#http-tuning)：IP 許可/拒否、リクエストサイズキャップ、アップストリーム初バイト時間、IP ごとのサインイン制限
37
38<h2 id="secret-expansion">
39 シークレット展開
40</h2>
41
42`client_secret`、`jwt_secret`、`postgres_url` などのシークレットを `gateway.yaml` に直接書き込まないでください。以下のいずれかの形式で参照すると、ゲートウェイはブート時に環境変数またはファイルから値を解決します：
43
44| 形式 | 解決先 | 用途 |
45| --------------- | ------------------------ | -------------------------------------------- |
46| `${VAR}` | 環境変数 `VAR`。未定義の場合はブート失敗。 | コンテナ環境変数、env インジェクション経由の AWS Secrets Manager |
47| `${file:/path}` | ファイルの内容、トリミング済み | Kubernetes Secret ボリュームマウント、Vault Agent、SOPS |
48
49<h2 id="required-sections">
50 必須セクション
51</h2>
52
53<h3 id="listen">
54 `listen`
55</h3>
56
57`listen` ブロックは、ゲートウェイがサービスを提供する場所を制御します：バインドアドレスとポート、外部から見えるオリジン、オプションの TLS 終了。
58
59| フィールド | 必須 | 説明 |
60| ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
61| `host` | いいえ | バインドアドレス。デフォルト `0.0.0.0`。 |
62| `port` | いいえ | バインドポート。デフォルト `8080`。 |
63| `public_url` | プロキシの背後 | 外部から見える `https://` オリジン。IdP `redirect_uri` と検出メタデータを構築するために使用されます。ALB、Ingress、Cloud Run などの TLS 終了プロキシの背後では必須です。ゲートウェイは独自のオリジンを構築する際に `X-Forwarded-*` ヘッダーを信頼しないためです。これらはクライアントがスプーフ可能です。`trusted_proxies` 以下はクライアント IP 解決のみを管理します。また、[テレメトリ](#telemetry)を有効にするためにも必須です。ゲートウェイはこの URL からクライアントにプッシュする OTLP エンドポイントを構築するためです。 |
64| `tls.cert` / `tls.key` | いいえ | ゲートウェイが TLS 自体を終了する場合の PEM パス |
65| `trusted_proxies` | いいえ | ゲートウェイの前にあるロードバランサーの CIDR または IP。設定すると、ゲートウェイはこれらのピアからのみ `X-Forwarded-For` を信頼し、IP ごとのレート制限と監査のための実際のクライアント IP を記録します。nginx `set_real_ip_from` と同等。 |
66
67<h3 id="oidc">
68 `oidc`
69</h3>
70
71OpenID Connect（OIDC）は、ゲートウェイが ID プロバイダーで使用する SSO プロトコルです。IdP 側で登録する内容については、[ID プロバイダー設定](/ja/claude-apps-gateway-deploy#identity-provider-setup)を参照してください。`oidc` ブロックはゲートウェイを ID プロバイダーに接続し、サインイン可能なユーザーを決定します。発行者と OAuth クライアントに名前を付け、メールとグループを含むクレームをマップし、メールドメインまたはグループによるサインインを制限します。
72
73| フィールド | 必須 | 説明 |
74| ------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
75| `issuer` | はい | OIDC 検出ベース。`/.well-known/openid-configuration` で検出を提供する必要があります。本番環境では HTTPS を使用してください。ゲートウェイは `http://` 発行者を受け入れます。`http://localhost:8081` などのループバック発行者は、`CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` がゲートウェイの環境に設定されていない限り、[SSRF ガード](/ja/claude-apps-gateway-deploy#threat-model-summary)によって拒否されます。 |
76| `client_id` / `client_secret` | はい | OAuth クライアント登録から |
77| `allowed_email_domains` | いいえ | `email` クレームがこれらのドメインのいずれかにない id\_token を拒否します。大文字小文字を区別しません。マルチテナント IdP の設定ミスに対する多層防御。この設定とは無関係に、`email_verified` クレームが明示的に `false` である id\_token は常に拒否されます。 |
78| `allowed_groups` | いいえ | サインインを `groups_claim` に対してマッチしたこれらの IdP グループのメンバーに制限します。許可されたメールドメイン内にあるが、これらのグループのいずれにも属していないユーザーは拒否されます。IdP がグループクレームを発行する必要があります。 |
79| `groups_claim` | いいえ | グループメンバーシップを含む id\_token クレーム。デフォルト `groups`。Microsoft Entra はアプリロールを `roles` の下に発行します。フラットキーまたは `/resource_access/gateway/roles` などのネストされたクレーム用の RFC 6901 JSON ポインタを受け入れます。 |
80| `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` はグループメールでマッチします。 |
81| `email_claim` | いいえ | ユーザーのメールを含む id\_token クレーム。デフォルト `email`。ADFS や Entra B2C などの一部の IdP は、代わりに `upn` または `preferred_username` を発行します。フラットキー、JSON ポインタ、または最初に存在するキーが使用されるフォールバックキーのリストを受け入れます。 |
82| `scopes` | いいえ | ゲートウェイが要求する OIDC スコープの完全なオーバーライド。デフォルト `[openid, profile, email, offline_access]`。IdP が認識しないスコープを拒否する場合、またはグループまたはメールを発行するカスタムスコープが必要な場合に設定します。`openid` を含める必要があります。`offline_access` を削除するとリフレッシュトークンが無効になるため、開発者は `session.ttl_hours` ごとにブラウザログインを再実行します。Google のリフレッシュトークンフロー などの IdP ごとのスコープレシピについては、[ID プロバイダー設定](/ja/claude-apps-gateway-deploy#identity-provider-setup)を参照してください。 |
83| `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`。 |
84| `userinfo_fallback` | いいえ | id\_token がメールまたはグループを省略する場合、`/userinfo` から取得します。Keycloak 軽量アクセストークン、Okta org サーバー、ADFS 最小トークンに必要です。id\_token は権威的なままです。userinfo はギャップのみを埋めます。デフォルト `false`。 |
85| `use_pkce` | いいえ | 認可リクエストで PKCE（S256）チャレンジを送信します。デフォルト `true`。IdP がこの機密クライアントの PKCE を拒否する場合のみ `false` に設定します。 |
86| `clock_skew_seconds` | いいえ | id\_token 時間クレームを検証する際にクロックドリフトを許容します。デフォルト `0`（厳密）。サインイン直後のホスト/IdP クロックスキューによる「トークン期限切れ/まだ有効でない」エラーが表示される場合は、増やします。 |
87| `token_endpoint_auth_method` | いいえ | トークンエンドポイント認証方法をオーバーライドします。`client_secret_basic` または `client_secret_post` を受け入れます。デフォルトで自動ネゴシエーション。 |
88| `id_token_signed_response_alg` | いいえ | 予想される id\_token 署名アルゴリズム。デフォルト `RS256`。ES256、PS256、または EdDSA で署名する IdP に設定します。 |
89| `additional_authorized_parties` | いいえ | `client_id` を超えて受け入れる追加の `azp` 値。Keycloak ブローカーとトークン交換フロー用。 |
90| `discovery_url` | いいえ | `issuer` から派生させるのではなく、この URL から検出ドキュメントを取得します。プロキシの背後にある IdP の場合、発行者ホストを書き直します。パスは `/.well-known/` を含む必要があります。 |
91| `form_action_origins` | いいえ | `/device` ページの `Content-Security-Policy: form-action` ディレクティブの追加オリジン。ゲートウェイはすでに `'self'` と検出された `authorization_endpoint` オリジンを許可していますが、Chrome は全リダイレクトチェーンに対して `form-action` を強制します。IdP が Azure AD から ADFS へのフェデレーション、ハブスポーク Okta、または企業 SSO インターセプターなど、2 番目のホストを通じてリダイレクトする場合、認可リクエストがリダイレクトする可能性のあるすべてのオリジンをリストします。 |
92| `ca_cert_pem` | いいえ | IdP リクエストのみのシステムトラストストアを置き換える PEM CA 証明書。企業 PKI の背後にある Keycloak または Dex に使用します。 |
93
94<h3 id="session">
95 `session`
96</h3>
97
98`session` ブロックは、サインイン後にゲートウェイが発行するベアラートークンの形状を決定します：それらに署名するシークレットと、どのくらい長く生きるか。
99
100| フィールド | 必須 | 説明 |
101| ------------ | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102| `jwt_secret` | はい | 少なくとも 32 バイトのエントロピー。例えば `openssl rand -base64 32` から。ゲートウェイの HS256 ベアラートークンに署名します。単一の文字列または回転用の配列を受け入れます：インデックス 0 が署名し、すべてのエントリが検証します。回転するには、新しいシークレットを先頭に追加し、`ttl_hours` 待機してから古いものを削除します。 |
103| `ttl_hours` | いいえ | ゲートウェイベアラートークンの有効期間。デフォルト `1`。CLI は IdP がリフレッシュトークンを発行する場合、有効期限前に無言でリフレッシュします。有効期間が短いほど、より速くプロビジョニング解除されます。長いほど、IdP ラウンドトリップが少なくなります。IdP が `offline_access` が利用できないため、リフレッシュトークンを発行できない場合、無言リフレッシュはないため、開発者が 1 時間ごとにブラウザログインに戻されるのを避けるために、これを `8` または `12` に上げます。 |
104
105<h3 id="store">
106 `store`
107</h3>
108
109`store` ブロックは、ゲートウェイを PostgreSQL データベースに指します。このデータベースは、デバイスグラントとレート制限カウンターを保持します。
110
111| フィールド | 必須 | 説明 |
112| ----------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
113| `postgres_url` | はい | `postgres://` または `postgresql://` URL。必須：デバイスグラント集合場所。ブラウザコールバックが書き込み、ポーリング CLI が読み込む場所。レプリカ間の状態が必要です。ゲートウェイはブート時に独自のスキーママイグレーションを実行するため、ロールはターゲットスキーマで `CREATE TABLE` が必要です。セキュリティポリシーがアプリケーションロールからの DDL を禁止する場合、マイグレーションを管理者ロールで実行し、最初と新しいリリースがマイグレーションを出荷するたびに、アプリロールに `SELECT, INSERT, UPDATE, DELETE` をゲートウェイのテーブルで付与します。[アップグレード](/ja/claude-apps-gateway-deploy#upgrades)と [Postgres](/ja/claude-apps-gateway-deploy#postgres) を参照してください。 |
114| `username` | いいえ | `postgres_url` のユーザーをオーバーライド |
115| `password` | いいえ | データベース認証情報。`postgres_url` ではなくここに設定して、認証情報を URL から外します。任意の文字を受け入れ、URL 認証情報よりも優先されます。 |
116| `max_connections` | いいえ | レプリカごとの Postgres 接続プール サイズ。デフォルト `5`。共有データベースに対して保守的でフレンドリーです。[支出制限](#admin)が有効な場合、ホットパスは推論リクエストごとに数回の操作を実行するため、専用データベースの負荷の下で増やし、レプリカ × これをデータベースの `max_connections` 以下に保ちます。 |
117
118ローカル開発の場合、`postgres_url` を使い捨て Postgres コンテナに指します。例えば `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。
119
120<h3 id="upstreams">
121 `upstreams`
122</h3>
123
124`upstreams` は順序付きリストです。ゲートウェイは、要求されたモデルを解決する最初のアップストリームに推論を転送します。`5xx`、`429`、またはタイムアウト時に次にフェイルオーバーします。他の `4xx` はしません。これらのエラーはリクエストではなくアップストリームに起因するためです。同じプロバイダーの複数のアップストリームは、異なる `name:` を設定する必要があります。
125
126Bedrock、Agent Platform、Foundry クライアントはスタートアップ時に 1 回構築され、SDK は内部的に認証情報をリフレッシュするため、クラウド認証情報のローテーションは再起動を必要としません。静的 Anthropic API キーとベアラーはスタートアップ時に読み込まれます。[Anthropic API](#anthropic-api) を参照してください。
127
128<h4 id="anthropic-api">
129 Anthropic API
130</h4>
131
132最小限の Anthropic アップストリームは、[Claude Console](https://platform.claude.com) からの API キーです：
133
134```yaml theme={null}
135upstreams:
136 - provider: anthropic
137 auth:
138 api_key: ${ANTHROPIC_API_KEY}
139 # または OAuth ベアラー（例：Workload-Identity-Federation 交換トークン）：
140 # oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
141 # base_url: https://api.anthropic.com # デフォルト；フォワードプロキシの場合はオーバーライド
142```
143
1442 つの認証情報形式は、送信するヘッダーが異なります：
145
146* **`api_key`**：`x-api-key` を送信します。Claude Console でローテーションし、env var を更新します。
147* **`oauth_token`**：`Authorization: Bearer` を送信します。組織が長期 API キーではなく短期トークンを発行する場合、ベアラー形式を使用します。ベアラーはスタートアップ時に 1 回読み込まれるため、シークレットを再マウントして再起動することで更新します。
148
149静的キーまたはベアラーの代わりに、Workload Identity Federation を使用できます。[Workload Identity Federation ガイド](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)に従って、フェデレーションルールを作成し、ワークロードの OIDC JWT をファイルとしてマウントします。例えば、Kubernetes プロジェクトサービスアカウントトークンまたは CI プラットフォームの id-token。ゲートウェイは JWT を短期ベアラーと交換し、自動的にリフレッシュします。トークンファイルはすべての交換で再読み込みされるため、ローテーションされたプロジェクトトークンは再起動なしで取得されます。
150
151```yaml theme={null}
152upstreams:
153 - provider: anthropic
154 auth:
155 federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
156 organization_id: ${ANTHROPIC_ORGANIZATION_ID}
157 identity_token_file: /var/run/secrets/anthropic/id-token
158 # workspace_id: wrkspc_... # ルールが 1 つ以上のワークスペースをカバーする場合は必須
159 # service_account_id: svac_... # オプションの予想ターゲットチェック
160```
161
162<h4 id="amazon-bedrock">
163 Amazon Bedrock
164</h4>
165
166ゲートウェイが置き換えるまたはフロントする、クライアント側の Bedrock デプロイメントについては、[Amazon Bedrock の Claude Code](/ja/amazon-bedrock) を参照してください。ゲートウェイ側のアップストリーム：
167
168```yaml theme={null}
169upstreams:
170 - provider: bedrock
171 region: us-east-1
172 auth: {} # 推奨：AWS デフォルト認証情報チェーン
173 # または明示的な認証情報：
174 # auth:
175 # aws_access_key_id: ${AWS_AKID}
176 # aws_secret_access_key: ${AWS_SK}
177 # aws_session_token: ${AWS_ST}
178 # または Bedrock API ベアラートークン：
179 # auth:
180 # aws_bearer_token: ${AWS_BEARER_TOKEN}
181 # FIPS または VPC エンドポイントデプロイメント用に bedrock-runtime エンドポイントをオーバーライド：
182 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com
183```
184
185空の `auth` ブロックは AWS SDK のデフォルト認証情報チェーンを使用します：env vars、`~/.aws/credentials`、ECS タスクロール、EC2 インスタンスメタデータ、または EKS の IRSA。本番環境では、コンテナイメージに静的キーを埋め込むのではなく、ゲートウェイポッドに IAM ロールを付与します。
186
187| セットアップ | 方法 |
188| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
189| IAM 権限 | ゲートウェイのプリンシパルに `bedrock:InvokeModel` と `bedrock:InvokeModelWithResponseStream` を推論プロファイル ARN と基盤モデル ARN の両方に付与します。US リージョンの組み込みカタログの場合：`arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` と `arn:aws:bedrock:*::foundation-model/anthropic.*`。 |
190| モデルアクセス | Bedrock コンソールで、リージョンごとに、必要な Claude モデルのモデルアクセスをリクエストして有効にします。クロスリージョン推論プロファイル（`us.anthropic.*`）は、プロファイルがスパンする各リージョンでモデルアクセスが必要です。 |
191| EKS（IRSA） | 上記のポリシーと、クラスターの OIDC プロバイダーのトラストポリシーを持つ IAM ロールを作成します。ゲートウェイのサービスアカウントにスコープされます。サービスアカウントに `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway` でアノテーションを付けます。`auth: {}` がそれを取得します。 |
192| ECS / EC2 | IAM ロールをタスク定義またはインスタンスプロファイルにアタッチします。`auth: {}` がそれを取得します。 |
193| その他の場所 | `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、`AWS_SESSION_TOKEN` env vars を通じて認証情報を渡すか、`auth:` で `${VAR}` 展開を使用して明示的に設定します。 |
194| リージョン | `region:` は API エンドポイントリージョンです。クロスリージョン推論プロファイルは、どれを選択するかに関わらず、地域（US、EU、APAC）全体でルーティングします。US 以外のリージョンまたはプロビジョニングスループット ARN の場合、正しいアップストリームごとの ID を持つ [`models:`](#models) ブロックを追加します。 |
195
196<h4 id="google-cloud-agent-platform">
197 Google Cloud Agent Platform
198</h4>
199
200同等のクライアント側セットアップについては、[Google Cloud の Claude Code](/ja/google-vertex-ai) を参照してください。ゲートウェイ側のアップストリーム：
201
202```yaml theme={null}
203upstreams:
204 - provider: vertex
205 region: us-east5
206 project_id: example-prod
207 auth: {} # 推奨：Application Default Credentials
208 # またはサービスアカウントキーファイル：
209 # auth: { service_account_json: /secrets/sa.json }
210 # Private Service Connect 用に aiplatform エンドポイントをオーバーライド：
211 # base_url: https://us-east5-aiplatform.p.googleapis.com
212```
213
214空の `auth` ブロックは Application Default Credentials を使用します：`GOOGLE_APPLICATION_CREDENTIALS`、GCE メタデータ、または GKE Workload Identity。サービスアカウント JSON キーファイルはサポートされていますが、推奨されません。Workload Identity を使用するか、GCE または Cloud Run インスタンスにサービスアカウントをアタッチします。
215
216`region: global` を設定して、地域のエンドポイントの代わりに [Agent Platform のグローバルエンドポイント](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)を使用します。Google は各リクエストを利用可能なリージョンにルーティングするため、リージョンごとのモデル可用性を追跡する必要はありません。特定のリージョンを設定すると、すべてのリクエストがそれにピンされます。
217
218| セットアップ | 方法 |
219| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
220| IAM 権限 | ゲートウェイのサービスアカウントに `roles/aiplatform.user` をプロジェクトに付与するか、`aiplatform.endpoints.predict` を持つカスタムロール。Agent Platform API（`aiplatform.googleapis.com`）を有効にします。 |
221| モデルアクセス | Model Garden で、プロジェクトの Claude モデルを有効にします。特定のリージョンに公開されます。サポートされているリージョンについてはモデルカードを確認してください。 |
222| GKE（Workload Identity） | GCP サービスアカウントをゲートウェイの Kubernetes サービスアカウントにバインドし、KSA に `iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com` でアノテーションを付けます。`auth: {}` がそれを取得します。 |
223| Cloud Run / GCE | サービスのサービスアカウントを `roles/aiplatform.user` を持つものに設定します。`auth: {}` がそれを取得します。 |
224| その他の場所 | `auth: { service_account_json: /secrets/sa.json }`。JSON キーファイルへのパス。シークレットとしてマウントされます。フィールドはキーの内容ではなくファイルパスを取得するため、`${file:…}` 展開は関係ありません。 |
225
226<h4 id="microsoft-foundry">
227 Microsoft Foundry
228</h4>
229
230クライアント側の Foundry デプロイメントについては、[Microsoft Foundry の Claude Code](/ja/microsoft-foundry) を参照してください。ゲートウェイ側のアップストリーム：
231
232```yaml theme={null}
233upstreams:
234 - provider: foundry
235 resource: example-foundry # https://example-foundry.services.ai.azure.com
236 auth: { use_azure_ad: true } # 推奨：DefaultAzureCredential / Managed Identity
237 # または API キー：
238 # auth:
239 # api_key: ${FOUNDRY_API_KEY}
240```
241
242`use_azure_ad: true` は `DefaultAzureCredential` を通じて解決します：AKS、ACI、または App Service の Managed Identity、Azure CLI、または環境認証情報。API キーは機能しますが、プロジェクト全体であり、自動的にローテーションされません。Foundry のエンドポイントは `resource:` から派生します。Azure Government などのソブリンクラウドの場合、オプションの `base_url` を設定してオーバーライドします。
243
244| セットアップ | 方法 |
245| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
246| RBAC | ゲートウェイのアイデンティティに `Azure AI User` または `Cognitive Services User` を Foundry リソースに付与 |
247| デプロイメント | Foundry は正規モデル ID ではなく、管理者が選択したデプロイメント名を使用します。各正規 ID をデプロイメント名にマップする [`models:`](#models) ブロックを追加します。 |
248| AKS（ワークロードアイデンティティ） | User-Assigned Managed Identity をクラスターの OIDC 発行者とフェデレーションし、ゲートウェイのサービスアカウントにバインドします。`use_azure_ad: true` は `WorkloadIdentityCredential` を通じてそれを取得します。 |
249| ACI / App Service | リソースでシステム割り当てまたはユーザー割り当てマネージドアイデンティティを有効にします。`use_azure_ad: true` がそれを取得します。 |
250| その他の場所 | `auth: { api_key: "${FOUNDRY_API_KEY}" }`。`{ }` 内の `${…}` をクォートします。 |
251
252<h4 id="multiple-upstreams">
253 複数のアップストリーム
254</h4>
255
256同じプロバイダーは、異なる `name:` で複数回表示できます。これは異なるリージョン、異なる認証情報チェーン経由の異なるアカウント、プロビジョニングスループット対オンデマンド、クロスプロバイダーフェイルオーバーをカバーします。
257
258ゲートウェイはアップストリームを順番に試します。`5xx`、`429`、タイムアウト、および欠落エンドポイント（`501`）はフェイルオーバーします。他の `4xx` はしません。`429` はアップストリーム容量ごとです。プロビジョニングスループット（PT）枯渇はオンデマンドにフェイルオーバーします。要求されたモデルを解決できないアップストリームはネットワークラウンドトリップなしでスキップされます。
259
260この例は、プロビジョニングスループット Bedrock 割り当てを最初にルーティングし、オンデマンドと 2 番目のアカウントにオーバーフロー、最後に Anthropic API にフォールバックします：
261
262```yaml theme={null}
263upstreams:
264 # プライマリ：ホームリージョンのプロビジョニングスループット。
265 - name: bedrock-pt
266 provider: bedrock
267 region: us-east-1
268 auth: {}
269 # オーバーフロー：オンデマンドクロスリージョン。
270 - name: bedrock-od
271 provider: bedrock
272 region: us-west-2
273 auth: {}
274 # 異なるアカウント：想定ロール認証情報経由の別の Bedrock 割り当て。
275 - name: bedrock-acct2
276 provider: bedrock
277 region: us-east-1
278 auth:
279 aws_access_key_id: ${ACCT2_AKID}
280 aws_secret_access_key: ${ACCT2_SK}
281 # 最後の手段：直接 Anthropic API。
282 - name: anthropic-fallback
283 provider: anthropic
284 auth:
285 api_key: ${ANTHROPIC_API_KEY}
286
287# アップストリームごとのモデル ID はアップストリームの `name:` でキーイングされます。`name:` のないアップストリームはプロバイダー文字列（例：`bedrock`）にデフォルト設定されます。モデルにリストされていないアップストリームはスキップされます。これは、プロビジョニングスループットにモデルをルーティングしながら、他のすべてがオンデマンドのままである方法です。
288models:
289 - id: claude-opus-4-8
290 label: Claude Opus 4.8
291 upstream_model:
292 bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef
293 bedrock-od: us.anthropic.claude-opus-4-8
294 bedrock-acct2: us.anthropic.claude-opus-4-8
295 anthropic-fallback: claude-opus-4-8
296```
297
298| レバー | 方法 |
299| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
300| 異なるリージョン | リージョンごとに 1 つの Bedrock アップストリーム。それぞれ独自の `region:` を持ちます。[`auto_include_builtin_models: true`](#models) を使用すると、クロスリージョン推論プロファイルは自動的にルーティングされます。リージョンピンデプロイメントの場合、`models:` ブロックを使用します。 |
301| 異なるアカウント | アカウントごとに 1 つの Bedrock アップストリーム。それぞれ `auth:` で独自の認証情報を持ちます。デフォルトチェーン（`auth: {}`）はポッドのアイデンティティを使用します。2 番目のアカウントの場合、明示的な認証情報またはベアラートークンを設定します。 |
302| プロビジョニングスループット | そのアップストリームの名前の `models:` でプロビジョニングスループット ARN にモデルをマップします。他のアップストリームはオンデマンド ID を保持するため、PT 容量はフェイルオーバー前に枯渇します。 |
303| VPC / FIPS エンドポイント | アップストリームで `base_url:` を VPC エンドポイントまたは FIPS エンドポイント URL に設定します。 |
304| モデルスコープルーティング | モデルの `upstream_model:` マップからアップストリームを省略し、そのアップストリームはそのモデルでスキップされます。例えば、Opus をプロビジョニングスループットにルーティングし、Sonnet と Haiku をオンデマンドにルーティングします。 |
305
306クラウドプロバイダー間、または直接 Anthropic API へのフェイルオーバーは、リクエストを管理する契約、地域、その他の条件を変更します。
307
308CLI は、どのアップストリームが特定のリクエストを提供するかに関わらず、ゲートウェイに同じ機能ゲーティングを適用するため、フェイルオーバーはアップストリームが拒否するボディフィールドを送信しません。
309
310<h2 id="optional-sections">
311 オプションセクション
312</h2>
313
314<h3 id="admin">
315 `admin`
316</h3>
317
318オプション。`/v1/organizations/spend_limits` を有効にします。これは Anthropic のパブリック Admin API をミラーリングし、`/v1/messages` で開発者ごとの支出強制を行います。[支出制限](/ja/claude-apps-gateway-spend-limits)で、キャップがどのように設定および強制されるかを参照してください。このセクションは、機能をオンにしてチューニングする `gateway.yaml` キーをカバーします。
319
320```yaml theme={null}
321admin:
322 # 管理エンドポイント用の名前付き静的 API キー。x-api-key として送信されます。
323 # ID は監査ログに admin-key:<id> として表示されるため、各キーは
324 # 属性可能です。回転用の配列：新しいキーを追加し、クライアントをロール、
325 # 古いものを削除します。
326 write_keys:
327 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
328 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
329 read_keys:
330 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
331 # 通常のゲートウェイ JWT（API キーなし）経由で完全な管理者を付与された IdP グループ。
332 admin_groups: [platform-finops]
333 blocked_message: request an increase at https://go.example.com/claude-limits
334```
335
336| フィールド | 必須 | 説明 |
337| ------------------------- | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
338| `write_keys` | いいえ | `{id, key}` の配列。これらのいずれかと一致する `x-api-key` は、支出制限をリスト、設定、削除できます。キー値は少なくとも 32 文字である必要があります。`id` は `read_keys` と `write_keys` 全体で一意である必要があります。 |
339| `read_keys` | いいえ | `{id, key}` の配列。読み取り専用：すべての `GET` エンドポイント。キャップのリスト、ID による 1 つの取得、[`/effective`](/ja/claude-apps-gateway-spend-limits#%2Feffective) と [`/audit`](/ja/claude-apps-gateway-spend-limits#%2Faudit) の読み取りを含みます。 |
340| `admin_groups` | いいえ | IdP グループ名。`groups` クレームがこれらのいずれかを含むゲートウェイ JWT は、完全な管理者アクセス、読み取りと書き込みを持ち、`oidc:<sub>` として監査されます。人間の管理者に使用します。マシンに API キーを使用します。 |
341| `blocked_message` | いいえ | ブロックされた開発者が見る `429 billing_error` に逐語的に追加されます。URL または Slack チャネルなど、完全な指示を書きます。未設定の場合、エラーは `spend limit reached` です。 |
342| `audit_retention_days` | いいえ | デフォルト `365`。古い `admin_audit` 行はスイープされます。 |
343| `spend_retention_months` | いいえ | デフォルト `13`。この期間より古い `spend` カウンター行はスイープされます。デフォルトは、年間比較レポート用に完全な年と現在の部分月を保持します。 |
344| `identity_retention_days` | いいえ | デフォルト `90`。`principal_emails` 行の最後に見た TTL。各開発者のメール、表示名、グループ（PII）を保持します。意図的に支出保持より短いため、プロビジョニング解除されたアイデンティティは、その匿名支出カウンターが残っている間に期限切れになります。 |
345| `group_limit_mode` | いいえ | `min`（デフォルト）または `max`。開発者が複数のグループにキャップがある場合、`min` は最も制限的なものを強制し、`max` は最も制限的でないものを強制します。強制と `/effective` の両方で使用されます。 |
346
347<h3 id="enforcement">
348 `enforcement`
349</h3>
350
351`enforcement` ブロックは、ストアが利用できない場合の支出制限チェックの動作を制御します。
352
353| フィールド | 必須 | 説明 |
354| ---------------------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
355| `fail_closed_on_error` | いいえ | デフォルト `false`。支出強制は Postgres 停止時にオープンで失敗するため、推論は稼働したままです。`true` に設定してクローズで失敗：上限を超えた開発者はブロックされますが、ストアに到達できない場合は他のすべてもブロックされます。[`admin:`](#admin) ブロックなしでは効果がありません。 |
356
357<h3 id="models">
358 `models`
359</h3>
360
361`models` ブロックはオプションの管理者がキュレーションしたモデルリストで、`/v1/models` で提供され、アップストリームごとのモデル ID を変換するために使用されます。US 以外の Bedrock リージョン、Bedrock プロビジョニングスループット ARN、Foundry デプロイメント名に必須です。
362
363```yaml theme={null}
364auto_include_builtin_models: true # false：以下のリストのみを公開
365models:
366 - id: claude-opus-4-8
367 label: Claude Opus 4.8
368 # description：オプションのテキスト。クライアントに表示される場合がある
369 upstream_model:
370 anthropic: claude-opus-4-8
371 bedrock: us.anthropic.claude-opus-4-8 # または推論プロファイル ARN
372 foundry: your-opus-deployment-name
373```
374
375<h3 id="managed">
376 `managed`
377</h3>
378
379`managed` ブロックは、IdP グループまたはメールドメインでキーイングされた、ロールベースのアクセスポリシーを定義します。ポリシーは順番に評価されます。最初のマッチが選択され、以下で説明する `match: {}` キャッチオール基盤にマージされます。ユーザーごとに `GET /managed/settings` で ETag/304 キャッシング付きで提供されます。
380
381```yaml theme={null}
382managed:
383 policies:
384 # 特定のグループを最初に。
385 - match: { groups: [eng-contractors] }
386 cli:
387 availableModels: [claude-sonnet-4-6]
388 permissions: { deny: ["WebFetch", "WebSearch"] }
389 # デフォルトキャッチオール最後：認証されたすべてのユーザーにマッチします。
390 - match: {}
391 cli:
392 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
393```
394
395`match: {}` キャッチオール。慣例的に最後にリストされます。基盤層として扱われます。他のすべてのポリシーは、設定しないキーについてキャッチオールから継承するため、ロール別エントリは組織デフォルトから異なるものだけをリストする必要があります。マージルールはキータイプに依存します：
396
397* **許可リスト**：`availableModels` と `permissions.allow`。特定のポリシーのリストは基盤のリストを完全に置き換えます。
398* **拒否リストとフックアレイ**：`permissions.deny`、`permissions.ask`、`disabledMcpjsonServers`、`deniedMcpServers`、`blockedMarketplaces`、およびすべての `hooks` イベントタイプアレイ。これらは基盤とポリシーの和集合を取得するため、組織全体の拒否または監査フックは、ロール別オーバーライドによって誤ってドロップされることはできません。
399* **レコードタイプキー**：`env`、`modelOverrides`、`skillOverrides`。これらは浅くマージするため、ロール別 `env` ブロックは設定するキーをオーバーライドし、基盤から残りを継承します。
400
401`availableModels` は `/v1/messages` でサーバー側でも強制されるため、拒否されたモデルはクライアントが送信するものに関わらず `400` を返します。
402
403| マッチャー | 動作 |
404| --------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
405| `match: {}` | 認証されたすべてのユーザーにマッチします。これで開始し、後で上にグループスコープポリシーを追加します。 |
406| `match: { groups: [a, b] }` | JWT の `groups` クレームがリストされたグループのいずれかを含む場合にマッチします。大文字小文字を区別します：グループは IdP の正確な大文字小文字と一致する必要があります。 |
407| `match: { email_domain: example.com }` | JWT の `email` クレームの最後の `@` の後の部分にマッチします。大文字小文字を区別しません。ポリシーごとに 1 つのドメインを受け入れます。 |
408| `match: { groups: [a], email_domain: example.com }` | 両方の条件がマッチする必要があります。 |
409
410ポリシーにマッチしない認証されたユーザーは、ゲートウェイのデフォルトを取得します。これは、カタログ内のすべてのモデルと管理設定なしを意味します。最後に `match: {}` キャッチオールを追加して、保証されたデフォルトポリシーが必要な場合。
411
412<Note>
413 ゲートウェイは独自のユーザーディレクトリを保持しません。ユーザーの IdP トークンから各リクエストを認可し、トークンの `groups` クレームからグループメンバーシップを読み込み、それに対してポリシーを評価します。列挙するロスターはなく、事前作成するアカウントもありません。したがって、SCIM エンドポイントはありません。SCIM が同期するものがないためです。
414
415 ユーザーとグループのライフサイクル管理を、真実の源である IdP のネイティブ SCIM プロビジョニングまたは専用アイデンティティガバナンスプラットフォームで実行します。メンバーシップとプロビジョニング解除はそこで管理され、トークンを通じてゲートウェイに自動的に流れます。Claude アカウント自体の SCIM プロビジョニングが必要な場合、それは [Claude for Enterprise](/ja/admin-setup) 機能です。
416
417 2 つの伝播クロックが適用されます：
418
419 * **ポリシーコンテンツ**：ポリシーを編集して再デプロイすると、接続されたクライアントの次のマネージド設定ポーリング時に到達します。1 時間以内。
420 * **グループメンバーシップ**：ユーザーのグループメンバーシップを変更すると、どのポリシーが彼らにマッチするかが変わります。これは次のセッション再発行時に有効になります。つまり、次の無言リフレッシュ。`session.ttl_hours` で制限されます。
421</Note>
422
423<h4 id="what-goes-in-cli">
424 `cli` に何が入るか
425</h4>
426
427各 `cli` 値は、完全な Claude Code `managed-settings.json` ドキュメントです。MDM または `/etc/claude-code/managed-settings.json` を通じてデプロイするのと同じスキーマ。ここでは YAML として表現されます。CLI は、マネージド層で配信されたドキュメントを適用します。ユーザーとプロジェクト設定の上。
428
429ゲートウェイは、ブート時に CLI の設定スキーマに対して各ドキュメントを検証するため、認識されないトップレベルキーまたは認識されたキーで形式が正しくない値は、すべての違反キーに名前を付けるエラーでブートに失敗します。スキーマの意図的にオープンな部分は、新しいクライアントがゲートウェイのスキーマが認識しないエントリを認識する可能性があるため、任意の値を受け入れます。これらのオープンキーは `env`、`pluginConfigs`、`permissions` の下にネストされたキーです。
430
431検証はゲートウェイのインストール済みバージョンにバンドルされたスキーマを使用するため、新しい Claude Code リリースで導入されたトップレベル設定キーをマネージド設定に入れるには、最初にゲートウェイをアップグレードする必要があります。新しいポリシーを 1 つのクライアントでスモークテストしてから、ロールアウトします。
432
433完全なキーリファレンスは [Claude Code 設定](/ja/settings#available-settings) にあります。オペレーターが最初に到達するキー：
434
435```yaml theme={null}
436managed:
437 policies:
438 - match: {}
439 cli:
440 # モデルアクセス（/v1/messages でサーバー側でも強制）
441 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
442
443 # 権限ポリシー
444 permissions:
445 deny:
446 - "WebFetch"
447 - "Read(./.env)"
448 - "Read(./secrets/**)"
449 disableBypassPermissionsMode: disable # --dangerously-skip-permissions をブロック
450 allowManagedPermissionRulesOnly: true # ユーザー/プロジェクト権限ルールを無視
451
452 # CLI プロセスにプッシュされた環境。DISABLE_UPDATES はバックグラウンドと手動更新をブロック；DISABLE_AUTOUPDATER はバックグラウンド更新のみを停止。
453 env:
454 DISABLE_UPDATES: "1" # 独自の配布経由でバージョンをピン
455
456 # 組織全体のフック。フックコマンドはゲートウェイではなく開発者マシンで実行されるため、パスはポリシー内のすべてのクライアント OS に存在する必要があります。
457 hooks:
458 PostToolUse:
459 - matcher: "Edit|Write"
460 hooks:
461 - { type: command, command: /usr/local/bin/audit-edit.sh }
462```
463
464| キー | 強制者 | 効果 |
465| ------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
466| `availableModels` | ゲートウェイ + CLI | モデル許可リスト。`/v1/messages` でもチェックされるため、パッチされたクライアントはバイパスできません。 |
467| `permissions.allow` / `.deny` | CLI | ツールとコマンドルール。[権限](/ja/permissions)を参照してください。 |
468| `permissions.disableBypassPermissionsMode` | CLI | `disable` に設定して [`bypassPermissions`](/ja/permission-modes#skip-all-checks-with-bypasspermissions-mode) をブロック。すべてのツール呼び出しを自動承認するモード、および `--dangerously-skip-permissions` フラグ。 |
469| `allowManagedPermissionRulesOnly` | CLI | `true` の場合、ユーザーとプロジェクト権限ルールは無視されます。このドキュメントのルールのみが適用されます。 |
470| `env` | CLI | CLI プロセスにマージされた環境変数。テレメトリ、自動更新、モデル名オーバーライドに使用します。 |
471| `hooks` | CLI | 組織全体の [フック](/ja/hooks)。 |
472
473これらの設定はネットワーク経由で到着するため、CLI は、シェルコマンドを実行したり、トラフィックがどこに行くかを変更したりできるものを適用する前に、各開発者に 1 回限りのセキュリティ承認ダイアログを表示します。ダイアログは以下をカバーします：
474
475* `hooks`
476* `env` 変数。CLI の組み込みセーフリストにない
477* `apiKeyHelper` と `statusLine` などのシェル実行設定
478* マネージド CLAUDE.md コンテンツ
479
480セーフリストは、どの `env` 変数が承認なしで適用されるかを決定します：
481
482* **セーフリスト上**：自動更新とモデル名変数
483* **セーフリストにない**：プロキシ変数、ベース URL 変数、`OTEL_EXPORTER_OTLP_ENDPOINT`
484
485ゲートウェイの [テレメトリ](#telemetry) 設定は `OTEL_EXPORTER_OTLP_ENDPOINT` をプッシュするため、`telemetry.forward_to` を設定すると、各インタラクティブクライアントで承認ダイアログがトリガーされます。`-p` フラグを使用した非インタラクティブ実行は、ダイアログをスキップし、承認なしで設定を適用します。ダイアログは、組織から開発者を保護するのではなく、開発者のマシンを侵害または敵対的なゲートウェイから保護するため、`-p` スキップは意図的なギャップではなく意図的です。
486
487開発者が拒否した場合、Claude Code は設定を適用せずに終了します。新しいフックまたは非セーフ env var を広いポリシーにプッシュすることは、マッチする開発者の次の起動時に承認プロンプトを意味します。
488
489`cli` キーは以前のリリースで `settings` という名前でした。その綴りはまだエイリアスとして受け入れられていますが、新しいデプロイメントは `cli` を使用する必要があります。
490
491<h4 id="precedence-with-other-managed-sources">
492 他のマネージドソースとの優先順位
493</h4>
494
495デバイスにローカル `managed-settings.json` または MDM 配信ポリシーもある場合、マネージドソースはマージされません。最優先ソースはすべてのポリシー設定を提供します。この順序でランク付けされます。最優先順位が最初：
496
4971. [ポリシーヘルパー](/ja/settings#compute-managed-settings-with-a-policy-helper)
4982. ゲートウェイ配信設定
4993. MDM。Windows の HKLM レジストリまたは macOS の plist 経由
5004. `managed-settings.json` ファイル
5015. HKCU レジストリ。Windows のみ
502
503埋め込みホストは SDK `managedSettings` オプションを通じてポリシーを提供できます。デフォルトでは無視され、マネージドソースが [`parentSettingsBehavior: "merge"`](/ja/settings#available-settings) でオプトインした場合のみ適用されます。ポリシーを厳しくできますが、緩くすることはできません。
504
505例外は、管理者ソースが設定する場合に尊重される小さなキーセットです。ユーザー書き込み可能な HKCU 層は除外されます：
506
507* `sandbox.network.allowManagedDomainsOnly` と `sandbox.filesystem.allowManagedReadPathsOnly`：ロックされている場合、対応する許可リストはソース全体で和集合されます。
508* [`allowAllClaudeAiMcps`](/ja/settings#available-settings)：claude.ai MCP サーバー許可リストの許可のみオーバーライド
509* `sandbox.bwrapPath` と `sandbox.socatPath`：[サンドボックス](/ja/sandboxing)ヘルパーバイナリへのファイルシステムパス
510
511`allowManagedPermissionRulesOnly` と `disableBypassPermissionsMode` はクロスソースではないため、勝利ソースの値のみが適用されます。
512
513ゲートウェイポリシーはマシン上のすべての Claude Code 呼び出しに適用されます。非インタラクティブ `claude -p` 実行と Agent SDK によって生成されたセッションを含みます。ゲートウェイがスタートアップ時に到達不可能な場合、署名されたセッションはポリシーなしで実行するのではなく、エラーで終了します。
514
515<Warning>
516 ポリシーの `cli` ブロック内の `mcpServers` はゲートウェイブートで拒否されます。グループごとの MCP 配布は利用できません。各デバイスでファイルベースの `managed-mcp.json` を通じて MCP サーバーをデプロイするか、開発者がローカルで追加できるようにします。
517</Warning>
518
519<h3 id="telemetry">
520 `telemetry`
521</h3>
522
523CLI は OpenTelemetry Protocol（OTLP）を HTTP メトリクス、ログ、有効な場合はトレースでゲートウェイに送信します。ゲートウェイはそれらを逐語的に各設定先にリレーします。[使用状況の監視](/ja/monitoring-usage)で、CLI が発行するメトリクスとイベントを参照してください。
524
525CLI は、ゲートウェイ発行 JWT から読み込まれた認証されたユーザーのアイデンティティで各エクスポートにスタンプを付けます：`user.id`、`user.email`、`user.groups` 属性。開発者ごとのコストと使用状況の属性は、開発者側の設定なしで機能します。
526
527```yaml theme={null}
528telemetry:
529 forward_to:
530 - url: https://otel-collector.internal.example.com
531 headers:
532 Authorization: ${OTLP_TOKEN}
533 # シグナルごとのオプトイン。デフォルト：メトリクスのみ。
534 metrics: true
535 logs: false
536 traces: false
537 - url: https://api.datadoghq.com/api/v2/otlp
538 headers:
539 DD-API-KEY: ${DD_API_KEY}
540```
541
542<Warning>
543 各宛先は `metrics`、`logs`、`traces` に独立してオプトインし、デフォルトはメトリクスのみです。シグナルは感度が異なります：
544
545 * **メトリクス**：トークンカウント、リクエストカウント、レイテンシなどの集計カウンター
546 * **ログとトレース**：完全な bash コマンド、ツール入力、ファイルパスを含むことができます。Claude Code が開発者のマシンで行うすべてをカバーします。
547
548 ログとトレースは、アクセス制御と保持ポリシーがデータを保証する宛先でのみ有効にします。
549</Warning>
550
551テレメトリは CLI でデフォルトでオフです。`telemetry.forward_to` を `listen.public_url` と一緒に設定するとオンになります。ゲートウェイは 5 つの env var を `/managed/settings` を通じてすべての接続されたクライアントにプッシュします：
552
553* `CLAUDE_CODE_ENABLE_TELEMETRY=1`
554* `OTEL_METRICS_EXPORTER=otlp`
555* `OTEL_LOGS_EXPORTER=otlp`
556* `OTEL_TRACES_EXPORTER=otlp`
557* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`
558
559プッシュされたエンドポイントはパブリック URL から構築されるため、メトリクスとログは開発者またはポリシーからの OTEL 設定を必要としません。プッシュされた設定はマネージド層で適用され、開発者がローカルで設定する `OTEL_*` 変数をオーバーライドします。
560
561[トレース](/ja/monitoring-usage#traces-beta)はさらに各クライアントで `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` を必要とします。ゲートウェイはその変数をプッシュしないため、マネージドポリシーの `env` ブロックを通じて設定します。CLI のセーフリストにはないため、ポリシーを通じてそれを配信することは、プッシュされた OTLP エンドポイントがすでにトリガーする同じ [セキュリティ承認ダイアログ](#managed)でカバーされます。
562
563protobuf と JSON OTLP エンコーディングの両方がリレーされ、OpenTelemetry 互換バックエンドは宛先として機能します。
564
565<h3 id="http-tuning">
566 HTTP チューニング
567</h3>
568
5694 つのオプションのトップレベルブロック、`access_control`、`limits`、`timeouts`、`rate_limits`。HTTP サーフェスをチューニングします。デフォルトはほとんどのデプロイメントに適しています。
570
571| ブロック | キー | デフォルト | 説明 |
572| ---------------- | ---------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
573| `access_control` | `allow_cidrs` / `deny_cidrs` | 空 | `trusted_proxies` 解決後のクライアントアドレスによるインバウンド IP 許可/拒否。`deny_cidrs` が最初にチェックされます。クライアントがマッチする場合、`allow_cidrs` もマッチしても拒否されます。`allow_cidrs` が空でない場合、ゲートウェイはデフォルト拒否です。`/healthz` と `/readyz` は `allow_cidrs` から除外されます。 |
574| `limits` | `max_request_bytes` | 32 MiB | 最大インバウンドリクエストボディ。サイズを超えるリクエストはボディがバッファリングされる前に `413` を取得します。大きなファイルまたは画像リクエストの場合は増やします。 |
575| `limits` | `max_request_header_bytes` | 未設定 | 設定すると、サイズを超えるヘッダーは `431` を返します。 |
576| `limits` | `max_url_length` | 未設定 | 設定すると、長すぎる URL は `414` を返します。 |
577| `timeouts` | `upstream_ttfb_ms` | 120000 | アップストリームのレスポンスヘッダー（初バイト時間）を待つ最大時間。レスポンスボディはその後、ウォールクロックキャップなしでストリーミングされます。直接 Anthropic アップストリームパスに適用されます。Bedrock、Agent Platform、Foundry はプロバイダー SDK 独自のタイムアウトで制限されます。 |
578| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 認証されていないデバイス認可エンドポイントの IP ごとのレート制限。共有エグレス IP または NAT の背後にある大規模な組織の場合は増やします。これらの制限は、デバイスグラント サインインフローにのみ適用され、`/v1/messages` 推論には適用されません。[ユーザーコードブルートフォース耐性](/ja/claude-apps-gateway-deploy#user-code-brute-force-resistance)を参照してください。 |
579| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | `/device` での `user_code` 送信の IP ごとのレート制限。 |
580
581<h2 id="complete-example">
582 完全な例
583</h2>
584
585この完全なリファレンス設定はすべてのコアセクションを実行します。[HTTP チューニングブロック](#http-tuning)はデフォルトを保持します。コピーして、不要なものを削除し、値を入力します。[クイックスタート](/ja/claude-apps-gateway#quickstart)の設定はこれの最小バージョンです。
586
587```yaml gateway.yaml theme={null}
588# 実行：
589# claude gateway --config gateway.yaml
590#
591# 運用ログの詳細度は CLAUDE_GATEWAY_LOG_LEVEL
592# 環境変数で制御されます（info | warn | error；デフォルト info）。監査イベントには影響しません。常に発行されます。
593
594listen:
595 host: 0.0.0.0
596 port: 8080
597 public_url: https://claude-gateway.internal.example.com
598 # TLS 終了 ingress の背後で実行する場合は tls ブロックを省略します。
599 # tls:
600 # cert: /certs/gateway.crt
601 # key: /certs/gateway.key
602 # trusted_proxies:
603 # - 10.0.0.0/8
604
605oidc:
606 issuer: https://example.okta.com
607 client_id: 0oa1example2
608 client_secret: ${OIDC_CLIENT_SECRET}
609 allowed_email_domains:
610 - example.com
611 # Okta org サーバーが発行者の場合は必須。id_token はメールとグループを省略できます。ゲートウェイは /userinfo から埋めます。
612 userinfo_fallback: true
613 # allowed_groups: [claude-code-users]
614 # Okta はグループスコープがリクエストされ、アプリのグループクレームフィルターが許可する場合のみグループを発行します。以下のコントラクターポリシーはグループでマッチするため、スコープはここでリクエストされます。
615 scopes: [openid, profile, email, offline_access, groups]
616 # extra_auth_params: { access_type: offline, prompt: consent } # Google
617 # groups_claim: groups # Entra アプリロール：`roles` を使用
618 # email_claim: email
619
620session:
621 jwt_secret: ${GATEWAY_JWT_SECRET} # openssl rand -base64 32
622 # ttl_hours: 1
623
624store:
625 postgres_url: ${GATEWAY_POSTGRES_URL}
626 # max_connections: 5
627
628# /v1/organizations/spend_limits を有効にします（Anthropic Admin API をミラーリング）
629# および /v1/messages での開発者ごとの支出強制。無効にするには省略します。
630# キャップ自体は admin API 経由で設定されます。ここではありません。
631# admin:
632# write_keys:
633# - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
634# read_keys:
635# - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
636# admin_groups: [platform-finops]
637# blocked_message: request an increase at https://go.example.com/claude-limits
638# # audit_retention_days: 365
639# # spend_retention_months: 13
640# # identity_retention_days: 90
641# # group_limit_mode: min
642
643# enforcement:
644# fail_closed_on_error: false
645
646upstreams:
647 - provider: anthropic
648 auth:
649 api_key: ${ANTHROPIC_API_KEY}
650
651 # - provider: bedrock
652 # region: us-east-1
653 # auth: {}
654
655 # - provider: vertex
656 # region: us-east5
657 # project_id: example-prod
658 # auth: {}
659
660 # - provider: foundry
661 # resource: example-foundry
662 # auth: { use_azure_ad: true }
663
664auto_include_builtin_models: true
665models:
666 - id: claude-opus-4-8
667 label: Claude Opus 4.8
668 upstream_model:
669 anthropic: claude-opus-4-8
670 # bedrock: us.anthropic.claude-opus-4-8
671 # vertex: claude-opus-4-8
672 # foundry: <your-opus-deployment-name>
673 - id: claude-sonnet-4-6
674 label: Claude Sonnet 4.6
675 upstream_model:
676 anthropic: claude-sonnet-4-6
677 - id: claude-haiku-4-5
678 label: Claude Haiku 4.5
679 upstream_model:
680 anthropic: claude-haiku-4-5
681
682managed:
683 policies:
684 - match: { groups: [contractors] }
685 cli:
686 availableModels: [claude-haiku-4-5]
687 # Default ピッカーオプションを availableModels に制限します。デフォルトの代わりに、コントラクターが default で 400 を取得しないようにします。
688 enforceAvailableModels: true
689 # allow はこれらのツールを自動承認します。残りをブロックしません。
690 # ツールを制限するには deny ルールを追加します。
691 permissions: { allow: [Read, Grep] }
692 - match: {}
693 cli:
694 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
695 permissions:
696 allow: [Read, Grep, Bash, Edit]
697 deny: ["WebFetch"]
698 env: { HTTP_PROXY: http://proxy.example.com:8080 }
699
700telemetry:
701 forward_to:
702 - url: https://otel.internal.example.com:4318
703 headers:
704 Authorization: Bearer ${OTEL_TOKEN}
705```
706
707<h2 id="client-side-managed-settings">
708 クライアント側マネージド設定
709</h2>
710
711上記のすべてはゲートウェイサーバーを設定します。開発者マシンをそれに指すことは、各デバイスで別々に設定されます。Claude Code の [マネージド設定](/ja/settings#settings-files) を通じて。ゲートウェイはこれらのキーをプッシュできません。ゲートウェイがどこにあるかをクライアントに伝えるものだからです。
712
713CLI の場合、OS ごとの `managed-settings.json` に両方のキーを設定します：
714
715```json theme={null}
716{
717 "forceLoginMethod": "gateway",
718 "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
719}
720```
721
722そのファイルを各デバイスにデプロイします。通常は MDM プラットフォーム経由。ファイルパスはプラットフォームによって異なります：
723
724| プラットフォーム | パス |
725| ----------- | ---------------------------------------------------------------------------------------------------------- |
726| macOS | `/Library/Application Support/ClaudeCode/managed-settings.json`、または `com.anthropic.claudecode` マネージド設定ドメイン |
727| Linux と WSL | `/etc/claude-code/managed-settings.json` |
728| Windows | `C:\Program Files\ClaudeCode\managed-settings.json`、または HKLM レジストリ経由のグループポリシー |
729
730`forceLoginGatewayUrl` と `forceLoginMethod` の `"gateway"` 値は、管理者制御マネージド層からのみ尊重されます。開発者が独自の `~/.claude/settings.json` で設定しても効果がありません。
731
732<h2 id="related">
733 関連
734</h2>
735
736* [Claude apps gateway 概要](/ja/claude-apps-gateway)：クイックスタートと開発者接続
737* [デプロイメントガイド](/ja/claude-apps-gateway-deploy)：IdP セットアップ、コンテナイメージ、Kubernetes と Cloud Run、運用
738* [支出制限](/ja/claude-apps-gateway-spend-limits)：開発者ごとのキャップと Admin API
