Konfigurasi gateway aplikasi Claude

Referensi untuk setiap opsi gateway.yaml: listener dan TLS, OIDC, session, Postgres store, Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, dan Microsoft Foundry upstreams, model routing, managed policies, dan telemetry.

Deployment gateway aplikasi Claude dikonfigurasi oleh satu file YAML, secara konvensional gateway.yaml. File ini mendefinisikan semua yang dilakukan gateway: di mana ia mendengarkan, bagaimana pengembang masuk, ke mana inference pergi, dan kebijakan serta telemetry mana yang berlaku. Halaman ini adalah referensi untuk setiap opsi dalam file tersebut.

Untuk menulis yang pertama, mulai dari quickstart, yang membangun config minimal yang berfungsi dan menjalankannya. Setelah Anda memiliki config yang Anda sukai, deployment guide mencakup containerizing dan hosting di Kubernetes, Cloud Run, atau platform Anda sendiri.

Gateway membaca file sekali, saat startup, dengan claude gateway --config /path/to/gateway.yaml. Setiap opsi divalidasi terhadap schema saat boot, jadi config yang salah format gagal saat start dengan error tingkat field daripada saat penggunaan pertama.

Complete example di akhir halaman ini menggunakan setiap bagian.

Struktur file

Lima bagian diperlukan. Setiap bagian lainnya opsional, dan bagian yang dihilangkan mengambil default-nya. Kunci yang tidak dikenal gagal boot, jadi typo muncul sebagai error bernama daripada setting yang diabaikan secara diam-diam.

Bagian yang diperlukan:

• 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

Bagian opsional:

• login_notice: pemberitahuan yang dilihat developer saat mereka masuk
• 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

Jangan menulis secret seperti client_secret, jwt_secret, atau postgres_url secara langsung di gateway.yaml. Rujuk secret tersebut dengan salah satu bentuk di bawah ini, dan gateway akan me-resolve nilainya saat boot dari environment variable atau file:

Bagian wajib

listen

Blok listen mengontrol tempat gateway melayani: alamat bind dan port, origin yang terlihat dari luar, serta terminasi TLS opsional.

Cantumkan frontend di trusted_proxies hanya jika entri X-Forwarded-For terakhir yang diteruskannya adalah entri yang tidak ditulis oleh developer mana pun. Jangan cantumkan alamat atau rentang apa pun yang digunakan developer untuk terhubung. Frontend yang menambahkan alamat dari setiap koneksi yang diterimanya memenuhi syarat. Frontend yang meneruskan header apa adanya seperti yang dikirim developer tidak memenuhi syarat.

Entri X-Forwarded-For yang ditulis sebagai ipv4:port atau [ipv6]:port, seperti yang dilakukan beberapa load balancer, dibaca dengan port dibuang. Alamat IPv6 dengan port yang ditambahkan tanpa tanda kurung siku dapat dibaca sebagai alamat yang berbeda atau tidak dibaca sama sekali. Matikan opsi port pada proxy mana pun yang menulis bentuk tersebut.

oidc

Blok oidc menghubungkan gateway ke penyedia identitas Anda dan menentukan siapa yang dapat masuk. Blok ini menyebutkan issuer dan klien OAuth, memetakan klaim yang membawa email dan grup, serta membatasi proses masuk berdasarkan domain email atau grup.

OpenID Connect (OIDC) adalah protokol SSO yang digunakan gateway dengan penyedia identitas Anda; lihat Penyiapan penyedia identitas untuk apa yang perlu didaftarkan di sisi IdP.

Autentikasi klien dengan sertifikat

Jika penyedia identitas Anda mengautentikasi klien OAuth dengan sertifikat alih-alih client secret, seperti yang dilakukan Microsoft Entra dengan kredensial sertifikat, atur token_endpoint_auth_method: private_key_jwt. Memerlukan Claude Code v2.1.284 atau yang lebih baru di server gateway.

Dengan konfigurasi ini gateway tidak mengirim secret. Gateway melakukan autentikasi ke endpoint token IdP dengan JWT berumur pendek yang ditandatangani dengan private key sertifikat saat developer masuk dan setiap kali gateway me-refresh sesi mereka. JWT ditandatangani dengan RS256 dan mengidentifikasi sertifikat melalui header thumbprint x5t dan x5t#S256 alih-alih kid. IdP Anda harus dapat menemukan sertifikat yang terdaftar berdasarkan thumbprint.

1. Buat kunci dan sertifikat

Buat private key RSA yang tidak terenkripsi dengan setidaknya 2048 bit, dalam bentuk PEM PKCS#8 atau PKCS#1, dan sertifikat untuknya. Gateway menolak untuk dimulai dengan kunci apa pun yang tidak memenuhi kondisi ini. Perintah openssl ini membuat kunci semacam itu dengan sertifikat self-signed yang berlaku selama satu tahun:

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

Perintah ini menulis idp-client.key dan idp-client.crt ke direktori saat ini. Salin atau mount kedua file di tempat yang dapat dibaca gateway. Contoh di langkah 3 menggunakan /etc/gateway/.

2. Unggah sertifikat ke IdP

Unggah sertifikat, bukan private key, ke app registration gateway di IdP.

3. Tambahkan kunci dan sertifikat ke gateway.yaml

Berikan private key dan sertifikat kepada gateway dalam blok client_assertion. Hilangkan client_secret, karena gateway menolak untuk dimulai ketika field itu diatur bersama dengan private_key_jwt. Blok oidc ini mengautentikasi gateway ke tenant Microsoft Entra dengan sertifikat:

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}

Kedua nilai adalah isi PEM, bukan path file, jadi muat file yang di-mount dengan ${file:/path} seperti pada contoh. Gateway menolak untuk dimulai kecuali certificate_pem adalah satu sertifikat PEM, tanpa sisa rantainya, yang public key-nya cocok dengan private_key_pem.

4. Restart gateway dan periksa log boot

Restart gateway dan temukan baris ini di log boot:

[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

Bandingkan thumbprint SHA-1 dengan yang ditampilkan IdP untuk sertifikat yang Anda unggah. Jika sertifikat telah kedaluwarsa atau belum berlaku, gateway tetap dimulai tetapi mencatat peringatan bahwa proses masuk dan refresh akan gagal sampai Anda menggantinya. Untuk memastikan bahwa IdP menerima sertifikat, minta satu developer masuk melalui gateway.

Merotasi sertifikat klien

Gateway membaca kunci dan sertifikat sekali saat boot, sehingga file yang diubah baru berlaku setelah restart. Lakukan rotasi dengan urutan ini agar tidak ada permintaan token yang menyajikan sertifikat yang tidak dimiliki IdP:

1. Unggah sertifikat baru ke IdP bersama dengan yang lama.
2. Ganti file kunci dan sertifikat yang dimuat gateway.yaml, lalu restart gateway. Jika Anda menjalankan beberapa replika, rolling restart dapat digunakan, karena IdP memiliki kedua sertifikat sampai Anda menghapus yang lama.
3. Setelah setiap replika di-restart, hapus sertifikat lama dari IdP.

Permintaan IdP melalui forward proxy

Upstream inferensi mematuhi HTTPS_PROXY dan HTTP_PROXY di setiap versi. Permintaan gateway sendiri ke IdP, yaitu discovery, JWKS, token, dan userinfo, dikirim langsung kecuali Anda mengatur oidc.use_proxy: true, yang memerlukan v2.1.227 atau yang lebih baru. Ketika variabel proxy diatur, use_proxy tidak diatur, dan issuer tidak tercakup oleh NO_PROXY, gateway tetap mengirim permintaan tersebut secara langsung dan mencatat pemberitahuan saat boot yang meminta Anda untuk memilih; use_proxy: false membuatnya tetap langsung dan menghilangkan pemberitahuan.

Dengan use_proxy: true, pod me-resolve hostname setiap endpoint IdP sendiri dan meminta proxy untuk melakukan CONNECT ke alamat IP hasil resolusi, sehingga proxy harus menerima CONNECT ke alamat IP setiap host yang disebutkan dalam dokumen discovery, tidak hanya issuer. Gunakan URL proxy http://. ca_cert_pem dan pelindung SSRF juga berlaku pada jalur yang melalui proxy.

Egress khusus proxy mengubah keduanya: selama aktif, permintaan IdP mengikuti proxy kecuali Anda mengatur use_proxy: false, dan gateway menyerahkan setiap hostname IdP ke proxy tanpa me-resolve-nya terlebih dahulu.

Egress khusus proxy

Atur CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1 di lingkungan gateway, di samping HTTPS_PROXY, ketika pod menjangkau host lain hanya melalui forward proxy tersebut dan tidak dapat me-resolve nama DNS publik sendiri, atau ketika proxy menolak CONNECT ke alamat IP. Memerlukan v2.1.277 atau yang lebih baru. Ini adalah environment variable alih-alih kunci gateway.yaml agar tidak ada apa pun di file konfigurasi yang dapat melonggarkan pemeriksaan alamat gateway.

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

Gateway mencatat satu baris network: saat boot selama egress khusus proxy aktif.

Setiap baris di bawah adalah satu kelas permintaan keluar pada gateway dengan HTTPS_PROXY diatur, secara default dan selama egress khusus proxy aktif.

Egress khusus proxy tetap nonaktif kecuali lingkungan gateway memenuhi ketiga kondisi berikut:

• HTTPS_PROXY atau HTTP_PROXY diatur.
• NO_PROXY dan no_proxy kosong. Jika platform Anda menyuntikkan salah satunya ke pod, atur keduanya ke nilai kosong pada container gateway. Mencantumkan kolektor telemetri di NO_PROXY membuat egress khusus proxy tetap nonaktif.
• CLAUDE_GATEWAY_ALLOW_LOOPBACK tidak diaktifkan. Kolektor atau IdP pada loopback milik pod sendiri tidak dapat digabungkan dengan egress khusus proxy, karena alamat loopback yang diserahkan ke proxy akan menjadi milik host proxy itu sendiri, jadi berikan layanan tersebut alamat yang dapat dijangkau proxy sebagai gantinya. Untuk alasan yang sama, gateway langsung menolak nama bergaya localhost selama egress khusus proxy aktif.

Ketika salah satu kondisi tersebut tidak terpenuhi, gateway mencatat peringatan saat boot yang menyebutkan variabel yang menghentikannya dan mempertahankan perilaku default.

Setelah egress khusus proxy aktif, izinkan setiap tujuan di proxy, termasuk kolektor internal dan host apa pun yang dikonfigurasi dengan alamat IP. Anda tetap dapat membuat IdP internal tetap langsung dengan oidc.use_proxy: false.

[!WARNING]

Aktifkan ini hanya jika allowlist proxy setidaknya seketat pemeriksaan gateway sendiri. Proxy harus menolak endpoint metadata cloud seperti 169.254.169.254 dan metadata.google.internal, alamat link-local, dan loopback milik host proxy sendiri, dan proxy harus menolaknya berdasarkan alamat hasil resolusi nama, tidak hanya berdasarkan nama, karena gateway tidak lagi menangkap hostname yang di-resolve ke salah satunya. Proxy yang terhubung ke mana pun yang diminta menghilangkan pelindung SSRF gateway untuk permintaan ini.

session

Blok session membentuk bearer token yang dicetak gateway setelah masuk: secret yang menandatanganinya dan berapa lama token tersebut berlaku.

store

Blok store mengarahkan gateway ke database PostgreSQL-nya, yang menyimpan device grant dan penghitung rate limit.

Untuk pengembangan lokal, arahkan postgres_url ke container Postgres sekali pakai, misalnya docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres.

upstreams

upstreams adalah daftar berurutan. Gateway meneruskan inferensi ke upstream pertama yang me-resolve model yang diminta, melewati upstream mana pun yang daftar groups-nya tidak menyertakan developer tersebut.

Pada 5xx, 429, 401, 403, 404, atau timeout, gateway melakukan failover ke upstream berikutnya; 4xx lainnya tidak, karena error tersebut disebabkan oleh permintaan, bukan oleh upstream. 401 atau 403 berarti upstream menolak kredensial yang digunakan gateway, atau menolak aksesnya, misalnya ke model yang diminta. 404 berarti upstream tersebut tidak melayani model yang diminta, sehingga upstream berikutnya dalam daftar masih dapat melayaninya.

Jika Anda mengatur forward_user_identity: true pada sebuah upstream, 429 yang dikembalikannya untuk permintaan yang membawa email developer tidak memicu failover. Lihat bagaimana penolakan batas per pengguna sampai ke developer.

Failover pada 404 memerlukan gateway v2.1.198 atau yang lebih baru. Rilis sebelumnya mengembalikan 404 pertama ke klien bahkan ketika upstream berikutnya dalam daftar melayani model tersebut.

Beberapa upstream dari penyedia yang sama harus mengatur name: yang berbeda.

Klien Amazon Bedrock, Claude Platform on AWS, Agent Platform Google Cloud, dan Microsoft Foundry dibangun sekali saat startup, dan SDK-nya me-refresh kredensial secara internal, sehingga merotasi kredensial cloud tidak memerlukan restart. Kunci API Anthropic statis dan bearer dibaca saat startup; lihat Anthropic API.

Pesan error upstream

Gateway mengembalikan respons error dari satu upstream, atau 502 miliknya sendiri, bergantung pada bagaimana upstream menjawab:

• Sebuah upstream mengembalikan status yang tidak memicu failover oleh gateway: respons upstream tersebut. Gateway tidak mencoba upstream lain.
• Setiap upstream yang dicoba gateway gagal dengan cara yang memicu failover: 429 terakhir. Jika tidak ada yang mengembalikan 429, gateway memprioritaskan, secara berurutan, 401 atau 403 terakhir, 404 terakhir, dan 501 terakhir. Jika tidak ada yang mengembalikan salah satu dari itu, 502 milik gateway sendiri, all upstreams failed (N attempted). N menghitung entri upstreams Anda, termasuk yang dilewati, dikurangi entri mana pun yang daftar groups-nya tidak menyertakan developer tersebut.

Ketika gateway mengembalikan respons upstream, gateway mempertahankan kode status upstream. Apakah pesan upstream dipertahankan bergantung pada penyedia. Body error dari upstream Anthropic API sampai ke developer tanpa perubahan.

Upstream Amazon Bedrock, Claude Platform on AWS, Agent Platform Google Cloud, dan Microsoft Foundry dapat menyebutkan ID akun, ARN role, dan ID proyek Anda dalam teks error-nya. Gateway mencatat teks lengkap tersebut di log operasional. Apa yang dilihat developer dari upstream tersebut bergantung pada penolakannya:

• 400 atau 413 dalam envelope error standar Anthropic: pesan milik upstream sendiri, seperti prompt is too long. Claude Platform on AWS, Agent Platform, dan Microsoft Foundry mengembalikan envelope ini untuk penolakan API model.
• 400 atau 413 dalam bentuk milik penyedia sendiri: token capability_rejected:. Ketika gateway tidak dapat mengklasifikasikan penolakan, upstream rejected the request pada 400 atau request too large for this upstream pada 413.
• Status lainnya: teks generik per status, seperti upstream rate limit exceeded pada 429.

Misalnya, gateway mengganti Input is too long for requested model. dari Amazon Bedrock dengan capability_rejected: prompt_too_long. Claude Code melakukan compact secara otomatis pada token tersebut, seperti halnya pada prompt is too long.

Mempertahankan pesan 400 atau 413 dari upstream cloud, atau menggantinya dengan token capability_rejected:, memerlukan gateway v2.1.233 atau yang lebih baru.

Anthropic API

Upstream Anthropic minimal adalah kunci API dari Claude Console:

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

Kedua bentuk kredensial berbeda dalam header yang dikirimnya:

• api_key: mengirim x-api-key. Rotasi di Claude Console dan perbarui env var.
• oauth_token: mengirim Authorization: Bearer. Gunakan bentuk bearer ketika organisasi Anda menerbitkan token berumur pendek alih-alih kunci API berumur panjang. Bearer dibaca sekali saat startup, jadi lakukan refresh dengan me-mount ulang secret dan melakukan restart.

Alih-alih kunci atau bearer statis, Anda dapat menggunakan Workload Identity Federation. Buat aturan federasi dengan mengikuti panduan Workload Identity Federation, lalu mount JWT OIDC workload Anda sebagai file, seperti projected service-account token Kubernetes atau id-token platform CI. Gateway menukar JWT dengan bearer berumur pendek dan me-refresh-nya secara otomatis. File token dibaca ulang pada setiap pertukaran, sehingga projected token yang dirotasi diambil tanpa 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

Header identitas per pengguna untuk proxy yang Anda jalankan

Anda dapat mengarahkan base_url dari upstream provider: anthropic ke proxy yang Anda jalankan alih-alih ke Anthropic API. Untuk memberi tahu proxy tersebut developer mana yang mengirim setiap permintaan, atur forward_user_identity: true pada upstream tersebut. Proxy kemudian dapat mengatribusikan pengeluaran per developer. Memerlukan gateway yang menjalankan Claude Code v2.1.233 atau yang lebih baru.

Misalnya, untuk proxy di upstream-gateway.internal.example.com:

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

Gateway menambahkan header berikut ke setiap permintaan yang diteruskannya ke upstream tersebut.

Ketika token IdP tidak membawa email, gateway hanya mengirim x-claude-gateway-user-id dan menghilangkan dua header email. Jika IdP Anda menempatkan email di klaim yang berbeda, atur oidc.email_claim ke klaim tersebut.

Proxy Anda tidak menerima header x-claude-code-* yang dikirim Claude Code, seperti x-claude-code-session-id. Gateway tidak meneruskannya ke upstream mana pun, jadi kelompokkan permintaan berdasarkan developer dengan header di tabel di atas.

Ketika proxy Anda menjawab 429 untuk permintaan yang membawa email developer, gateway mengembalikan respons tersebut ke developer apa adanya alih-alih melakukan failover ke upstream berikutnya, sehingga anggaran atau rate limit per pengguna pada proxy Anda tetap berlaku. Respons lain dari proxy mengikuti aturan failover biasa. Jika token IdP seorang developer tidak membawa email, gateway meneruskan permintaan mereka tanpa header email, sehingga 429 untuk salah satu permintaan tersebut dihitung sebagai kapasitas upstream dan memicu failover. Sebelum v2.1.267 di server gateway, setiap 429 memicu failover.

Atur forward_user_identity hanya pada upstream yang base_url-nya adalah proxy yang Anda operasikan. Gateway mengirim email developer ke server mana pun yang disebutkan oleh base_url tersebut. Jika base_url adalah Anthropic API, yang merupakan default, gateway menolak untuk dimulai.

[!NOTE]

Jika Anda mengatur forward_user_identity pada upstream Amazon Bedrock, gateway keluar saat startup dengan Unrecognized key(s) in object: 'forward_user_identity'. Jika proxy Anda berada di depan Bedrock, cantumkan sebagai upstream provider: anthropic sebagai gantinya. Gateway mengirim format Anthropic Messages ke upstream tersebut, sehingga proxy Anda harus menerjemahkan permintaan untuk Bedrock. Untuk menyebutkan setiap developer ke AWS sebagai gantinya, lihat Atribusi biaya AWS per developer.

Amazon Bedrock

Untuk deployment Amazon Bedrock sisi klien yang digantikan atau dilayani di depannya oleh gateway, lihat Claude Code di Amazon Bedrock. Upstream sisi gateway:

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

Blok auth kosong menggunakan rantai kredensial default AWS SDK: env var, ~/.aws/credentials, ECS task role, metadata instans EC2, atau IRSA di EKS. Di produksi, berikan IAM role kepada pod gateway alih-alih menyematkan kunci statis dalam image container.

Kredensial eksplisit harus lengkap: gateway gagal saat boot ketika aws_access_key_id dan aws_secret_access_key tidak diatur bersamaan, atau ketika aws_session_token diatur tanpanya. Sebelum v2.1.207, blok auth: yang parsial lolos validasi.

Menerapkan guardrail Amazon Bedrock

Untuk menerapkan guardrail Amazon Bedrock ke setiap permintaan inferensi yang dikirim gateway melalui upstream Bedrock, tambahkan blok guardrail ke upstream tersebut. Memerlukan Claude Code v2.1.281 atau yang lebih baru di server gateway.

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

Berikan juga bedrock:ApplyGuardrail pada guardrail kepada principal yang menandatangani permintaan upstream ini: principal AWS milik gateway, atau dengan assume_role role yang disebutkan di role_arn.

Atur guardrail pada setiap upstream bedrock atau tidak sama sekali. Gateway menolak untuk dimulai jika ada campuran, karena failover dapat mengirim permintaan ke upstream Bedrock yang tidak memiliki guardrail.

Guardrail hanya mencakup upstream Bedrock. Jika Anda mencantumkan penyedia lain di upstreams, gateway mengirim permintaan ke penyedia tersebut tanpa guardrail, atau menolak untuk dimulai jika penyedia tersebut adalah mantle.

Ketika permintaan /v1/messages yang body-nya membawa field amazon-bedrock-*, seperti amazon-bedrock-guardrailConfig, mencapai upstream Bedrock yang memiliki guardrail, gateway menjawab 400 alih-alih meneruskannya.

[!WARNING]

Secara default gateway tidak menambahkan tag input ke prompt, sehingga filter guardrail yang diterapkan Amazon Bedrock hanya pada input bertag tidak berjalan pada lalu lintas melalui gateway. Untuk menambahkan tag, atur input_tagging. Untuk filter mana yang bergantung pada tag input, lihat input tags di dokumentasi Amazon Bedrock.

Menambahkan tag input guardrail

Agar gateway menambahkan tag input yang dibutuhkan filter prompt attacks pada guardrail Amazon Bedrock, atur input_tagging di blok guardrail dan mulai ulang gateway. Atur nilai yang sama pada setiap upstream bedrock, atau gateway menolak untuk dimulai. Memerlukan Claude Code v2.1.316 atau yang lebih baru di server gateway. Gateway pada versi yang tidak memiliki key ini keluar saat startup dengan Unrecognized key(s) in object: 'input_tagging'.

[!WARNING]

Menurut dokumentasi Amazon Bedrock, setiap filter dalam guardrail berhenti mengevaluasi konten tanpa tag begitu permintaan membawa tag input. Coba input_tagging pada gateway uji sebelum Anda mengaturnya pada gateway yang digunakan developer.

input_tagging menerima salah satu nilai berikut:

Dengan last_message, jika pesan user sejak balasan terakhir Claude tidak berisi teks untuk ditandai, gateway menandai pesan sistem di tengah percakapan sejak balasan tersebut. Panggilan tool dihitung sebagai balasan.

Panduan Amazon Bedrock untuk filter prompt attacks adalah menandai input pengguna sehingga system prompt dikecualikan. Jika Anda mengatur all_messages_and_system, filter yang menandai system prompt Claude Code sendiri dapat memblokir permintaan.

Contoh di bawah menandai teks di setiap pesan user:

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

Pesan user juga dapat berisi teks yang ditambahkan Claude Code, seperti system reminder, jadi periksa di gateway uji bahwa permintaan biasa tidak diblokir.

Dalam pengujian Anthropic, sesi yang ditandai mempertahankan pembacaan prompt cache dari satu prompt ke prompt berikutnya, dan tag tidak menambahkan token input.

Yang tidak dicakup tag input

Tidak ada nilai input_tagging yang menghentikan developer yang dengan sengaja menempatkan teks di tempat yang tidak diberi tag. Jangan mengandalkan guardrail untuk mengevaluasi bagian-bagian permintaan berikut:

• Konten yang tidak ditandai gateway: pesan yang tidak dicakup nilai input_tagging Anda, definisi tool, input panggilan tool, gambar, dan PDF, di antaranya. Kecuali Anda mengatur all_messages_and_system, system prompt juga tidak ditandai.
• Hasil tool: berisi apa yang dikembalikan tool Claude, seperti isi file dan halaman web. Dalam pengujian Anthropic, filter kata tidak mengevaluasinya, dengan atau tanpa tag.

Jika akun atau organisasi AWS Anda memberlakukan guardrail, lihat dokumentasi Amazon Bedrock untuk cara guardrail tersebut memperlakukan tag input.

Mencatat filter guardrail mana yang terpicu

Untuk mengetahui filter guardrail Amazon Bedrock mana yang memblokir permintaan developer, atur guardrail_trace: true pada upstream Bedrock, restart gateway, dan minta developer mengirim permintaan lagi. Kemudian temukan event guardrail.trace permintaan tersebut di log audit. Memerlukan Claude Code v2.1.314 atau yang lebih baru di server gateway. Gateway yang lebih lama menolak untuk mulai saat menemukan guardrail_trace.

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

Gateway menulis event guardrail.trace, tanpa teks yang cocok, saat filter terpicu atau tindakan guardrail adalah INTERVENED. Temukan event developer berdasarkan email atau sub. Satu permintaan streaming dapat menghasilkan beberapa event, dan salah satunya dapat memiliki daftar filters kosong, jadi baca setiap event yang memiliki request_id yang sama:

Event tidak menyertakan teks yang dicocokkan filter, termasuk field match dari trace Bedrock. Developer tidak menerima data trace Bedrock, karena gateway menghapusnya dari setiap balasan, baik streaming maupun tidak.

Jika klien mengirim field amazon-bedrock-* dalam body permintaan /v1/messages, gateway menjawab 400 pada upstream yang mengatur guardrail_trace.

Bedrock di akun AWS lain

Atur assume_role pada upstream Bedrock dan gateway menggunakan identitas AWS-nya sendiri hanya untuk memanggil sts:AssumeRole pada role yang Anda sebutkan, yang dapat berada di akun AWS yang berbeda dari gateway. Setiap permintaan Bedrock dari upstream tersebut ditandatangani dengan kredensial satu jam yang dikembalikan STS, sehingga tidak ada access key berumur panjang yang melintasi akun.

Memerlukan gateway yang menjalankan Claude Code v2.1.281 atau yang lebih baru. Gateway yang lebih lama menolak untuk dimulai ketika menemukan kunci ini.

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

Blok assume_role menerima tiga kunci:

Trust policy role menyebutkan principal milik gateway sendiri, seperti IRSA atau ECS task role-nya. Principal tersebut memerlukan sts:AssumeRole pada role dan tidak memerlukan izin Bedrock sendiri. Hapus Condition jika Anda tidak mengatur external_id.

{
  "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 permintaan dengan kredensial milik upstream sendiri. Gateway mencatat error STS beserta apa yang perlu diperiksa, lalu mencoba upstream berikutnya yang Anda cantumkan. Pesan error upstream menjelaskan apa yang diterima klien ketika tidak ada upstream yang berhasil. Upstream berikutnya tanpa assume_role akan melayani permintaan dengan kredensialnya sendiri, jadi cantumkan upstream seperti itu hanya jika memang itu yang Anda inginkan.
• Gateway memanggil endpoint STS regional sts.<region>.amazonaws.com, yang harus dapat dijangkau jaringannya. Untuk endpoint FIPS, atur AWS_USE_FIPS_ENDPOINT=true di lingkungan gateway alih-alih use_fips_endpoint di file konfigurasi AWS.
• assume_role memerlukan kredensial sumber SigV4: gateway menolak untuk mulai jika diatur bersama aws_bearer_token.
• Tanpa daftar groups, setiap developer yang diizinkan gateway dapat menggunakan upstream ini. Untuk membatasi model mana yang dapat digunakan developer, atur availableModels dalam kebijakan managed.
• Agar model yang dilayani melalui role tersebut tidak juga dilayani dari akun lain, berikan id kustom yang peta upstream_model-nya hanya berisi nama upstream ini. Untuk id seperti itu, gateway melewati setiap upstream lain, sehingga baik permintaan maupun penghitungan token untuk permintaan yang dibatalkan tidak dapat melakukan failover ke akun lain.
• Permintaan untuk nama model bawaan masih dapat mencapai upstream ini, dan gateway menandatanganinya dengan role yang sama. Cantumkan upstream ini paling akhir kecuali akunnya juga harus melayani model-model tersebut.

Contoh ini memberi satu model id kustom yang hanya dilayani oleh upstream terisolasi:

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

Atribusi biaya AWS per developer

Secara default gateway menandatangani setiap permintaan Bedrock dengan satu kredensial, sehingga AWS melihat permintaan semua developer di bawah satu principal IAM. Tambahkan session_name: email ke assume_role dan gateway memanggil sts:AssumeRole sekali per developer per jam, dengan nama sesi diatur ke email developer tersebut, dan menandatangani permintaan mereka dengan kredensial yang dikembalikan, sehingga permintaan setiap developer mencapai AWS di bawah sesi assumed-role mereka sendiri. Role dapat berada di akun milik gateway sendiri.

Memerlukan gateway yang menjalankan Claude Code v2.1.281 atau yang lebih baru. Atribusi biaya di AWS menjelaskan IAM role dan tempat penagihan AWS menampilkan sesi-sesi tersebut.

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

session_name memilih klaim terverifikasi mana yang menjadi RoleSessionName AWS: email atau sub. Gateway menulis karakter apa pun selain huruf ASCII, digit, dan _+,.@- sebagai hex =XX per byte UTF-8, dan memendekkan hasil yang lebih panjang dari 64 karakter menjadi prefiks ditambah hash, sehingga nama sesi setiap developer tetap valid dan unik. Permintaan dari developer yang tokennya tidak memiliki klaim tersebut tidak dikirim melalui upstream ini, dan log operator menyarankan untuk beralih ke sub atau mengatur oidc.email_claim.

Developer yang aktif membutuhkan satu panggilan STS per jam per replika gateway, dan permintaan pertama yang bersamaan berbagi satu panggilan.

Gateway juga membuat satu panggilan sendiri pada role ini: penghitungan token untuk permintaan yang ditinggalkan klien, agar batas pengeluaran tetap akurat. Penghitungan tersebut dan permintaan fallback satu token-nya ditandatangani oleh sesi bersama claude-apps-gateway, sehingga AWS mengatribusikan fallback tersebut ke claude-apps-gateway alih-alih ke developer.

Untuk atribusi per developer yang ketat, atur assume_role dengan session_name pada setiap upstream Bedrock yang Anda cantumkan. Upstream tanpanya menandatangani permintaan yang dilayaninya dengan kredensialnya sendiri.

Endpoint Mantle Amazon Bedrock

Penyedia mantle mengirim inferensi ke endpoint Mantle Amazon Bedrock. Penyedia ini memerlukan Claude Code v2.1.283 atau yang lebih baru di server gateway. Rilis gateway sebelumnya menolaknya saat boot, jadi upgrade setiap replika sebelum menambahkannya.

Contoh di bawah menempatkan Mantle di urutan pertama, dengan upstream Amazon Bedrock di belakangnya untuk melayani setiap model yang tidak dicantumkan oleh field models:

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: {}

Tabel di bawah mencantumkan field yang spesifik untuk upstream mantle.

Berikan identitas AWS upstream tersebut aksi IAM milik Mantle sendiri untuk inferensi dan penghitungan token, yang dicantumkan di Menggunakan endpoint Mantle.

Untuk ID model Mantle yang tidak dikenal gateway, tambahkan entri ke blok models: tingkat atas yang upstream_model-nya memetakan nama upstream ini ke ID tersebut. Lalu cantumkan juga id entri tersebut di field models upstream ini.

Pengaturan guardrail dan assume_role dari upstream bedrock tidak berlaku untuk permintaan yang dilayani Mantle:

• guardrail: gateway tidak menerapkan guardrail Bedrock pada permintaan yang dikirimnya ke Mantle, sehingga gateway menolak untuk dimulai ketika upstream mantle dicantumkan sementara ada upstream bedrock yang mengatur guardrail.
• assume_role: atur pada upstream mantle itu sendiri. Tanpanya, permintaan yang dilayani Mantle dikirim dengan kredensial auth milik upstream mantle sendiri.

Untuk arti respons error milik Mantle sendiri, lihat Error endpoint Mantle.

Claude Platform on AWS

Claude Platform on AWS melayani Anthropic API first-party di infrastruktur AWS pada aws-external-anthropic.<region>.api.aws. Platform ini menggunakan ID model first-party, mematuhi header anthropic-beta sebagaimana dikirim, dan melayani count_tokens, sehingga tidak ada terjemahan khusus Bedrock yang berlaku. Penyedia anthropicAws memerlukan Claude Code v2.1.198 atau yang lebih baru; rilis gateway sebelumnya menolaknya saat boot.

Untuk deployment sisi klien dari platform yang sama, lihat Claude Code di Claude Platform on AWS. Upstream sisi gateway:

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

Platform ini berjalan di akun AWS yang terpisah dari Amazon Bedrock dan menandatangani permintaan SigV4 untuk nama layanannya sendiri, aws-external-anthropic, sehingga IAM role yang dibatasi untuk Bedrock tidak mengotorisasinya. Kunci API di auth.api_key diutamakan ketika kredensial SigV4 juga diatur. Blok auth kosong menggunakan rantai kredensial default AWS SDK, rantai yang sama yang digunakan upstream Amazon Bedrock.

Karena platform me-resolve ID model first-party, katalog bawaan dirutekan ke sana tanpa blok models:. Ketika Anda mengkurasi daftar models:, beri kunci entri anthropicAws: dengan ID first-party.

Google Cloud Agent Platform

Untuk penyiapan sisi klien yang setara, lihat Claude Code di Google Cloud. Upstream sisi gateway:

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

Blok auth kosong menggunakan Application Default Credentials: GOOGLE_APPLICATION_CREDENTIALS, metadata GCE, atau GKE Workload Identity. File kunci JSON service account didukung tetapi tidak dianjurkan; gunakan Workload Identity atau lampirkan service account ke instans GCE atau Cloud Run.

Atur region: global untuk menggunakan endpoint global untuk Agent Platform Google Cloud alih-alih endpoint regional. Google kemudian merutekan setiap permintaan ke region yang tersedia, sehingga Anda tidak perlu melacak ketersediaan model per region. Mengatur region tertentu menyematkan setiap permintaan ke region tersebut.

Microsoft Foundry

Untuk deployment Microsoft Foundry sisi klien, lihat Claude Code di Microsoft Foundry. Upstream sisi gateway:

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}

use_azure_ad: true di-resolve melalui DefaultAzureCredential: Managed Identity di AKS, ACI, atau App Service; Azure CLI; atau kredensial lingkungan. Kunci API berfungsi tetapi berlaku untuk seluruh proyek dan tidak dirotasi secara otomatis. Endpoint Microsoft Foundry diturunkan dari resource:; atur base_url opsional untuk menimpanya pada sovereign cloud seperti Azure Government.

Header statis pada permintaan upstream

Untuk menambahkan header tetap ke permintaan yang dikirim gateway ke satu upstream, atur headers: pada upstream tersebut. Gunakan ini ketika proxy yang Anda jalankan di depan penyedia merutekan atau mengatribusikan lalu lintas berdasarkan header.

headers: memerlukan Claude Code v2.1.277 atau yang lebih baru di server gateway. Gateway yang lebih lama menolak untuk dimulai ketika menemukan kunci ini. Upgrade setiap replika sebelum Anda menambahkan kunci ini, dan hapus kunci ini sebelum Anda melakukan rollback ke versi sebelumnya.

Header dikirim ke server yang disebutkan oleh base_url, atau ke endpoint milik penyedia sendiri ketika base_url tidak diatur. Penyedia juga menerimanya kecuali proxy Anda menghapusnya.

Contoh ini menjangkau upstream provider: vertex melalui proxy di upstream-proxy.internal.example.com. Contoh ini mengatur header x-source yang dibaca proxy, dan mengirim token dari environment variable PROXY_TOKEN sebagai x-proxy-token:

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}

