Langsung ke konten utama
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
  • 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

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 yang diperlukan

listen

Blok listen mengontrol di mana gateway melayani: bind address dan port, origin yang terlihat secara eksternal, dan optional TLS termination.

oidc

Blok oidc menghubungkan gateway ke identity provider Anda dan memutuskan siapa yang dapat masuk. Ini menamai issuer dan OAuth client, memetakan claims yang membawa email dan groups, dan membatasi sign-in berdasarkan email domain atau group. OpenID Connect (OIDC) adalah protokol SSO yang digunakan gateway dengan identity provider Anda; lihat Identity provider setup untuk apa yang harus didaftarkan di sisi IdP.

session

Blok session membentuk bearer tokens yang dimint gateway setelah sign-in: secret yang menandatanganinya dan berapa lama mereka hidup.

store

Blok store menunjukkan gateway ke database PostgreSQL-nya, yang menyimpan device grants dan rate-limit counters. Untuk local development, arahkan postgres_url ke throwaway Postgres container, misalnya docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres.

upstreams

upstreams adalah ordered list. Gateway meneruskan inference ke upstream pertama yang menyelesaikan model yang diminta. Pada 5xx, 429, 401, 403, 404, atau timeout ia failover ke next; 4xx lainnya tidak, karena error tersebut dapat diatribusikan ke request daripada upstream. 401 atau 403 berarti credential gateway sendiri gagal terhadap upstream itu, dan 404 berarti upstream itu tidak melayani model yang diminta, jadi upstream yang lebih baru dalam list masih bisa. Failover pada 404 memerlukan gateway v2.1.198 atau lebih baru. Release sebelumnya mengembalikan 404 pertama ke client bahkan ketika upstream yang lebih baru dalam list melayani model. Multiple upstreams dari provider yang sama harus menetapkan distinct name:. Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, dan Microsoft Foundry clients dibangun sekali saat startup, dan SDK mereka refresh credentials secara internal, jadi rotating cloud credentials tidak memerlukan restart. Static Anthropic API keys dan bearers dibaca saat startup; lihat Anthropic API.

Anthropic API

Minimal Anthropic upstream adalah API key dari Claude Console:
Dua bentuk credential berbeda dalam header yang mereka kirim:
  • api_key: mengirim x-api-key. Rotate di Claude Console dan update env var.
  • oauth_token: mengirim Authorization: Bearer. Gunakan bentuk bearer ketika org Anda mengeluarkan short-lived tokens daripada long-lived API keys. Bearer dibaca sekali saat startup, jadi refresh dengan remount secret dan restart.
Daripada static key atau bearer, Anda dapat menggunakan Workload Identity Federation. Buat federation rule dengan mengikuti Workload Identity Federation guide, kemudian mount workload’s OIDC JWT Anda sebagai file, seperti Kubernetes projected service-account token atau CI platform’s id-token. Gateway menukar JWT untuk short-lived bearer dan refresh secara otomatis. Token file dibaca ulang pada setiap exchange, jadi rotated projected tokens diambil tanpa restart.

Amazon Bedrock

Untuk client-side Amazon Bedrock deployment yang digantikan atau di-front oleh gateway, lihat Claude Code on Amazon Bedrock. Gateway-side upstream:
Empty auth block menggunakan AWS SDK’s default credential chain: env vars, ~/.aws/credentials, ECS task role, EC2 instance metadata, atau IRSA pada EKS. Dalam production, berikan gateway pod IAM role daripada embedding static keys dalam container image. Explicit credentials harus lengkap: gateway gagal saat boot ketika aws_access_key_id dan aws_secret_access_key tidak diatur bersama, atau ketika aws_session_token diatur tanpa mereka. Sebelum v2.1.207, partial auth: block lulus validasi.

Claude Platform on AWS

Claude Platform on AWS melayani first-party Anthropic API pada infrastruktur AWS di aws-external-anthropic.<region>.api.aws. Ini menggunakan first-party model IDs, menghormati header anthropic-beta seperti yang dikirim, dan melayani count_tokens, jadi tidak ada terjemahan spesifik Bedrock yang berlaku. Provider anthropicAws memerlukan Claude Code v2.1.198 atau lebih baru; release gateway sebelumnya menolaknya saat boot. Untuk client-side deployment dari platform yang sama, lihat Claude Code on Claude Platform on AWS. Gateway-side upstream:
Platform berjalan di akun AWS terpisah dari Amazon Bedrock dan menandatangani SigV4 requests untuk nama service-nya sendiri, aws-external-anthropic, jadi Bedrock-scoped IAM role tidak mengotorisasinya. API key di auth.api_key mengambil precedence ketika SigV4 credentials juga diatur. Empty auth block menggunakan AWS SDK’s default credential chain, chain yang sama yang digunakan upstream Amazon Bedrock. Karena platform menyelesaikan first-party model IDs, built-in catalog routes ke sana tanpa models: block. Ketika Anda mengkurasi daftar models:, key entry anthropicAws: dengan first-party ID.

