Konfigurasi gateway aplikasi Claude

​

Struktur file

• listen: bind address, public URL, TLS termination
• oidc: identity provider Anda (IdP), termasuk issuer, client, claim mapping, dan siapa yang boleh masuk
• session: bearer tokens yang dimint gateway, dengan secret dan lifetime
• store: PostgreSQL, untuk device grants dan rate-limit counters
• upstreams: ke mana inference pergi, apakah Anthropic, Amazon Bedrock, Claude Platform di AWS, Agent Platform Google Cloud, atau Microsoft Foundry

• admin: Admin API auth dan retention untuk spend limits
• enforcement: perilaku spend-limit fail-open atau fail-closed
• pricing: contracted rates dan multiplier untuk spend meter dan untuk cost figures yang dilihat developer
• models dan auto_include_builtin_models: daftar model yang dikurasi admin dan per-upstream IDs
• managed: managed settings policies berdasarkan IdP group
• telemetry: OTLP forwarding ke observability stack Anda
• access_control, limits, timeouts, rate_limits: IP allow/deny, request size caps, upstream time-to-first-byte, dan per-IP sign-in limits
• load_test_mode: load test gateway tanpa memanggil model provider

​

Ekspansi secret

​

Bagian yang diperlukan

​

listen

​

oidc

​

Autentikasi client dengan sertifikat

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

​

Rotasi sertifikat client

1. Unggah sertifikat baru ke IdP di samping sertifikat lama.
2. Ganti file key dan sertifikat yang dimuat oleh gateway.yaml, lalu restart gateway.
3. Hapus sertifikat lama dari IdP.

​

IdP requests through a forward proxy

​

Proxy-only egress

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 atau HTTP_PROXY diatur.
• NO_PROXY dan no_proxy kosong. Jika platform Anda menyuntikkan salah satu ke pods, atur keduanya ke nilai kosong pada container gateway. Mendaftar telemetry collector di NO_PROXY menjaga proxy-only egress off.
• CLAUDE_GATEWAY_ALLOW_LOOPBACK tidak diaktifkan. Collector atau IdP pada loopback pod sendiri tidak dapat dikombinasikan dengan proxy-only egress, karena loopback address yang diserahkan ke proxy akan menjadi proxy host sendiri, jadi berikan services tersebut address yang dapat dicapai proxy. Untuk alasan yang sama gateway menolak localhost-style names sepenuhnya saat proxy-only egress aktif.

​

session

​

store

​

upstreams

​

Upstream error messages

• Upstream mengembalikan status yang gateway tidak fail over pada: response upstream itu. Gateway tidak mencoba upstreams lebih lanjut.
• Setiap upstream yang gateway coba gagal dengan cara yang fails over pada: 429 terakhir. Ketika tidak ada yang mengembalikan 429, gateway lebih suka, secara berurutan, 401 atau 403 terakhir, 404 terakhir, dan 501 terakhir. Ketika tidak ada yang mengembalikan salah satu dari itu, 502 gateway sendiri, all upstreams failed (N attempted), di mana N menghitung setiap entry dalam upstreams, termasuk entries yang gateway lewati karena mereka tidak melayani model yang diminta.

• 400 atau 413 dalam Anthropic’s standard error envelope: message upstream sendiri, seperti prompt is too long. Claude Platform on AWS, Agent Platform, dan Microsoft Foundry mengembalikan envelope ini untuk model API rejections.
• 400 atau 413 dalam provider’s own shape: token capability_rejected:. Ketika gateway tidak dapat mengklasifikasi rejection, upstream rejected the request pada 400 atau request too large for this upstream pada 413.
• Status apa pun: generic per-status copy, seperti upstream rate limit exceeded pada 429.

​

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: mengirim x-api-key. Rotate di Claude Console dan update env var.
• oauth_token: mengirim Authorization: Bearer. Gunakan bentuk bearer ketika org Anda mengeluarkan short-lived tokens daripada long-lived API keys. Bearer dibaca sekali saat startup, jadi refresh dengan remount secret dan restart.

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" } }
  }]
}

