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:

• 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 tulis secrets seperti client_secret, jwt_secret, atau postgres_url langsung di gateway.yaml. Referensikan mereka dengan salah satu bentuk di bawah, dan gateway menyelesaikan nilai 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.

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 dapat me-resolve model yang diminta.

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. Ketika tidak ada yang mengembalikan 429, gateway mengutamakan, secara berurutan, 401 atau 403 terakhir, 404 terakhir, dan 501 terakhir. Ketika tidak ada yang mengembalikan salah satu dari itu, 502 milik gateway sendiri, all upstreams failed (N attempted), di mana N menghitung setiap entri di upstreams, termasuk entri yang dilewati gateway karena tidak melayani model yang diminta.

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

[!WARNING]

Gateway tidak mendukung input tag guardrail. Gateway tidak menambahkan guard content tag ke prompt, sehingga filter guardrail yang diterapkan Amazon Bedrock hanya pada input yang diberi tag tidak berjalan pada lalu lintas melalui gateway. Untuk filter mana yang bergantung pada input tag, lihat input tags dalam dokumentasi Amazon Bedrock.

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.

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 hanya berlaku untuk provider: bedrock dan memerlukan kredensial sumber SigV4: gateway menolak untuk dimulai ketika diatur bersama aws_bearer_token.
• Setiap developer yang diterima gateway dapat menggunakan upstream ini; managed mengatur developer mana yang boleh menggunakan model mana. Agar model yang dilayani melalui role ini tidak juga dilayani dari akun lain, berikan model tersebut id kustom yang map 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 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: claude-opus-restricted          # a custom id, not a built-in model name
    upstream_model:
      bedrock-isolated: us.anthropic.claude-opus-4-8   # the only upstream that serves it

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: upstream mantle tidak menerima assume_role. Permintaan yang dilayani Mantle dikirim dengan kredensial auth milik upstream mantle sendiri, dan tidak diatribusikan per developer.

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.

Setiap permintaan dimulai dari upstream pertama. Sebuah permintaan mencapai upstream berikutnya hanya ketika setiap upstream sebelumnya telah gagal atau tidak melayani model yang diminta.

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

Untuk upstream Anthropic API, timeouts.upstream_ttfb_ms membatasi waktu tunggu pada upstream yang mati. Pengaturan tersebut tidak berlaku untuk penyedia lain, di mana gateway menunggu hingga satu jam agar upstream mulai merespons.

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.

Bagian opsional

admin

Opsional. Mengaktifkan /v1/organizations/spend_limits, yang mencerminkan Admin API publik Anthropic, dan penegakan pengeluaran per-pengembang di /v1/messages. Lihat Batas pengeluaran untuk cara batas ditetapkan dan diterapkan; bagian ini mencakup kunci gateway.yaml yang mengaktifkan fitur dan menyetelnya.