Google Cloud Agent Platform

Untuk equivalent client-side setup, lihat Claude Code on Google Cloud. Gateway-side upstream:
Empty auth block menggunakan Application Default Credentials: GOOGLE_APPLICATION_CREDENTIALS, GCE metadata, atau GKE Workload Identity. Service-account JSON key files didukung tetapi tidak disarankan; gunakan Workload Identity atau attach service account ke GCE atau Cloud Run instance. Atur region: global untuk menggunakan global endpoint untuk Google Cloud’s Agent Platform daripada regional. Google kemudian route setiap request ke available region, jadi Anda tidak track per-region model availability. Menetapkan region spesifik pin setiap request ke sana.

Microsoft Foundry

Untuk client-side Foundry deployment, lihat Claude Code on Microsoft Foundry. Gateway-side upstream:
use_azure_ad: true resolves melalui DefaultAzureCredential: Managed Identity pada AKS, ACI, atau App Service; Azure CLI; atau environment credentials. API keys bekerja tetapi project-wide dan tidak rotate secara otomatis. Foundry’s endpoint diturunkan dari resource:; atur optional base_url untuk override untuk sovereign clouds seperti Azure Government.

Multiple upstreams

Provider yang sama dapat muncul lebih dari sekali dengan distinct name:. Ini mencakup different regions, different accounts via different credential chains, provisioned throughput versus on-demand, dan cross-provider fallback. Gateway mencoba upstreams secara berurutan. 5xx, 429, 401, 403, 404, timeouts, dan missing-endpoint (501) failover; 4xx lainnya tidak. 429 adalah per-upstream capacity, jadi provisioned-throughput (PT) exhaustion failover ke on-demand. 404 adalah per-upstream model availability, jadi upstream yang belum enable model tidak memblokir upstream yang lebih baru dalam list yang melayaninya. Upstream yang tidak dapat menyelesaikan model yang diminta dilewati tanpa network round-trip. Contoh ini route provisioned-throughput Bedrock allotment pertama, overflow ke on-demand dan second account, dan fallback ke Anthropic API terakhir:
Failover antara cloud providers, atau ke direct Anthropic API, mengubah agreement, geography, dan terms lainnya yang mengatur request. CLI menerapkan feature gating yang sama ke gateways terlepas dari upstream mana yang melayani request tertentu, jadi failover tidak mengirim body field yang upstream akan tolak.

Bagian opsional

admin

Opsional. Mengaktifkan /v1/organizations/spend_limits, yang mencerminkan Anthropic’s public Admin API, dan per-developer spend enforcement pada /v1/messages. Lihat Spend limits untuk bagaimana caps ditetapkan dan ditegakkan; bagian ini mencakup gateway.yaml keys yang mengaktifkan fitur dan menyetelnya.

enforcement

Blok enforcement mengontrol bagaimana pemeriksaan spend-limit berperilaku ketika store tidak tersedia.

models

Blok models adalah daftar model yang dikurasi admin opsional, disajikan di /v1/models dan digunakan untuk menerjemahkan ID model per upstream. Ini diperlukan untuk wilayah Bedrock non-AS, ARN throughput provisioned Bedrock, dan nama deployment Foundry.

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: {} yang dijelaskan di bawah. Mereka disajikan per-user di GET /managed/settings dengan caching ETag/304.
Catch-all match: {}, secara konvensional terdaftar terakhir, diperlakukan sebagai lapisan dasar. Setiap kebijakan lainnya mewarisi kunci apa pun yang tidak ditetapkan dari catch-all, jadi 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 daftar dasar.
  • Deny-lists dan hook arrays: permissions.deny, permissions.ask, disabledMcpjsonServers, deniedMcpServers, blockedMarketplaces, dan setiap array jenis event hooks. Ini mengambil union dari dasar dan kebijakan, jadi deny org-wide atau audit hook tidak dapat secara tidak sengaja dijatuhkan oleh override per-peran.
  • Record-typed keys: env, modelOverrides, dan skillOverrides. Ini shallow-merge, jadi blok env per-peran menimpa kunci yang ditetapkan dan mewarisi sisanya dari dasar.