• Jika STS menolak atau tidak dapat dijangkau, gateway tidak mengirim request dengan credentials upstream sendiri. Ini mencatat STS error dengan apa yang harus diperiksa, kemudian mencoba upstream berikutnya yang Anda daftarkan. Upstream error messages mencakup apa yang client terima ketika tidak ada upstream yang berhasil. Upstream yang lebih baru tanpa assume_role akan melayani request dengan credentials-nya sendiri, jadi daftarkan satu hanya jika itu adalah apa yang Anda inginkan.
• Gateway memanggil regional STS endpoint sts.<region>.amazonaws.com, yang network-nya harus jangkau. Untuk FIPS endpoint, atur AWS_USE_FIPS_ENDPOINT=true di environment gateway daripada use_fips_endpoint di AWS config file.
• assume_role berlaku pada provider: bedrock saja dan memerlukan SigV4 source credentials: gateway menolak untuk memulai ketika itu diatur di sebelah aws_bearer_token.
• Setiap developer yang gateway terima dapat menggunakan upstream ini; managed mengatur developer mana yang dapat menggunakan model mana. Untuk menjaga model yang dilayani melalui role dari juga dilayani dari account lain, berikan itu custom id yang upstream_model map-nya hanya memiliki upstream ini’s name. Untuk id seperti itu gateway melewati setiap upstream lain, jadi baik request maupun token count untuk request yang dibatalkan tidak dapat failover ke account lain. Request untuk built-in model name masih dapat mencapai upstream ini, dan gateway menandatanganinya dengan role yang sama. Daftarkan upstream ini terakhir kecuali account-nya juga harus melayani model tersebut.

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 endpoint

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: gateway tidak menerapkan Bedrock guardrail pada requests yang dikirimnya ke Mantle, jadi gateway menolak untuk memulai ketika upstream mantle didaftarkan sementara upstream bedrock mana pun menetapkan guardrail.
• assume_role: upstream mantle tidak menerima assume_role. Requests yang dilayani Mantle dikirim dengan credentials auth milik upstream mantle sendiri, dan tidak diatribusikan per developer.

​

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}

​

Static headers on upstream requests

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 dan x-api-key
• host, content-type, dan user-agent
• Nama apa pun yang dimulai dengan anthropic-, x-goog-, x-amz-, atau x-amzn-

​

Multiple upstreams

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

​

Bagian opsional

​

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 atau lebih baru di server gateway. Versi sebelumnya menolak kunci yang tidak dikenal saat boot.
• Blok admin: atau, di v2.1.268 atau lebih baru, blok managed: dengan setidaknya satu kebijakan. Gateway menolak untuk memulai dengan pricing diatur dan tidak ada blok, karena tidak ada yang akan membacanya.

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

• Baris menggantikan harga daftar untuk permintaan yang upstream, upstreams[].name, layani untuk model. Itu termasuk tarif fast mode yang lebih tinggi, jadi permintaan fast dan standard diukur dengan tarif yang sama empat.
• ID bawaan seperti claude-sonnet-4-6, dicocokkan seperti models[].id, mencakup setiap bentuk tertanggal, bentuk Amazon Bedrock regional, atau bentuk Google Cloud’s Agent Platform yang meter hargai sebagai model itu. String lain apa pun, seperti alias atau ARN profil inferensi, cocok dengan ID yang dikirim klien atau string yang dikirim upstream, tidak peka huruf besar-kecil.
• Di mana baris tumpang tindih, meter memilih baris yang paling spesifik daripada baris pertama: baris yang model adalah string model yang tepat dikirim upstream, kemudian baris yang cocok dengan ID yang tepat yang dikirim klien, kemudian baris yang menamai model bawaan.
• Nama upstream yang tidak dikenal gagal boot, begitu juga dua baris untuk satu upstream yang menamai model yang sama, termasuk dua ejaan dari satu model bawaan. Gateway memperingatkan saat boot tentang baris yang tidak ada model yang dapat diminta yang dapat menggunakannya.
• Permintaan pencarian web tetap pada harga daftar $0.01; pengali masih berlaku untuk mereka.

​

Tandai harga naik

pricing:
  multiplier: 1.2

​

Kirim tarif ke klien yang masuk

