Skip to main content
Halaman ini mencakup sisi operasional menjalankan gateway aplikasi Claude: mendaftarkan klien OAuth di penyedia identitas (IdP) Anda, menyebarkan gateway sebagai kontainer, dan menjalankannya sehari-hari. Untuk setiap opsi dalam file gateway.yaml yang dibaca gateway saat boot, lihat Referensi Konfigurasi. Penyebaran produksi mengikuti empat langkah secara berurutan, dan bagian di bawah cocok dengan mereka. Dua yang pertama adalah tempat Anda membuat pilihan; dua yang kedua adalah materi referensi untuk dikonsultasikan setelah berjalan.
  1. Siapkan penyedia identitas Anda: daftarkan klien OAuth dan periksa catatan per-IdP untuk Okta, Entra, dan Google
  2. Sebarkan gateway: bangun gambar kontainer yang disematkan dan jalankan di Kubernetes, Cloud Run, atau platform Anda sendiri. Bagian ini juga mencakup keputusan biaya, bypass, gateway-ganda, dan serverless
  3. Siapkan operasi: log, probe kesehatan, perilaku pemadaman, rotasi rahasia, dan peningkatan. Referensi untuk ketika Anda menghubungkan pemantauan dan runbook
  4. Tinjau postur keamanan: aliran data ke mana, model ancaman, dan jawaban kepatuhan. Referensi untuk tinjauan keamanan
Jika masuk atau boot gagal di sepanjang jalan, langsung ke Troubleshooting, yang dikunci pada kesalahan yang Anda lihat.
Sebarkan di jaringan pribadi Anda. Claude Code hanya terhubung ke gateway yang alamatnya pribadi. Ini adalah penjaga keamanan, karena gateway yang dipercaya dapat mendorong pengaturan yang menjalankan perintah pada mesin pengembang. Letakkan gateway yang Anda sebarkan di belakang penyeimbang beban internal atau VPN dan berikan nama host yang hanya diselesaikan ke IP pribadi. Jika jaringan internal Anda bernomor dari ruang IPv4 publik yang dimiliki organisasi Anda, lihat Izinkan gateway pada ruang alamat publik yang Anda miliki.

​
Penyiapan penyedia identitas

Daftarkan aplikasi web OAuth/OpenID Connect (OIDC) rahasia dengan URI pengalihan tunggal, https://<gateway>/oauth/callback, dan tetapkan ke pengguna atau grup yang harus memiliki akses gateway. IdP apa pun yang sesuai dengan OIDC berfungsi: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate, dan lainnya. IdP harus memenuhi tiga persyaratan:
  • Melayani /.well-known/openid-configuration, melalui HTTPS dalam produksi; gateway menerima http:// issuer, dan issuer loopback juga memerlukan CLAUDE_GATEWAY_ALLOW_LOOPBACK=1
  • Mendukung aliran kode otorisasi. PKCE (Proof Key for Code Exchange) aktif secara default; nonaktifkan dengan oidc.use_pkce: false untuk IdP yang tidak mendukungnya
  • Mengembalikan email dan secara opsional groups dalam id_token, atau melayaninya dari endpoint userinfo dengan oidc.userinfo_fallback: true
Untuk PKI pribadi, atur oidc.ca_cert_pem. Beberapa penyedia menangani klaim email dan grup secara berbeda:
  • Okta: server otorisasi org di https://example.okta.com mengembalikan id_token tipis yang menghilangkan email dan groups, jadi atur oidc.userinfo_fallback: true kapan pun Anda menggunakannya sebagai issuer. Server otorisasi khusus seperti https://example.okta.com/oauth2/default yang menyertakan email dan secara opsional groups dalam id_token memancarkannya secara langsung dan tidak memerlukan fallback. Okta memancarkan groups hanya ketika scope groups diminta dalam oidc.scopes dan filter klaim grup aplikasi memungkinkannya; userinfo_fallback tidak dapat mengisi klaim yang IdP tidak diminta.
  • Microsoft Entra ID: issuer = https://login.microsoftonline.com/<tenant-id>/v2.0. Entra memancarkan Object ID grup daripada nama, jadi gunakan GUID dalam managed.policies.match.groups, atau gunakan App Roles untuk nama yang dapat dibaca manusia. Jika penyewa Anda memancarkan peran di bawah roles bukan groups, atur oidc.groups_claim: roles.
  • Google Workspace: issuer = https://accounts.google.com. id_token Google tidak membawa grup. Untuk menggunakan allowed_groups berbasis grup atau managed.policies dengan Google sebagai IdP, konfigurasikan oidc.google_groups, yang mencari grup setiap pengguna melalui Admin SDK Directory API menggunakan akun layanan dengan delegasi di seluruh domain. Tanpa itu, gunakan oidc.allowed_email_domains untuk gating keanggotaan dan managed.policies.match.email_domain untuk penugasan kebijakan. Google juga mengabaikan scope offline_access standar. Untuk token refresh, atur oidc.scopes: [openid, profile, email] dan oidc.extra_auth_params: { access_type: offline, prompt: consent }.
