Claude apps gateway 設定

​

ファイル構造

• listen：バインドアドレス、パブリック URL、TLS ターミネーション
• oidc：ID プロバイダー（IdP）、発行者、クライアント、クレームマッピング、サインイン可能なユーザーを含む
• session：ゲートウェイが発行するベアラートークン、シークレット、ライフタイム
• store：デバイスグラント、レート制限カウンター用の PostgreSQL
• upstreams：推論の送信先、Anthropic、Amazon Bedrock、AWS 上の Claude Platform、Google Cloud の Agent Platform、Microsoft Foundry のいずれか

• login_notice：開発者がサインイン時に表示される通知
• admin：Admin API 認証、支出制限の保持
• enforcement：支出制限のフェイルオープンまたはフェイルクローズ動作
• pricing：契約レート、支出メーター用の乗数、開発者が表示するコスト数値用の乗数
• models と auto_include_builtin_models：管理者がキュレーションしたモデルリスト、アップストリームごとの ID
• managed：IdP グループ別の管理設定ポリシー
• telemetry：オブザーバビリティスタックへの OTLP フォワーディング
• access_control、limits、timeouts、rate_limits：IP 許可/拒否、リクエストサイズ上限、アップストリーム初バイト到達時間、IP ごとのサインイン制限
• load_test_mode：モデルプロバイダーを呼び出さずにゲートウェイをロードテストする

​

シークレット展開

​

必須セクション

​

listen

​

oidc

​

証明書によるクライアント認証

openssl req -x509 -newkey rsa:2048 -nodes -keyout idp-client.key -out idp-client.crt -days 365 -subj "/CN=claude-gateway"

oidc:
  issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
  client_id: <application-id>
  token_endpoint_auth_method: private_key_jwt
  client_assertion:
    private_key_pem: ${file:/etc/gateway/idp-client.key}
    certificate_pem: ${file:/etc/gateway/idp-client.crt}

[gateway] 2026-10-01T23:07:40.512Z info oidc: client authentication private_key_jwt; certificate CN=claude-gateway, SHA-1 thumbprint DE92821854EE8BAA1D98C758FAA04AABE80B9F57, expires Oct  1 23:07:31 2027 GMT

​

クライアント証明書をローテーションする

1. 新しい証明書を、古い証明書と並べて IdP にアップロードします。
2. gateway.yaml が読み込む鍵と証明書のファイルを置き換えてから、ゲートウェイを再起動します。複数のレプリカを実行している場合は、古い証明書を削除するまで IdP が両方の証明書を持っているため、ローリング再起動が機能します。
3. すべてのレプリカが再起動したら、古い証明書を IdP から削除します。

​

フォワードプロキシ経由の IdP リクエスト

​

プロキシのみのエグレス

export HTTPS_PROXY=http://proxy.corp.example.com:3128
export NO_PROXY=
export no_proxy=
export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1

• HTTPS_PROXY または HTTP_PROXY が設定されている。
• NO_PROXY と no_proxy が空である。プラットフォームがいずれかを Pod に注入する場合は、ゲートウェイコンテナで両方を空の値に設定してください。NO_PROXY にテレメトリコレクターを列挙すると、プロキシのみのエグレスはオフのままになります。
• CLAUDE_GATEWAY_ALLOW_LOOPBACK がオンになっていない。Pod 自身のループバック上にあるコレクターや IdP は、プロキシのみのエグレスと組み合わせることはできません。プロキシに渡されたループバックアドレスはプロキシホスト自身のものになってしまうため、代わりにそれらのサービスにはプロキシが到達できるアドレスを与えてください。同じ理由で、プロキシのみのエグレスが有効な間、ゲートウェイは localhost のような名前を一律に拒否します。

​

session

​

store

​

upstreams

​

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

• ゲートウェイがフェイルオーバーしないステータスをアップストリームが返した場合: そのアップストリームのレスポンス。ゲートウェイはそれ以上のアップストリームを試行しません。
• ゲートウェイが試行したすべてのアップストリームが、フェイルオーバーの対象となる形で失敗した場合：最後の 429。429 を返したものがない場合、ゲートウェイは最後の 401 または 403、最後の 404、最後の 501 の順に優先します。それらのいずれも返されなかった場合は、ゲートウェイ自身の 502、all upstreams failed (N attempted) を返します。N は、スキップされたものも含めた upstreams のエントリ数から、groups リストにその開発者が含まれていないものを除いた数です。