availableModels juga ditegakkan server-side di /v1/messages, jadi model yang ditolak mengembalikan 400 terlepas dari apa yang dikirim klien. Pengguna yang terautentikasi yang tidak cocok dengan kebijakan apa pun mendapat 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.
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 dihitung dan tidak ada akun untuk dibuat sebelumnya, dan oleh karena itu tidak ada endpoint SCIM, karena tidak ada apa pun untuk SCIM sinkronkan ke.Jalankan manajemen siklus hidup pengguna dan grup di sumber kebenaran, yang merupakan penyediaan SCIM asli IdP 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 redeploy mencapai klien yang terhubung pada polling managed-settings berikutnya mereka, dalam satu jam
  • Keanggotaan grup: mengubah keanggotaan grup pengguna mengubah kebijakan mana yang cocok dengan mereka. Ini berlaku pada re-mint sesi berikutnya, berarti refresh senyap berikutnya, dibatasi oleh session.ttl_hours.

Apa yang masuk di cli

Setiap nilai cli adalah dokumen managed-settings.json Claude Code yang lengkap, skema yang sama yang akan Anda deploy melalui MDM atau /etc/claude-code/managed-settings.json, diekspresikan di sini sebagai YAML. CLI menerapkan dokumen yang dikirimkan pada tingkat terkelola, di atas pengaturan pengguna dan proyek. Gateway memvalidasi setiap dokumen terhadap skema pengaturan CLI saat boot, jadi kunci tingkat atas yang tidak dikenali atau kunci yang dikenali dengan nilai yang salah bentuk gagal boot dengan error yang menamai setiap kunci yang bermasalah. Bagian skema yang sengaja terbuka masih menerima nilai arbitrer, karena klien yang lebih baru mungkin mengenali entri yang skema gateway tidak. Kunci terbuka ini adalah env, pluginConfigs, dan kunci yang bersarang di bawah permissions. Karena validasi menggunakan skema yang disertakan dengan versi gateway yang terinstal, menempatkan kunci pengaturan tingkat atas yang diperkenalkan oleh rilis Claude Code yang lebih baru ke konfigurasi terkelola memerlukan upgrade gateway terlebih dahulu. Smoke-test kebijakan baru pada satu klien sebelum meluncurkannya. Referensi kunci lengkap ada di Claude Code settings. Kunci yang paling sering dicari operator:
Karena pengaturan ini tiba melalui jaringan, CLI menunjukkan setiap developer dialog persetujuan keamanan satu kali sebelum menerapkan apa pun yang dapat menjalankan perintah shell atau mengubah ke mana traffic pergi. Dialog mencakup:
  • hooks
  • Variabel env yang tidak ada di daftar aman bawaan CLI
  • pengaturan eksekusi shell seperti apiKeyHelper dan statusLine
  • konten CLAUDE.md yang terkelola
Daftar aman menentukan variabel env mana yang berlaku tanpa persetujuan:
  • Pada daftar aman: auto-update dan model-name vars
  • Tidak pada daftar aman: proxy vars, base-URL vars, dan OTEL_EXPORTER_OTLP_ENDPOINT
Konfigurasi telemetry gateway mendorong OTEL_EXPORTER_OTLP_ENDPOINT, jadi pengaturan telemetry.forward_to memicu dialog pada setiap klien interaktif. Run non-interaktif dengan flag -p tidak dapat menampilkan dialog. Ini menerapkan pengaturan yang didorong untuk run itu saja dan tidak merekamnya sebagai disetujui, jadi sesi interaktif berikutnya developer masih menampilkan dialog. Sebelum v2.1.207, run non-interaktif menyimpan pengaturan sebagai disetujui dan tidak ada sesi interaktif yang lebih baru menampilkan dialog untuk mereka. Jika developer menolak, Claude Code keluar daripada menerapkan kebijakan. Mendorong hook baru atau variabel env non-aman ke kebijakan yang luas oleh karena itu berarti prompt persetujuan pada startup berikutnya setiap developer yang cocok. Kunci cli dinamai settings dalam rilis sebelumnya. Ejaan itu masih diterima sebagai alias, tetapi deployment baru harus menggunakan cli.

Precedence dengan sumber terkelola lainnya

Jika perangkat juga memiliki managed-settings.json lokal atau kebijakan yang dikirimkan MDM, sumber terkelola tidak bergabung. Sumber prioritas tertinggi menyediakan semua pengaturan kebijakan, diurutkan dalam urutan ini dengan prioritas tertinggi terlebih dahulu:
  1. Policy helper
  2. Pengaturan yang dikirimkan gateway
  3. MDM, melalui registri HKLM di Windows atau plist di macOS
  4. File managed-settings.json
  5. Registri HKCU, hanya di Windows