Token refresh memungkinkan gateway untuk memperbarui sesi pengembang secara diam-diam, tanpa mengirim pengembang kembali ke browser. Mereka juga mendorong deprovisioning, karena ketika IdP menonaktifkan pengguna, refresh berikutnya gagal dan sesi berakhir dalam ttl_hours. Gateway meminta offline_access secara default untuk mendapatkan token refresh. Jika IdP Anda memerlukan persetujuan eksplisit untuk akses offline, konfigurasikan klien OAuth untuk memungkinkannya.Jika IdP Anda tidak dapat mengeluarkan token refresh sama sekali, gateway masih berfungsi, tetapi tidak ada pembaruan diam-diam, jadi pengembang menjalankan kembali login browser ketika sesi mereka berakhir. Untuk mencegah itu terjadi setiap jam, naikkan session.ttl_hours ke 8 atau 12. Tradeoff adalah latensi deprovisioning, karena tanpa token refresh pengguna yang dinonaktifkan tetap memiliki akses sampai TTL yang lebih lama berlalu.

​
Penyebaran

Gateway adalah satu biner Linux stateless yang berkoordinasi melalui Postgres, jadi sebarkan dengan cara Anda menyebarkan layanan stateless lainnya di lingkungan Anda. Simpan di dalam jaringan Anda, di mana pengembang dan IdP Anda dapat menjangkaunya melalui HTTPS, dan perlakukan seperti layanan lainnya yang menyimpan kredensial produksi. Beberapa keputusan membentuk penyebaran di luar tempat berjalan:
  • Biaya: tidak ada lisensi terpisah atau biaya per-kursi. Gateway adalah bagian dari biner claude, jadi Anda membayar untuk inferensi melalui komitmen yang ada, ditambah komputasi yang dijalankannya.
  • Bypass: gateway tidak memberlakukan bahwa satu-satunya rute ke model melaluinya. Pengembang dengan kredensial mereka sendiri masih dapat memanggil penyedia secara langsung, jadi menutup jalur itu adalah keputusan kebijakan jaringan, misalnya memblokir egress ke api.anthropic.com kecuali dari gateway. Memblokir egress itu juga merusak pemeriksaan keamanan domain WebFetch, yang memanggil api.anthropic.com dari mesin setiap pengembang. Atur skipWebFetchPreflight: true dalam kebijakan terkelola untuk menonaktifkannya.
  • Multiple gateways: setiap adalah penyebaran terpisah dengan konfigurasinya sendiri, dan CLI menyimpan kepercayaan dan kredensial per nama host gateway, jadi tim dapat menggunakan gateway yang berbeda tanpa konflik. Untuk melayani beberapa issuer OIDC, jalankan instance terpisah.
  • Serverless: Cloud Run berfungsi jika Anda mengatur min-instances: 1 untuk menghindari penemuan OIDC dingin. Lambda dan Cloud Functions tidak berfungsi, karena gateway adalah server HTTP yang berjalan lama.
Setiap topologi produksi di sini menempatkan proxy L7, seperti Ingress, frontend Cloud Run, atau ALB, di depan replika HTTP biasa. Atur listen.trusted_proxies ke rentang sumber proxy sehingga gateway membaca IP klien dari X-Forwarded-For. Gateway menghormati header hanya ketika peer TCP dipercaya. Contoh yang dikerjakan Google Cloud dan AWS memiliki nilai konkret per topologi. Tanpa proxy terpercaya, setiap permintaan tampak berasal dari IP proxy, yang meruntuhkan batas laju per-IP menjadi satu bucket bersama dan mencatat IP proxy dalam acara audit. Jangan alihkan permintaan ke endpoint otorisasi perangkat dan token gateway, misalnya dengan penulisan ulang HTTP-ke-HTTPS atau kanonikalisasi host di ingress. Claude Code tidak mengikuti pengalihan pada permintaan tersebut, jadi aturan ingress yang mengalihkannya merusak sign-in dan penyegaran token. Berikan proxy waktu tunggu idle yang lebih lama dari interval keepalive gateway, yang bergantung pada upstream:
  • Pada setiap upstream kecuali provider: anthropic, gateway menulis SSE ping setelah aliran diam selama sekitar 15 detik.
  • Pada provider: anthropic, gateway melewatkan respons tanpa perubahan, termasuk ping API Anthropic sendiri.
Default seperti 60 detik ALB cukup untuk menjaga aliran yang tenang tetap terbuka. Contoh yang dikerjakan AWS menaikkannya hingga satu jam, dan baris pemecahan masalahnya mencakup gateway yang lebih lama dari v2.1.229, yang tidak mengirim apa pun selama periode tenang pada upstream yang sekarang mendapatkan ping.

​
Gambar kontainer

Bangun gambar Anda sendiri di sekitar biner claude asli dari rilis Claude Code standar:
  1. Unduh build Linux untuk arsitektur gambar Anda dari rilis yang disematkan; lihat Instal versi spesifik untuk URL unduhan.
  2. Verifikasi terhadap manifest.json yang ditandatangani GPG rilis seperti yang dijelaskan dalam Integritas biner dan penandatanganan kode.
  3. Salin ke konteks build.