• 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 など、ステータスごとの汎用的な文言。

​

Anthropic 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

• api_key: x-api-key を送信します。Claude Console でローテーションし、環境変数を更新してください。
• oauth_token: Authorization: Bearer を送信します。組織が長期間有効な API キーの代わりに短命のトークンを発行する場合は、ベアラー形式を使用してください。ベアラーは起動時に一度だけ読み込まれるため、シークレットを再マウントして再起動することでリフレッシュします。

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

自分で運用するプロキシ向けのユーザーごとの ID ヘッダー

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

​

Amazon Bedrock

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

Amazon Bedrock ガードレールを適用する

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123                    # guardrail ID or full ARN
      version: "1"                     # a published version number, or DRAFT
 # keep the quotes: a bare 1 fails at boot

ガードレールの入力タグを追加する

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123
      version: "1"
      input_tagging: user_messages

入力タグの対象外となるもの

• ゲートウェイがタグを付けないコンテンツ: input_tagging の値が対象外とするメッセージ、ツール定義、ツール呼び出しの入力、画像、PDF などです。all_messages_and_system を設定しない限り、システムプロンプトもタグ付けされません。
• ツールの結果: ファイルの内容や Web ページなど、Claude のツールが返す内容が含まれます。Anthropic のテストでは、タグの有無にかかわらず、単語フィルターはこれらを評価しませんでした。

どのガードレールフィルターが作動したかをログに記録する

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123
      version: "1"
    guardrail_trace: true              # default false; beside guardrail, not inside it

別の AWS アカウントの Bedrock

upstreams:
  - name: bedrock-isolated
    provider: bedrock
    region: us-east-1
    auth: {}                           # the gateway's own role: it only calls STS
    assume_role:
      role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
      # external_id: ${BEDROCK_ROLE_EXTERNAL_ID}   # when the role's trust policy requires one

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::111111111111:role/claude-gateway" },
    "Action": "sts:AssumeRole",
    "Condition": { "StringEquals": { "sts:ExternalId": "your-external-id" } }
  }]
}

• STS が拒否した場合や到達できない場合、ゲートウェイはアップストリーム自身の認証情報でリクエストを送信しません。確認すべき点とともに STS エラーをログに記録し、列挙した次のアップストリームを試行します。どのアップストリームも成功しなかった場合にクライアントが受け取る内容については、アップストリームのエラーメッセージで説明しています。assume_role のない後続のアップストリームは自身の認証情報でリクエストを処理するため、それを意図する場合にのみ列挙してください。
• ゲートウェイはリージョンの STS エンドポイント sts.<region>.amazonaws.com を呼び出すため、ゲートウェイのネットワークからそこに到達できる必要があります。FIPS エンドポイントを使用するには、AWS 設定ファイルの use_fips_endpoint ではなく、ゲートウェイの環境で AWS_USE_FIPS_ENDPOINT=true を設定してください。
• assume_role には SigV4 のソース認証情報が必要です。aws_bearer_token と並べて設定すると、ゲートウェイは起動を拒否します。
• groups リストがない場合、ゲートウェイが許可するすべての開発者がこのアップストリームを使用できます。開発者が使用できるモデルを制限するには、managed ポリシーで availableModels を設定してください。
• ロール経由で提供されるモデルが別のアカウントからも提供されないようにするには、そのモデルに、upstream_model マップにこのアップストリームの名前のみを持つカスタム ID を割り当ててください。そのような ID の場合、ゲートウェイは他のすべてのアップストリームをスキップするため、リクエストも、中断されたリクエストのトークンカウントも、別のアカウントにフェイルオーバーすることはありません。
• 組み込みのモデル名に対するリクエストは引き続きこのアップストリームに到達する可能性があり、ゲートウェイはそれを同じロールで署名します。このアカウントでそれらのモデルも提供すべきでない限り、このアップストリームは最後に記載してください。