• Apa yang ditambahkan gateway: kecuali blok cli kebijakan sudah menetapkan modelPricing, gateway menambahkan multiplier dan, untuk setiap ID model yang dapat diminta klien, baris override dari upstream pertama yang melayani ID itu. Tarif yang hanya upstream failover yang mengenakan tetap di gateway.
• Opt satu kebijakan keluar: atur modelPricing ke {} dalam blok cli kebijakan itu, dan pengembangnya tetap pada harga daftar.
• Pertahankan tarif kebijakan sendiri: kebijakan yang blok cli menetapkan modelPricing dengan multiplier atau overrides sendiri menyimpan modelPricing itu utuh, dan gateway tidak menambahkan tarif sendiri ke dalamnya.

​

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

• Allow-lists: availableModels dan permissions.allow. Daftar kebijakan spesifik sepenuhnya menggantikan dasar.
• Deny-lists dan hook arrays: permissions.deny, permissions.ask, disabledMcpjsonServers, deniedMcpServers, blockedMarketplaces, dan setiap array jenis acara hooks. Ini mengambil gabungan dasar dan kebijakan, sehingga hook deny atau audit di seluruh org tidak dapat secara tidak sengaja dijatuhkan oleh override per-peran.
• Record-typed keys: env, modelOverrides, dan skillOverrides. Ini shallow-merge, jadi blok env per-peran menimpa kunci yang ditetapkannya dan mewarisi sisanya dari dasar.

• Ketika nilai hilang atau kosong, gateway menolak permintaan dengan pesan model is required. Pemeriksaan itu memerlukan gateway yang menjalankan Claude Code v2.1.228 atau lebih baru.
• Ketika nilai ada tetapi bukan string, gateway menolak permintaan dengan pesan model must be a string. Memerlukan gateway yang menjalankan Claude Code v2.1.221 atau lebih baru.

​

Mulai sesi pada model yang diizinkan kebijakan

• Alias seperti sonnet, atau ID bawaan seperti claude-sonnet-4-6: sesi dimulai pada salah satu model tersebut, dan opsi Default di /model mengarah ke model itu
• Tidak ada alias atau ID bawaan dalam daftar: sesi masih dapat dimulai pada default bawaan, jadi atur juga model ke salah satu ID yang terdaftar dalam blok cli kebijakan itu

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

​

Nilai matcher yang menghentikan gateway saat boot

• Daftar groups kosong
• Entri kosong dalam groups atau dalam admin_groups
• email_domain kosong
• email_domain yang berisi @, whitespace, atau koma. Gateway memangkas nilai dan menghapus satu @ terkemuka sebelum pemeriksaan ini. Tulis satu domain telanjang, seperti example.com.

• email_domain kosong: gateway melewati pemeriksaan domain, jadi kebijakan dengan email_domain kosong dan tidak ada daftar groups cocok dengan setiap pengguna yang diautentikasi
• Daftar groups kosong: kebijakan tidak cocok dengan siapa pun
• email_domain berisi @, whitespace, atau koma: kebijakan tidak cocok dengan siapa pun
• Entri kosong dalam groups atau dalam admin_groups: entri cocok dengan pengguna hanya ketika klaim IdP groups pengguna itu juga berisi entri kosong. Dalam admin_groups, kecocokan itu memberikan akses admin. Jika daftar admin_groups Anda tidak pernah berisi entri kosong, tidak ada yang mendapatkan akses admin dengan cara ini.

​

Apa yang masuk dalam 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
• Variabel env yang memerlukan persetujuan pengembang, seperti proxy dan variabel URL dasar
• pengaturan eksekusi shell seperti apiKeyHelper dan statusLine
• pengaturan biner sandbox sandbox.bwrapPath, sandbox.socatPath, dan sandbox.ripgrep
• Pengaturan sandbox yang mencegat lalu lintas, menyuntikkan kredensial, atau melemahkan isolasi, seperti sandbox.network.tlsTerminate dan pengaturan port proxy. Dialog persetujuan keamanan mencantumkan semuanya.

​

Context window dalam sesi terminal

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

​

Server MCP dalam kebijakan

​

Overlay Claude Desktop