Cerminkan rilis ke registri internal Anda jika build Anda tidak dapat menjangkau host rilis, dan sematkan versi yang dijalankan armada Anda. Di luar biner, gambar membutuhkan:
  • Gambar berbasis glibc: build glibc hanya memiliki dependensi dinamis perpustakaan glibc. Gambar berbasis Musl memerlukan build linux-x64-musl atau linux-arm64-musl ditambah paket tambahan; lihat Penyiapan Alpine Linux.
  • Direktori status yang dapat ditulis: gateway berjalan sebagai pengguna apa pun, tetapi gambar minimal tidak memiliki rumah yang dapat ditulis. Atur CLAUDE_CONFIG_DIR ke jalur yang dapat ditulis seperti /tmp/.claude.
  • Perintah kontainer: claude gateway --config /etc/claude/gateway.yaml, dengan file konfigurasi dipasang hanya-baca dan rahasia disuplai sebagai variabel lingkungan; gateway mendengarkan di listen.port, default 8080.

​
Kubernetes

Jalankan gateway sebagai Deployment, seperti layanan stateless apa pun:
  • Pasang konfigurasi dari ConfigMap dan rahasia dari Secret; referensikan rahasia dalam YAML melalui ${file:/path/to/secret} atau sebagai variabel lingkungan
  • Hentikan TLS di Ingress dan atur listen.public_url ke nama host Ingress
  • Arahkan probe kesiapan ke GET /readyz dan probe liveness ke GET /healthz
Untuk contoh lengkap yang dikerjakan di AWS, mencakup ECS Fargate atau EKS, Amazon RDS, dan AWS Secrets Manager, lihat Sebarkan di AWS. Lebih suka identitas beban kerja platform daripada kunci statis; referensi upstreams memiliki detail penyiapan per-platform. Untuk pasangan lintas cloud, seperti upstream Amazon Bedrock di GKE, atur kredensial eksplisit dalam blok auth upstream sebagai gantinya.

​
Cloud Run

Konfigurasikan layanan sebagai berikut:
  • Biarkan listen.port pada default 8080, yang cocok dengan PORT default Cloud Run, atau atur port: ${PORT}
  • Atur public_url ke asal yang dapat dijangkau secara eksternal. Untuk produksi ini biasanya nama host penyeimbang beban internal, karena /login menolak alamat publik dan URL *.run.app diselesaikan ke satu, jadi URL Cloud Run saja hanya berfungsi untuk uji coba curl atau browser. Pengecualiannya adalah jaringan di mana *.run.app diselesaikan secara pribadi melalui Private Service Connect dan zona pribadi Cloud DNS; dalam topologi itu URL Cloud Run adalah public_url yang valid. Contoh yang dikerjakan Google Cloud mencakup keduanya.
  • Pasang konfigurasi sebagai volume rahasia
  • Atur min-instances: 1 untuk menghindari penemuan OIDC dingin pada permintaan pertama
Untuk contoh lengkap yang dikerjakan di Google Cloud, mencakup Cloud Run atau GKE, Cloud SQL, dan Secret Manager, lihat Sebarkan di Google Cloud.

​
Dorong URL gateway ke mesin pengembang

Setelah gateway melayani, dorong forceLoginMethod, forceLoginGatewayUrl, dan parentSettingsBehavior: "merge" ke mesin setiap pengembang melalui pengaturan terkelola, melalui MDM atau dengan menulis managed-settings.json per-OS secara langsung. Tanpa ini, /login menampilkan pemilih akun standar tanpa opsi gateway. Setelah Anda menyebarkan kunci, Claude Code berhenti menggunakan kunci API sisa atau login claude.ai di mesin, jadi rencanakan push bersama dengan instruksi sign-in Anda. Kebijakan administrator memerlukan sign-in gateway Cloud menjelaskan pesan yang dilihat pengembang. Lihat di mana setiap mekanisme menyimpan kebijakan untuk jalur file, dan Pengaturan terkelola sisi klien untuk setara bootstrapUrl Claude Desktop.

​
Peluncuran besar

Sign-in dibatasi laju per alamat IP klien, dan default cocok untuk tim kecil. Setiap alamat mendapatkan 30 awal sign-in dan 10 pengajuan kode setiap 10 menit. Peluncuran ke ribuan pengembang dapat mencapai batas tersebut pada pagi pertama, karena salah satu dari dua alasan:
  • Gateway tidak dapat melihat melewati penyeimbang beban Anda. Tanpa listen.trusted_proxies, setiap pengembang tampak berasal dari alamat penyeimbang beban dan berbagi satu batas. Atur sebelum apa pun. Gateway mencatat peringatan pertama kali mengabaikan header X-Forwarded-For.
  • Banyak pengembang berbagi beberapa alamat egress NAT atau VPN. Mereka berbagi batas alamat tersebut bahkan ketika trusted_proxies benar. Naikkan rate_limits agar sesuai.