models:
  - id: restricted-claude-opus-4-8      # a custom id, not a built-in model name
    upstream_model:
      bedrock-isolated: us.anthropic.claude-opus-4-8   # the only upstream that serves it

開発者ごとの AWS コスト帰属

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # the gateway's own role: it only calls STS
    assume_role:
      role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user
      session_name: email              # or sub

​

Amazon Bedrock Mantle エンドポイント

upstreams:
  - provider: mantle
    region: us-east-1
    models: [claude-opus-4-7, claude-haiku-4-5]   # required
    auth: {}                           # AWS default credential chain
  - provider: bedrock
    region: us-east-1
    auth: {}

• guardrail: ゲートウェイは Mantle に送信するリクエストに Bedrock ガードレールを適用しないため、いずれかの bedrock アップストリームで guardrail が設定されている状態で mantle アップストリームが列挙されていると、起動を拒否します。
• assume_role：mantle アップストリーム自体に設定してください。設定しない場合、Mantle が処理するリクエストは mantle アップストリーム自身の auth の認証情報で送信されます。

​

Claude Platform on AWS

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

​

Google Cloud Agent Platform

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

​

Microsoft Foundry

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}

​

アップストリームリクエストの静的ヘッダー

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    base_url: https://upstream-proxy.internal.example.com
    auth: {}
    headers:
      x-source: claude-apps-gateway
      x-proxy-token: ${PROXY_TOKEN}

• authorization と x-api-key
• host、content-type、user-agent
• anthropic-、x-goog-、x-amz-、x-amzn- で始まる名前

​

複数のアップストリーム

• アップストリームが失敗した
• アップストリームが要求されたモデルを提供していない
• アップストリームに開発者を含まない groups リストがある

• provider: anthropic アップストリーム: timeouts.upstream_ttfb_ms。デフォルトは 120 秒
• その他のプロバイダー: 最大 1 時間。ストリーミングリクエストでこの待機時間を短縮するには、ゲートウェイ v2.1.295 以降で timeouts.upstream_ttfb_ms を設定します。非ストリーミングのモデルリクエストは、いずれの場合も最大 1 時間待機します

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 static keys.
  - 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

​

各チームを専用のアップストリームに送る

upstreams:
  - name: bedrock-payments
    provider: bedrock
    region: us-east-1
    auth: {}
    assume_role:
      role_arn: arn:aws:iam::111111111111:role/claude-gateway-bedrock
    groups: [payments-eng]
  - name: bedrock-search
    provider: bedrock
    region: us-east-1
    auth: {}
    assume_role:
      role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
    groups: [search-eng]
  - name: bedrock-shared               # no groups: open to everyone, so listed last
    provider: bedrock
    region: us-east-1
    auth: {}

• エントリ: 各グループは、IdP が groups クレームで送信するとおりに正確に記述します。このクレームは match.groups も読み取ります。ゲートウェイは、空のリストまたは空のエントリを検出すると起動を拒否します。エントリを IdP と照合することはしないため、誰にも一致しないエントリがあっても警告は出ません。
• 順序: groups リストを持たないアップストリームは最後に配置します。このアップストリームはすべてのユーザーに対応するため、前のほうに列挙すると、チーム専用のアップストリームより先にそのチームのリクエストを受け取ってしまいます。

開発者が列挙されたどのグループにも属さない場合

API Error: 400 you aren't in a group that can use this gateway. Ask your administrator to add you to one

• oidc.allowed_groups が設定されている場合: ゲートウェイは更新を拒否し、セッションが終了します
• それ以外で、groups リストを持たないアップストリームがある場合: 開発者のリクエストはそのアップストリームに移ります
• それ以外で、すべてのアップストリームに groups リストがある場合: 開発者のリクエストは上記のエラーで失敗します

​

オプションセクション

​

login_notice

login_notice: This gateway is for Example Corp staff. For access questions, email it-help@example.com.

​

admin

admin:
  # Named static API keys for the admin endpoints, sent as x-api-key.
  # The id appears in the audit log as admin-key:<id> so each key is
  # attributable. Array for rotation: add the new key, roll clients,
  # remove the old.
  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}" }
  # IdP groups granted full admin via the normal gateway JWT (no API key).
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits
  # Try eng-platform's pooled budget first, then eng-all's, then any other group's.
  pooled_conflict_rule: priority_list
  pooled_priority_order: [eng-platform, eng-all]