Nilai berupa teks ASCII yang dapat dicetak tanpa spasi di kedua ujungnya. Beri tanda kutip pada angka, true, atau false agar YAML membacanya sebagai teks.

Untuk menjaga secret tetap di luar file konfigurasi, gunakan ekspansi secret untuk memuat nilai dari environment variable dengan ${VAR} atau dari file dengan ${file:/path}. ${VAR} yang di-resolve menjadi nilai kosong menghentikan gateway untuk dimulai.

headers: berfungsi pada setiap penyedia, dan setiap upstream hanya mengirim header miliknya sendiri.

Tidak setiap permintaan yang dikirim gateway ke upstream membawanya:

Pada upstream Amazon Bedrock atau Claude Platform on AWS yang menandatangani permintaan dengan AWS SigV4, header ini merupakan bagian dari tanda tangan, sehingga proxy Anda harus meneruskannya tanpa perubahan.

Jika Anda menggunakan nama yang dicadangkan gateway, gateway menolak untuk dimulai, dan error startup menyebutkan header tersebut. Nama yang dicadangkan meliputi:

• authorization dan x-api-key
• host, content-type, dan user-agent
• Nama apa pun yang diawali dengan anthropic-, x-goog-, x-amz-, atau x-amzn-

Beberapa upstream

Penyedia yang sama dapat muncul lebih dari sekali dengan name: yang berbeda. Ini mencakup region yang berbeda, akun yang berbeda melalui rantai kredensial yang berbeda, provisioned throughput versus on-demand, dan fallback lintas penyedia.

Gateway mencoba upstream secara berurutan. 5xx, 429, 401, 403, 404, timeout, dan endpoint yang tidak ada (501) memicu failover; 4xx lainnya tidak.

429 adalah kapasitas per upstream, sehingga habisnya provisioned-throughput (PT) memicu failover ke on-demand. Jika Anda mengatur forward_user_identity: true pada sebuah upstream, 429 untuk permintaan yang membawa email developer justru merupakan penolakan per pengguna dan tidak memicu failover.

Sebuah permintaan melewati suatu upstream hanya dalam kasus-kasus berikut:

• Upstream tersebut gagal
• Upstream tersebut tidak melayani model yang diminta
• Upstream tersebut memiliki daftar groups yang tidak mencakup developer tersebut

Gateway tidak menyimpan catatan upstream yang gagal, sehingga selama sebuah upstream mati, setiap permintaan yang mencapainya tetap mencobanya dan menunggu hingga gagal sebelum melanjutkan.

Gateway menunggu selama ini agar respons mulai diterima:

• Upstream provider: anthropic: timeouts.upstream_ttfb_ms, 120 detik secara default
• Penyedia lain: hingga satu jam. Untuk mempersingkat waktu tunggu tersebut bagi permintaan streaming, atur timeouts.upstream_ttfb_ms pada gateway v2.1.295 atau yang lebih baru. Permintaan model non-streaming tetap menunggu hingga satu jam dalam kedua kasus

404 adalah ketersediaan model per upstream, sehingga upstream yang belum mengaktifkan sebuah model tidak menghalangi upstream berikutnya yang melayaninya. Upstream yang tidak dapat me-resolve model yang diminta dilewati tanpa round-trip jaringan.

Contoh ini merutekan alokasi provisioned-throughput Amazon Bedrock terlebih dahulu, meluap ke on-demand dan akun kedua, dan beralih ke Anthropic API sebagai fallback terakhir:

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

Failover antar penyedia cloud, atau ke Anthropic API langsung, mengubah perjanjian, wilayah geografis, dan ketentuan lain yang mengatur permintaan tersebut.

CLI menerapkan pembatasan fitur yang sama pada gateway terlepas dari upstream mana yang melayani permintaan tertentu, sehingga secara default failover tidak mengirim field body yang akan ditolak oleh upstream. Jika Anda mengatur TTL cache satu jam dalam sebuah kebijakan, pengaturan tersebut dikirim ke setiap upstream dalam daftar, jadi atur hanya jika semua upstream menerimanya.

Kirim setiap tim ke upstream-nya sendiri

Untuk mengirim permintaan setiap tim ke akun AWS atau proyek Google Cloud-nya sendiri, cantumkan satu upstream per tim dan berikan masing-masing daftar groups. Hanya developer dalam grup IdP yang tercantum yang dapat menjangkau upstream tersebut, baik pada percobaan pertama maupun saat failover. Setiap penyedia menerima groups. Memerlukan Claude Code v2.1.314 atau yang lebih baru pada server gateway.

Contoh ini memberikan masing-masing satu akun AWS kepada grup payments-eng dan search-eng, serta menambahkan upstream tanpa daftar groups yang dapat digunakan oleh setiap developer:

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: {}

Dengan konfigurasi contoh tersebut, permintaan setiap developer dimulai dari upstream pertama pada barisnya dan berpindah ke upstream berikutnya saat failover:

Ketika upstream suatu tim menolak model yang diminta dengan 403, gateway mencoba upstream berikutnya pada baris tim tersebut yang melayani model itu. Untuk mempertahankan tim pada satu upstream, berikan daftar groups pada setiap upstream, dan pastikan tidak ada upstream lain yang mencantumkan grup tempat developer tim tersebut berada. Tim tersebut kemudian tidak memiliki failover, dan permintaan dari developer yang tidak berada dalam grup mana pun yang tercantum akan gagal dengan 400.

Agar setiap developer mencapai upstream yang Anda maksud, tulis entri yang cocok secara persis dan letakkan upstream terbuka di posisi terakhir:

• Entri: tulis setiap grup persis seperti yang dikirim IdP Anda dalam klaim groups, yang juga dibaca oleh match.groups. Gateway menolak untuk dimulai ketika menemukan daftar kosong atau entri kosong. Gateway tidak memeriksa entri terhadap IdP Anda, sehingga entri yang tidak cocok dengan siapa pun tidak memunculkan peringatan.
• Urutan: letakkan upstream yang tidak memiliki daftar groups di posisi terakhir. Upstream tersebut melayani semua orang, sehingga jika dicantumkan lebih awal, upstream itu akan mengambil permintaan suatu tim sebelum upstream milik tim tersebut.

[!WARNING]

Gateway yang lebih lama dari v2.1.314 menolak untuk dimulai ketika menemukan groups, jadi tingkatkan versi setiap replika sebelum Anda menambahkannya.

Sebelum Anda melakukan rollback, hapus setiap upstream yang memiliki daftar groups beserta setiap kunci upstream_model atau override harga yang menyebutnya, dan pertahankan setidaknya satu upstream. Jika hanya kunci groups yang dihapus, upstream tersebut terbuka bagi setiap developer. Kunci atau override yang masih menyebut upstream yang telah dihapus akan mencegah gateway dimulai, dengan references unknown upstream.

Apa yang terjadi ketika developer tidak berada dalam grup mana pun yang tercantum