admin:
  # Named static API keys for the admin endpoints, sent as x-api-key.
  # The id appears in the audit log as admin-key:<id> so each key is
  # attributable. Array for rotation: add the new key, roll clients,
  # remove the old.
  write_keys:
    - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
    - { id: ci,        key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
  read_keys:
    - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
  # IdP groups granted full admin via the normal gateway JWT (no API key).
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits

enforcement

Blok enforcement mengontrol bagaimana pemeriksaan batas pengeluaran berperilaku ketika penyimpanan tidak tersedia.

pricing

Blok pricing memberi tahu meter pengeluaran apa yang harus dikenakan alih-alih harga daftar USD, sehingga batas dan /effective mencerminkan tarif kontrak Anda. Jumlah tetap dalam USD dan tetap merupakan perkiraan, bukan faktur. Dua prasyarat:

• Claude Code v2.1.227 atau lebih baru di server gateway. Versi sebelumnya menolak kunci yang tidak dikenal saat boot.
• Blok admin: atau, di v2.1.268 atau lebih baru, blok managed: dengan setidaknya satu kebijakan. Gateway menolak untuk memulai dengan pricing diatur dan tidak ada blok, karena tidak ada yang akan membacanya.

pricing:
  multiplier: 0.85
  overrides:
    - upstream: bedrock-eu
      model: claude-sonnet-4-6
      input: 3.30
      output: 16.50
      cache_read: 0.33
      cache_write: 4.125

Bagaimana meter mencocokkan baris override:

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

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

Tandai harga naik

Dengan v2.1.271 atau lebih baru di server gateway, Anda dapat menetapkan 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 pengembang mencapai batas mereka lebih cepat. Gateway mencatat peringatan saat boot yang mengatakan demikian.

Pengali tidak mengubah apa yang dikenakan penyedia upstream untuk permintaan.

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

Server gateway sebelumnya dari v2.1.271 menolak untuk memulai jika Anda menetapkan multiplier di atas 1.

Kirim tarif ke klien yang masuk

Dengan v2.1.268 atau lebih baru di server gateway, gateway juga menempatkan tarif dari pricing ke dalam kebijakan managed yang disajikannya, sebagai pengaturan terkelola modelPricing. Pengembang yang cocok dengan kebijakan kemudian melihat tarif pricing untuk upstream pertama yang melayani setiap ID model di /usage, baris status, dan OpenTelemetry. Pengembang yang tidak cocok dengan kebijakan apa pun tidak menerima pengaturan terkelola, sehingga angka mereka tetap pada harga daftar. Klien menerapkan pengaturan di Claude Code v2.1.242 atau lebih baru.

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

models

Blok models adalah daftar model yang dikurasi admin opsional, disajikan di /v1/models dan digunakan untuk menerjemahkan ID model per upstream. Diperlukan untuk region Amazon Bedrock non-AS, ARN throughput-provisioned 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 default ke nama penyedia. Kunci yang tidak cocok dengan upstream apa pun gagal boot, jadi abaikan 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; kecocokan pertama dipilih, kemudian digabungkan ke basis catch-all match: {}. Mereka disajikan 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: {}, secara konvensional terdaftar terakhir, diperlakukan sebagai lapisan dasar. Setiap kebijakan lain mewarisi kunci apa pun yang tidak ditetapkannya dari catch-all, sehingga entri per-peran hanya perlu mencantumkan apa yang berbeda dari default org. Aturan penggabungan tergantung pada jenis kunci:

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

availableModels juga diterapkan server-side di /v1/messages, jadi model yang ditolak mengembalikan 400 terlepas dari apa yang dikirim klien. Daftar kosong menolak setiap model. Pemeriksaan ini juga mencakup model tempat sesi dimulai sebelum pengembang memilih model, jadi mulai sesi pada model yang diizinkan kebijakan.

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

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

Pengguna yang diautentikasi yang tidak cocok dengan kebijakan apa pun mendapatkan default gateway, yang berarti setiap model dalam katalog dan tidak ada pengaturan terkelola. Tambahkan catch-all match: {} terakhir jika Anda menginginkan kebijakan default yang dijamin.

[!NOTE]

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

Jalankan manajemen siklus hidup pengguna dan grup di sumber kebenaran, yang merupakan penyediaan SCIM asli 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 penyediaan SCIM dari akun Claude itu sendiri, itu adalah kemampuan Claude for Enterprise.

Dua jam propagasi berlaku:

• Konten kebijakan: mengedit kebijakan dan men-deploy ulang mencapai 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 dengan mereka. Ini berlaku pada pembaruan sesi berikutnya, yang berarti penyegaran senyap berikutnya, dibatasi oleh session.ttl_hours.

Claude Desktop mengikuti jadwalnya sendiri.

Mulai sesi pada model yang diizinkan kebijakan

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

Untuk memperbaikinya, atur enforceAvailableModels: true dalam blok cli yang sama, lalu periksa jenis entri apa 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 masih dapat dimulai pada default bawaan, jadi atur juga model ke salah satu ID yang terdaftar dalam blok cli kebijakan itu

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

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

Nilai matcher yang menghentikan gateway saat boot

Saat boot, gateway memeriksa blok match dari setiap kebijakan dan daftar admin_groups. Salah satu dari nilai ini menghentikan gateway dengan kesalahan yang menamai bidang:

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

Sebelum v2.1.232, gateway dimulai dengan nilai-nilai ini. Setiap nilai memiliki efek ini:

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

Memilih cli atau code

[!WARNING]

Ketika suatu kebijakan menggunakan kunci code, masing-masing hal berikut menghentikan gateway untuk mulai:

• Versi gateway: code memerlukan Claude Code v2.1.296 atau yang lebih baru di server gateway. Gateway versi lebih lama menolak untuk mulai ketika 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 sekaligus, atau ejaan lamanya settings, menghentikan gateway saat boot. Letakkan setiap blok di bawah satu kunci, dalam satu kali edit.

Pengaturan Claude Code suatu kebijakan, seperti aturan yang menolak pembacaan file .env, diletakkan 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 tersebut menentukan di mana pengaturan ditegakkan:

• cli: terminal, ekstensi VS Code dan JetBrains, serta 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 tetap berfungsi seperti sebelumnya, dan gateway yang menemukan cli dalam kebijakan dengan kunci desktop memberi peringatan saat boot dan tetap dimulai. 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 penolakan di bawah code, dengan kunci desktop kosong:

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

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

Apa yang masuk dalam cli

Setiap nilai code atau cli adalah dokumen managed-settings.json Claude Code yang lengkap, dengan skema yang sama yang akan Anda deploy melalui MDM atau /etc/claude-code/managed-settings.json, yang di sini dinyatakan 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, jadi kunci tingkat atas yang tidak dikenali gagal boot dengan kesalahan yang menamai setiap kunci yang menyinggung. Bagian skema yang sengaja terbuka masih menerima nilai arbitrer, karena klien yang lebih baru mungkin mengenali entri yang skema gateway tidak. Kunci terbuka ini termasuk env, pluginConfigs, dan kunci bersarang di bawah permissions.

Karena validasi menggunakan skema yang disertakan dengan versi gateway yang diinstal, menempatkan kunci pengaturan tingkat atas yang diperkenalkan oleh rilis Claude Code yang lebih baru ke dalam konfigurasi terkelola memerlukan upgrade gateway terlebih dahulu. Smoke-test kebijakan baru pada satu klien sebelum menggulirnya.

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

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 tiba melalui jaringan, CLI menunjukkan kepada setiap pengembang dialog persetujuan keamanan sebelum menerapkan pengaturan yang tercantum di bawah:

• hooks
• Variabel env yang memerlukan persetujuan pengembang, seperti proxy dan variabel URL dasar
• pengaturan eksekusi shell seperti apiKeyHelper dan statusLine
• pengaturan biner sandbox sandbox.bwrapPath, sandbox.socatPath, dan sandbox.ripgrep
• Pengaturan sandbox yang mencegat lalu lintas, menyuntikkan kredensial, atau melemahkan isolasi, seperti sandbox.network.tlsTerminate dan pengaturan port proxy. Dialog persetujuan keamanan mencantumkan semuanya.

Memori persetujuan mencakup berapa lama persetujuan berlangsung dan kapan dialog muncul lagi.

Claude Code menerapkan beberapa variabel env yang dikirimkan tanpa menunjukkan dialog persetujuan kepada pengembang, seperti pengaturan pemilihan model dan batas numerik. Variabel yang dikirimkan lainnya dapat memerlukan persetujuan pengembang sebelum berlaku; nilai proxy, URL dasar, atau OTEL_EXPORTER_OTLP_ENDPOINT yang tidak kosong selalu demikian. Ketika variabel yang dikirimkan memerlukan persetujuan, dialog menamakannya.

Environment variable dan dialog persetujuan memiliki detail, termasuk empat toggle privasi yang nilai yang dikirimkan memutuskan apakah mereka memerlukan persetujuan. Sebelum v2.1.218, Claude Code menerapkan lebih sedikit variabel tanpa bertanya kepada pengembang, jadi lebih banyak variabel yang dikirimkan memicu dialog.

Konfigurasi telemetri gateway mendorong OTEL_EXPORTER_OTLP_ENDPOINT, jadi menetapkan telemetry.forward_to memicu dialog pada setiap klien interaktif. Dialog melindungi mesin pengembang dari gateway yang dikompromikan atau bermusuhan, bukan organisasi dari pengembang.

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 pengembang menolak, Claude Code keluar dari sesi itu daripada menerapkan kebijakan. Ketika Anda mendorong hook baru, atau variabel env apa pun yang memicu dialog, ke kebijakan yang luas, setiap pengembang yang cocok oleh karena itu melihat dialog dalam sesi interaktif mereka. Sesi interaktif yang berjalan menunjukkannya pada polling per jam berikutnya, dan sebaliknya muncul pada startup interaktif pengembang berikutnya.

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

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 sufiks [1m], dan sesi melakukan compact pada sekitar 967K token. Sebelum Claude Code v2.1.287 di mesin pengembang, 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 sebagai gantinya, atur window auto-compact dalam env kebijakan:

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

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

Untuk menonaktifkan konteks 1M sebagai gantinya, atur CLAUDE_CODE_DISABLE_1M_CONTEXT: "1" dalam blok env yang sama. Claude Code kemudian memperlakukan setiap model sebagai memiliki window 200K. Dalam sesi interaktif, setiap pengembang menyetujui variabel ini dalam dialog persetujuan sebelum berlaku.

Prompt cache satu jam

Untuk meminta TTL prompt cache satu jam alih-alih lima menit default, tambahkan kunci-kunci ini ke blok code, cli, atau settings yang sudah ada pada kebijakan dan restart gateway. Kunci-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, alur kerja, dan permintaan latar belakang. Contoh ini menambahkan keduanya ke kebijakan match: {} dengan kunci cli:

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

[!WARNING]

Atur 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 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 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 kebijakan, atur managedMcpServers dalam blok cli kebijakan itu. Anda memerlukan Claude Code v2.1.259 atau lebih baru di server gateway dan pada klien.

Gateway memeriksa setiap entri saat boot dengan aturan yang sama yang diterapkan Claude Code pada klien, dan jika entri gagal pemeriksaan, gateway menolak untuk memulai dan menamai entri.

Jika Anda menulis referensi ${VAR} dalam gateway.yaml, gateway menyelesaikannya dari lingkungannya saat boot melalui ekspansi rahasia 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 diperluas.

Gateway menolak ejaan .mcp.json mcpServers dalam blok cli, dan kesalahan bootnya menamai managedMcpServers sebagai kunci yang digunakan. Sebelum v2.1.259, gateway menolak definisi server MCP apa pun dalam blok cli.

Overlay Claude Desktop

Jika organisasi Anda juga men-deploy Claude Desktop, gateway yang sama melayani kedua klien. Arahkan bootstrapUrl, dalam konfigurasi terkelola Claude Desktop, ke <listen.public_url>/user/bootstrap. Claude Desktop menurunkan penerbit OAuth dari URL itu, menjalankan sign-in kode perangkat yang sama terhadap gateway ini, dan mengambil konfigurasinya dari respons.

[!NOTE]

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

Jika Anda tidak men-deploy Claude Desktop, tinggalkan desktop sepenuhnya dari 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 lebih baru di server gateway. Konteks diperluas di Claude Desktop membahas opsi konteks 1M setiap model

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

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

• Endpoint OTLP yang menunjuk ke gateway itu sendiri, dan atribut identitas pengguna yang masuk. Gateway meneruskan ekspor yang diterimanya di endpoint itu ke tujuan forward_to Anda. Ini menyertakan endpoint dan atribut ketika Anda menetapkan telemetry.forward_to dan listen.public_url.

  Claude Desktop mengekspor setiap sinyal dengan satu pengkodean: http/protobuf, atau http/json ketika Anda menetapkan OTEL_EXPORTER_OTLP_PROTOCOL atau salah satu varian per-sinyal ke http/json dalam env kebijakan. Sebelum Claude Code v2.1.261 di server gateway, respons menetapkan http/json terlepas, jadi kolektor yang hanya menerima protobuf menolak ekspor Claude Desktop

Untuk menetapkan disabledBuiltinTools, coworkEgressAllowedHosts, atau pengaturan managedMcpServers Claude Desktop sendiri dalam blok desktop kebijakan, Anda memerlukan Claude Code v2.1.232 atau lebih baru di server gateway. managedMcpServers Claude Desktop mengambil nilai array daripada objek.

Gateway menghilangkan kunci tanpa padanan Claude Desktop, seperti hooks dan aturan izin yang dibatasi 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 ketika semua hal berikut terpenuhi:

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

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. Ketika dua kondisi pertama terpenuhi dan salah satu dari dua kondisi terakhir gagal, pengguna yang cocok dengan kebijakan mendapatkan salah satu hasil berikut:

• Melalui HTTPS, ketika Claude Desktop membundel Claude Code v2.1.296 atau yang lebih baru: tab Code tidak dimulai, dan balasan atas prompt pengguna menjelaskan alasannya
• Melalui HTTPS, ketika 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 mana pun yang dibundel Claude Desktop

Ketika 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 Di mana managedMcpServers berlaku.

Tetapkan pengaturan Claude Desktop secara langsung

Tambahkan blok desktop opsional bersama cli untuk menetapkan pengaturan Claude Desktop secara langsung. Tulis pengaturan dari referensi konfigurasi terkelola Claude Desktop sebagai nama kunci datar. Tinggalkan kunci yang Claude Desktop baca hanya dari MDM atau file lokal, seperti bootstrapUrl; gateway menolaknya saat boot.

Contoh ini menetapkan tiga kunci Claude Desktop untuk grup eng-contractors bersama 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 opsional; Claude Desktop menerapkan default sendiri untuk kunci apa pun yang Anda abaikan.

Apa yang ditolak gateway saat boot

Gateway memvalidasi setiap blok desktop saat boot terhadap skema konfigurasi yang Claude Desktop itu sendiri gunakan, jadi kesalahan muncul di startup gateway sebagai kesalahan yang menamai kunci daripada mencapai setiap desktop yang terhubung. Gateway gagal saat boot ketika blok berisi:

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

Jika Anda menggunakan nilai atau bentuk entri yang sudah deprecated, seperti entri managedMcpServers tanpa transport, gateway dimulai dan mencatat peringatan yang menamai pengganti.

Sebelum v2.1.232, gateway menerima daftar tetap 11 kunci gerbang fitur, 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 disertakan dengan versi yang diinstal, seperti yang dilakukannya pada blok cli. Untuk mengirimkan pengaturan yang diperkenalkan oleh rilis Claude Desktop yang lebih baru, upgrade gateway terlebih dahulu. Misalnya, userPluginMarketplacesEnabled dan userPluginUploadsEnabled memerlukan Claude Code v2.1.260 atau lebih baru di server gateway dan Claude Desktop 1.37937.0 atau lebih baru di mesin anggota.

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

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

Bagaimana kebijakan peran mewarisi blok desktop dasar

Gateway mengisi kunci yang blok desktop kebijakan tidak ditetapkan dari blok desktop catch-all match: {}, dengan cara yang sama mengisi blok cli kebijakan dari dasar. Jika Anda menetapkan disabledBuiltinTools atau builtinToolPolicy dalam dasar dan kebijakan peran, gateway menyimpan pembatasan dasar:

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

Untuk setiap kunci lain, jika Anda menetapkannya dalam kebijakan peran, gateway menggunakan nilai kebijakan peran. Gateway mengganti array atau objek bersarang seperti banner secara keseluruhan, jadi jika Anda menetapkan banner.text dalam kebijakan peran, gateway menjatuhkan banner.backgroundColor 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 start 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 me-restart aplikasi. Setelah 24 jam secara default, Claude Desktop menampilkan dialog restart dan me-restart dengan sendirinya setelah 2 menit tidak aktif

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

Konteks diperluas di Claude Desktop

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

Entri models tidak mendapatkan opsi 1M ketika:

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

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

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

Contoh ini menawarkan opsi secara manual untuk alias kustom yang dirutekan ke profil inferensi aplikasi, 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

Hapus opsi 1M

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

Variabel tersebut juga mencapai sesi terminal pengembang yang cocok dengan kebijakan. Untuk apa yang diubahnya di sana, lihat Konteks diperluas.

Prioritas dengan sumber terkelola lainnya

Jika perangkat juga memiliki kebijakan yang dikirimkan MDM atau managed-settings.json lokal, pengaturan yang dikirimkan gateway mendapat peringkat pertama. Prioritas dalam tingkat terkelola di halaman pengaturan terkelola mengatakan kapan sumber lokal berlaku, dan memiliki kunci yang Claude Code baca dari setiap sumber admin terlepas dari sumber mana yang dipilihnya, seperti kunci penguncian sandbox, forceRemoteSettingsRefresh, dan penggabungan env per-variabel. policyHelper yang dikonfigurasi dalam profil MDM atau file pengaturan terkelola hanya berjalan ketika gateway tidak mengirimkan pengaturan; entri mengatakan apa yang digantikan oleh outputnya.

Host penyematan seperti Claude Desktop dapat memasok kebijakan melalui opsi SDK managedSettings. Pengaturan induk dari host penyematan mengatakan kapan Claude Code menerapkannya, dan Batasi pengaturan induk mencantumkan pengaturan arah allow mana yang masih berlaku tanpa kunci allowManaged*Only.

Kebijakan gateway berlaku untuk setiap invokasi Claude Code pada mesin, termasuk jalankan claude -p non-interaktif dan sesi yang dihasilkan oleh Agent SDK. Jika gateway tidak dapat dijangkau saat startup, sesi yang masuk keluar dengan kesalahan daripada berjalan tanpa kebijakan mereka.

telemetry

CLI mengirim metrik, log, dan, ketika diaktifkan, jejak ke gateway, yang meneruskannya verbatim ke setiap tujuan yang dikonfigurasi. Ekspor menggunakan OpenTelemetry Protocol (OTLP) melalui HTTP. Untuk melewati relay dan memiliki sesi ekspor langsung ke kolektor Anda, namai kolektor dalam kebijakan. Lihat Monitoring usage untuk metrik dan acara yang CLI pancarkan.

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. Dengan demikian, 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 memberi stempel telemetri mereka dengan user.email dan user.groups bersama enduser.id, sehingga Anda dapat mencakup penggunaan terminal, Desktop, dan Cowork dengan satu kueri di 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 penyedia identitas Anda keluarkan untuk pengguna, yang tetap sama ketika email pengguna berubah. Sesi terminal memberi stempel nilai yang sama di bawah user.id, jadi kueri yang cocok enduser.sub terhadap terminal user.id mencakup penggunaan terminal, Desktop, dan Cowork satu pengguna bersama-sama. Pada ekspor Desktop dan Cowork, user.id adalah pengidentifikasi anonim, bukan subjek.

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

Jika daftar grup pengguna lebih panjang dari 255 karakter setelah dikodekan persen, atau nama grup berisi koma atau tanda sama dengan, gateway meninggalkan user.groups dari telemetri Desktop dan Cowork pengguna itu daripada memotongnya. Sesi terminal pengguna itu masih membawa daftar lengkap.

Gateway meninggalkan enduser.sub ketika subjek lebih panjang dari 255 karakter setelah dikodekan persen, atau berisi spasi, karakter di luar ASCII yang dapat dicetak, atau salah satu dari , ; = \ " %. Telemetri Desktop dan Cowork pengguna itu menyimpan atribut lainnya.

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

Anda memerlukan Claude Code v2.1.274 atau 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 adalah metrik saja. Sinyal berbeda dalam sensitivitas:

• Metrik: penghitung agregat seperti jumlah token, jumlah permintaan, dan latensi
• Log dan jejak: dapat membawa perintah Bash lengkap, input tool, dan jalur file, mencakup apa pun yang Claude Code lakukan di mesin pengembang

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

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

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

Untuk kolektor dalam kluster, paparkan melalui HTTPS di alamat internalnya sendiri, atau jalankan sebagai sidecar dengan variabel yang ditetapkan.

Ketika HTTPS_PROXY ditetapkan, gateway mengirim ekspor melalui proxy itu.

Untuk mencapai kolektor internal secara langsung, tambahkan ke NO_PROXY berdasarkan nama host atau domain dengan titik terkemuka seperti .internal.example.com, yang memerlukan Claude Code v2.1.277 atau lebih baru di server gateway. Pastikan gateway dapat mencapai kolektor tanpa proxy. Entri tanpa titik terkemuka cocok hanya dengan nama yang tepat itu, bukan nama di bawahnya. Rentang CIDR tidak cocok.

Dengan proxy-only egress diaktifkan, izinkan kolektor dalam proxy sebagai gantinya, karena entri NO_PROXY apa pun menjaga proxy-only egress tetap mati.

Telemetri dimatikan dalam CLI secara default. Ketika Anda menetapkan telemetry.forward_to dan listen.public_url, gateway mengaktifkannya untuk klien yang terhubung dengan mendorong enam environment variable melalui /managed/settings:

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

Ketika Anda menambahkan label Anda sendiri, gateway juga mendorong OTEL_RESOURCE_ATTRIBUTES.

Sebelum Claude Code v2.1.265 di server gateway, gateway mendorong ketiga pemilih eksportir sebagai otlp, termasuk untuk sinyal yang tidak ada tujuan yang memilih.

Endpoint yang didorong dibangun dari URL publik, jadi metrik dan log tidak memerlukan konfigurasi OTEL dari pengembang atau kebijakan.

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

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

Tanpa tujuan forward_to untuk sinyal, gateway menerima dan membuangnya. Jika pengembang sudah mengekspor telemetri Claude Code ke salah satu kolektor Anda, tambahkan sebagai tujuan forward_to, dengan log atau jejak diaktifkan jika mereka mengekspor itu, sehingga terus menerima data mereka setelah mereka masuk. Untuk melewati relay sebagai gantinya, namai kolektor dalam kebijakan.

Jejak juga memerlukan CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 pada setiap klien. Atur dalam blok env kebijakan terkelola, karena gateway tidak mendorongnya. Pengembang menyetujuinya dalam dialog persetujuan keamanan yang sama yang sudah dipicu oleh endpoint yang didorong.

Atur ke 1 hanya dalam kebijakan yang grupnya ingin Anda lacak. Kebijakan yang tidak menetapkannya mewarisi nilai dari kebijakan catch-all match: {} Anda jika kebijakan itu menetapkan satu, per aturan penggabungan. Untuk menjaga klien grup dari mengirim jejak bahkan ketika pengembang menetapkan variabel secara lokal, atur ke 0 dalam kebijakan grup itu.

Kedua pengkodean OTLP protobuf dan JSON diteruskan, dan backend yang kompatibel OpenTelemetry apa pun bekerja sebagai tujuan.

Mengirim metrik kumulatif

Jika collector Anda hanya menerima metrik kumulatif, atur OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE ke cumulative. Claude Code mengirim metrik delta secara default, dan gateway meneruskannya tanpa mengonversinya. Atur 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, atur 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 kepadanya sebagai pengaturan induk.

Tambahkan label Anda sendiri

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

Sesi mendapatkan label hanya ketika Anda juga menetapkan 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 memulai ketika label melanggar salah satu aturan ini, dan kesalahan startup menamai label:

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

Anda memerlukan Claude Code v2.1.281 atau lebih baru di server gateway untuk menetapkan telemetry.resource_attributes. Gateway sebelumnya menolak untuk memulai ketika menemukan kunci. Upgrade setiap replika sebelum Anda menambahkan kunci, dan hapus kunci sebelum Anda kembali ke versi sebelumnya.

Sesi terminal yang masuk melalui /login menerima label sebagai OTEL_RESOURCE_ATTRIBUTES, didorong dengan variabel telemetri lainnya. Jika Anda menetapkan OTEL_RESOURCE_ATTRIBUTES dalam blok env kebijakan, sesi terminal yang cocok dengan kebijakan itu 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 berdasarkannya di backend yang tidak mengindeks atribut sumber. Untuk mematikan salinan itu, lihat Kontrol kardinalitas metrik.

Perubahan grup selama sesi terbuka

Sesi terminal menempatkan user.groups pada resource OTLP dan sekali lagi 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 yang baru. Resource mempertahankan grup lama hingga developer me-restart Claude Code, jadi kelompokkan berdasarkan atribut pada titik data atau event.

Jika Anda mengaktifkan resource_to_telemetry_conversion di exporter Prometheus remote write milik OpenTelemetry Collector, exporter tersebut mengganti 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 series membawa label user_groups dari titik datanya sendiri.

Ekspor langsung ke kolektor Anda

Untuk memiliki sesi yang masuk melalui /login mengirim telemetri langsung ke kolektor Anda alih-alih melalui relay, atur OTEL_EXPORTER_OTLP_ENDPOINT ke URL dasar https:// kolektor dalam 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 di sana melalui OTLP/HTTP. Memerlukan Claude Code v2.1.265 atau lebih baru di setiap mesin pengembang. Klien sebelumnya mengekspor melalui relay.

Untuk mengautentikasi ke kolektor, atur OTEL_EXPORTER_OTLP_HEADERS dalam blok env yang sama. Sesi tidak pernah mengirim token sesi gateway pengembang ke kolektor yang dinamai dengan cara ini.

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

Claude Code memeriksa endpoint sebelum mengekspor sinyal secara langsung, dan menyimpan sinyal itu di relay ketika pemeriksaan gagal. Pemeriksaan termasuk:

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

Endpoint yang Anda namai mengubah hanya di mana ekspor pergi. Anda masih memilih sinyal mana yang mengekspor sama sekali dengan pemilih OTEL_*_EXPORTER.

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

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

Ketika pengembang keluar, atau masuk ke gateway yang berbeda, ekspor ke kolektor berhenti dan Claude Code menjatuhkan setiap batch yang tersisa daripada mengirimkannya.

Ketika tujuan gagal

Gateway tidak membuffer, mencoba ulang, atau menyimpan telemetri, jadi itu menjatuhkan ekspor yang tidak mencapai tujuan daripada mengirimkannya terlambat. Setiap tujuan berhasil atau gagal sendiri, dan klien yang mengekspor menerima respons sukses bagaimanapun, jadi pengiriman yang gagal muncul hanya dalam log gateway.

Setelah lima pengiriman berturut-turut yang gagal ke tujuan, gateway menjeda penerusan ke dalamnya dalam rentang 30 detik, mencatat setiap jeda, sampai pengiriman berhasil. Respons kesalahan apa pun, timeout, atau kesalahan koneksi menghitung sebagai pengiriman yang gagal, kecuali 400, 413, 415, 422, dan 431, yang berarti kolektor menolak payload ekspor itu sebagai salah format atau terlalu besar.

Payload yang ditolak tidak memajukan atau mengatur ulang penghitung kegagalan: gateway terus meneruskan ke tujuan dan mencatat peringatan yang menamakannya dan status, pada penolakan pertama tujuan dan setiap seratus setelahnya.

Penyetelan HTTP

Empat blok tingkat atas opsional, access_control, limits, timeouts, dan rate_limits, menyetel surface HTTP. Default cocok untuk sebagian besar deployment.

Jika Anda meninggalkan kedua daftar access_control kosong, yang merupakan default, gateway melayani alamat klien apa pun, jadi hanya jaringan Anda yang membatasi siapa yang dapat mencapainya. Itu penting karena gateway dapat mendorong pengaturan terkelola yang menjalankan perintah di mesin pengembang.

Sementara allow_cidrs kosong, gateway memperingatkan di dua tempat, tanpa mengubah cara itu menjawab permintaan apa pun:

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

Kedua sinyal menggunakan alamat klien saat gateway menyelesaikannya. Jika load balancer, port-forward, atau tunnel meneruskan lalu lintas dan tidak terdaftar dalam listen.trusted_proxies, gateway melihat alamat relay, yang biasanya pribadi, sehingga baik peringatan runtime maupun daftar allow pribadi tidak menangkap lalu lintas yang diteruskan melaluinya.

Di belakang front end seperti itu, atur listen.trusted_proxies terlebih dahulu sehingga gateway melihat alamat klien nyata, dan jaga gateway dan semua yang di depannya tidak dapat dijangkau dari internet publik apa pun keadaannya.

load_test_mode

Blok load_test_mode memungkinkan Anda untuk load test gateway tanpa memanggil penyedia model. Sementara itu aktif, gateway membangun dan menandatangani setiap permintaan penyedia seperti biasa, membuangnya alih-alih mengirimkannya, dan streaming respons kalengan kembali melalui jalur respons normalnya. Respons adalah teks pengisi yang dimulai dengan kalimat yang mengatakan itu kalengan.

Memerlukan Claude Code v2.1.282 atau lebih baru di server gateway. Gateway sebelumnya menolak untuk memulai ketika menemukan kunci. Upgrade setiap replika sebelum Anda menambahkan blok, dan hapus blok sebelum Anda kembali.

Contoh di bawah mengaktifkan mode dengan default, respons sekitar 750 token teks yang streaming 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

Tes beban dalam mode ini mencakup gateway, Postgres Anda, dan semua yang di depan gateway. Itu tidak mencakup batas, kecepatan, atau jalur jaringan penyedia.

Tidak ada permintaan model yang dikirim ke penyedia, jadi CPU replika per permintaan adalah perkiraan dan terbaca lebih rendah dari produksi, yang juga mengenkripsi lalu lintasnya ke penyedia. Konfirmasi jumlah replika dengan pilot kecil terhadap penyedia nyata. Sebelum v2.1.283, perkiraan terbaca jauh lebih rendah.

Sementara mode aktif, permintaan dapat membawa header x-load-test-user yang menyimpan angka bulat hingga tujuh digit. Gateway menghitung setiap angka sebagai pengembang terpisah, dengan email dan grup pengembang yang tokennya datang dengan permintaan.

Berikan deployment load-test database kosongnya sendiri, karena gateway menolak untuk memulai dengan mode aktif terhadap database di mana pengembang apa pun sudah menghabiskan apa pun.

[!WARNING]

Jangan pernah mengaktifkan ini untuk gateway yang digunakan pengembang. Setiap permintaan mendapatkan respons kalengan dan tidak ada model yang dipanggil. Gateway mencatat peringatan load_test_mode is on saat boot dan menandai setiap acara audit inference dengan load_test: true sementara 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.

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com
  # Omit the tls block when running behind a TLS-terminating ingress.
  # tls:
  #   cert: /certs/gateway.crt
  #   key: /certs/gateway.key
  # trusted_proxies:
  #   - 10.0.0.0/8

oidc:
  issuer: https://example.okta.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains:
    - example.com
  # Required when the issuer is the Okta org server, whose id_tokens
  # can omit email and groups; the gateway fills them from /userinfo.
  userinfo_fallback: true
  # allowed_groups: [claude-code-users]
  # Okta emits groups only when the `groups` scope is requested and the
  # app's groups claim filter allows them. The contractors policy below
  # matches on groups, so the scope is requested here.
  scopes: [openid, profile, email, offline_access, groups]
  # extra_auth_params: { access_type: offline, prompt: consent }  # Google
  # groups_claim: groups          # Entra app roles: use `roles`
  # email_claim: email

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}   # openssl rand -base64 32
  # ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}
  # max_connections: 5
  # connect_timeout_seconds: 5
  # readiness_grace_seconds: 300   # keep passing the readiness check through a database failover

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