​

プール予算の順序

• default_order: 制限額が最も大きいものから順に試し、制限額が同じ場合はグループ名の昇順で試します
• priority_list: pooled_priority_order 内のグループの予算をリストの順に試し、その後、その他のグループの予算をグループ名の順に試します

​

enforcement

​

pricing

• ゲートウェイサーバー上の Claude Code v2.1.227 以降。以前のバージョンはブート時に不明なキーを拒否します。
• admin: ブロック、または v2.1.268 以降では、少なくとも 1 つのポリシーを持つ managed: ブロック。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 に対して処理するリクエストのリスト価格を置き換えます。これには、より高い fast mode レートも含まれるため、fast リクエストと標準リクエストは同じ 4 つのレートでメーターされます。
• claude-sonnet-4-6 などの組み込み ID（models[].id と同様にマッチング）は、メーターがそのモデルとして価格設定するすべての日付付き形式、地域の Amazon Bedrock 形式、または Google Cloud の Agent Platform 形式をカバーします。エイリアスや推論プロファイル ARN などの他の文字列は、クライアントが送信した ID または上流に送信された文字列と大文字小文字を区別せずにマッチングします。
• 行が重複する場合、メーターは最初の行ではなく最も具体的な行を選択します：model が上流に送信された正確なモデル文字列である行、次にクライアントが送信した正確な ID とマッチングする行、次に組み込みモデルを指定する行。
• 不明な上流名はブート失敗を引き起こし、1 つの上流に対して同じモデルを指定する 2 つの行も同様です（1 つの組み込みモデルの 2 つの表記を含む）。ゲートウェイはブート時に、リクエスト可能なモデルが使用できない行について警告します。
• Web 検索リクエストは $0.01 のリスト価格のままです。乗数はそれらにも適用されます。

​

価格をマークアップする

pricing:
  multiplier: 1.2

​

サインイン済みクライアントにレートを送信する

• ゲートウェイが追加するもの：ポリシーの cli ブロックが既に modelPricing を設定していない限り、ゲートウェイは multiplier と、クライアントがリクエストできるすべてのモデル ID について、その ID を処理する最初の上流の上書き行を追加します。フェイルオーバー上流のみが請求するレートはゲートウェイに留まります。
• groups リスト を持つアップストリーム: そのようなアップストリームがあるモデル ID を処理する最初のアップストリームである場合、ゲートウェイはその ID の行を追加しません。その場合、開発者にはその ID に対する Claude Code 独自の料金（Claude Code が ID を認識する場合はモデルの標準料金）に multiplier を掛けた値が表示されます。
• 1 つのポリシーをオプトアウトする：そのポリシーの cli ブロックで modelPricing を {} に設定すると、そのデベロッパーはリスト価格のままです。
• ポリシー独自のレートを保持する：cli ブロックが独自の multiplier または overrides で modelPricing を設定するポリシーは、その modelPricing 全体を保持し、ゲートウェイはそれに独自のレートを追加しません。

​

models

auto_include_builtin_models: true   # false: expose only the list below
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    # description: optional text shown in clients that surface it
    upstream_model:
      anthropic: claude-opus-4-8
      bedrock: us.anthropic.claude-opus-4-8   # or an inference-profile ARN
      foundry: your-opus-deployment-name

​

managed

managed:
  policies:
    # Specific groups first.
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        permissions: { deny: ["WebFetch", "WebSearch"] }
    # Default catch-all last: matches everyone who authenticated.
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        # Make the Default option in /model resolve inside each policy's
        # list. The eng-contractors policy inherits enforceAvailableModels.
        enforceAvailableModels: true

• 許可リスト：availableModels と permissions.allow。特定のポリシーのリストは基盤のリストを完全に置き換えます。
• 拒否リストとフック配列: ベースとポリシーの和集合になります。
  • permissions.deny と permissions.ask
  • disabledMcpjsonServers と deniedMcpServers
  • blockedMarketplaces と deniedModels
  • hooks のイベントタイプ配列