Untuk mengukur max, bagi pengembang dengan alamat egress yang mereka bagikan. Perkirakan berapa banyak dari mereka yang sign-in dalam satu periode window_seconds, yang default 10 menit. Kemudian gandakan untuk mencakup percobaan ulang dan pengembang yang sign-in ke Claude Code dan Claude Desktop. Sebagai contoh, 10.000 pengembang di belakang 4 alamat egress sign-in secara merata selama satu jam. Itu adalah 2.500 pengembang per alamat dan sekitar 420 dari mereka dalam setiap 10 menit, yang Anda gandakan dan bulatkan ke 1.000. Contoh di bawah menetapkan kedua batas ke 1.000:
device_verify adalah apa yang menghentikan seseorang dari menebak kode sign-in pengembang lain, jadi naikkan hanya sejauh perkiraan Anda membutuhkan. Bahkan pada batas ini, kode adalah 8 karakter dari alfabet 20 karakter dan kedaluwarsa setelah 10 menit, jadi menebak tetap tidak praktis; lihat Ketahanan brute-force kode pengguna. Ketika IdP Anda mengeluarkan token refresh, Claude Code memperbarui sesi secara diam-diam, jadi Anda dapat mengembalikan batas setelah peluncuran. Tanpa token refresh, pengembang sign-in lagi setiap session.ttl_hours. Ukur kedua batas untuk laju stabil itu juga dan biarkan mereka naik. Ketika batas tercapai, Claude Code v2.1.274 atau lebih baru menampilkan The gateway is limiting sign-in attempts right now. Gateway pada v2.1.274 atau lebih baru menampilkan Too many attempts came from your network address pada halaman verifikasi, dengan pengaturan untuk diperiksa. Ini juga menulis baris log sign-in refused yang menamai pengaturan untuk diubah.

​
Operasi

Setelah gateway melayani lalu lintas, operasi sehari-hari membaca lognya, menyelidiki kesehatannya, dan memutar rahasianya sesuai jadwal Anda. Subbagian mencakup masing-masing, ditambah apa yang disimpan Postgres dan bagaimana upgrade dan rollback berperilaku.

​
Log

Gateway menulis dua aliran ke stderr, keduanya ramah JSON:
  • Acara audit: JSON satu baris per acara yang relevan dengan keamanan. Pipa stderr ke agregator log Anda. Acara yang dipancarkan termasuk config.load, session.mint, session.refresh, device.authorize, device.verify, device.callback, auth.denied, access.denied, access.public_client, inference, managed.serve, desktop_bootstrap.serve, desktop_bootstrap.denied, spend.blocked, admin.denied, admin.limit.upsert, dan admin.limit.delete. Bidang bervariasi menurut acara:
    • Acara mint dan refresh yang berhasil membawa sub, email, client_ip, dan hasilnya
    • auth.denied dan access.denied membawa alasan dan IP klien, ditambah jalur permintaan untuk auth.denied, karena tidak ada identitas pengguna yang ada pada penolakan tersebut. Dua alasan access.denied mengubah apa yang dibawa acara:
      • xff_unparseable: acara juga membawa entri X-Forwarded-For yang tidak dapat dibaca
      • client_ip_unknown: acara tidak membawa IP klien, karena koneksi tidak memiliki alamat peer sementara daftar access_control ditetapkan
    • access.public_client membawa IP klien dari permintaan pertama per proses yang tiba dari alamat publik sementara access_control.allow_cidrs kosong. Gateway melayani permintaan seperti biasa; acara menandakan bahwa gateway mungkin dapat dijangkau dari internet publik. Lihat referensi access_control untuk apa yang dihitung sebagai publik dan untuk daftar izin yang direkomendasikan.
    • inference mencatat upstream mana yang melayani permintaan dan status respons
    • desktop_bootstrap.denied mencatat pengambilan bootstrap Claude Desktop yang ditolak dengan alasan (not_configured, policy_not_opted_in, atau no_policy_matched) dan identitas pengguna
    • admin.denied mencatat upaya autentikasi admin-API yang ditolak dengan IP klien, metode, jalur, dan alasan, tanpa materi kunci yang disajikan: invalid_key ketika x-api-key disajikan tetapi tidak cocok dengan kunci yang dikonfigurasi, bearer_rejected ketika hanya header Authorization yang disajikan dan tidak memverifikasi sebagai sesi gateway di admin.admin_groups, atau no_credentials ketika tidak ada header yang disajikan
  • Log operasional: baris yang dapat dibaca manusia dengan awalan [gateway] untuk boot, peringatan, dan kesalahan upstream. Variabel lingkungan CLAUDE_GATEWAY_LOG_LEVEL mengontrol verbositas dan menerima debug, info, warn, atau error, dengan info sebagai default. Pada debug, setiap sign-in dan refresh juga mencatat nama, bukan nilai, dari klaim dalam id_token, ditambah nama klaim userinfo ketika userinfo_fallback menyediakan apa pun, sehingga Anda dapat mendiagnosis pengaturan email_claim dan groups_claim tanpa mencatat PII. Ini tidak mempengaruhi acara audit, yang selalu dipancarkan.

​
Kesehatan