• Daftar model, dari availableModels. Konteks diperluas di Claude Desktop membahas opsi konteks 1M setiap model
• Tool yang dinonaktifkan, dari entri permissions.deny nama tool telanjang. Jika Anda menetapkan disabledBuiltinTools dalam blok desktop kebijakan, gateway melayani gabungan nilai Anda dan daftar yang diturunkan, sehingga Anda dapat menonaktifkan lebih banyak tool dengan cara ini tetapi tidak dapat mengaktifkan kembali yang Anda nonaktifkan melalui permissions.deny
• Allowlist egress, dari sandbox.network.allowedDomains. Jika Anda menetapkan coworkEgressAllowedHosts dalam blok desktop kebijakan, gateway menggunakan nilai itu alih-alih daftar yang diturunkan
• Endpoint OTLP yang menunjuk ke gateway itu sendiri, dan atribut identitas pengguna yang masuk. Gateway meneruskan ekspor yang diterimanya di endpoint itu ke tujuan forward_to Anda. Ini menyertakan endpoint dan atribut ketika Anda menetapkan telemetry.forward_to dan listen.public_url. Claude Desktop mengekspor setiap sinyal dengan satu pengkodean: http/protobuf, atau http/json ketika Anda menetapkan OTEL_EXPORTER_OTLP_PROTOCOL atau salah satu varian per-sinyal ke http/json dalam env kebijakan. Sebelum Claude Code v2.1.261 di server gateway, respons menetapkan http/json terlepas, jadi kolektor yang hanya menerima protobuf menolak ekspor 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" }

• Kunci yang tidak dikenal
• Kunci yang dikenali yang nilainya Claude Desktop akan menolak atau diam-diam jatuhkan, seperti nilai kosong atau sub-kunci yang salah eja di dalam entri bersarang. Sebelum v2.1.260, gateway diam-diam menjatuhkan bidang yang salah eja di dalam objek bersarang dari entri managedMcpServers atau orgPluginSettings alih-alih gagal saat boot.
• Kunci yang gateway hitung sendiri: koneksi inferensi, daftar model, dan relay OTLP. Konfigurasikan melalui upstreams, models, dan forward_to pada bagian telemetry.
• Alias warisan dari kunci saat ini. Dalam kesalahan boot, gateway menamai kunci kanonis untuk ditulis.

• disabledBuiltinTools: gateway menggunakan gabungan daftar dasar dan daftar kebijakan
• builtinToolPolicy: jika Anda menetapkan tool ke nilai selain allow dalam dasar, gateway menyimpan nilai itu bahkan jika Anda menetapkan allow untuk tool yang sama dalam kebijakan peran

​

Konteks diperluas di Claude Desktop

• Upstream yang dapat melayani entri memetakannya ke model tanpa dukungan 1M, termasuk upstream yang hanya dijangkau gateway saat failover
• Baik id maupun nilai upstream_model apa pun dari entri tidak menamai model Claude, seperti alias kustom yang dirutekan ke ARN profil inferensi aplikasi

• Mulai pengguna pada opsi 1M: atur modelPrefer1mContext: true dalam blok desktop kebijakan. Pengguna yang belum memilih model memulai pada opsi 1M ketika model terdaftar pertama memilikinya. Pengguna yang sudah memilih model mempertahankan pilihan mereka.
• Tawarkan opsi secara manual: lakukan ini jika server gateway Anda menjalankan versi lebih lama dari v2.1.284, atau entri tidak menamai model Claude. Cantumkan model dua kali dalam models, sekali dengan ID polosnya dan sekali dengan [1m] ditambahkan, keduanya dengan peta upstream_model yang sama. Claude Desktop menampilkan pasangan tersebut sebagai satu model dengan opsi 1M. Gateway menyajikan entri [1m] tanpa memeriksanya, jadi tambahkan hanya untuk model yang dilayani upstream Anda pada 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

​

Prioritas dengan sumber terkelola lainnya

​

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> melewati validasi konfigurasi, tetapi penjaga SSRF memblokir setiap ekspor dengan ECONNREFUSED_SSRF kecuali Anda menetapkan CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 dalam lingkungan gateway
• http://127.0.0.1:<port> atau http://[::1]:<port> gagal boot kecuali variabel itu ditetapkan

• CLAUDE_CODE_ENABLE_TELEMETRY=1
• OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER, dan OTEL_TRACES_EXPORTER, masing-masing ditetapkan ke otlp jika setidaknya satu tujuan forward_to mengaktifkan sinyal itu dan ke none sebaliknya
• OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
• OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