• レコード型キー：env、modelOverrides、skillOverrides。これらは浅くマージされるため、ロールごとの env ブロックは設定するキーを上書きし、残りを基盤から継承します。

• 値が欠落しているか空の場合、ゲートウェイはメッセージ model is required でリクエストを拒否します。このチェックには Claude Code v2.1.228 以降を実行しているゲートウェイが必要です。
• 値が存在しているが文字列ではない場合、ゲートウェイはメッセージ model must be a string でリクエストを拒否します。Claude Code v2.1.221 以降を実行しているゲートウェイが必要です。

​

一致するすべてのポリシーを適用する

managed:
  policy_mode: layered
  policies:
    - match: { groups: [no-web] }
      cli:
        permissions: { deny: ["WebFetch"] }
    - match: { groups: [opus-users] }
      cli:
        availableModels: [opus, sonnet]
    - match: {}
      cli:
        availableModels: [sonnet]
        enforceAvailableModels: true

• 許可リスト、単一の値、sandbox などのブロック：それぞれ、それを設定している一致ポリシーのうち最初に記述されたものから丸ごと取得されるため、2 つのグループの availableModels リストが合算されることはありません。
• 拒否リストとフック配列：一致するすべてのポリシーにわたって合算されるため、2 つのグループに属するユーザーには両方のグループの拒否ルールが適用されます。
• env、modelOverrides、skillOverrides：エントリは名前ごとにマージされ、その名前を設定している一致ポリシーのうち最初に記述されたものの値が使用されます。
• desktop キー：ベースの desktop ブロックのルールに従ってマージされます。

• ! パターン：いずれかのポリシー（match: {} ポリシーを含む）の permissions.deny または permissions.ask リスト内の Read ルールまたは Edit ルールにおける ! による否定
• キャッチオール以外でのフックの制限：match: {} 以外のポリシーにおける disableAllHooks、allowedHttpHookUrls、または httpHookAllowedEnvVars

​

ポリシーが許可するモデルでセッションを開始する

• sonnet などのエイリアス、または claude-sonnet-4-6 などの組み込み ID：セッションはそれらのモデルのいずれかで開始し、/model の Default オプションはそのモデルに解決されます
• リストにエイリアスも組み込み ID もない場合：セッションは引き続き組み込みのデフォルトで開始する可能性があるため、そのポリシーの cli ブロックで model もリスト内の ID のいずれかに設定してください

managed:
  policies:
    - match: { groups: [restricted-projects] }
      cli:
        availableModels: [restricted-claude-opus-4-8]
        enforceAvailableModels: true
        model: restricted-claude-opus-4-8
        env:
          ANTHROPIC_DEFAULT_OPUS_MODEL: restricted-claude-opus-4-8   # opus and Default resolve to the ID too

​

ゲートウェイをブート時に停止させる matcher 値

• 空の groups リスト
• groups または admin_groups の空のエントリ
• 空の email_domain
• @、空白、またはコンマを含む email_domain。ゲートウェイはこのチェックの前に値をトリミングし、先頭の @ を 1 つ削除します。example.com のように、ドメインのみを 1 つ記述してください。

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

​

cli と code のどちらを選ぶか

• cli: ターミナル、VS Code と JetBrains の拡張機能、Agent SDK。cli の下では、Claude Desktop の Code タブには 派生した設定 が適用されるため、Read(./.env) のようなスコープ付きルールはそこでのユーザーの操作を止めません。
• code: 同じ場所に加え、Claude Desktop の Code タブもカバーできます。

managed:
  policies:
    - match: {}
      code:
        permissions: { deny: ["Read(./.env)"] }
      desktop: {}

• Code タブを対象にするには：ユーザーのマシンが Code タブで code の設定を適用するの条件を満たしたら、code に切り替えます
• cli のままにするには：ポリシーで cli の横に serve_to_desktop: false を設定して、警告を抑制します

​

cli に何を入れるか