Gateway melayani GET /healthz sebagai probe liveness dan GET /readyz sebagai probe kesiapan. /readyz memverifikasi toko dapat dijangkau. Jika Anda menetapkan store.readiness_grace_seconds, /readyz terus melaporkan siap selama hingga banyak detik setelah toko berhenti menjawab. Kedua endpoint dikecualikan dari access_control.allow_cidrs, jadi probe terus bekerja pada pendengar yang terkunci. Dokumen penemuan OAuth di /.well-known/oauth-authorization-server juga mengembalikan 200 hanya setelah pemuatan konfigurasi, penemuan OIDC, konstruksi klien upstream, dan migrasi Postgres semua berhasil, jadi berfungsi ganda sebagai pemeriksaan boot end-to-end.

​
Permintaan upstream bersamaan

Secara default, setiap replika gateway mengirim paling banyak 256 permintaan upstream pada waktu yang sama. Respons streaming dihitung terhadap batas sampai aliran berakhir. Permintaan yang tiba sementara replika berada di batas menunggu di dalam gateway untuk slot gratis. Pengembang melihat respons yang lambat dimulai atau tampak hang. Pada upstream provider: anthropic, permintaan yang menunggu lebih lama dari timeouts.upstream_ttfb_ms menyerah pada upstream itu, dan gagal dengan 502 ketika tidak ada upstream yang melayaninya kemudian. Baris log startup yang berisi upstream requests: menunjukkan batas yang berlaku. Sementara replika memiliki lebih banyak permintaan terbuka daripada batas, itu juga mencatat peringatan yang berisi client requests are open, paling banyak sekali per menit. Untuk melayani lebih banyak permintaan sekaligus, Anda memiliki dua opsi:
  • Tambahkan replika.
  • Naikkan batas pada setiap replika. Atur variabel lingkungan BUN_CONFIG_MAX_HTTP_REQUESTS pada kontainer gateway ke angka bulat dari 1 hingga 65535, kemudian mulai ulang kontainer.
Replika mengisi batasnya pada tingkat permintaan sekitar batas dibagi dengan rata-rata jumlah detik permintaan tetap terbuka. Misalnya, jika permintaan tetap terbuka selama 10 detik rata-rata, replika pada batas default 256 mengisinya pada sekitar 26 permintaan per detik. Jika Anda autoscale pada CPU, replika di batas mengantrekan permintaan tanpa memicu scale-out, jadi atur target di bawah level CPU yang ditunjukkan replika Anda ketika mereka mencatat peringatan client requests are open.
Setiap permintaan terbuka menyimpan memori dalam proses gateway sementara itu streaming dan sementara menunggu slot. Jika Anda menyimpan batas pada 256, memori pada replika yang kelebihan beban masih tumbuh, karena permintaan yang menunggu menyimpan badan permintaan mereka. Ukuran memori kontainer untuk jumlah permintaan terbuka di puncak, dan pantau memori ketika Anda mengubah batas. Replika yang kehabisan memori dibunuh dan menjatuhkan setiap aliran yang dipegang.

​
Perilaku pemadaman

Jika Postgres turun, gateway itu sendiri terus melayani pengembang yang masuk dan masuk baru gagal. Apakah pengembang benar-benar terus bekerja tergantung pada bagaimana orchestrator Anda menangani kesiapan:
  • Sesi yang ada: token pembawa memvalidasi secara lokal dengan rahasia JWT, penyegaran sesi tidak menyentuh toko, dan proses gateway masih dapat melayani inferensi
  • Masuk baru: gagal sampai Postgres pulih, karena aliran perangkat dan penghitung batas lajunya tinggal di Postgres
  • Penegakan batas pengeluaran: gagal terbuka secara default selama pemadaman, jadi inferensi masih mengalir; balikkan ke gagal tertutup jika Anda lebih suka memblokir daripada menjalankan tanpa meter
  • Kesiapan: secara default /readyz melaporkan tidak siap segera setelah Postgres tidak dapat dijangkau, jadi setiap replika gagal pemeriksaan kesiapannya sekaligus. Di mana lalu lintas hanya mencapai replika yang lulus pemeriksaan, semua lalu lintas, termasuk inferensi yang masih dapat dilayani gateway, gagal sampai Postgres pulih. Probe liveness di /healthz terus lulus sepanjang waktu.
Jika IdP Anda turun, sesi yang ada bekerja sampai ttl_hours dan masuk baru gagal. Penyegaran sesi mendapat jawaban coba-lagi dan berjalan setelah IdP kembali. Atur ttl_hours yang lebih lama jika IdP Anda memiliki jendela pemeliharaan yang sering.

​
Periode grace kesiapan

Untuk menjaga pengembang yang masuk tetap bekerja melalui pemadaman Postgres yang singkat seperti failover database, atur store.readiness_grace_seconds lebih lama dari waktu yang diperlukan failover, misalnya 300. Dengan batas pengeluaran aktif dan perilaku gagal-terbuka default, permintaan melalui replika yang tetap siap tidak diukur sampai Postgres pulih, jadi simpan nilai serendah yang mencakup failover Anda. Jika Anda menetapkan enforcement.fail_closed_on_error: true, gateway menolak inferensi pengembang yang masuk dengan pesan 429 spend limit unavailable sampai Postgres pulih, bahkan sementara replika masih lulus pemeriksaan kesiapan mereka. Pengaturan memerlukan Claude Code v2.1.282 atau lebih baru pada server gateway. Gateway yang lebih awal menolak untuk memulai ketika menemukan kunci, jadi upgrade setiap replika sebelum Anda menambahkannya. Upgrade mencakup rollback. Jika Anda menunjukkan probe kesiapan ke /healthz sebagai gantinya, replika juga terus lulus melalui pemadaman, tetapi /healthz tidak pernah melaporkan tidak siap, jadi replika yang koneksi Postgres-nya tidak pulih terus lulus juga.

