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 のいずれか

• 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 は空です。プラットフォームがいずれかをポッドに注入する場合、ゲートウェイコンテナの両方を空の値に設定します。NO_PROXY にテレメトリコレクターをリストすると、プロキシのみのエグレスがオフのままです。
• CLAUDE_GATEWAY_ALLOW_LOOPBACK がオンになっていません。ポッド独自のループバック上のコレクターまたは IdP は、プロキシのみのエグレスと組み合わせることはできません。ループバックアドレスがプロキシに渡されるとプロキシホスト独自のものになるため、代わりにプロキシが到達できるアドレスをそれらのサービスに与えてください。同じ理由で、ゲートウェイはプロキシのみのエグレスがアクティブな場合、localhost スタイルの名前を完全に拒否します。

​

session

​

store

​

upstreams

​

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

• ゲートウェイがフェイルオーバーしないステータスをアップストリームが返した：そのアップストリームのレスポンス。ゲートウェイはそれ以上のアップストリームを試みません。
• ゲートウェイが試みたすべてのアップストリームがフェイルオーバーする方法で失敗した：最後の 429。いずれも 429 を返さなかった場合、ゲートウェイは順に、最後の 401 または 403、最後の 404、最後の 501 を優先します。いずれも返さなかった場合、ゲートウェイ独自の 502。all upstreams failed (N attempted)。N は upstreams のすべてのエントリをカウントします。要求されたモデルを提供しないためゲートウェイがスキップしたエントリを含みます。

• 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 キーではなく短期トークンを発行する場合、ベアラーフォームを使用します。ベアラーはスタートアップ時に 1 回読み込まれるため、シークレットを再マウントして再起動することでリフレッシュします。

upstreams:
  - provider: anthropic
    auth:
      federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
      organization_id: ${ANTHROPIC_ORGANIZATION_ID}
      identity_token_file: /var/run/secrets/anthropic/id-token
      # workspace_id: wrkspc_...       # required if the rule covers >1 workspace
      # service_account_id: svac_...   # optional expected-target check

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

​

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

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:
  - 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 は provider: bedrock にのみ適用され、SigV4 ソース認証情報が必要です。ゲートウェイは aws_bearer_token と一緒に設定されている場合、起動を拒否します。
• ゲートウェイが許可するすべての開発者はこのアップストリームを使用できます。managed はどの開発者がどのモデルを使用できるかを制御します。ロールを通じて提供されるモデルが別のアカウントからも提供されるのを防ぐには、upstream_model マップにこのアップストリームの名前のみを持つカスタム id をそのモデルに与えます。そのような id の場合、ゲートウェイは他のすべてのアップストリームをスキップするため、リクエストも、中断されたリクエストのトークンカウントも、別のアカウントにフェイルオーバーすることはありません。組み込みモデル名へのリクエストは引き続きこのアップストリームに到達する可能性があり、ゲートウェイはそれを同じロールで署名します。このアカウントでもそれらのモデルを提供する場合を除き、このアップストリームを最後にリストしてください。

models:
  - id: claude-opus-restricted          # 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

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 アップストリームは assume_role を受け付けません。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- で始まる任意の名前

​

複数のアップストリーム

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

​

オプションセクション

​

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

​

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 を処理する最初の上流の上書き行を追加します。フェイルオーバー上流のみが請求するレートはゲートウェイに留まります。
• 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、およびすべての hooks イベントタイプ配列。これらは基盤とポリシーの和集合を取るため、組織全体の拒否または監査フックがロールごとの上書きで誤って削除されることはありません。
• レコード型キー：env、modelOverrides、skillOverrides。これらは浅くマージされるため、ロールごとの env ブロックは設定するキーを上書きし、残りを基盤から継承します。

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

​

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

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

managed:
  policies:
    - match: { groups: [restricted-projects] }
      cli:
        availableModels: [claude-opus-restricted]
        enforceAvailableModels: true
        model: claude-opus-restricted

​

ゲートウェイをブート時に停止させる 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: {}

​

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"

​

ポリシー内の MCP サーバー

​

Claude Desktop オーバーレイ

• availableModels からのモデルリスト。各モデルの 1M コンテキストオプションについては Claude Desktop の拡張コンテキスト を参照してください
• ツール名のみの permissions.deny エントリからの無効化されたツール。ポリシーの desktop ブロックで disabledBuiltinTools を設定した場合、ゲートウェイは指定した値と導出されたリストの和集合を提供します。そのため、この方法でさらにツールを無効化できますが、permissions.deny で無効化したツールを再度有効化することはできません
• sandbox.network.allowedDomains からの出力許可リスト。ポリシーの desktop ブロックで coworkEgressAllowedHosts を設定した場合、ゲートウェイは導出されたリストの代わりにその値を使用します
• ゲートウェイ自体を指す 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 のエクスポートを拒否していました

• ポリシーに 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 設定なしで開始されます

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 で設定してください。
• 現在のキーのレガシーエイリアス。ブートエラーでは、ゲートウェイは記述すべき正規のキーを示します。

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

• 閉じている場合：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

​

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

​

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 はローカルで設定されたエンドポイントを無視します。ポリシーが コレクターをエンドポイントとして指定 しない限り、エクスポートはゲートウェイに送られます。

​

独自のラベルを追加する

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.

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

# Enables /v1/organizations/spend_limits (mirrors the Anthropic Admin API)
# and per-developer spend enforcement on /v1/messages. Omit to disable.
# Caps themselves are set via the admin API, not here.
# admin:
#   write_keys:
#     - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
#   read_keys:
#     - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
#   admin_groups: [platform-finops]
#   blocked_message: request an increase at https://go.example.com/claude-limits
#   # audit_retention_days: 365
#   # spend_retention_months: 13
#   # identity_retention_days: 90
#   # group_limit_mode: min

# enforcement:
#   fail_closed_on_error: false

# 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, Bash, Edit]
          deny: ["WebFetch"]
        env: { HTTP_PROXY: http://proxy.example.com:8080 }

telemetry:
  forward_to:
    - url: https://otel.internal.example.com:4318
      headers:
        Authorization: Bearer ${OTEL_TOKEN}

​

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

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

​

関連

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