Jika setiap upstream memiliki daftar groups, developer yang tidak berada dalam grup mana pun tersebut akan melihat error ini, dan gateway tidak menghubungi penyedia mana pun:

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

Tambahkan developer tersebut ke grup yang tercantum di IdP Anda, atau tambahkan upstream tanpa daftar groups.

Gateway membaca ulang grup developer pada setiap refresh token. Jika IdP Anda tidak menyertakan grup dalam refresh, developer tersebut kemudian tidak memiliki grup:

• oidc.allowed_groups diatur: gateway menolak refresh, dan sesi berakhir
• Jika tidak, dan ada upstream tanpa daftar groups: permintaan developer berpindah ke upstream tersebut
• Jika tidak, dan setiap upstream memiliki daftar groups: permintaan developer gagal dengan error tersebut

Jika endpoint userinfo IdP Anda mengembalikan klaim groups dan oidc.google_groups tidak diatur, atur oidc.userinfo_fallback ke true untuk mengisi grup dari sana.

Bagian opsional

login_notice

Untuk menampilkan pemberitahuan kepada developer saat mereka masuk, atur kunci tingkat atas login_notice ke teks pemberitahuan, hingga 500 karakter. Contoh ini menyebutkan untuk siapa gateway ini ditujukan dan ke mana harus bertanya tentang akses:

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

Developer melihat teks tersebut di bawah Notice from <gateway hostname> pada halaman verifikasi gateway di browser dan pada layar masuk interaktif di terminal. Baris baru dalam teks menjadi spasi. Pemberitahuan muncul sebelum masuk, sehingga siapa pun yang dapat menjangkau gateway dapat membacanya.

Memerlukan Claude Code v2.1.319 atau yang lebih baru di server gateway, dan juga di mesin developer untuk layar terminal. Gateway versi lebih lama menolak untuk dimulai ketika menemukan kunci tersebut. Tingkatkan setiap replika sebelum Anda menambahkan kunci, dan hapus kunci sebelum Anda melakukan rollback.

admin

Opsional. Mengaktifkan /v1/organizations/spend_limits, yang mencerminkan Admin API publik Anthropic, serta penegakan batas pengeluaran per developer pada /v1/messages. Lihat Batas pengeluaran untuk cara batas ditetapkan dan ditegakkan; bagian ini membahas kunci gateway.yaml yang mengaktifkan fitur tersebut dan menyesuaikannya.

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]

Urutan anggaran gabungan

Anggaran gabungan adalah satu batas bulanan yang dibelanjakan bersama oleh seluruh grup. Untuk menetapkannya, tambahkan pooled_budget ke permintaan yang menetapkan batas bulanan grup, seperti "pooled_budget": {"amount": "500000"} untuk $5.000. Permintaan tersebut juga menerima scope grup, "period": "monthly", dan amount, yang tetap menjadi batas masing-masing anggota.

Untuk developer yang berada di beberapa grup semacam itu, setiap permintaan dihitung terhadap anggaran pertama yang pengeluarannya masih di bawah batasnya, dan ditolak ketika setiap anggaran sudah habis. pooled_conflict_rule menetapkan urutan gateway mencoba anggaran tersebut:

• default_order: batas terbesar terlebih dahulu, dan batas yang sama diurutkan menaik berdasarkan nama grup
• priority_list: anggaran grup-grup dalam pooled_priority_order, sesuai urutan daftar, lalu anggaran grup lain berdasarkan nama grup

Jika Anda mencantumkan grup tanpa pooled_conflict_rule: priority_list, gateway mengabaikan daftar tersebut dan mencatat peringatan saat boot.

Server gateway yang lebih lama dari v2.1.319 menolak untuk dimulai ketika menemukan pooled_conflict_rule atau pooled_priority_order. Tingkatkan setiap replika sebelum Anda menambahkan salah satu kunci tersebut, dan hapus kedua kunci sebelum Anda melakukan rollback.

enforcement

Blok enforcement mengontrol perilaku pemeriksaan batas pengeluaran saat penyimpanan tidak tersedia.

pricing

Blok pricing memberi tahu meter pengeluaran tarif apa yang dikenakan sebagai pengganti harga daftar USD, sehingga batas dan /effective mencerminkan tarif kontrak Anda. Jumlah tetap dalam USD dan tetap merupakan estimasi, bukan faktur. Ada dua prasyarat:

• Claude Code v2.1.227 atau yang lebih baru di server gateway. Versi sebelumnya menolak kunci yang tidak dikenal saat boot.
• Blok admin: atau, pada v2.1.268 atau yang lebih baru, blok managed: dengan setidaknya satu kebijakan. Gateway menolak untuk mulai jika pricing disetel tanpa salah satu blok tersebut, 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

Cara meter mencocokkan baris override:

• Sebuah baris menggantikan harga daftar untuk permintaan yang dilayani upstream, sebuah upstreams[].name, untuk model. Itu termasuk tarif fast mode yang lebih tinggi, sehingga permintaan fast dan standar diukur dengan empat tarif yang sama.
• ID bawaan seperti claude-sonnet-4-6, yang dicocokkan seperti models[].id, mencakup setiap bentuk bertanggal, bentuk regional Amazon Bedrock, atau bentuk Agent Platform Google Cloud yang diberi harga oleh meter sebagai model tersebut. String lain, seperti alias atau ARN inference-profile, dicocokkan dengan ID yang dikirim klien atau string yang dikirim ke upstream, tanpa membedakan huruf besar-kecil.
• Jika baris tumpang tindih, meter memilih baris yang paling spesifik, bukan baris pertama: baris yang model-nya adalah string model persis yang dikirim ke upstream, lalu baris yang cocok dengan ID persis yang dikirim klien, lalu baris yang menyebut model bawaan.
• Nama upstream yang tidak dikenal menggagalkan boot, begitu pula dua baris untuk satu upstream yang menyebut model yang sama, termasuk dua ejaan dari satu model bawaan. Gateway memberi peringatan saat boot tentang baris yang tidak dapat digunakan oleh model apa pun yang dapat diminta.
• Permintaan web-search tetap pada harga daftar $0.01; multiplier tetap berlaku untuk permintaan tersebut.

Untuk tarif per region, berikan setiap region upstream bernama miliknya sendiri dan satu baris per upstream.

Menaikkan harga

Dengan v2.1.271 atau yang lebih baru di server gateway, Anda dapat menyetel multiplier di atas 1, hingga 10, untuk mengukur lebih dari yang dikenakan penyedia, misalnya tarif chargeback internal. Contoh ini mengukur setiap permintaan pada 120% dari harga:

pricing:
  multiplier: 1.2

Dengan blok admin:, markup juga berlaku untuk batas pengeluaran. Meter menghitung 120% dari harga, sehingga developer mencapai batasnya lebih cepat. Gateway mencatat peringatan saat boot yang menyatakan hal tersebut.

Multiplier tidak mengubah apa yang dikenakan penyedia upstream untuk permintaan tersebut.

Jika gateway juga mengirim tarif ke klien yang sudah masuk, developer memerlukan Claude Code v2.1.271 atau yang lebih baru untuk melihat markup. Klien sebelumnya mengabaikan multiplier di atas 1 dan menampilkan biaya tanpanya.

Server gateway yang lebih lama dari v2.1.271 menolak untuk mulai jika Anda menyetel multiplier di atas 1.

Mengirim tarif ke klien yang sudah masuk

Dengan v2.1.268 atau yang lebih baru di server gateway, gateway juga memasukkan tarif dari pricing ke dalam kebijakan managed yang dilayaninya, sebagai pengaturan terkelola modelPricing.

Pengembang yang cocok dengan suatu kebijakan kemudian melihat tarif pricing di /usage, baris status, dan OpenTelemetry. Pengembang yang tidak cocok dengan kebijakan mana pun tidak menerima pengaturan terkelola, sehingga angka mereka tetap pada harga daftar. Klien menerapkan pengaturan ini di Claude Code v2.1.242 atau yang lebih baru.

• Apa yang ditambahkan gateway: kecuali blok cli suatu kebijakan sudah menyetel modelPricing, gateway menambahkan multiplier dan, untuk setiap ID model yang dapat diminta klien, baris override dari upstream pertama yang melayani ID tersebut. Tarif yang hanya dikenakan oleh upstream failover tetap di gateway.
• Upstream dengan daftar groups: ketika salah satunya merupakan upstream pertama yang melayani suatu ID model, gateway tidak menambahkan baris untuk ID tersebut. Pengembang kemudian melihat tarif Claude Code sendiri untuk ID tersebut, yaitu tarif standar model ketika Claude Code mengenali ID tersebut, dikalikan multiplier.
• Mengecualikan satu kebijakan: setel modelPricing ke {} di blok cli kebijakan tersebut, dan developer-nya tetap pada harga daftar.
• Mempertahankan tarif milik kebijakan: kebijakan yang blok cli-nya menyetel modelPricing dengan multiplier atau overrides sendiri mempertahankan modelPricing tersebut secara utuh, dan gateway tidak menambahkan tarifnya sendiri ke dalamnya.

models

Blok models adalah daftar model opsional yang dikurasi admin, dilayani di /v1/models dan digunakan untuk menerjemahkan ID model per upstream. Blok ini wajib untuk region Amazon Bedrock di luar AS, ARN provisioned-throughput Amazon Bedrock, dan nama deployment Microsoft Foundry.

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

Setiap kunci di bawah upstream_model harus cocok dengan name dari upstream yang dikonfigurasi, yang secara default adalah nama penyedia. Kunci yang tidak cocok dengan upstream mana pun menggagalkan boot, jadi hapus baris untuk penyedia yang tidak Anda gunakan.

managed

Blok managed mendefinisikan kebijakan akses berbasis peran yang dikunci pada grup IdP atau domain email. Kebijakan dievaluasi secara berurutan; secara default kecocokan pertama yang dipilih, lalu digabungkan ke basis catch-all match: {}. Pengguna yang cocok dengan dua kebijakan peran hanya mendapatkan yang pertama, sehingga aturan deny dari kebijakan kedua tidak berlaku kecuali Anda menerapkan setiap kebijakan yang cocok. Kebijakan dilayani per pengguna di GET /managed/settings dengan caching ETag/304.

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

Catch-all match: {}, yang secara konvensi dicantumkan terakhir, diperlakukan sebagai lapisan dasar. Setiap kebijakan lain mewarisi kunci apa pun yang tidak disetelnya dari catch-all, sehingga entri per peran hanya perlu mencantumkan apa yang berbeda dari default organisasi. Aturan penggabungan bergantung pada jenis kunci:

• Allow-list: availableModels dan permissions.allow. Daftar kebijakan spesifik sepenuhnya menggantikan daftar dasar.
• Deny-list dan array hook: permissions.deny, permissions.ask, disabledMcpjsonServers, deniedMcpServers, blockedMarketplaces, deniedModels, dan setiap array tipe event hooks. Kunci ini mengambil gabungan (union) dari dasar dan kebijakan, sehingga deny atau hook audit di seluruh organisasi tidak dapat terhapus secara tidak sengaja oleh override per peran.
• Kunci bertipe record: env, modelOverrides, dan skillOverrides. Kunci ini digabungkan secara dangkal (shallow-merge), sehingga blok env per peran menimpa kunci yang disetelnya dan mewarisi sisanya dari dasar.

availableModels juga ditegakkan di sisi server pada /v1/messages, sehingga model yang ditolak mengembalikan 400 terlepas dari apa yang dikirim klien. Daftar kosong menolak setiap model. Pemeriksaan ini juga mencakup model yang digunakan sesi saat dimulai sebelum developer memilih model, jadi mulai sesi pada model yang diizinkan kebijakan.

Gateway memvalidasi nilai model sendiri sebelum meneruskan permintaan, sehingga nilai yang salah format tidak pernah mencapai upstream. Gateway menolak permintaan dengan 400 dalam dua kasus:

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

Pengguna terautentikasi yang tidak cocok dengan kebijakan apa pun mendapatkan default gateway, yang berarti setiap model dalam katalog dan tanpa pengaturan terkelola. Tambahkan catch-all match: {} di akhir jika Anda menginginkan kebijakan default yang terjamin.

Letakkan aturan deny di seluruh organisasi dalam kebijakan match: {}, karena aturan kebijakan grup hanya berlaku selama token pengguna membawa grup tersebut.

[!NOTE]

Gateway tidak menyimpan direktori pengguna sendiri. Gateway mengotorisasi setiap permintaan dari token IdP pengguna, membaca keanggotaan grup dari klaim groups token dan mengevaluasi kebijakan terhadapnya. Tidak ada daftar pengguna untuk dienumerasi dan tidak ada akun untuk dibuat sebelumnya, dan karena itu tidak ada endpoint SCIM, karena tidak ada yang perlu disinkronkan oleh SCIM.

Jalankan manajemen siklus hidup pengguna dan grup di sumber kebenaran, yaitu provisioning SCIM bawaan IdP Anda atau platform tata kelola identitas khusus. Keanggotaan dan deprovisioning yang diatur di sana mengalir ke gateway secara otomatis melalui token. Jika Anda menginginkan provisioning SCIM untuk akun Claude itu sendiri, itu adalah kemampuan Claude for Enterprise.

Ada dua waktu propagasi yang berlaku:

• Isi kebijakan: mengedit kebijakan dan men-deploy ulang menjangkau klien Claude Code yang terhubung pada polling pengaturan terkelola berikutnya, dalam satu jam, kecuali perubahan yang hanya berlaku pada peluncuran berikutnya
• Keanggotaan grup: mengubah keanggotaan grup pengguna mengubah kebijakan mana yang cocok dengannya. Ini berlaku pada penerbitan ulang sesi berikutnya, yaitu refresh senyap berikutnya, yang dibatasi oleh session.ttl_hours.

Claude Desktop mengikuti jadwalnya sendiri.

Menerapkan setiap kebijakan yang cocok

Pengguna yang cocok dengan beberapa kebijakan peran hanya mendapatkan yang pertama kecuali Anda mengatur policy_mode: layered di samping policies. Dengan layered, setiap kebijakan yang cocok dengan pengguna berlaku, hingga kebijakan match: {} pertama.