​
Rotasi rahasia JWT

Putar rahasia penandatanganan dalam tiga langkah sehingga sesi yang ada tetap valid:
  1. Hasilkan rahasia baru. Tambahkan ke depan array session.jwt_secret.
  2. Gulung penyebaran. Token baru menandatangani dengan rahasia baru; token lama masih memverifikasi.
  3. Setelah ttl_hours ditambah margin, hapus rahasia lama dan gulung lagi.
Rotasi juga satu-satunya cara untuk memaksa sesi keluar sebelum mereka berakhir: token pembawa memvalidasi secara lokal terhadap rahasia JWT, jadi tidak ada pencabutan per-sesi. Mengganti rahasia sepenuhnya, tanpa menyimpan yang lama dalam array, membatalkan setiap sesi yang luar biasa sekaligus. Untuk offboarding individual, deprovision pengguna di IdP Anda; sesi mereka berakhir dalam ttl_hours.

​
Postgres

Gateway menyimpan lima tabel data ditambah tabel _migrations, semuanya dibuat oleh migrasi waktu boot-nya: Loop 30 detik mengakhiri baris kv melewati TTL mereka, dan sapuan per jam memberlakukan jendela retensi pada tabel pengeluaran, jadi tidak ada yang tumbuh tanpa batas. Tanpa batas pengeluaran yang dikonfigurasi, hanya kv yang ditulis. Gateway menerapkan migrasi skema sendiri saat boot dan pada setiap upgrade, jadi peran database-nya memerlukan hak untuk membuat dan mengubah tabel. Arahkan ke database atau skema yang didedikasikan untuk gateway untuk menjaga hibah tetap sempit. Dengan batas pengeluaran digunakan, database yang hilang berarti pelacakan pengeluaran dan batas yang hilang, bukan hanya login ulang pengembang, jadi jalankan backup reguler. Untuk menghapus satu pengembang yang pergi segera daripada menunggu retensi, jalankan DELETE FROM principal_emails WHERE principal = '<sub>' secara langsung; itu menghapus satu-satunya tabel yang menyimpan email, nama, dan grup mereka. Baris spend dan admin_audit mereferensikan hanya sub OIDC pseudonim.

​
Upgrade

Replika tidak memiliki status, jadi restart bergulir tidak kehilangan status gateway. Gateway menjalankan migrasi skema saat boot, yang berarti menyebarkan biner baru secara otomatis memigrasikan database. Replika bersamaan menserialisasi pada kunci advisory Postgres, jadi hanya satu yang menerapkan setiap migrasi. Ketika orchestrator Anda menghentikan replika dengan SIGTERM, seperti dalam restart bergulir atau scale-in, gateway berhenti menerima koneksi baru dan membiarkan permintaan dan aliran yang sudah dalam penerbangan selesai sebelum keluar. Itu menunggu hingga 25 detik, disebut jendela drain, kemudian menutup apa pun yang masih terbuka. SIGINT, seperti Ctrl+C di terminal, memulai drain yang sama, dan sinyal kedua selama drain menutup permintaan terbuka dan keluar langsung. Draining memerlukan gateway v2.1.274 atau lebih baru. Generasi panjang dapat streaming selama berapa menit. Pada Kubernetes dan Amazon ECS, naikkan keduanya bersama-sama untuk memberikan aliran tersebut lebih banyak waktu:
  • Jendela drain: atur variabel lingkungan CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS pada kontainer gateway ke angka bulat positif milidetik, seperti 120000. Gateway mengabaikan nilai dalam bentuk apa pun, seperti 120s, dan menyimpan default 25 detik
  • Periode grace orchestrator Anda: terminationGracePeriodSeconds pada Kubernetes, atau stopTimeout pada Amazon ECS
Periode grace default ke 30 detik di kedua platform. Simpan setidaknya 5 detik lebih lama dari jendela drain, atau orchestrator membunuh gateway sebelum drain selesai. Pada Kubernetes, tambahkan durasi hook preStop apa pun juga, karena periode grace mulai menghitung sebelum hook berjalan daripada ketika gateway menerima SIGTERM. Platform Anda juga dapat membatasi berapa lama drain dapat berjalan:
  • Amazon ECS on Fargate: stopTimeout memungkinkan paling banyak 120 detik
  • Cloud Run: menghentikan instance 10 detik setelah SIGTERM, jadi aliran terbuka mendapat paling banyak 10 detik di sana, apa pun jendela drain-nya