Host embedding dapat menyediakan kebijakan melalui opsi SDK managedSettings. Ini diabaikan secara default dan berlaku hanya ketika sumber terkelola opt in dengan parentSettingsBehavior: "merge", disaring sehingga dapat mengencangkan kebijakan tetapi tidak melonggarkannya. Satu-satunya pengecualian adalah kunci berikut, yang dihormati ketika sumber admin apa pun di atas tingkat HKCU yang dapat ditulis pengguna menetapkannya, terlepas dari sumber mana yang menyediakan sisa kebijakan:
  • sandbox.network.allowManagedDomainsOnly dan sandbox.filesystem.allowManagedReadPathsOnly: ketika terkunci, allowlist yang sesuai adalah union di seluruh sumber
  • allowAllClaudeAiMcps: override allow-only untuk allowlist server MCP claude.ai
  • sandbox.bwrapPath dan sandbox.socatPath: jalur filesystem ke binary helper sandbox
  • forceRemoteSettingsRefresh: memblokir startup hingga pengaturan terkelola jarak jauh segar diambil, jadi kebijakan MDM atau file yang menetapkannya dihormati bahkan ketika payload jarak jauh yang di-cache yang kekurangan kunci adalah sumber prioritas tertinggi
Setiap kunci lainnya, termasuk allowManagedPermissionRulesOnly dan disableBypassPermissionsMode, berasal dari sumber prioritas tertinggi saja. Lihat Settings precedence untuk aturan yang sama di halaman pengaturan. Kebijakan gateway berlaku untuk setiap invokasi Claude Code pada mesin, termasuk run non-interaktif claude -p dan sesi yang dihasilkan oleh Agent SDK. Jika gateway tidak dapat dijangkau saat startup, sesi yang masuk keluar dengan error daripada menjalankan tanpa kebijakan mereka.
mcpServers di dalam blok cli kebijakan ditolak saat boot gateway. Distribusi MCP per-grup tidak tersedia; deploy server MCP melalui managed-mcp.json berbasis file pada setiap perangkat atau biarkan developer menambahkannya secara lokal.

telemetry

CLI mengirim metrik, log, dan, ketika diaktifkan, trace OpenTelemetry Protocol (OTLP) melalui HTTP ke gateway, yang meneruskan mereka verbatim ke setiap tujuan yang dikonfigurasi. Lihat Monitoring usage untuk metrik dan event yang CLI emit. CLI memberi stempel setiap export dengan identitas pengguna yang terautentikasi, dibaca dari JWT yang diterbitkan gateway: atribut user.id, user.email, dan user.groups. Atribusi biaya dan penggunaan per-developer oleh karena itu bekerja tanpa konfigurasi sisi developer.
Setiap tujuan opt into metrics, logs, dan traces secara independen, dan default adalah metrics saja. Signal berbeda dalam sensitivitas:
  • Metrics: counter agregat seperti token counts, request counts, dan latency
  • Logs dan traces: dapat membawa perintah bash lengkap, tool inputs, dan jalur file, mencakup apa pun yang Claude Code lakukan pada mesin developer
Aktifkan logs dan traces hanya pada tujuan dengan kontrol akses dan kebijakan retensi yang data jamin.
Telemetry off dalam CLI secara default. Mengonfigurasi telemetry.forward_to bersama dengan listen.public_url mengaktifkannya. Gateway mendorong lima variabel env ke setiap klien yang terhubung melalui /managed/settings:
  • CLAUDE_CODE_ENABLE_TELEMETRY=1
  • OTEL_METRICS_EXPORTER=otlp
  • OTEL_LOGS_EXPORTER=otlp
  • OTEL_TRACES_EXPORTER=otlp
  • OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
Endpoint yang didorong dibangun dari URL publik, jadi metrik dan log tidak memerlukan konfigurasi OTEL dari developer atau kebijakan. Konfigurasi yang didorong diterapkan pada tingkat terkelola, menimpa variabel OTEL_* yang developer atur secara lokal. Traces selain itu memerlukan CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 pada setiap klien. Gateway tidak mendorong variabel itu, jadi atur melalui blok env kebijakan terkelola. Ini tidak pada daftar aman CLI, jadi mengirimkannya melalui kebijakan dicakup oleh dialog security approval yang sama yang endpoint OTLP yang didorong sudah trigger. Kedua encoding OTLP protobuf dan JSON direlai, dan backend apa pun yang kompatibel dengan OpenTelemetry bekerja sebagai tujuan.

HTTP tuning

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

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.
gateway.yaml

Managed settings sisi client

Semua di atas mengonfigurasi gateway server. Menunjukkan developer machines ke sana dikonfigurasi secara terpisah, pada setiap device, melalui Claude Code’s managed settings. Gateway tidak dapat mendorong keys ini sendiri, karena mereka adalah apa yang memberitahu client di mana gateway berada. Untuk CLI, atur kedua keys dalam per-OS managed-settings.json:
Deploy file itu ke setiap device, typically via MDM platform Anda. File path berbeda by platform: forceLoginGatewayUrl, dan "gateway" value dari forceLoginMethod, dihormati hanya dari admin-controlled managed tier. Developer menetapkan mereka dalam ~/.claude/settings.json mereka sendiri tidak memiliki efek.