policy_mode memerlukan Claude Code v2.1.316 atau yang lebih baru di server gateway. Gateway pada versi yang tidak memilikinya menolak untuk mulai saat menemukan kunci tersebut. Tingkatkan setiap replika sebelum Anda menambahkan kunci, dan hapus kunci sebelum Anda melakukan rollback ke versi sebelumnya. Contoh ini memiliki satu grup yang kehilangan WebFetch dan satu grup yang mendapatkan Opus:

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

Tabel ini menunjukkan apa yang diterima pengguna yang berada di no-web dan opus-users dalam mode default, first_match, dan dalam layered.

Gateway menggabungkan setiap kebijakan yang cocok ke kebijakan yang tercantum di bawahnya, dengan aturan penggabungan yang sama seperti lapisan basis:

• Allowlist, nilai tunggal, dan blok seperti sandbox: masing-masing diambil secara utuh dari kebijakan cocok yang tercantum pertama yang mengaturnya, sehingga daftar availableModels dari dua grup tidak dijumlahkan.
• Daftar deny dan array hook: ini dijumlahkan di seluruh kebijakan yang cocok, sehingga pengguna di dua grup mendapatkan aturan deny dari kedua grup.
• env, modelOverrides, dan skillOverrides: entri digabungkan berdasarkan nama, dan kebijakan cocok yang tercantum pertama yang mengatur suatu nama memberikan nilainya.
• Kunci desktop: ini digabungkan berdasarkan aturan untuk blok desktop basis.

[!WARNING]

Kebijakan dapat dijumlahkan menjadi aturan yang lebih longgar daripada yang diberikan salah satunya saja. Misalnya, kebijakan match: {} mengatur sandbox.enabled: true, kebijakan satu grup mengatur permissions.allow: ["Bash"], dan kebijakan grup lain mengatur sandbox.enabled: false. Pengguna di kedua grup menerima Bash yang diizinkan dengan sandbox nonaktif. Dalam kasus ini, cantumkan kebijakan yang mengizinkan Bash terlebih dahulu, dan salin seluruh blok sandbox dari kebijakan match: {} ke dalamnya.

Dengan layered, gateway menolak untuk mulai pada beberapa pengaturan, termasuk yang berikut:

• Pola !: negasi ! dalam aturan Read atau Edit di daftar permissions.deny atau permissions.ask kebijakan mana pun, termasuk milik kebijakan match: {}
• Batasan pada hook di luar catch-all: disableAllHooks, allowedHttpHookUrls, atau httpHookAllowedEnvVars di kebijakan mana pun selain match: {}

Memulai sesi pada model yang diizinkan kebijakan

Jika availableModels tidak menyertakan model default Claude Code, sesi mendapatkan respons 400 hingga developer memilih model yang tercantum, misalnya dengan /model. Dalam sesi gateway, default-nya adalah model Opus yang dituju alias opus, dan availableModels saja tidak mengubahnya.

Untuk memperbaikinya, setel enforceAvailableModels: true di blok cli yang sama, lalu periksa jenis entri yang ada dalam daftar:

• 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 dapat tetap dimulai pada default bawaan, jadi setel juga model ke salah satu ID yang tercantum di blok cli kebijakan tersebut

Kebijakan ini mencantumkan satu ID kustom yang didefinisikan models, dan memulai sesi pada ID tersebut:

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

Nilai matcher yang menghentikan gateway saat boot

Saat boot, gateway memeriksa blok match setiap kebijakan dan daftar admin_groups. Salah satu nilai berikut menghentikan gateway dengan error yang menyebutkan bidangnya:

• Daftar groups yang kosong
• Entri kosong di groups atau di admin_groups
• email_domain yang kosong
• email_domain yang berisi @, spasi, atau koma. Gateway memangkas nilai tersebut dan menghapus satu @ di awal sebelum pemeriksaan ini. Tulis satu domain polos, seperti example.com.

Sebelum v2.1.232, gateway tetap mulai dengan nilai-nilai ini. Setiap nilai memiliki efek berikut:

• email_domain kosong: gateway melewati pemeriksaan domain, sehingga kebijakan dengan email_domain kosong dan tanpa daftar groups cocok dengan setiap pengguna yang terautentikasi
• Daftar groups kosong: kebijakan tidak cocok dengan siapa pun
• email_domain yang berisi @, spasi, atau koma: kebijakan tidak cocok dengan siapa pun
• Entri kosong di groups atau di admin_groups: entri tersebut hanya cocok dengan pengguna jika klaim groups IdP pengguna itu juga berisi entri kosong. Di admin_groups, kecocokan itu memberikan akses admin. Jika daftar admin_groups Anda tidak pernah berisi entri kosong, tidak ada yang memperoleh akses admin dengan cara ini.

Memilih cli atau code

[!WARNING]

Jika kebijakan menggunakan kunci code, masing-masing hal berikut mencegah gateway untuk mulai:

• Versi gateway: code memerlukan Claude Code v2.1.296 atau yang lebih baru di server gateway. Gateway yang lebih lama menolak untuk mulai saat menemukan kunci tersebut. Tingkatkan setiap replika sebelum Anda menambahkan kunci, dan ubah code kembali ke cli sebelum Anda melakukan rollback ke versi sebelumnya.
• Kunci campuran: file yang memiliki code dan cli, atau ejaan sebelumnya settings, menghentikan gateway saat boot. Letakkan setiap blok di bawah satu kunci, dalam satu pengeditan.

Pengaturan Claude Code suatu kebijakan, seperti aturan yang menolak membaca file .env, ditempatkan dalam blok di bawah kunci cli atau code. code adalah kunci yang direkomendasikan, dan cli adalah kunci lama. Kedua kunci menerima isi yang sama. Kunci menentukan di mana pengaturan ditegakkan:

• cli: terminal, ekstensi VS Code dan JetBrains, dan Agent SDK. Di bawah cli, tab Code di Claude Desktop mendapatkan pengaturan turunan, sehingga aturan berlingkup seperti Read(./.env) tidak menghentikan pengguna di sana.
• code: tempat yang sama, dan tab Code di Claude Desktop juga dapat dicakup.

File yang menggunakan cli berfungsi seperti sebelumnya, dan gateway yang menemukan cli dalam kebijakan dengan kunci desktop memberi peringatan saat boot dan tetap mulai. Beralihlah ke code agar pengaturan juga dapat mencakup tab Code.

Sebelum beralih, baca Menerapkan pengaturan code di tab Code. Kebijakan memerlukan kunci desktop dan mesin pengguna memerlukan penyiapan sebelum pengaturan berlaku di sana, dan pencarian web dimatikan di Claude Desktop.

Kebijakan ini menempatkan aturan deny di bawah code, dengan kunci desktop kosong:

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

Saat beralih, hapus baris serve_to_desktop apa pun dalam pengeditan yang sama yang mengganti nama blok. Di mana suatu instruksi menyebut blok cli, gunakan blok code Anda.

serve_to_desktop: true adalah cara lama untuk menawarkan pengaturan cli suatu kebijakan ke tab Code. Ini tidak berpengaruh ketika Claude Desktop terhubung melalui bootstrapUrl. Selama kebijakan Anda menggunakan cli, peringatan boot yang menyebut kunci ini berarti pengaturan tersebut tidak mencapai tab Code:

• Untuk mencakup tab Code: beralih ke code, setelah mesin pengguna memenuhi kondisi di Menerapkan pengaturan code di tab Code
• Untuk tetap menggunakan cli: tetapkan serve_to_desktop: false di samping cli dalam suatu kebijakan untuk menyembunyikan peringatan

Apa yang dimasukkan ke cli

Setiap nilai code atau cli adalah dokumen managed-settings.json Claude Code yang lengkap, skema yang sama yang akan Anda deploy melalui MDM atau /etc/claude-code/managed-settings.json, yang dinyatakan di sini sebagai YAML. CLI menerapkan dokumen yang dikirim pada tingkat terkelola, di atas pengaturan pengguna dan proyek, sebagai pengganti pengaturan terkelola server. Karena itu CLI mengabaikan pengaturan yang dibatasi untuk sumber kebijakan tingkat OS, seperti policyHelper dan wslInheritsWindowsSettings.

Gateway memvalidasi setiap dokumen terhadap skema pengaturan CLI saat boot, sehingga kunci tingkat atas yang tidak dikenali menggagalkan boot dengan error yang menyebutkan setiap kunci yang bermasalah. Bagian skema yang sengaja dibuat terbuka tetap menerima nilai arbitrer, karena klien yang lebih baru mungkin mengenali entri yang tidak dikenali skema gateway. Kunci terbuka ini mencakup env, pluginConfigs, dan kunci yang bersarang di bawah permissions.

Karena validasi menggunakan skema yang dibundel dengan versi gateway yang terpasang, memasukkan kunci pengaturan tingkat atas yang diperkenalkan oleh rilis Claude Code yang lebih baru ke dalam konfigurasi terkelola memerlukan peningkatan gateway terlebih dahulu. Lakukan smoke test pada kebijakan baru di satu klien sebelum meluncurkannya.

Referensi kunci lengkap ada di Pengaturan Claude Code. Kunci yang paling sering digunakan operator terlebih dahulu:

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 }

Karena pengaturan ini datang melalui jaringan, CLI menampilkan dialog persetujuan keamanan kepada setiap developer sebelum menerapkan pengaturan yang tercantum di bawah ini:

• hooks
• variabel env yang memerlukan persetujuan developer, seperti variabel proxy dan base-URL
• 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.

Memori persetujuan membahas berapa lama persetujuan bertahan dan kapan dialog muncul lagi.

Claude Code menerapkan beberapa variabel env yang dikirimkan tanpa menampilkan dialog persetujuan kepada pengembang, seperti pengaturan pemilihan model dan batas numerik. Variabel lain yang dikirimkan dapat memerlukan persetujuan pengembang; nilai proxy, base-URL, atau OTEL_EXPORTER_OTLP_ENDPOINT yang tidak kosong selalu memerlukannya. Ketika variabel yang dikirimkan memerlukan persetujuan, dialog menyebutkannya. Environment variable dan dialog persetujuan berisi detailnya, termasuk empat toggle privasi yang nilai kirimannya menentukan apakah memerlukan persetujuan.

Konfigurasi telemetri gateway mengirim OTEL_EXPORTER_OTLP_ENDPOINT, sehingga menyetel telemetry.forward_to memicu dialog pada setiap klien interaktif. Dialog ini melindungi mesin developer dari gateway yang disusupi atau berniat jahat, bukan melindungi organisasi dari developer.

Eksekusi non-interaktif, seperti claude -p, sesi Agent SDK, atau sesi di tab Code Claude Desktop, tidak dapat menampilkan dialog. Eksekusi tersebut menerapkan pengaturan yang dikirim hanya untuk eksekusi itu dan tidak mencatatnya sebagai disetujui, sehingga sesi interaktif developer berikutnya tetap menampilkan dialog.

Jika developer menolak, Claude Code keluar dari sesi tersebut alih-alih menerapkan kebijakan. Karena itu, saat Anda mengirim hook baru, atau env var apa pun yang memicu dialog, ke kebijakan yang luas, setiap developer yang cocok akan melihat dialog dalam sesi interaktif mereka. Sesi interaktif yang sedang berjalan menampilkannya pada polling per jam berikutnya, dan jika tidak, dialog muncul pada startup interaktif developer berikutnya.

Kunci cli bernama settings pada rilis sebelumnya, dan gateway masih menerima ejaan tersebut sebagai alias. Untuk deployment baru, gunakan code.

Menguji kebijakan sebelum deployment

Untuk menguji perubahan kebijakan, mulai gateway dengan database Postgres sekali pakai. Gateway terhubung ke Postgres dan menerapkan migrasi skemanya sebelum memeriksa isi blok cli, code, dan desktop. Ketika tidak dapat menjangkau database, proses mulai berhenti di could not connect to Postgres dan tidak melaporkan apa pun tentang isinya.

Context window dalam sesi terminal

Sesi terminal yang masuk melalui /login menggunakan context window 1M untuk Opus 4.7 dan yang lebih baru, Sonnet 5 dan yang lebih baru, serta model Fable. ID model tidak memerlukan akhiran [1m], dan sesi melakukan compact pada sekitar 967K token. Sebelum Claude Code v2.1.287 di mesin developer, Claude Code memperlakukan model Opus dan Fable sebagai memiliki window 200K kecuali ID model diakhiri dengan [1m].

Agar sesi terminal melakukan compact pada batas 200K, setel window auto-compact di env kebijakan:

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

Claude Code menerapkan variabel ini tanpa menampilkan dialog persetujuan kepada developer. Variabel ini berlaku untuk setiap model, termasuk ID model yang diakhiri dengan [1m].

Untuk mematikan konteks 1M, setel CLAUDE_CODE_DISABLE_1M_CONTEXT: "1" di blok env yang sama. Claude Code kemudian memperlakukan setiap model sebagai memiliki window 200K. Dalam sesi interaktif, setiap developer menyetujui variabel ini di dialog persetujuan sebelum variabel tersebut berlaku.

Prompt cache satu jam

Untuk meminta TTL prompt cache satu jam alih-alih lima menit default, tambahkan kunci ini ke blok code, cli, atau settings yang sudah ada di kebijakan, lalu mulai ulang gateway. Kunci ini memerlukan Claude Code v2.1.242 atau yang lebih baru di server gateway dan di klien.

promptCacheTtl mencakup percakapan utama. subagentPromptCacheTtl bersifat opsional dan mencakup subagent, workflow, dan permintaan latar belakang. Contoh ini menambahkan keduanya ke kebijakan match: {} dengan kunci cli:

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

[!WARNING]

Setel kunci ini hanya jika upstream Anda menawarkan TTL satu jam untuk setiap model yang dilayani gateway. Jika upstream menolak TTL tersebut, permintaan gagal, dan baik gateway maupun Claude Code tidak mencoba ulang permintaan dengan TTL lima menit. Untuk Amazon Bedrock, periksa model, region, dan batas yang didukung.

Untuk mengonfirmasi promptCacheTtl, masuk ke gateway sebagai pengguna yang cocok dengan kebijakan dan periksa TTL mana yang digunakan oleh penulisan cache Anda. Berikan --model untuk mengulangi pemeriksaan bagi setiap model yang dilayani gateway.

Penulisan cache satu jam lebih mahal daripada penulisan lima menit. Agar batas pengeluaran menghitung tarif yang lebih tinggi tersebut, Anda memerlukan v2.1.286 atau yang lebih baru di server gateway.