# enforcement:
#   fail_closed_on_error: false

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

# Meter at contracted rates instead of USD list price. Requires admin: or a
# managed: policy. With managed:, the same rates also go to signed-in clients.
# Rates below are placeholders, not real contract prices.
# pricing:
#   multiplier: 0.85
#   overrides:
#     - { upstream: anthropic, model: claude-sonnet-4-6, input: 3.30, output: 16.50, cache_read: 0.33, cache_write: 4.125 }

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

  # - provider: bedrock
  #   region: us-east-1
  #   auth: {}

  # - provider: mantle
  #   region: us-east-1
  #   models: [claude-opus-4-8, claude-opus-4-7, claude-haiku-4-5]
  #   auth: {}

  # - provider: anthropicAws
  #   region: us-east-1
  #   workspace_id: wrkspc_...
  #   auth:
  #     api_key: ${ANTHROPIC_AWS_API_KEY}

  # - provider: vertex
  #   region: us-east5
  #   project_id: example-prod
  #   auth: {}

  # - provider: foundry
  #   resource: example-foundry
  #   auth: { use_azure_ad: true }

auto_include_builtin_models: true
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      anthropic: claude-opus-4-8
      # bedrock: us.anthropic.claude-opus-4-8
      # mantle: anthropic.claude-opus-4-8
      # anthropicAws: claude-opus-4-8
      # vertex: claude-opus-4-8
      # foundry: <your-opus-deployment-name>
  - id: claude-sonnet-4-6
    label: Claude Sonnet 4.6
    upstream_model:
      anthropic: claude-sonnet-4-6
  - id: claude-haiku-4-5
    label: Claude Haiku 4.5
    upstream_model:
      anthropic: claude-haiku-4-5

managed:
  policies:
    - match: { groups: [contractors] }
      cli:
        availableModels: [claude-haiku-4-5]
        # allow auto-approves these tools; it does not block the rest.
        # Add deny rules to restrict tools.
        permissions: { allow: [Read, Grep] }
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        # Constrain the Default picker option to each policy's availableModels
        # instead of the built-in default, so no role gets a 400 on Default.
        # The contractors policy inherits this key.
        enforceAvailableModels: true
        permissions:
          allow: [Read, Grep, Bash, Edit]
          deny: ["WebFetch"]
        env: { HTTP_PROXY: http://proxy.example.com:8080 }

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

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