• Variabel yang ditetapkan secara lokal: Claude Code menerapkan variabel yang didorong di tingkat terkelola, jadi masing-masing menimpa nilai yang ditetapkan pengembang untuk itu secara lokal.
• Endpoint yang dikonfigurasi secara lokal: dengan ekspor OTLP/HTTP diaktifkan, CLI mengabaikan endpoint yang dikonfigurasi secara lokal apa pun, terlepas dari apakah gateway mendorong variabel telemetri. Ekspornya pergi ke gateway kecuali kebijakan menamai kolektor Anda sebagai endpoint.

​

Tambahkan label Anda sendiri

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

• Nama menggunakan hanya huruf, digit, ., _, dan -
• Nama tidak dicadangkan. Dibandingkan dalam huruf apa pun, nama yang dicadangkan adalah semua yang dimulai dengan user., enduser., atau identity., ditambah service.name, service.version, claude.deployment_mode, host.arch, os.type, os.version, dan wsl.version
• Nilai adalah ASCII yang dapat dicetak non-kosong tanpa spasi dan tidak ada , ; = \ " %
• Nilai paling banyak 255 karakter saat gateway menghitungnya setelah pengkodean persen, jadi /, :, dan @ masing-masing menghitung sebagai tiga
• Nilai adalah teks, jadi kutip angka, true, atau false

​

Ekspor langsung ke kolektor Anda

• Endpoint berasal dari gateway itu sendiri. Jika Anda menetapkan variabel yang sama dalam profil MDM atau managed-settings.json lokal, ekspor tetap di relay.
• URL menggunakan https://, atau http:// ke alamat loopback
• URL diselesaikan ke jalur yang berakhir di /v1/<signal>, tanpa kueri atau fragmen. Claude Code membangun jalur itu sendiri dari variabel generik. Ini menggunakan variabel per-sinyal seperti OTEL_EXPORTER_OTLP_METRICS_ENDPOINT seperti yang ditulis, jadi sertakan jalur lengkap di sana.
• URL bukan host gateway itu sendiri. Endpoint yang ditujukan ke gateway menyimpan jalur relay dan token sesinya.
• Baik Anda maupun pengembang tidak mengonfigurasi otelHeadersHelper dalam sumber pengaturan apa pun. Dengan helper yang dikonfigurasi, setiap sinyal tetap di relay.

• Jika gateway sudah mendorong variabel telemetri, mereka mencakup enablement, pemilih, dan protokol, dan endpoint eksplisit Anda menimpa nilai <public_url> yang didorong. Atur pemilih OTEL_*_EXPORTER ke otlp sendiri hanya untuk sinyal yang tidak ada tujuan forward_to yang mengaktifkan.
• Jika tidak, juga atur CLAUDE_CODE_ENABLE_TELEMETRY=1, pemilih OTEL_*_EXPORTER, dan OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf.

​

Ketika tujuan gagal

​

Penyetelan HTTP

• Saat boot: peringatan dalam log operasional merekomendasikan hanya mengizinkan rentang pribadi 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, dan fc00::/7, ditambah rentang internal lainnya yang pengembang Anda terhubung dari. Jika Anda mengikat gateway ke alamat loopback dan tidak menetapkan trusted_proxies atau public_url, seperti dalam pengembangan lokal, peringatan tidak muncul.
• Saat runtime: pertama kali permintaan tiba dari alamat di luar rentang pribadi itu, gateway mencatat peringatan dan memancarkan acara audit access.public_client yang membawa IP klien. Keduanya menyala sekali per proses. Alamat link-lokal, 169.254.0.0/16 dan fe80::/10, tidak dihitung sebagai publik. Gateway menjawab /healthz dan /readyz sebelum pemeriksaan ini berjalan, jadi probe kesehatan dari rentang publik tidak memicunya.

​

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

​

Contoh lengkap

# 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}

​

Managed settings sisi client

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

​

Terkait

• Claude apps gateway overview: quickstart dan developer connection
• Deployment guide: IdP setup, container image, Kubernetes dan Cloud Run, dan operations
• Spend limits: per-developer caps dan Admin API