managed:
  policies:
    - match: {}
      cli:
        # Model access (also enforced server-side at /v1/messages)
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        enforceAvailableModels: true              # Default resolves inside the list

        # Permission policy
        permissions:
          deny:
            - "WebFetch"
            - "Read(./.env)"
            - "Read(./secrets/**)"
          disableBypassPermissionsMode: disable   # blocks --dangerously-skip-permissions
        allowManagedPermissionRulesOnly: true     # ignore user/project permission rules

        # Environment pushed into the CLI process. DISABLE_UPDATES blocks
        # background and manual updates; DISABLE_AUTOUPDATER stops only
        # background updates.
        env:
          DISABLE_UPDATES: "1"                    # pin versions via your own distribution

        # Org-wide hooks. Hook commands run on developer machines, not the
        # gateway, so the path must exist on every client OS in the policy.
        hooks:
          PostToolUse:
            - matcher: "Edit|Write"
              hooks:
                - { type: command, command: /usr/local/bin/audit-edit.sh }

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

​

デプロイ前にポリシーをテストする

​

ターミナルセッションのコンテキストウィンドウ

managed:
  policies:
    - match: {}
      cli:
        env:
          CLAUDE_CODE_AUTO_COMPACT_WINDOW: "200000"

​

1 時間のプロンプトキャッシュ

managed:
  policies:
    - match: {}
      cli:
        promptCacheTtl: 1h
        subagentPromptCacheTtl: 1h

​

ポリシー内の MCP サーバー

​

Claude Desktop オーバーレイ

ゲートウェイが Claude Desktop 用に導出する設定

• モデルリスト。availableModels から導出されます。このリストには、ポリシーが deniedModels または availableModelsMatch: exact でブロックしたモデルは含まれません。このフィルターには、ゲートウェイサーバー上の Claude Code v2.1.299 以降が必要です。各モデルの 1M コンテキストオプションについては Claude Desktop の拡張コンテキスト で説明しています
• ツール名のみの permissions.deny エントリからの無効化されたツール。ポリシーの desktop ブロックで disabledBuiltinTools を設定した場合、ゲートウェイは指定した値と導出されたリストの和集合を提供します。そのため、この方法でさらにツールを無効化できますが、permissions.deny で無効化したツールを再度有効化することはできません
• sandbox.network.allowedDomains から導出される送信許可リスト。ポリシーの desktop ブロックで coworkEgressAllowedHosts を設定すると、ゲートウェイは導出リストの代わりにその値を使用します。ゲートウェイが提供する許可リストに * が含まれ、かつゲートウェイが Claude Desktop の allowedWorkspaceFolders も提供していない場合、Claude Desktop は Code タブで Bash サンドボックスをオンにしません
• ゲートウェイ自体を指す OTLP エンドポイントと、サインインしたユーザーのアイデンティティ属性。ゲートウェイはそのエンドポイントで受け取ったエクスポートを forward_to の宛先にリレーします。telemetry.forward_to と listen.public_url の両方を設定した場合に、エンドポイントと属性が含まれます。 Claude Desktop はすべてのシグナルを 1 つのエンコーディングでエクスポートします：http/protobuf、またはポリシーの env で OTEL_EXPORTER_OTLP_PROTOCOL またはそのシグナルごとのバリアントのいずれかを http/json に設定した場合は http/json です。ゲートウェイサーバー上の Claude Code v2.1.261 より前では、レスポンスは常に http/json を設定していたため、protobuf のみを受け入れるコレクターは Claude Desktop のエクスポートを拒否していました

Code タブで code 設定を適用する

• ポリシーに desktop キーもあること（空の desktop: {} でもかまいません）
• Claude Desktop がバージョン 2.9939.2 以降であること
• マシン上の Claude Code 管理設定が このゲートウェイを指定している こと
• そのマシンが、プライベートネットワーク上で HTTPS 経由でゲートウェイに到達できること

• HTTPS 経由で、Claude Desktop に Claude Code v2.1.296 以降がバンドルされている場合: Code タブは開始されず、ユーザーのプロンプトへの応答でその理由が示されます
• HTTPS 経由で、Claude Desktop にそれより前のバージョンがバンドルされている場合: Code タブは code 設定なしで開始され、セッション内ではそのことは何も示されません
• プレーン HTTP 経由の場合: Claude Desktop にどのバージョンがバンドルされていても、Code タブは code 設定なしで開始されます