Ketika jendela drain berakhir dengan permintaan masih terbuka, gateway mencatat peringatan yang berisi drain window over after, menghitung permintaan yang dipotongnya, dan menamai kedua pengaturan untuk dinaikkan. Migrasi adalah append-only, jadi rollback ke biner sebelumnya yang mengetahui lebih sedikit migrasi aman; itu mengabaikan baris ekstra. Rollback juga memvalidasi ulang YAML terhadap skema biner yang lebih lama, jadi konfigurasi yang mengadopsi kunci yang diperkenalkan oleh rilis yang lebih baru gagal boot pada yang lebih lama. Hapus kunci baru sebelum rollback. Karena Anda menyematkan versi gateway dalam gambar Anda sendiri, perbaikan dalam rilis Claude Code baru, termasuk perbaikan keamanan, mencapai penyebaran Anda hanya ketika Anda memperbarui pin dan menyebarkan ulang. Sertakan gateway dalam kadence patching yang sama yang Anda gunakan untuk layanan lain yang menyimpan kredensial produksi.

​
Keamanan

Bagian ini menjawab pertanyaan yang ditanyakan tinjauan keamanan: aliran data apa melalui gateway dan ke mana perginya, serangan mana yang dipertahankan desain, dan jawaban mana yang termasuk dalam kuesioner kepatuhan.

​
Aliran data

​
Ringkasan model ancaman

Gateway duduk di dalam perimeter jaringan Anda, tetapi laptop pengembang individual tidak diperlakukan sebagai terpercaya. Desain memperhitungkan ini dalam tiga cara:
  • Pengembang menyimpan JWT berumur pendek bukan kunci upstream mentah. Leg CLI-ke-gateway menggunakan hibah perangkat RFC 8628, dan pertukaran kode otorisasi gateway dengan IdP menjalankan PKCE dalam konfigurasi default, jadi kode otorisasi IdP yang disadap tidak berguna.
  • Halaman verifikasi perangkat memberlakukan POST asal-sama dan batas laju per-IP per RFC 8628 §5.1. Lihat Resistansi brute-force kode pengguna.
  • Permintaan gateway ke IdP Anda, kolektor OTLP Anda, dan upstream provider: anthropic melalui penjaga server-side request forgery (SSRF) yang menyelesaikan DNS, memblokir alamat link-lokal dan cloud-metadata ditambah loopback secara default, dan menyematkan koneksi ke IP yang diselesaikan, jadi URL yang dipengaruhi operator tidak dapat dialihkan ke endpoint metadata cloud. Rentang pribadi RFC 1918 secara sengaja diizinkan, karena IdP dan kolektor OTLP biasanya tinggal di IP pribadi. Untuk penyedia lainnya, gateway menolak base_url yang menamai salah satu alamat tersebut atau nama host metadata saat memuat konfigurasi, dan SDK penyedia kemudian terhubung tanpa pemeriksaan DNS. Jika Anda mengaktifkan egress hanya-proxy, pemeriksaan alamat itu berpindah ke proxy forward Anda: gateway menyerahkan nama host dan daftar izin proxy harus menolak tujuan tersebut. Atur CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 dalam lingkungan gateway hanya ketika sesuatu yang harus dijangkau gateway secara sah tinggal di loopback, seperti IdP pengembangan lokal atau kolektor OTLP sidecar di localhost. Variabel ini melonggarkan blok loopback untuk setiap URL yang dikonfigurasi operator dan juga melewati peringatan waktu boot yang memeriksa apakah pod dapat menjangkau endpoint metadata cloud, jadi lebih baik memberikan kolektor alamat internal sendiri.
Jika Anda menambahkan kontrol egress Anda sendiri, gateway harus menjangkau server metadata kapan pun menggunakan kredensial metadata instance seperti identitas beban kerja. Dua ancaman berada di luar cakupan karena mereka adalah infrastruktur Anda untuk diamankan:
  • Host gateway yang dikompromikan: host menyimpan kredensial upstream dan mendistribusikan pengaturan terkelola ke setiap pengembang yang terhubung, jadi kontrol atas konfigurasi gateway sebanding dengan kontrol atas MDM Anda. Dialog persetujuan CLI untuk pengaturan yang mampu shell membatasi perubahan diam-diam tetapi tidak menggantikan keamanan host.
  • Penyedia OIDC yang berbahaya: penyedia menandatangani id_token yang dipercaya gateway, jadi dapat menegaskan identitas apa pun. Penyaringan dan pengamanan IdP Anda adalah tanggung jawab Anda.

​
Resistansi brute-force kode pengguna

user_code yang diketik pengembang ke halaman verifikasi /device adalah 8 karakter yang diambil dari alfabet 20 karakter, yang menghasilkan 20⁸ atau sekitar 2,56×10¹⁰ kombinasi, dan berakhir setelah 10 menit. Gateway menerapkan batas laju per-IP pada endpoint hibah perangkat, dapat dikonfigurasi melalui rate_limits. Naikkan batas jika banyak pengembang masuk dari alamat NAT korporat bersama tunggal. Peluncuran besar menunjukkan cara mengukurnya. Batas hanya berlaku pada aliran masuk, bukan pada inferensi.