Server MCP dalam kebijakan

Untuk menyediakan server MCP ke klien Claude Code yang cocok dengan suatu kebijakan, setel managedMcpServers di blok cli kebijakan tersebut. Anda memerlukan Claude Code v2.1.259 atau yang lebih baru di server gateway dan di klien.

Gateway memeriksa setiap entri saat boot dengan aturan yang sama yang diterapkan Claude Code di klien, dan jika suatu entri gagal dalam pemeriksaan, gateway menolak untuk mulai dan menyebutkan entri tersebut.

Jika Anda menulis referensi ${VAR} di gateway.yaml, gateway menyelesaikannya dari environment-nya saat boot melalui ekspansi secret sebelum menjalankan pemeriksaan entri, sehingga setiap klien yang cocok menerima nilai literal dan dapat membacanya. Panduan header untuk server yang disediakan berlaku untuk nilai yang sudah diekspansi.

Gateway menolak ejaan .mcp.json mcpServers di blok cli, dan error boot-nya menyebut managedMcpServers sebagai kunci yang harus digunakan. Sebelum v2.1.259, gateway menolak definisi server MCP apa pun di blok cli.

Overlay Claude Desktop

Jika organisasi Anda juga men-deploy Claude Desktop, gateway yang sama melayani kedua klien. Arahkan bootstrapUrl, di konfigurasi terkelola Claude Desktop, ke <listen.public_url>/user/bootstrap. Claude Desktop menurunkan penerbit OAuth dari URL tersebut, menjalankan proses masuk device-code yang sama terhadap gateway ini, dan mengambil konfigurasinya dari respons.

[!NOTE]

Memerlukan Claude Code v2.1.203 atau yang lebih baru di server gateway, dan opt-in eksplisit: /user/bootstrap mengembalikan 404 kecuali kebijakan yang cocok dengan pengguna memiliki kunci desktop. desktop: {} kosong mengikutsertakan suatu kebijakan, dan kunci desktop pada lapisan dasar match: {} mengikutsertakan setiap kebijakan yang mewarisinya. Log audit mencatat setiap permintaan sebagai desktop_bootstrap.serve atau desktop_bootstrap.denied.

Jika Anda tidak men-deploy Claude Desktop, jangan sertakan desktop sama sekali dalam kebijakan Anda; gateway kemudian mengembalikan 404 dari /user/bootstrap untuk setiap pengguna.

Pengaturan yang diturunkan gateway untuk Claude Desktop

Gateway menurunkan sebagian besar respons bootstrap dari blok cli atau code kebijakan yang cocok dan dari konfigurasi gateway tingkat atas:

• Daftar model, dari availableModels. Daftar ini tidak menyertakan model yang diblokir kebijakan dengan deniedModels atau availableModelsMatch: exact. Filter ini memerlukan Claude Code v2.1.299 atau yang lebih baru di server gateway. Konteks diperluas di Claude Desktop membahas opsi konteks 1M setiap model

• Tool yang dinonaktifkan, dari entri permissions.deny berupa nama tool polos. Jika Anda menyetel disabledBuiltinTools di blok desktop kebijakan, gateway melayani gabungan nilai Anda dan daftar turunan, sehingga Anda dapat menonaktifkan lebih banyak tool dengan cara ini tetapi tidak dapat mengaktifkan kembali tool yang Anda nonaktifkan melalui permissions.deny

• Allowlist egress, dari sandbox.network.allowedDomains. Jika Anda menyetel coworkEgressAllowedHosts di blok desktop kebijakan, gateway menggunakan nilai tersebut alih-alih daftar turunan. Jika allowlist yang dilayani gateway menyertakan * dan gateway tidak juga melayani allowedWorkspaceFolders Claude Desktop, Claude Desktop tidak mengaktifkan sandbox Bash di tab Code

• Endpoint OTLP yang mengarah ke gateway itu sendiri, dan atribut identitas pengguna yang masuk. Gateway meneruskan ekspor yang diterimanya di endpoint tersebut ke tujuan forward_to Anda. Gateway menyertakan endpoint dan atribut tersebut saat Anda menyetel telemetry.forward_to dan listen.public_url.

  Claude Desktop mengekspor setiap sinyal dengan satu encoding: http/protobuf, atau http/json saat Anda menyetel OTEL_EXPORTER_OTLP_PROTOCOL atau salah satu varian per sinyalnya ke http/json di env kebijakan. Sebelum Claude Code v2.1.261 di server gateway, respons selalu menyetel http/json, sehingga collector yang hanya menerima protobuf menolak ekspor Claude Desktop

Untuk menyetel disabledBuiltinTools, coworkEgressAllowedHosts, atau pengaturan managedMcpServers milik Claude Desktop di blok desktop kebijakan, Anda memerlukan Claude Code v2.1.232 atau yang lebih baru di server gateway. managedMcpServers milik Claude Desktop menerima nilai array, bukan objek.

Gateway menghilangkan kunci yang tidak memiliki padanan di Claude Desktop, seperti hooks dan aturan izin berlingkup seperti Bash(npm *), dari respons bootstrap.

Menerapkan pengaturan code di tab Code

Pengaturan Claude Code yang dimiliki kebijakan di bawah kunci code berlaku di tab Code Claude Desktop jika semua kondisi berikut terpenuhi:

• Kebijakan juga memiliki kunci desktop, dan desktop: {} kosong juga dihitung
• Claude Desktop versi 2.9939.2 atau yang lebih baru
• Pengaturan terkelola Claude Code di mesin menyebut gateway ini
• Mesin tersebut menjangkau gateway melalui HTTPS di jaringan pribadi

Dua kondisi terakhir berlaku untuk mesin mana pun yang menjalankan Claude Code untuk sesi tersebut. Untuk sesi lokal, itu adalah komputer pengguna sendiri. Untuk sesi tab Code melalui SSH, itu adalah host jarak jauh.

Deploy pengaturan terkelola sisi klien ke mesin-mesin tersebut sebelum Anda mengganti nama cli menjadi code. Jika dua kondisi pertama terpenuhi dan salah satu dari dua kondisi terakhir tidak terpenuhi, pengguna yang cocok dengan kebijakan mendapatkan salah satu hasil berikut:

• Melalui HTTPS, jika Claude Desktop membundel Claude Code v2.1.296 atau yang lebih baru: tab Code tidak dimulai, dan balasan untuk prompt pengguna menjelaskan alasannya
• Melalui HTTPS, jika Claude Desktop membundel versi yang lebih lama: tab Code dimulai tanpa pengaturan code Anda, dan tidak ada apa pun dalam sesi yang memberitahukannya
• Melalui HTTP biasa: tab Code dimulai tanpa pengaturan code Anda, versi apa pun yang dibundel Claude Desktop

Jika proxy di depan gateway menjawab /managed/settings dengan 404 miliknya sendiri, tab Code juga dimulai tanpa pengaturan code Anda, termasuk di mesin yang memenuhi keempat kondisi.

Dalam kebijakan yang memiliki kunci desktop, blok code yang berisi pengaturan mematikan tool WebSearch di Cowork, Chat, dan tab Code. Untuk server MCP, lihat Tempat managedMcpServers berlaku.

Menyetel pengaturan Claude Desktop secara langsung

Tambahkan blok desktop opsional di samping cli untuk menyetel pengaturan Claude Desktop secara langsung. Tulis pengaturan dari referensi konfigurasi terkelola Claude Desktop sebagai nama kunci datar. Jangan sertakan kunci yang hanya dibaca Claude Desktop dari MDM atau file lokal, seperti bootstrapUrl; gateway menolaknya saat boot.

Contoh ini menyetel tiga kunci Claude Desktop untuk grup eng-contractors di samping pengaturan cli-nya:

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

Setiap kunci bersifat opsional; Claude Desktop menerapkan default-nya sendiri untuk kunci apa pun yang Anda hilangkan.

Apa yang ditolak gateway saat boot

Gateway memvalidasi setiap blok desktop saat boot terhadap skema konfigurasi yang digunakan Claude Desktop sendiri, sehingga kesalahan muncul saat gateway dimulai sebagai error yang menyebutkan kunci tersebut, alih-alih menjangkau setiap desktop yang terhubung. Gateway gagal saat boot jika suatu blok berisi:

• Kunci yang tidak dikenal
• Kunci yang dikenali yang nilainya akan ditolak atau diam-diam dibuang oleh Claude Desktop, seperti nilai kosong atau sub-kunci yang salah eja di dalam entri bersarang. Sebelum v2.1.260, gateway diam-diam membuang bidang yang salah eja di dalam objek bersarang dari entri managedMcpServers atau orgPluginSettings alih-alih gagal saat boot.
• Kunci yang dihitung gateway sendiri: koneksi inferensi, daftar model, dan relay OTLP. Konfigurasikan semua itu melalui upstreams, models, dan forward_to di bagian telemetry.
• Alias lama dari kunci saat ini. Dalam error boot, gateway menyebutkan kunci kanonis yang harus ditulis.

Jika Anda menggunakan nilai atau bentuk entri yang sudah deprecated, seperti entri managedMcpServers tanpa transport, gateway tetap mulai dan mencatat peringatan yang menyebutkan penggantinya.

Sebelum v2.1.232, gateway menerima daftar tetap berisi 11 kunci feature-gate, seperti chatTabEnabled dan disableAutoUpdates, dan menolak setiap kunci lain saat boot. Sebelum v2.1.227, gateway juga menolak chatTabEnabled dan chatAdvancedFileAnalysisEnabled saat boot.

Kunci yang memerlukan versi gateway atau Claude Desktop yang lebih baru

Gateway memvalidasi blok desktop terhadap skema yang dibundel dengan versi terpasangnya, seperti halnya blok cli. Untuk mengirim pengaturan yang diperkenalkan oleh rilis Claude Desktop yang lebih baru, tingkatkan gateway terlebih dahulu. Misalnya, userPluginMarketplacesEnabled dan userPluginUploadsEnabled memerlukan Claude Code v2.1.260 atau yang lebih baru di server gateway dan Claude Desktop 1.37937.0 atau yang lebih baru di mesin anggota.

blockReadsOutsideWorkingDirectories, disableBypassPermissionsMode, configRecheckIntervalMinutes, dan sshClientPath memerlukan Claude Code v2.1.281 atau yang lebih baru di server gateway. Begitu pula nilai required dari microsoftAuthBroker dan bidang continuousAccessEvaluation dari entri managedMcpServers Microsoft 365. Rilis Claude Desktop yang lebih lama dari nilai required membacanya sebagai disabled, jadi setel required hanya setelah Claude Desktop setiap anggota mendukungnya. Referensi konfigurasi terkelola Claude Desktop mencantumkan rilis yang pertama kali membaca setiap kunci.

[!NOTE]

sshTransport memerlukan Claude Code v2.1.293 atau yang lebih baru di server gateway.

Jika Anda menyetel orgPluginSettings di blok desktop kebijakan, gateway melayaninya dalam bentuk array yang dibaca Claude Desktop 1.15200.0 dan yang lebih baru. Desktop yang lebih lama mengabaikan array tersebut dan tidak menegakkan kebijakan tool plugin, jadi perbarui anggota ke 1.15200.0 atau yang lebih baru sebelum Anda mengandalkannya.

Cara kebijakan peran mewarisi blok desktop dasar

Gateway mengisi kunci yang tidak disetel oleh blok desktop suatu kebijakan dari blok desktop catch-all match: {}, dengan cara yang sama seperti mengisi blok cli kebijakan dari dasar. Jika Anda menyetel disabledBuiltinTools atau builtinToolPolicy di dasar dan di kebijakan peran, gateway mempertahankan pembatasan dasar:

• disabledBuiltinTools: gateway menggunakan gabungan daftar dasar dan daftar kebijakan
• builtinToolPolicy: jika Anda menyetel suatu tool ke nilai selain allow di dasar, gateway mempertahankan nilai tersebut meskipun Anda menyetel allow untuk tool yang sama di kebijakan peran

Untuk setiap kunci lain, jika Anda menyetelnya di kebijakan peran, gateway menggunakan nilai kebijakan peran. Gateway menggantikan array atau objek bersarang seperti banner secara utuh, sehingga jika Anda menyetel banner.text di kebijakan peran, gateway membuang banner.backgroundColor dari dasar.

Kapan perubahan kebijakan mencapai Claude Desktop

Setelah Anda men-deploy ulang gateway dengan kebijakan yang diubah, Claude Desktop menerapkan sebagian besar pengaturan hanya saat dimulai berikutnya:

• Tertutup: Claude Desktop mengambil respons bootstrap saat dimulai, sehingga perubahan berlaku sejak dimulai berikutnya
• Terbuka: Claude Desktop memeriksa respons yang berubah setiap 10 menit secara default dan menerapkan beberapa pengaturan tanpa restart. Untuk sisanya, seperti skillCreationEnabled, pengguna melihat kartu Relaunch Claude Desktop di sidebar dan mempertahankan konfigurasi sebelumnya hingga mereka memulai ulang aplikasi. Setelah 24 jam secara default, Claude Desktop menampilkan dialog restart dan memulai ulang dengan sendirinya setelah 2 menit tidak ada aktivitas

Untuk mempersingkat 24 jam tersebut, setel relaunchEnforcementHours di blok desktop kebijakan. Anda memerlukan Claude Code v2.1.260 atau yang lebih baru di server gateway dan Claude Desktop 1.40609.0 atau yang lebih baru di mesin anggota. Dengan 0, dialog muncul segera setelah Claude Desktop menemukan perubahan.

Konteks diperluas di Claude Desktop

Jika Anda melayani Claude Desktop dari gateway, pemilih modelnya menawarkan opsi konteks 1M untuk setiap model tercantum yang dapat berjalan dengan context window 1M. Ini termasuk Claude Opus 4.6 dan yang lebih baru, Claude Sonnet 4.6 dan yang lebih baru, serta model Fable. Opsi tersebut adalah varian [1m] model, yang dijelaskan di Konteks diperluas. Anda memerlukan Claude Code v2.1.284 atau yang lebih baru di server gateway.

Entri models tidak mendapatkan opsi 1M jika:

• Upstream yang dapat melayani entri memetakannya ke model tanpa dukungan 1M, termasuk upstream yang dijangkau gateway hanya saat failover
• Baik id-nya maupun nilai upstream_model-nya tidak ada yang menyebut model Claude, seperti alias kustom yang dirutekan ke ARN application inference profile

Untuk mengubah apa yang ditawarkan pemilih, gunakan salah satu dari cara berikut:

• Memulai pengguna pada opsi 1M: setel modelPrefer1mContext: true di blok desktop kebijakan. Pengguna yang belum memilih model mulai pada opsi 1M jika model pertama yang tercantum memilikinya. Pengguna yang sudah memilih model mempertahankan pilihannya.
• Menawarkan opsi secara manual: lakukan ini jika server gateway Anda menjalankan versi yang lebih lama dari v2.1.284, atau suatu entri tidak menyebut model Claude. Cantumkan model dua kali di 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 melayani entri [1m] tanpa memeriksanya, jadi tambahkan entri tersebut hanya untuk model yang dilayani upstream Anda pada 1M.

Contoh ini menawarkan opsi secara manual untuk alias kustom yang dirutekan ke application inference profile, dan memulai pengguna baru pada opsi tersebut:

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

Menghapus opsi 1M

Untuk menghapus opsi dari pemilih, setel CLAUDE_CODE_DISABLE_1M_CONTEXT: "1" di blok env di bawah kunci cli kebijakan. Jika Anda juga mencantumkan entri yang id-nya diakhiri [1m], gateway tetap melayaninya, jadi hapus juga entri tersebut.

Variabel ini juga menjangkau sesi terminal developer yang cocok dengan kebijakan. Untuk apa yang diubahnya di sana, lihat Konteks diperluas.

Prioritas dengan sumber terkelola lainnya

Jika perangkat juga memiliki kebijakan yang dikirim MDM atau managed-settings.json lokal, pengaturan yang dikirim gateway berada di peringkat pertama. Prioritas dalam tingkat terkelola di halaman pengaturan terkelola menjelaskan kapan sumber lokal berlaku, dan memuat kunci yang dibaca Claude Code dari setiap sumber admin terlepas dari sumber mana yang dipilihnya, seperti kunci penguncian sandbox, forceRemoteSettingsRefresh, dan penggabungan env per variabel. policyHelper yang dikonfigurasi di profil MDM atau file pengaturan terkelola hanya berjalan jika gateway tidak mengirim pengaturan; entri tersebut menjelaskan apa yang digantikan oleh output-nya.

Host penyemat seperti Claude Desktop dapat menyediakan kebijakan melalui opsi SDK managedSettings. Pengaturan induk dari host penyemat menjelaskan kapan Claude Code menerapkannya, dan Membatasi pengaturan induk mencantumkan pengaturan berarah izin (allow) mana yang tetap berlaku tanpa kunci allowManaged*Only.

Kebijakan gateway berlaku untuk setiap pemanggilan Claude Code di mesin, termasuk eksekusi claude -p non-interaktif dan sesi yang dibuat oleh Agent SDK. Jika gateway tidak dapat dijangkau saat startup, sesi yang sudah masuk keluar dengan error alih-alih berjalan tanpa kebijakannya.

telemetry

CLI mengirim metrik, log, dan, jika diaktifkan, trace ke gateway, yang meneruskannya apa adanya ke setiap tujuan yang dikonfigurasi. Ekspor menggunakan OpenTelemetry Protocol (OTLP) melalui HTTP. Untuk melewati relay dan membuat sesi mengekspor langsung ke collector Anda, sebutkan collector dalam kebijakan. Lihat Memantau penggunaan untuk metrik dan event yang dipancarkan CLI.

Dalam sesi yang masuk melalui /login, CLI membubuhkan identitas pengguna terautentikasi pada setiap ekspor, yang dibaca dari JWT yang diterbitkan gateway: atribut user.id, user.email, dan user.groups. Karena itu atribusi biaya dan penggunaan per developer berfungsi tanpa konfigurasi di sisi developer. Event yang dicatat Claude Code sebelum developer masuk tidak membawa identitas ini. Untuk melihat atribut mana yang mengikuti perubahan grup developer, lihat Perubahan grup selama sesi terbuka.

Sesi Claude Desktop dan Cowork yang masuk melalui gateway membubuhkan user.email dan user.groups pada telemetrinya bersama enduser.id, sehingga Anda dapat mencakup penggunaan terminal, Desktop, dan Cowork dengan satu kueri pada user.email atau user.groups. user.groups adalah daftar grup IdP yang dipisahkan koma.

Telemetri Desktop dan Cowork juga membawa enduser.sub, klaim sub yang diterbitkan penyedia identitas Anda untuk pengguna, yang tetap sama ketika email pengguna berubah. Sesi terminal membubuhkan nilai yang sama di bawah user.id, sehingga kueri yang mencocokkan enduser.sub dengan user.id terminal mencakup penggunaan terminal, Desktop, dan Cowork satu pengguna sekaligus. Pada ekspor Desktop dan Cowork, user.id adalah pengidentifikasi anonim, bukan subjek.

Seperti semua data OpenTelemetry dari Claude Code, atribut ini hanya dikirim ke tujuan yang dikonfigurasi organisasi Anda, tidak pernah ke Anthropic.

Jika daftar grup pengguna lebih panjang dari 255 karakter setelah percent-encoding, atau nama grup berisi koma atau tanda sama dengan, gateway tidak menyertakan user.groups pada telemetri Desktop dan Cowork pengguna tersebut alih-alih memotongnya. Sesi terminal pengguna tersebut tetap membawa daftar lengkap.

Gateway tidak menyertakan enduser.sub jika subjek lebih panjang dari 255 karakter setelah percent-encoding, atau berisi spasi, karakter di luar ASCII yang dapat dicetak, atau salah satu dari , ; = \ " %. Telemetri Desktop dan Cowork pengguna tersebut mempertahankan atribut lainnya.

Anda memerlukan Claude Code v2.1.265 atau yang lebih baru di server gateway untuk user.email dan user.groups pada telemetri Desktop dan Cowork, dan Claude Desktop 1.24012 atau yang lebih baru di mesin setiap developer untuk user.groups.

Anda memerlukan Claude Code v2.1.274 atau yang lebih baru di server gateway untuk enduser.sub.

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}

[!WARNING]

Setiap tujuan memilih metrics, logs, dan traces secara independen, dan default-nya hanya metrik. Sinyal-sinyal ini berbeda dalam tingkat sensitivitasnya:

• Metrik: penghitung agregat seperti jumlah token, jumlah permintaan, dan latensi
• Log dan trace: dapat membawa perintah Bash lengkap, input tool, dan path file, mencakup apa pun yang dilakukan Claude Code di mesin developer

Aktifkan log dan trace hanya pada tujuan dengan kontrol akses dan kebijakan retensi yang sesuai untuk data tersebut.

Setiap URL forward_to harus menggunakan https://, dengan satu pengecualian untuk collector di antarmuka loopback gateway itu sendiri:

• http://localhost:<port> lolos validasi konfigurasi, tetapi penjaga SSRF memblokir setiap ekspor dengan ECONNREFUSED_SSRF kecuali Anda menyetel CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 di environment gateway
• http://127.0.0.1:<port> atau http://[::1]:<port> menggagalkan boot kecuali variabel tersebut disetel

Untuk collector di dalam cluster, ekspos collector melalui HTTPS di alamat internalnya sendiri, atau jalankan sebagai sidecar dengan variabel tersebut disetel.

Jika HTTPS_PROXY disetel, gateway mengirim ekspor melalui proxy tersebut.

Untuk menjangkau collector internal secara langsung, tambahkan collector ke NO_PROXY berdasarkan hostname atau berdasarkan domain dengan titik di awal seperti .internal.example.com, yang memerlukan Claude Code v2.1.277 atau yang lebih baru di server gateway. Pastikan gateway dapat menjangkau collector tanpa proxy. Entri tanpa titik di awal hanya cocok dengan nama persis tersebut, bukan nama di bawahnya. Rentang CIDR tidak dicocokkan.

Dengan egress khusus proxy diaktifkan, izinkan collector di proxy sebagai gantinya, karena entri NO_PROXY apa pun membuat egress khusus proxy tetap nonaktif.

Telemetri dimatikan di CLI secara default. Saat Anda menyetel telemetry.forward_to dan listen.public_url, gateway mengaktifkannya untuk klien yang terhubung dengan mengirim enam environment variable melalui /managed/settings:

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

Saat Anda menambahkan label sendiri, gateway juga mengirim OTEL_RESOURCE_ATTRIBUTES.

Sebelum Claude Code v2.1.265 di server gateway, gateway mengirim ketiga pemilih exporter sebagai otlp, termasuk untuk sinyal yang tidak dipilih oleh tujuan mana pun.

Endpoint yang dikirim dibangun dari URL publik, sehingga metrik dan log tidak memerlukan konfigurasi OTEL dari developer atau kebijakan.

Developer yang masuk melalui /login tidak dapat mengalihkan ekspor dengan konfigurasi OTEL mereka sendiri:

• Variabel yang disetel secara lokal: Claude Code menerapkan variabel yang dikirim pada tingkat terkelola, sehingga masing-masing menimpa nilai yang disetel developer secara lokal.
• Endpoint yang dikonfigurasi secara lokal: dengan ekspor OTLP/HTTP diaktifkan, CLI mengabaikan endpoint apa pun yang dikonfigurasi secara lokal, baik gateway mengirim variabel telemetri maupun tidak. Ekspornya dikirim ke gateway kecuali kebijakan menyebut collector Anda sebagai endpoint.

Tanpa tujuan forward_to untuk suatu sinyal, gateway menerima lalu membuangnya. Jika developer sudah mengekspor telemetri Claude Code ke salah satu collector Anda, tambahkan collector itu sebagai tujuan forward_to, dengan log atau trace diaktifkan jika mereka mengekspornya, agar collector tetap menerima data mereka setelah mereka masuk. Untuk melewati relay, sebutkan collector dalam kebijakan.

Trace juga memerlukan CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 di setiap klien. Setel variabel ini di blok env kebijakan terkelola, karena gateway tidak mengirimnya. Developer menyetujuinya dalam dialog persetujuan keamanan yang sama yang sudah dipicu oleh endpoint yang dikirim.

Setel ke 1 hanya di kebijakan yang grupnya ingin Anda lacak. Kebijakan yang tidak menyetelnya mewarisi nilai dari kebijakan catch-all match: {} Anda jika kebijakan tersebut menyetelnya, sesuai aturan penggabungan. Agar klien suatu grup tidak mengirim trace bahkan saat developer menyetel variabel secara lokal, setel ke 0 di kebijakan grup tersebut.

Encoding OTLP protobuf dan JSON sama-sama diteruskan, dan backend apa pun yang kompatibel dengan OpenTelemetry dapat berfungsi sebagai tujuan.

Mengirim metrik kumulatif

Jika collector Anda hanya menerima metrik kumulatif, setel OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE ke cumulative. Claude Code mengirim metrik delta secara default, dan gateway meneruskannya tanpa mengonversinya. Setel variabel di tempat setiap jenis sesi membacanya:

• Sesi terminal: di blok env di bawah kunci cli atau code kebijakan
• Sesi Cowork yang berjalan di mesin pengguna: di blok env dari pengaturan terkelola sisi klien di mesin tersebut
• Sesi tab Code di bawah kebijakan code: di blok env kebijakan, setelah Anda memenuhi kondisi agar pengaturan code berlaku
• Sesi tab Code di bawah kebijakan cli: di blok env dari pengaturan terkelola sisi klien di mesin yang menjalankan sesi. Melalui SSH, itu adalah host jarak jauh.

Jika Anda menambahkan variabel ke pengaturan terkelola suatu mesin, setel juga parentSettingsBehavior: "merge" di sumber dengan prioritas tertinggi di mesin tersebut. Tanpanya, sesi Cowork dan sesi tab Code di bawah kebijakan cli berjalan tanpa allowlist egress dan kebijakan lain yang diteruskan Claude Desktop kepada sesi tersebut sebagai pengaturan induk.

Menambahkan label sendiri

Untuk memasang label tetap seperti service.namespace atau deployment.environment.name pada telemetri sesi yang masuk melalui gateway, setel telemetry.resource_attributes. Setiap label adalah atribut resource OpenTelemetry, dan setiap tujuan menerima label yang sama.

Sesi hanya mendapatkan label jika Anda juga menyetel telemetry.forward_to dan listen.public_url. Contoh ini menambahkan dua label:

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

Gateway menolak untuk mulai jika suatu label melanggar salah satu aturan berikut, dan error startup menyebutkan label tersebut:

• Nama hanya menggunakan huruf, angka, ., _, dan -
• Nama tidak dicadangkan. Dibandingkan tanpa memedulikan huruf besar-kecil, nama yang dicadangkan adalah semua yang diawali user., enduser., atau identity., ditambah service.name, service.version, claude.deployment_mode, host.arch, os.type, os.version, dan wsl.version
• Nilai berupa ASCII yang dapat dicetak dan tidak kosong, tanpa spasi dan tanpa , ; = \ " %
• Nilai paling banyak 255 karakter sebagaimana dihitung gateway setelah percent-encoding, sehingga /, :, dan @ masing-masing dihitung sebagai tiga
• Nilai berupa teks, jadi beri tanda kutip pada angka, true, atau false

Anda memerlukan Claude Code v2.1.281 atau yang lebih baru di server gateway untuk menyetel telemetry.resource_attributes. Gateway yang lebih lama menolak untuk mulai saat menemukan kunci tersebut. Tingkatkan setiap replika sebelum Anda menambahkan kunci, dan hapus kunci sebelum Anda melakukan rollback ke versi sebelumnya.

Sesi terminal yang masuk melalui /login menerima label sebagai OTEL_RESOURCE_ATTRIBUTES, yang dikirim bersama variabel telemetri lainnya. Jika Anda menyetel OTEL_RESOURCE_ATTRIBUTES di blok env kebijakan, sesi terminal yang cocok dengan kebijakan tersebut mendapatkan nilai itu alih-alih label. Claude Desktop menerima label dari gateway bersama user.email dan atribut identitas lainnya.