Claude Desktop の設定を直接指定する

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

ゲートウェイがブート時に拒否するもの

• 不明なキー
• 空の値やネストされたエントリ内のサブキーのスペルミスなど、Claude Desktop が拒否するか黙って破棄する値を持つ認識済みのキー。v2.1.260 より前では、ゲートウェイは managedMcpServers または orgPluginSettings エントリのネストされたオブジェクト内のスペルミスのあるフィールドを、ブート時に失敗させずに黙って破棄していました。
• ゲートウェイ自身が計算するキー：推論接続、モデルリスト、OTLP リレー。これらは upstreams、models、telemetry セクションの forward_to で設定してください。
• 現在のキーのレガシーエイリアス。ブートエラーでは、ゲートウェイは記述すべき正規のキーを示します。

より新しいゲートウェイまたは Claude Desktop のバージョンが必要なキー

ロールポリシーが基盤の desktop ブロックを継承する仕組み

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

ポリシーの変更が Claude Desktop に届くタイミング

• 閉じている場合：Claude Desktop は起動時にブートストラップレスポンスを取得するため、変更は次回の起動から適用されます
• 開いている場合：Claude Desktop はデフォルトで 10 分ごとにレスポンスの変更を確認し、一部の設定は再起動なしで適用します。skillCreationEnabled などのその他の設定については、ユーザーのサイドバーに Relaunch Claude Desktop カードが表示され、アプリを再起動するまで以前の設定が維持されます。デフォルトでは 24 時間後に、Claude Desktop は再起動ダイアログを表示し、2 分間操作がないと自動的に再起動します

​

Claude Desktop の拡張コンテキスト

• エントリを処理できる上流が、1M をサポートしないモデルにエントリをマッピングしている場合。ゲートウェイがフェイルオーバー時にのみ到達する上流も含みます
• id も upstream_model の値も Claude モデルを指定していない場合。例えば、アプリケーション推論プロファイル ARN にルーティングされるカスタムエイリアスなど

• ユーザーを 1M オプションで開始する：ポリシーの desktop ブロックで modelPrefer1mContext: true を設定します。まだモデルを選択していないユーザーは、リストの最初のモデルに 1M オプションがある場合、1M オプションで開始します。既にモデルを選択したユーザーはその選択を維持します。
• オプションを手動で提供する：ゲートウェイサーバーが v2.1.284 より古いバージョンを実行している場合や、エントリが Claude モデルを指定していない場合に使用します。models にモデルを 2 回リストします。1 回はプレーンな ID で、もう 1 回は [1m] を付加して、どちらも同じ upstream_model マップを指定します。Claude Desktop はこのペアを 1M オプション付きの 1 つのモデルとして表示します。ゲートウェイは [1m] エントリをチェックせずに提供するため、上流が 1M で処理するモデルに対してのみ追加してください。

models:
  - id: corp-sonnet
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod
  - id: corp-sonnet[1m]
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod

managed:
  policies:
    - match: {}
      desktop:
        modelPrefer1mContext: true

1M オプションを削除する

​

他の管理ソースとの優先順位

​

telemetry

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      # Per-signal opt-in. Default: metrics only.
      metrics: true
      logs: false
      traces: false
    - url: https://api.datadoghq.com/api/v2/otlp
      headers:
        DD-API-KEY: ${DD_API_KEY}

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

• 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 はプッシュされた変数を管理層で適用するため、それぞれがデベロッパーがローカルで設定した値を上書きします。
• ローカルで設定されたエンドポイント：OTLP/HTTP エクスポートが有効な場合、ゲートウェイがテレメトリ変数をプッシュしたかどうかに関わらず、CLI はローカルで設定されたエンドポイントを無視します。ポリシーが コレクターをエンドポイントとして指定 しない限り、エクスポートはゲートウェイに送られます。

​

累積メトリクスを送信する

• ターミナルセッション: ポリシーの cli または code キー の下の env ブロック
• ユーザーのマシンで実行される Cowork セッション: そのマシン上の クライアント側の管理設定 の env ブロック
• code ポリシーの下の Code タブセッション: code 設定が適用される条件 を満たしたうえで、ポリシーの env ブロック
• cli ポリシーの下の Code タブセッション: セッションを実行するマシン上のクライアント側の管理設定の env ブロック。SSH 経由の場合はリモートホストです。