​
Postur kepatuhan

  • Residensi data: bidang data sendiri gateway mengirim tidak ada ke Anthropic kecuali API Anthropic adalah upstream yang dikonfigurasi; ketika itu, perjanjian penanganan data yang ada berlaku untuk jalur inferensi. Telemetri, audit, identitas, dan pengaturan hanya pergi ke tujuan yang Anda konfigurasikan.
  • Lalu lintas proses host: proses host adalah Claude Code CLI. claude gateway berjalan di bawah aturan pihak ketiga yang sama seperti Amazon Bedrock dan penyebaran Agent Platform Google Cloud dan mengirim tidak ada ke Anthropic. Sebelum v2.1.227, proses host mengirim telemetri startup seperti versi produk dan platform, yang pengaturan CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 dalam lingkungan kontainer mematikan. Rilis tersebut juga mengirim satu permintaan HEAD saat boot, tanpa body atau kredensial, ke /api/hello di https://api.anthropic.com, atau di ANTHROPIC_BASE_URL ketika lingkungan menetapkannya, kecuali lingkungan juga menetapkan variabel proxy seperti HTTPS_PROXY atau sertifikat klien mTLS. Mereka mengabaikan respons, jadi memblokir permintaan itu di firewall egress tidak mempengaruhi gateway.
  • Analitik klien: CLI menonaktifkan analitik penggunaan sendiri dan pelaporan kesalahan saat masuk ke gateway. Sebelum masuk pertama kali, CLI masih mengirim acara startup ke Anthropic, termasuk pada mesin yang pengaturan terkelola memaksa masuk gateway. Untuk menjaga itu juga, berikan DISABLE_TELEMETRY dalam pengaturan terkelola sisi klien yang sama yang memaksa masuk gateway.
  • Pelaporan kesalahan: CLI mematikan pelaporan kesalahan kapan pun permintaan model perginya ke endpoint apa pun selain API pihak pertama Anthropic, seperti Amazon Bedrock atau ANTHROPIC_BASE_URL kustom.
  • Mesin klien: CLI pengembang masih mengirim pemeriksaan nama host WebFetch dan pemeriksaan versi ke Anthropic kecuali CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 dan skipWebFetchPreflight: true diatur. Lihat penggunaan data.
  • Peringkat survei: saat masuk ke gateway, CLI menonaktifkan unggahan peringkat terikat Anthropic bersama dengan aliran analitik, jadi tidak mengirim peringkat ke Anthropic.
  • Berbagi transkrip: memilih Ya pada prompt berbagi transkrip survei menulis file lokal di bawah ~/.claude/feedback-bundles/ bukan mengunggah ke Anthropic.
  • Pembaruan klien: pemeriksaan pembaruan terpisah dari lalu lintas gateway. Sematkan versi melalui distribusi Anda sendiri dan atur DISABLE_UPDATES jika laptop tidak boleh mengambil rilis. DISABLE_AUTOUPDATER menghentikan hanya pembaruan latar belakang sementara claude update masih berfungsi.
  • TLS: layani public_url melalui HTTPS dalam produksi, baik dari pendengar gateway sendiri melalui listen.tls atau dari ingress yang menghentikan TLS di depan replika HTTP biasa, dengan listen.public_url diatur dalam kedua kasus. Gateway tidak menolak HTTP biasa. IdP harus melayani HTTPS dalam produksi, dan Postgres mendukung ?sslmode=require. Atur Strict-Transport-Security di ingress Anda.
  • Pengungkapan kerentanan: ikuti Melaporkan masalah keamanan

​
Troubleshooting

Untuk pertanyaan dan umpan balik, gunakan dukungan Claude Code, atau buka masalah di repositori GitHub Claude Code. Saat melaporkan masalah, sertakan:
  • Masalah gateway: stderr gateway untuk jendela yang relevan, gateway.yaml Anda dengan rahasia diedit, versi gateway, ditampilkan di halaman pendaratan di / dan dalam header respons x-cc-gateway-version di /managed/settings, dan apa yang berubah baru-baru ini
  • Masalah login: pengembang menjalankan claude --debug-file ./claude-debug.txt, mereproduksi, dan mengirim file itu ditambah log audit gateway untuk jendela yang sama
  • Masalah inferensi: model yang diminta, upstream yang dikonfigurasi, dan log audit gateway untuk permintaan, yang mencatat upstream mana yang melayaninya dan status respons
Stderr gateway mencakup aliran acara audit, log audit mencatat identitas pengembang, dan file debug mencatat output hook dan server MCP dari mesin pengembang. Tinjau dan redaksi ini sebelum memposting ke issue publik. Pesan Cloud gateway sign-in was not completed menamai nama host gateway. Ketika Claude Code memiliki sidik jari yang di-pin dan yang disajikan, pesan juga menampilkan 16 karakter pertama dari masing-masing. Jika Claude Code melaporkan couldn't load your organization's managed settings setelah masuk gateway, Claude Code menamai alasannya, memulai ulang di tempat, dan melanjutkan percakapan. Jika Claude Code tidak dapat memulai ulang, misalnya dalam sesi latar belakang, Claude Code mengakhiri sesi dan menyimpan masuk.