Claude Code juga menyalin setiap label ke setiap titik data metrik, sehingga Anda dapat memfilter metrik berdasarkan label tersebut di backend yang tidak mengindeks atribut resource. Untuk mematikan salinan tersebut, lihat Kontrol kardinalitas metrik.

Perubahan grup selama sesi terbuka

Sesi terminal menempatkan user.groups pada resource OTLP dan juga pada setiap titik data metrik dan event. Jika grup developer berubah saat sesi terbuka, titik data dan event untuk penggunaan setelah refresh senyap berikutnya membawa grup baru. Resource mempertahankan grup lama hingga developer memulai ulang Claude Code, jadi kelompokkan berdasarkan atribut pada titik data atau event.

Jika Anda mengaktifkan resource_to_telemetry_conversion di exporter Prometheus remote write pada OpenTelemetry Collector, exporter menggantikan user.groups setiap titik data dengan milik resource, sehingga setiap titik data menampilkan grup lama. Untuk mempertahankan nilai titik data, hapus user.groups dari resource sebelum exporter tersebut.

Processor resource OpenTelemetry Collector ini menghapus atribut tersebut di pipeline yang mencantumkannya:

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

Setelah Anda menambahkan resource/drop-user-groups ke processors pipeline metrik, setiap seri membawa label user_groups dari titik data miliknya sendiri.

Ekspor langsung ke collector Anda

Agar sesi yang masuk melalui /login mengirim telemetri langsung ke collector Anda alih-alih melalui relay, atur OTEL_EXPORTER_OTLP_ENDPOINT ke URL dasar https:// milik collector di blok env dari kebijakan terkelola. Claude Code menambahkan /v1/metrics, /v1/logs, atau /v1/traces ke URL yang Anda atur, seperti https://otel-collector.example.com:4318, dan mengekspor setiap sinyal ke sana melalui OTLP/HTTP. Memerlukan Claude Code v2.1.265 atau yang lebih baru di mesin setiap pengembang. Klien yang lebih lama mengekspor melalui relay.

Untuk mengautentikasi ke collector, atur OTEL_EXPORTER_OTLP_HEADERS di blok env yang sama. Sesi tidak pernah mengirim token sesi gateway milik pengembang ke collector yang ditentukan dengan cara ini.

Saat Anda menambahkan atau mengubah endpoint ini dalam kebijakan, Claude Code meminta setiap pengembang untuk menyetujuinya di dialog persetujuan keamanan sebelum menerapkannya dalam sesi interaktif.

Claude Code memeriksa endpoint sebelum mengekspor sinyal secara langsung, dan mempertahankan sinyal tersebut di relay ketika pemeriksaan gagal. Pemeriksaan tersebut meliputi:

• Endpoint berasal dari gateway itu sendiri. Jika Anda mengatur variabel yang sama di profil MDM atau managed-settings.json lokal, ekspor tetap melalui relay.
• URL menggunakan https://, atau http:// ke alamat loopback
• URL mengarah ke path yang berakhiran /v1/<signal>, tanpa query atau fragment. Claude Code membangun path tersebut sendiri dari variabel generik. Variabel per sinyal seperti OTEL_EXPORTER_OTLP_METRICS_ENDPOINT digunakan apa adanya, jadi sertakan path lengkap di sana.
• URL bukan host milik gateway itu sendiri. Endpoint yang ditujukan ke gateway tetap menggunakan jalur relay beserta token sesinya.
• Baik Anda maupun pengembang tidak mengonfigurasi otelHeadersHelper di sumber pengaturan mana pun. Jika helper dikonfigurasi, setiap sinyal tetap melalui relay.

Endpoint yang Anda tentukan hanya mengubah ke mana ekspor dikirim. Anda tetap memilih sinyal mana yang diekspor sama sekali dengan selektor OTEL_*_EXPORTER.

Endpoint saja tidak mengaktifkan ekspor, jadi atur juga variabel yang mengaktifkannya, kecuali gateway sudah mendorongnya:

• Jika gateway sudah mendorong variabel telemetri, variabel tersebut mencakup pengaktifan, selektor, dan protokol, dan endpoint eksplisit Anda menimpa nilai <public_url> yang didorong. Atur sendiri selektor OTEL_*_EXPORTER ke otlp hanya untuk sinyal yang tidak diaktifkan oleh tujuan forward_to mana pun.
• Jika tidak, atur juga CLAUDE_CODE_ENABLE_TELEMETRY=1, selektor OTEL_*_EXPORTER, dan OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf.

Saat pengembang keluar, atau masuk ke gateway yang berbeda, ekspor ke collector berhenti dan Claude Code membuang setiap batch yang tersisa alih-alih mengirimkannya.

Saat tujuan gagal

Gateway tidak melakukan buffer, retry, atau menyimpan telemetri, sehingga gateway membuang ekspor yang tidak mencapai tujuan alih-alih mengirimkannya terlambat. Setiap tujuan berhasil atau gagal secara terpisah, dan klien yang mengekspor menerima respons sukses dalam kedua kasus, sehingga pengiriman yang gagal hanya muncul di log gateway.

Setelah lima kali pengiriman gagal berturut-turut ke suatu tujuan, gateway menjeda penerusan ke tujuan tersebut dalam rentang 30 detik, mencatat setiap jeda ke log, hingga pengiriman berhasil. Setiap respons error, timeout, atau error koneksi dihitung sebagai pengiriman yang gagal, kecuali 400, 413, 415, 422, dan 431, yang berarti collector menolak payload ekspor tersebut karena formatnya salah atau terlalu besar.

Payload yang ditolak tidak menambah maupun mereset hitungan kegagalan: gateway tetap meneruskan ke tujuan tersebut dan mencatat peringatan ke log yang menyebutkan tujuan dan statusnya, pada penolakan pertama dari tujuan tersebut dan setiap penolakan keseratus sesudahnya.

Penyetelan HTTP

Empat blok tingkat atas opsional, access_control, limits, timeouts, dan rate_limits, menyesuaikan surface HTTP. Nilai default cocok untuk sebagian besar deployment.

Jika Anda membiarkan kedua daftar access_control kosong, yang merupakan default, gateway melayani alamat klien mana pun, sehingga hanya jaringan Anda yang membatasi siapa yang dapat menjangkaunya. Hal itu penting karena gateway dapat mendorong pengaturan terkelola yang menjalankan perintah di mesin pengembang.

Selama allow_cidrs kosong, gateway memberi peringatan di dua tempat, tanpa mengubah cara gateway menjawab permintaan apa pun:

• Saat boot: peringatan di log operasional merekomendasikan untuk hanya mengizinkan rentang privat 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 lain tempat pengembang Anda terhubung. Jika Anda mengikat gateway ke alamat loopback dan tidak mengatur trusted_proxies maupun public_url, seperti dalam pengembangan lokal, peringatan tersebut tidak muncul.
• Saat runtime: pertama kali permintaan tiba dari alamat di luar rentang privat tersebut, gateway mencatat peringatan ke log dan memancarkan audit event access.public_client yang membawa IP klien. Keduanya hanya terpicu sekali per proses. Alamat link-local, 169.254.0.0/16 dan fe80::/10, tidak dihitung sebagai publik. Gateway menjawab /healthz dan /readyz sebelum pemeriksaan ini berjalan, sehingga probe kesehatan dari rentang publik tidak memicunya.

Kedua sinyal menggunakan alamat klien sebagaimana di-resolve oleh gateway. Jika load balancer, port-forward, atau tunnel meneruskan lalu lintas dan tidak tercantum di listen.trusted_proxies, gateway melihat alamat relay tersebut, yang biasanya privat, sehingga baik peringatan runtime maupun daftar izin privat tidak menangkap lalu lintas yang diteruskan melaluinya.

Jika relay tersebut semestinya berada di listen.trusted_proxies, cantumkan di sana. Bagaimanapun juga, pastikan gateway dan semua yang berada di depannya tidak dapat dijangkau dari internet publik.

load_test_mode

Blok load_test_mode memungkinkan Anda melakukan uji beban pada gateway tanpa memanggil penyedia model. Selama mode ini aktif, gateway membangun dan menandatangani setiap permintaan penyedia seperti biasa, membuangnya alih-alih mengirimkannya, dan men-stream balasan siap pakai kembali melalui jalur respons normalnya. Balasan tersebut berupa teks pengisi yang diawali dengan kalimat yang menyatakan bahwa balasan itu adalah balasan siap pakai.

Memerlukan Claude Code v2.1.282 atau yang lebih baru di server gateway. Gateway yang lebih lama menolak untuk dijalankan saat menemukan kunci tersebut. Tingkatkan setiap replika sebelum Anda menambahkan blok ini, dan hapus blok ini sebelum Anda melakukan rollback.

Contoh di bawah ini mengaktifkan mode dengan nilai default, yaitu balasan berisi kira-kira 750 token teks yang di-stream selama sekitar 10 detik:

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

Load test dalam mode ini mencakup gateway, Postgres Anda, dan semua yang berada di depan gateway. Load test ini tidak mencakup batas, kecepatan, dan jalur jaringan provider, atau waktu tunggu pada batas permintaan upstream bersamaan setiap replika. Replika tetap mencatat peringatan client requests are open ketika jumlah permintaan terbuka melebihi batas tersebut, yaitu titik di mana permintaan produksi mulai menunggu.

Tidak ada permintaan model yang dikirim ke penyedia, sehingga CPU per permintaan pada replika hanyalah perkiraan dan terbaca lebih rendah daripada di produksi, yang juga mengenkripsi lalu lintasnya ke penyedia. Konfirmasikan jumlah replika dengan pilot kecil terhadap penyedia sebenarnya. Sebelum v2.1.283, perkiraan tersebut terbaca jauh lebih rendah.

Selama mode aktif, permintaan dapat membawa header x-load-test-user yang berisi bilangan bulat hingga tujuh digit. Gateway menghitung setiap angka sebagai pengembang terpisah, dengan email dan grup milik pengembang yang tokennya disertakan bersama permintaan.

Berikan deployment uji beban database kosongnya sendiri, karena gateway menolak untuk dijalankan dengan mode aktif terhadap database yang di dalamnya ada pengembang yang sudah menghabiskan biaya apa pun.

[!WARNING]

Jangan pernah mengaktifkan ini untuk gateway yang digunakan oleh pengembang. Setiap permintaan mendapat balasan siap pakai dan tidak ada model yang dipanggil. Gateway mencatat peringatan load_test_mode is on ke log saat boot dan menandai setiap audit event inference dengan load_test: true selama mode aktif.

Contoh lengkap

Config reference penuh ini menggunakan setiap core section; HTTP tuning blocks menyimpan defaults mereka. Salin, hapus apa yang Anda tidak butuhkan, dan isi values Anda. Config dalam Quickstart adalah minimal version dari ini.

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

Pengaturan terkelola sisi klien

Semua hal di atas mengonfigurasi server gateway. Anda mengarahkan mesin pengembang ke gateway secara terpisah, di setiap perangkat, melalui pengaturan terkelola Claude Code. Gateway tidak dapat mendorong kunci login itu sendiri, karena kunci itulah yang memberi tahu klien di mana gateway berada.

Untuk CLI, atur kunci-kunci ini dalam managed-settings.json per OS. Dua kunci login merutekan /login setiap pengembang ke gateway Anda:

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

parentSettingsBehavior: "merge" menjaga pengiriman allowlist egress oleh Claude Desktop ke sesi Claude Code yang tertanam di dalamnya tetap berfungsi; Kirimkan kebijakan ke sesi Claude Desktop menjelaskan mekanismenya dan di mana opt-in harus berada.

Untuk mencegah pengembang melewati gateway dengan variabel penyedia cloud atau ANTHROPIC_BASE_URL milik mereka sendiri, tambahkan "allowedProviders": ["gateway"] ke file yang sama. Claude Code kemudian menolak setiap sesi di mesin itu yang tidak disiapkan untuk Cloud gateway, dan hanya menerima gateway yang disebutkan oleh forceLoginGatewayUrl atau gateway yang URL-nya ditetapkan blok env file tersebut sebagai ANTHROPIC_BASE_URL. claude gateway menolak berjalan di mesin yang menetapkan daftar ini, jadi jangan atur kunci ini di host gateway. Lihat entri allowedProviders dalam referensi pengaturan. Memerlukan Claude Code v2.1.285 atau lebih baru.

Deploy file managed-settings.json ke setiap perangkat, biasanya melalui platform MDM Anda. Jalur file berbeda menurut platform. Lihat di mana setiap mekanisme menyimpan kebijakan.

Secara default, kebijakan registri di Windows atau plist managed-preferences di macOS menggantikan file managed-settings.json alih-alih digabungkan dengannya, kecuali untuk kunci pengecualian dan pemeriksaan lintas sumber di atas. Ketiga kunci dalam cuplikan ini mengikuti aturan sumber berprioritas tertinggi, jadi armada yang mengirimkan kebijakan melalui Group Policy atau profil konfigurasi harus menempatkan ketiganya dalam mekanisme itu sebagai gantinya.

Untuk Claude Desktop, atur kunci bootstrapUrl dalam konfigurasi terkelola milik Claude Desktop sendiri ke <listen.public_url>/user/bootstrap. Alur sign-in dan kebijakan per grup kemudian sama dengan milik CLI setelah sebuah kebijakan melakukan opt-in di sisi server dengan kunci desktop; tanpa opt-in itu, /user/bootstrap mengembalikan 404. Lihat Overlay Claude Desktop untuk bagian sisi servernya.

Claude Code menghormati forceLoginGatewayUrl, gatewayInternalNetworks, dan nilai "gateway" dari forceLoginMethod dari sumber terkelola di mesin: managed-settings.json, plist macOS atau registri HKLM Windows, atau pembantu kebijakan. Menetapkannya dalam payload gateway tidak mengonfigurasi sign-in gateway. Untuk ~/.claude/settings.json milik pengembang sendiri, lihat Atur URL gateway dalam pengaturan pengguna.

Jangan sertakan forceLoginMethod dan forceLoginOrgUUID dalam payload. Claude Code tetap membaca kedua kunci itu dari payload untuk pemeriksaan kredensial saat startup, jadi bagi pengembang yang menyimpan kredensial yang diterbitkan Anthropic di mesin, Claude Code keluar saat startup seperti dijelaskan di bawah Administrator policy requires a Cloud gateway sign-in bahkan setelah mereka masuk.

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