​

独自のラベルを追加する

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
  resource_attributes:
    service.namespace: claude
    deployment.environment.name: prod

• 名前には文字、数字、.、_、- のみを使用する
• 名前は予約されていない。大文字小文字を区別せずに比較した場合、予約名は user.、enduser.、identity. で始まるすべての名前と、service.name、service.version、claude.deployment_mode、host.arch、os.type、os.version、wsl.version です
• 値は空でない印字可能 ASCII で、スペースと , ; = \ " % のいずれも含まない
• 値はゲートウェイがパーセントエンコード後にカウントして最大 255 文字。そのため /、:、@ はそれぞれ 3 文字としてカウントされます
• 値はテキストであるため、数値、true、false は引用符で囲む

​

セッション中のグループの変更

processors:
  resource/drop-user-groups:
    attributes:
      - key: user.groups
        action: delete

​

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

• エンドポイントがゲートウェイ自体から来ていること。MDM プロファイルやローカルの managed-settings.json で同じ変数を設定した場合、エクスポートはリレーに残ります。
• URL が https://、またはループバックアドレスへの http:// を使用していること
• URL が /v1/<signal> で終わるパスに解決され、クエリやフラグメントがないこと。Claude Code は汎用変数からこのパスを自身で構築します。OTEL_EXPORTER_OTLP_METRICS_ENDPOINT などのシグナルごとの変数は記述どおりに使用するため、そこには完全なパスを含めてください。
• URL がゲートウェイ自身のホストではないこと。ゲートウェイ宛てのエンドポイントはリレーパスとそのセッショントークンを維持します。
• 管理者とデベロッパーのどちらも、いずれの設定ソースでも otelHeadersHelper を設定していないこと。ヘルパーが設定されている場合、すべてのシグナルはリレーに残ります。

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

​

宛先が失敗した場合

​

HTTP チューニング

• ブート時：運用ログの警告で、プライベート範囲 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 も設定していない場合、この警告は表示されません。
• 実行時：これらのプライベート範囲外のアドレスから初めてリクエストが届いたとき、ゲートウェイは警告をログに記録し、クライアント IP を含む access.public_client 監査イベント を発行します。どちらもプロセスごとに 1 回発生します。リンクローカルアドレス 169.254.0.0/16 と fe80::/10 はパブリックとしてカウントされません。ゲートウェイはこのチェックの実行前に /healthz と /readyz に応答するため、パブリック範囲からのヘルスプローブではトリガーされません。

​

load_test_mode

load_test_mode:
  enabled: true
  reply_tokens: 750     # roughly how many tokens of text each canned reply carries
  reply_seconds: 9.5    # how long a streamed reply takes

​

完全な例

# 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.
# Set CLAUDE_GATEWAY_LOG_FORMAT=json to write operational log lines as JSON
# objects with severity, time, and message.

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
  # connect_timeout_seconds: 5
  # readiness_grace_seconds: 300   # keep passing the readiness check through a database failover

# Notice shown at sign-in. Anyone who can reach the gateway can read it.
# login_notice: This gateway is for Example Corp staff. For access questions, email it-help@example.com.

# 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
#   # pooled_conflict_rule: priority_list
#   # pooled_priority_order: [eng-platform, eng-all]

# enforcement:
#   fail_closed_on_error: false

# Load test this deployment without calling a model provider. Never on a
# gateway that developers use: every request gets a canned reply.
# load_test_mode:
#   enabled: true
#   # reply_tokens: 750
#   # reply_seconds: 9.5

# 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: mantle
  #   region: us-east-1
  #   models: [claude-opus-4-8, claude-opus-4-7, claude-haiku-4-5]
  #   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
      # mantle: 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]
        # 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]
        # Constrain the Default picker option to each policy's availableModels
        # instead of the built-in default, so no role gets a 400 on Default.
        # The contractors policy inherits this key.
        enforceAvailableModels: true
        permissions:
          allow: [Read, Grep, 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}

​

クライアント側で管理される設定

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

​

関連

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