SpyBara
Go Premium

claude-apps-gateway-deploy.md 2026-11-10 21:57 UTC to 2026-11-11 22:59 UTC

This page contains 138 additions and 138 deletions.

2026
Mon 2 23:57 Wed 4 23:59 Fri 6 23:01 Mon 9 23:02 Wed 11 22:59 Fri 13 01:02

Penyebaran dan operasi gateway aplikasi Claude

Daftarkan gateway dengan IdP Anda, bangun kontainer, sebarkan di Kubernetes atau Cloud Run, dan operasikan: pemeriksaan kesehatan, rotasi rahasia, peningkatan, dan keamanan.

[!NOTE]

Rencanakan jaringan gateway Anda terlebih dahulu. Saat masuk, Claude Code menolak gateway aplikasi Claude yang nama host-nya di-resolve ke alamat IP publik, bahkan yang tidak dapat dijangkau dari internet.

Gateway aplikasi Claude dapat mendorong pengaturan ke mesin pengguna, termasuk hook yang menjalankan perintah shell. Pemeriksaan ini membantu mencegah pengguna secara tidak sengaja masuk ke gateway berbahaya di internet publik. Jauhkan juga gateway Anda sendiri dari internet.

Pilih alamat gateway sebelum Anda memilih tempat menjalankannya. Biasanya, itu adalah alamat privat yang dijangkau pengguna di jaringan internal Anda atau melalui VPN. Jika jaringan internal Anda menggunakan rentang IPv4 publik, Anda dapat mencantumkan satu rentang yang mencakup gateway dan mesin pengguna Anda. Claude Code menganggap kecocokan tersebut sebagai tanda bahwa gateway berada di jaringan internal Anda. Lihat Pilih alamat untuk gateway. Jika tidak ada yang sesuai dengan jaringan Anda, hubungi tim akun Anthropic Anda.

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.

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. Gateway melakukan autentikasi ke IdP dengan client secret dari pendaftaran tersebut, atau dengan sertifikat yang Anda unggah ke pendaftaran jika IdP Anda menggunakan kredensial sertifikat sebagai gantinya.

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

[!WARNING]

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.

Deployment

Gateway adalah satu binary Linux stateless yang berkoordinasi melalui Postgres, jadi deploy gateway dengan cara yang sama seperti Anda men-deploy layanan stateless lainnya di lingkungan Anda. Tempatkan gateway di dalam jaringan Anda, di mana developer Anda dapat menjangkaunya melalui HTTPS dan gateway dapat menjangkau IdP Anda, dan perlakukan gateway seperti layanan apa pun yang menyimpan kredensial produksi.

Beberapa keputusan membentuk deployment di luar tempat gateway dijalankan:

  • Biaya: tidak ada lisensi terpisah atau biaya per kursi. Gateway merupakan bagian dari binary claude, jadi Anda membayar inferensi melalui komitmen yang sudah ada, ditambah komputasi tempat gateway berjalan.
  • Bypass: gateway tidak memaksakan bahwa satu-satunya rute ke model harus melewatinya. Developer yang memiliki kredensial sendiri tetap dapat memanggil penyedia secara langsung, jadi menutup jalur tersebut merupakan keputusan kebijakan jaringan, misalnya memblokir egress ke api.anthropic.com kecuali dari gateway. Memblokir egress tersebut juga merusak pemeriksaan keamanan domain WebFetch, yang memanggil api.anthropic.com dari mesin setiap developer. Atur skipWebFetchPreflight: true dalam kebijakan terkelola untuk menonaktifkannya.
  • Beberapa gateway: masing-masing merupakan deployment terpisah dengan konfigurasinya sendiri, dan CLI menyimpan kepercayaan serta kredensial per hostname gateway, sehingga tim dapat menggunakan gateway yang berbeda tanpa konflik. Untuk melayani beberapa penerbit OIDC, jalankan instance terpisah.
  • Serverless: Cloud Run dapat digunakan jika Anda mengatur min-instances: 1 untuk menghindari OIDC discovery dalam kondisi cold. Lambda dan Cloud Functions tidak dapat digunakan, karena gateway adalah server HTTP yang berjalan lama.

Setiap topologi produksi di sini menempatkan proxy L7, seperti Ingress, front end Cloud Run, atau ALB, di depan replika HTTP biasa. Atur listen.trusted_proxies ke rentang sumber proxy agar gateway membaca IP klien dari X-Forwarded-For. Gateway hanya menghormati header tersebut ketika peer TCP tepercaya. Contoh lengkap Google Cloud dan AWS memiliki nilai konkret per topologi. Tanpa trusted proxies, setiap permintaan tampak berasal dari IP proxy, yang menyatukan rate limit per IP menjadi satu bucket bersama dan mencatat IP proxy dalam event audit.

Jangan mengalihkan permintaan ke endpoint otorisasi perangkat dan token milik gateway, misalnya dengan penulisan ulang HTTP-ke-HTTPS atau kanonikalisasi host di ingress. Claude Code tidak mengikuti pengalihan pada permintaan tersebut, sehingga aturan ingress yang mengalihkannya akan merusak proses masuk dan penyegaran token.

Berikan proxy idle timeout apa pun yang lebih lama daripada interval keepalive gateway, yang bergantung pada upstream:

  • Pada setiap upstream kecuali provider: anthropic, gateway menulis SSE ping setelah stream diam selama sekitar 15 detik.
  • Pada provider: anthropic, gateway meneruskan respons tanpa perubahan, termasuk ping milik Anthropic API sendiri.

Nilai default seperti 60 detik pada ALB sudah cukup untuk menjaga stream yang sepi tetap terbuka. Contoh lengkap AWS tetap menaikkannya menjadi satu jam, dan baris pemecahan masalahnya mencakup gateway yang lebih lama dari v2.1.229, yang tidak mengirim apa pun selama periode sepi pada upstream yang sekarang mendapatkan ping.

Memilih alamat untuk gateway

Claude Code menerima alamat gateway dengan salah satu dari dua cara:

  • Alamat privat: tempatkan gateway di belakang load balancer internal atau VPN, dengan hostname yang hanya di-resolve ke alamat privat, seperti RFC 1918 atau CGNAT 100.64.0.0/10. Mesin pengguna dapat berada di alamat apa pun. Prasyarat jaringan privat mencantumkan rentang yang diterima.
  • Blok yang dideklarasikan: jika jaringan internal Anda menggunakan ruang IPv4 publik yang dimiliki organisasi Anda, cantumkan blok tersebut dalam pengaturan terkelola gatewayInternalNetworks. Gateway dan mesin pengguna harus sama-sama berada dalam blok tersebut. Lihat Mengizinkan gateway pada ruang alamat publik yang Anda miliki.

Jika tidak ada satu blok pun yang mencakup keduanya, berikan gateway alamat privat sebagai gantinya.

Image container

Buat image Anda sendiri di sekitar binary native claude dari rilis standar Claude Code:

  1. Unduh build Linux untuk arsitektur image Anda dari rilis yang disematkan; lihat Menginstal versi tertentu untuk URL unduhan.
  2. Verifikasi build tersebut terhadap manifest.json rilis yang ditandatangani GPG seperti yang dijelaskan dalam Integritas binary dan penandatanganan kode.
  3. Salin ke dalam konteks build.

Cerminkan rilis ke registry internal Anda jika build Anda tidak dapat menjangkau host rilis, dan sematkan versi yang dijalankan oleh armada Anda.

Selain binary, image memerlukan:

  • Image berbasis glibc: satu-satunya dependensi dinamis dari build glibc adalah library glibc. Image berbasis musl memerlukan build linux-x64-musl atau linux-arm64-musl ditambah paket tambahan; lihat Penyiapan Alpine Linux.
  • Direktori state yang dapat ditulis: gateway berjalan sebagai pengguna apa pun, tetapi image minimal tidak memiliki direktori home yang dapat ditulis. Atur CLAUDE_CONFIG_DIR ke path yang dapat ditulis seperti /tmp/.claude.
  • Perintah container: claude gateway --config /etc/claude/gateway.yaml, dengan file konfigurasi di-mount secara read-only dan secret disediakan sebagai environment variable; gateway mendengarkan pada listen.port, default 8080.

Kubernetes

Jalankan gateway sebagai Deployment, seperti layanan stateless lainnya:

  • Mount konfigurasi dari ConfigMap dan secret dari Secret; rujuk secret dalam YAML melalui ${file:/path/to/secret} atau sebagai environment variable
  • Terminasi TLS di Ingress dan atur listen.public_url ke hostname Ingress
  • Arahkan readiness probe ke GET /readyz dan liveness probe ke GET /healthz

Untuk contoh lengkap di AWS, yang mencakup ECS Fargate atau EKS, Amazon RDS, dan AWS Secrets Manager, lihat Deploy di AWS.

Utamakan workload identity platform dibandingkan 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 milik upstream sebagai gantinya.

Cloud Run

Konfigurasikan layanan sebagai berikut:

  • Biarkan listen.port pada nilai default 8080, yang sesuai dengan PORT default Cloud Run, atau atur port: ${PORT}
  • Atur public_url ke origin yang dapat dijangkau dari luar. Untuk produksi, ini biasanya hostname load balancer internal, karena /login menolak alamat publik dan URL *.run.app di-resolve ke alamat publik, sehingga URL Cloud Run saja hanya dapat digunakan untuk smoke test dengan curl atau browser. Pengecualiannya adalah jaringan tempat *.run.app di-resolve secara privat melalui Private Service Connect dan zona privat Cloud DNS; dalam topologi tersebut, URL Cloud Run merupakan public_url yang valid. Contoh lengkap Google Cloud mencakup keduanya.
  • Mount konfigurasi sebagai volume secret
  • Atur min-instances: 1 untuk menghindari OIDC discovery dalam kondisi cold pada permintaan pertama

Untuk contoh lengkap di Google Cloud, yang mencakup Cloud Run atau GKE, Cloud SQL, dan Secret Manager, lihat Deploy di Google Cloud.

Mendorong URL gateway ke mesin developer

Setelah gateway melayani, dorong forceLoginMethod, forceLoginGatewayUrl, dan parentSettingsBehavior: "merge" ke mesin setiap developer melalui pengaturan terkelola, melalui MDM atau dengan menulis managed-settings.json per OS secara langsung.

Setelah Anda men-deploy kunci-kunci tersebut, Claude Code berhenti menggunakan kunci API atau login claude.ai yang tersisa di mesin, jadi rencanakan pendorongan ini bersama dengan instruksi masuk Anda. Administrator policy requires a Cloud gateway sign-in menjelaskan pesan yang dilihat developer.

Lihat tempat setiap mekanisme menyimpan kebijakan untuk path file, dan Pengaturan terkelola sisi klien untuk padanan bootstrapUrl di Claude Desktop.

Peluncuran berskala besar

Proses masuk dikenai rate limit per alamat IP klien, dan nilai default-nya cocok untuk tim kecil. Setiap alamat mendapatkan 30 permulaan masuk dan 10 pengiriman kode setiap 10 menit. Peluncuran ke ribuan developer dapat mencapai batas tersebut pada pagi pertama, karena salah satu dari dua alasan:

  • Gateway tidak dapat melihat melewati load balancer Anda. Tanpa listen.trusted_proxies, setiap developer tampak berasal dari alamat load balancer dan berbagi satu batas. Gateway menulis peringatan ke log pertama kali ia mengabaikan header X-Forwarded-For. Jika load balancer seharusnya ada di listen.trusted_proxies, cantumkan load balancer tersebut sebelum Anda mengubah hal lainnya. Jika developer masih berbagi satu alamat, naikkan rate_limits.
  • Banyak developer berbagi beberapa alamat egress NAT atau VPN. Mereka berbagi batas dari alamat-alamat tersebut bahkan ketika trusted_proxies sudah benar. Naikkan rate_limits agar sesuai.

Untuk menentukan ukuran max, bagi jumlah developer dengan jumlah alamat egress yang mereka gunakan bersama. Perkirakan berapa banyak dari mereka yang masuk dalam satu periode window_seconds, yaitu 10 menit secara default. Kemudian gandakan untuk mencakup retry dan developer yang masuk ke Claude Code maupun Claude Desktop.

Sebagai contoh, 10.000 developer di belakang 4 alamat egress masuk secara merata selama satu jam. Itu berarti 2.500 developer per alamat dan sekitar 420 di antaranya dalam setiap 10 menit, yang Anda gandakan dan bulatkan ke atas menjadi 1.000. Contoh di bawah ini mengatur kedua batas menjadi 1.000:

rate_limits:
  device_authorization: { max: 1000, window_seconds: 600 }
  device_verify: { max: 1000, window_seconds: 600 }

device_verify adalah yang mencegah seseorang menebak kode masuk milik developer lain, jadi naikkan hanya sejauh yang dibutuhkan oleh perkiraan Anda. Bahkan pada batas ini, sebuah kode terdiri dari 8 karakter dari alfabet 20 karakter dan kedaluwarsa setelah 10 menit, sehingga menebak tetap tidak praktis; lihat Ketahanan kode pengguna terhadap brute-force.

Ketika IdP Anda menerbitkan refresh token, Claude Code memperbarui sesi secara diam-diam, sehingga Anda dapat mengembalikan batas setelah peluncuran. Tanpa refresh token, developer masuk kembali setiap session.ttl_hours. Tentukan ukuran kedua batas untuk laju tetap tersebut juga dan biarkan tetap dinaikkan.

Ketika batas tercapai, Claude Code v2.1.274 atau yang lebih baru menampilkan The gateway is limiting sign-in attempts right now. Gateway pada v2.1.274 atau yang lebih baru menampilkan Too many attempts came from your network address pada halaman verifikasi, beserta pengaturan yang perlu diperiksa. Gateway juga menulis baris log sign-in refused yang menyebutkan pengaturan yang perlu 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
    • guardrail.trace mencatat filter mana yang terpicu, tanpa teks yang cocok
    • 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.

Tulis log operasional sebagai JSON

Jika pengumpul log Anda membaca level setiap baris dari bidang JSON, atur CLAUDE_GATEWAY_LOG_FORMAT=json di environment gateway. Memerlukan Claude Code v2.1.319 atau lebih baru pada server gateway.

Setiap baris log operasional kemudian menjadi satu objek dengan severity, time, dan message:

{"severity":"INFO","time":"2026-11-04T17:03:21.512Z","message":"claude gateway listening on http://0.0.0.0:8080"}

severity adalah level log dalam huruf kapital, dengan warn ditulis sebagai WARNING. Start yang gagal berupa baris ERROR.

Acara audit, yang juga dikirim ke stderr, tidak berubah. Acara tersebut membawa ts dan evt, dan tidak membawa severity.

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.

[!WARNING]

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.

Dalam uji beban dengan load_test_mode, permintaan tidak menunggu pada batas ini, tetapi replika tetap mencatat peringatan client requests are open.

Pertahankan API_TIMEOUT_MS di atas waktu hingga byte pertama gateway

Jika Anda menurunkan API_TIMEOUT_MS untuk mencoba ulang permintaan yang tidak terjawab lebih cepat, pertahankan nilainya di atas waktu yang dibutuhkan gateway untuk mengirim byte pertama dari respons streaming. Permintaan yang menunggu lebih lama akan mengalami timeout, begitu pula setiap retry yang menunggu selama itu, hingga giliran berakhir dengan Request timed out kecuali tenggat byte pertama mengakhirinya.

  • provider: anthropic: atur API_TIMEOUT_MS di atas waktu terlama yang dibutuhkan upstream Anda untuk mengirim acara pertamanya.
  • Setiap upstream lainnya: atur nilainya lebih dari 20 detik di atas waktu terlama yang dibutuhkan upstream Anda untuk mengembalikan header respons. Gateway mengirim ping keepalive pertamanya sekitar 15 detik setelah header tersebut, kecuali acara pertama upstream datang lebih cepat. Gateway yang lebih lama dari v2.1.229 tidak mengirim ping, jadi gunakan aturan provider: anthropic di sana.

Di atas waktu tersebut, perhitungkan juga waktu menunggu slot kosong dan waktu menunggu upstream yang sedang down sebelum failover. Pertahankan juga nilainya di atas permintaan non-streaming terlama.

Mencoba ulang permintaan yang tidak terjawab lebih cepat dengan tenggat byte pertama

Agar Claude Code mencoba ulang permintaan streaming yang tidak terjawab lebih cepat, berikan tenggat byte pertama dengan mengatur CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS pada mesin pengembang Anda. Tenggat ini membatasi berapa lama upaya pertama menunggu header respons. Tanpanya, upaya tersebut dapat menunggu 5 hingga 6 menit. Memerlukan Claude Code v2.1.307 atau lebih baru pada mesin pengembang.

Atur variabel ke angka bulat positif dalam milidetik, di blok env kebijakan gateway atau di shell pengembang. Pertahankan nilainya di atas waktu hingga byte pertama terlama gateway Anda, atau Claude Code dapat membatalkan dan mengirim ulang permintaan sehat yang header-nya membutuhkan waktu lebih lama. Contoh ini mengatur 60 detik di shell pengembang:

export CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS=60000

Pengiriman ulang yang tidak terjawab dapat menunggu 5 hingga 6 menit, sampai timeout idle body mengakhirinya dan Claude Code mencobanya ulang dalam anggaran retry. Jika Anda menurunkan API_TIMEOUT_MS hanya untuk mencoba ulang lebih cepat, hapus nilai tersebut, atau satu pengiriman ulang yang tidak terjawab dapat mengakhiri giliran dengan No response from API.

Untuk memastikan tenggat tersebut terpicu, minta pengembang memulai Claude Code dengan debug logging, lalu cari [first-byte] no response headers di log.

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 statusnya dalam database PostgreSQL:

  • Database: PostgreSQL itu sendiri, di-host sendiri atau terkelola, pada versi minimum atau lebih baru. Database yang hanya mengimplementasikan protokol Postgres, seperti database SQL terdistribusi, tidak didukung.
  • Alamat: store.postgres_url menerima satu host. Jika database memiliki beberapa node, gunakan alamat yang berada di depannya, seperti endpoint layanan terkelola Anda, load balancer, atau IP virtual. Atur periode grace kesiapan yang lebih lama dari waktu yang diperlukan failover.

Gateway menyimpan lima tabel data ditambah tabel _migrations, semuanya dibuat oleh migrasi waktu boot-nya:

Tabel Isi Retensi
kv Hibah perangkat (TTL 10 menit) dan penghitung batas laju TTL per baris
spend Penghitung pengeluaran periode-ke-tanggal per-principal, dalam sen admin.spend_retention_months, default 13
spend_limits Batas pengeluaran yang dikonfigurasi Sampai dihapus melalui API
admin_audit Jejak mutasi Admin API admin.audit_retention_days, default 365
principal_emails Email terakhir dilihat setiap principal, nama tampilan, dan grup IdP. Berisi PII. admin.identity_retention_days sejak aktivitas terakhir, default 90

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.

Tentukan ukuran connection pool

Setiap replika membuka hingga store.max_connections koneksi Postgres, lima secara default. Pertahankan replika × store.max_connections pada atau di bawah jumlah koneksi yang tersisa di database untuk gateway:

  • Replika: hitung jumlah terbanyak yang berjalan sekaligus. Mulai dari maksimum autoscaling Anda, atau jumlah replika Anda jika Anda tidak menggunakan autoscale, lalu tambahkan replika ekstra yang dimulai oleh rolling update sebelum menghentikan yang lama. Pada Amazon ECS dengan pengaturan default, dan pada Cloud Run, jumlahnya bisa sebanyak itu lagi.
  • Koneksi yang tersisa: ambil max_connections database, lalu kurangi yang dicadangkan database dan yang dipegang oleh klien lain. PostgreSQL mencadangkan superuser_reserved_connections, tiga secara default. Layanan terkelola dapat mencadangkan lebih banyak, jadi periksa dokumentasinya.

Misalnya, ambil maksimum autoscaling enam, rolling update yang memulai paling banyak dua replika ekstra, dan pool default lima. Itu membutuhkan (6 + 2) × 5 = 40 koneksi. Database dengan max_connections 50 dan dua koneksi yang dipegang oleh klien lain memiliki 50 − 3 − 2 = 45 koneksi tersisa, jadi totalnya muat.

Jika total Anda tidak muat, ubah salah satu dari berikut ini:

  • Database: naikkan max_connections-nya
  • Replika: jalankan lebih sedikit, atau minta orchestrator Anda memulai lebih sedikit replika ekstra dalam rolling update
  • Pool: turunkan store.max_connections, tetapi dengan batas pengeluaran aktif, pertahankan cukup besar untuk beban setiap replika. Jika tidak, pemeriksaan pengeluaran dapat mengalami timeout saat menunggu koneksi, dan gateway mencatat spend check failed: spend precheck timed out.

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 lain 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.

[!WARNING]

Menghapus hanya kunci groups dari sebuah upstream membuatnya terbuka bagi setiap pengembang. Lihat apa yang perlu dihapus sebelum Anda melakukan 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

Data Jalur Dikirim ke Anthropic oleh gateway
Inferensi (prompt, penyelesaian) CLI → gateway → upstream Anda Hanya jika API Anthropic adalah upstream yang dikonfigurasi
Telemetri (metrik OTLP, ditambah log dan jejak opt-in) CLI → gateway → kolektor Anda Tidak pernah
Identitas (email, grup, sub) IdP → gateway → CLI; CLI memberi stempel pada ekspor OTLP. Jika Anda mengaktifkan forward_user_identity, gateway juga mengirimkan email pengembang dan subjek IdP sebagai header ke proxy Anda Tidak pernah
Pengaturan terkelola YAML gateway Anda → CLI Tidak pernah
Log audit Stderr gateway → agregator Anda Tidak pernah

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. Permintaan marketplace plugin memiliki sakelar nonaktifnya sendiri. 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

Permintaan marketplace plugin

Claude Code mengambil marketplace plugin langsung dari mesin setiap pengembang, bukan melalui gateway. Persyaratan akses jaringan mencantumkan host-hostnya.

Pertama kali pengembang memulai sesi terminal interaktif, Claude Code mendaftarkan marketplace resmi, claude-plugins-official. Claude Code mengunduh katalog dari downloads.claude.ai dan, jika itu gagal, mengkloningnya dari github.com. Marketplace dan plugin mana yang diperbarui otomatis membahas penyegaran berikutnya.

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 tidak menghentikan pendaftaran pertama. Salah satu dari pengaturan terkelola berikut dapat menghentikannya:

  • Daftar marketplace: allowlist strictKnownMarketplaces yang tidak menyertakan marketplace tersebut, atau entri blockedMarketplaces yang menamainya
  • Environment variable: CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL diatur ke "1" dalam blok env terkelola

Pendaftaran pertama dapat berjalan sebelum pengembang masuk ke gateway, ketika belum ada kebijakan gateway yang tiba. Untuk mencakup permulaan pertama itu, berikan pilihan Anda dalam pengaturan terkelola sisi klien serta dalam blok cli atau code kebijakan gateway.

Pemecahan masalah

Untuk pertanyaan dan masukan, gunakan dukungan Claude Code, atau buka issue di repositori GitHub Claude Code. Anda juga dapat menghubungi tim akun Anthropic Anda. Saat melaporkan masalah, sertakan:

  • Masalah gateway: stderr gateway untuk rentang waktu yang relevan, gateway.yaml Anda dengan rahasia yang sudah disamarkan, versi gateway, yang ditampilkan di halaman landing pada / dan di header respons x-cc-gateway-version pada /managed/settings, serta apa yang berubah baru-baru ini
  • Masalah login: developer menjalankan claude --debug-file ./claude-debug.txt, mereproduksi masalahnya, lalu mengirim file tersebut beserta log audit gateway untuk rentang waktu yang sama
  • Masalah inferensi: model yang diminta, upstream yang dikonfigurasi, dan log audit gateway untuk permintaan tersebut, yang mencatat upstream mana yang melayaninya dan status responsnya

stderr gateway mencakup aliran event audit, log audit mencatat identitas developer, dan file debug mencatat output hook dan server MCP dari mesin developer. Tinjau dan samarkan informasi ini sebelum memposting ke issue publik.

Gejala Penyebab Perbaikan
/login seorang developer menampilkan pemilih akun standar alih-alih layar Cloud gateway forceLoginMethod atau forceLoginGatewayUrl tidak diatur dalam pengaturan terkelola di mesin tersebut Deploy file pengaturan terkelola ke perangkat; /login membaca URL gateway dari sana
Permintaan seorang developer gagal dengan Not signed in to the Cloud gateway — run /login. Pengaturan terkelola mesin tersebut mengatur forceLoginMethod: "gateway" atau forceLoginGatewayUrl, dan sesi tidak memiliki sign-in gateway. Login claude.ai yang tersisa tidak memenuhi persyaratan ini. Minta developer menjalankan /login dan menyelesaikan sign-in gateway. Lihat juga Administrator policy requires a Cloud gateway sign-in.
Claude Desktop melaporkan bahwa konfigurasi bootstrap-nya tidak dapat diambil /user/bootstrap mengembalikan 404: kebijakan yang cocok dengan pengguna tidak memiliki kunci desktop, atau tidak ada kebijakan yang cocok. Log audit gateway mencatat setiap penolakan sebagai desktop_bootstrap.denied beserta alasannya. Tambahkan blok desktop ke kebijakan yang cocok dengan pengguna, atau ke lapisan dasar match: {}; desktop: {} kosong sudah cukup. Lihat Overlay Claude Desktop.
Log audit menampilkan auth.denied dengan reason: invalid_token pada /v1/logs atau /v1/metrics Anda mengatur otelHeadersHelper dalam pengaturan terkelola sebuah mesin. Dalam sesi Claude Desktop di mesin tersebut, Claude Code mengirim header Authorization dari helper ke relay telemetri gateway sebagai pengganti token sesi. Jika Claude Desktop menyertakan Claude Code sebelum v2.1.307, Anda mendapatkan penolakan yang sama jika Anda mengatur header Authorization di OTEL_EXPORTER_OTLP_HEADERS atau bentuk per-sinyalnya dalam pengaturan tersebut. Hapus helper dari pengaturan tersebut. Jika Claude Desktop menyertakan Claude Code sebelum v2.1.307, hapus variabel tersebut.
Startup menampilkan Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support. Build Claude Code yang terinstal lebih lama daripada dukungan gateway Minta developer memperbarui Claude Code ke rilis yang menyertakan dukungan Cloud gateway
Startup keluar dengan Administrator policy requires a Cloud gateway sign-in on this machine Lingkungan developer mengatur ANTHROPIC_API_KEY atau ANTHROPIC_AUTH_TOKEN, pengaturan mereka mengonfigurasi apiKeyHelper, atau kunci API dari login Claude Console sebelumnya masih tersimpan Minta developer membersihkan setiap hal yang berlaku: hapus pengaturan variabel tersebut, hapus entri apiKeyHelper, atau jalankan claude auth logout untuk menghapus kunci yang tersimpan. Sesi yang memilih penyedia cloud dengan CLAUDE_CODE_USE_* kemudian dimulai tanpa sign-in; untuk setiap sesi lainnya, minta mereka memulai claude dan sign-in dengan /login. Lihat juga Administrator policy requires a Cloud gateway sign-in.
Startup atau /login melaporkan Claude Code may not be enabled for your organization setelah 403 saat memuat pengaturan terkelola Gateway, atau sesuatu di depannya, menjawab permintaan /managed/settings dengan 403. Rute pengaturan milik gateway sendiri tidak pernah menjawab 403. Status tersebut berasal dari pemeriksaan IP access_control atau dari proxy atau WAF di depan gateway. Log audit mencatat penolakan pemeriksaan IP sebagai access.denied beserta alasannya. Developer tetap dalam keadaan sign-in. Periksa log audit untuk access.denied pada saat kegagalan terjadi dan perbaiki daftar access_control atau front end, lalu minta developer memulai claude lagi
CLI /login: The gateway is limiting sign-in attempts right now, atau Request failed with status code 429 pada versi yang lebih lama. Halaman /device mungkin menampilkan Too many attempts kepada developer yang belum pernah mencoba sebelumnya Rate limit sign-in per IP telah tercapai. Entah listen.trusted_proxies tidak mencakup load balancer, sehingga setiap developer berbagi alamatnya, atau banyak developer berbagi alamat egress NAT atau VPN. Event audit dengan result: rate_limited menampilkan satu atau beberapa nilai client_ip yang sama. Jika load balancer termasuk dalam listen.trusted_proxies, daftarkan terlebih dahulu. Lalu naikkan rate_limits jika developer masih berbagi alamat. Lihat Peluncuran skala besar.
CLI /login: Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip> Hostname gateway di-resolve ke setidaknya satu alamat IP publik. Claude Code memeriksa setiap alamat hasil resolve dan mengharuskan semuanya bersifat privat. Penyebab umumnya adalah nama dual-stack di mana satu family di-resolve ke alamat publik, termasuk load balancer dual-stack internal AWS, yang mengembalikan alamat AAAA dalam rentang publik. Buat nama gateway hanya di-resolve ke alamat privat di mesin developer. Untuk nama dual-stack, hapus record rentang publik atau sediakan nama DNS terpisah yang khusus internal. Lihat prasyarat jaringan privat. Jika alamat tersebut adalah ruang alamat publik yang dimiliki dan digunakan secara internal oleh organisasi Anda, deklarasikan blok tersebut sebagai gantinya.
CLI /login: Gateway login would go through proxy <proxy>, which is not on a private network HTTPS_PROXY atau HTTP_PROXY berlaku untuk host gateway dan hostname proxy di-resolve ke alamat publik. Proxy yang host-nya hanya di-resolve ke alamat privat diizinkan dan tidak memicu error ini Tambahkan host gateway ke NO_PROXY di mesin developer agar koneksinya langsung, atau gunakan proxy yang hostname-nya di-resolve ke alamat privat. Pesan tersebut menyebutkan entri NO_PROXY yang tepat untuk ditambahkan
CLI /login: Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it Gateway berada di blok yang dideklarasikan dalam gatewayInternalNetworks, dan mesin developer menjangkaunya dari alamat di luar blok tersebut: pool alamat VPN, segmen NAT container atau WSL2, atau jaringan yang bukan milik Anda Minta developer menjalankan /login dari OS host di jaringan Anda. Jika alamat yang ditampilkan juga merupakan ruang publik milik organisasi Anda sendiri, ganti entri gateway dengan blok yang mencakup keduanya, hingga /8; entri kedua yang tumpang tindih akan ditolak. Jika tidak ada blok yang mencakup keduanya, lihat Memilih alamat untuk gateway
CLI /login: Every address for gateway host <host> must be inside its declared network <block>, and it also resolves to <ip> Nama gateway di-resolve ke alamat di luar blok yang dideklarasikan dalam gatewayInternalNetworks: situs kedua, atau record IPv6 pada nama dual-stack. Di bawah blok yang dideklarasikan, setiap record harus berada di dalam satu blok IPv4 tersebut, termasuk alamat privat dan IPv6 Publikasikan hanya record di dalam blok untuk nama gateway di mesin developer, atau sediakan nama terpisah yang khusus internal
CLI /login: <host> is on the declared network <block>, which Claude Code checks over a direct connection, not through an HTTP proxy HTTPS_PROXY atau HTTP_PROXY berlaku untuk gateway pada blok yang dideklarasikan Di mesin developer, tambahkan entri NO_PROXY yang disebutkan dalam pesan
CLI /login: pesan yang diawali dengan gatewayInternalNetworks in managed settings Nilai tersebut melanggar salah satu aturan validasi, dan pesan tersebut menyebutkan aturan yang mana. Hingga Anda memperbaikinya, Claude Code menolak setiap /login gateway baru di mesin tersebut, termasuk gateway pada alamat privat; sign-in yang sudah ada tetap berfungsi Di sumber pengaturan terkelola yang Anda deploy, perbaiki entri yang disebutkan dalam pesan, lalu jalankan ulang /login
CLI /login: Could not resolve the configured HTTP proxy Hostname di HTTPS_PROXY atau HTTP_PROXY tidak dapat di-resolve dari mesin developer, biasanya karena mesin tersebut tidak terhubung ke jaringan perusahaan Minta developer terhubung ke jaringan atau VPN Anda lalu mencoba ulang, atau perbaiki URL proxy
CLI /login: Could not resolve gateway host <host> Mesin tidak dapat me-resolve nama DNS internal gateway, biasanya karena tidak berada di jaringan perusahaan Minta developer terhubung ke jaringan atau VPN Anda, lalu coba ulang /login
Boot keluar dengan error validasi konfigurasi yang menyebutkan store.postgres_url Postgres tidak dikonfigurasi; gateway memerlukan Postgres Atur store.postgres_url. Untuk pengembangan lokal, gunakan container sekali pakai: docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres.
Boot keluar: store.postgres_url in <path> is not a URL the gateway can read, atau sebelum v2.1.290 hanya Invalid URL atau URI error URL tidak dapat di-parse, misalnya karena mencantumkan lebih dari satu host atau kata sandinya memiliki /, ?, #, atau % yang tidak di-encode Sebutkan satu host, dan pindahkan kata sandi ke store.password
Boot keluar: requires the native binary Berjalan di bawah Node alih-alih binary native Instal Claude Code dengan salah satu metode instalasi standalone
Boot keluar dengan error discovery OIDC setelah config.load oidc.issuer tidak dapat dijangkau, atau rantai TLS tidak dipercaya Periksa bahwa issuer dapat dijangkau dari pod dan menyajikan /.well-known/openid-configuration. Atur ca_cert_pem untuk PKI privat. Jika pod menjangkau IdP hanya melalui forward proxy, atur oidc.use_proxy: true; pada versi sebelum v2.1.227, berikan pod rute langsung ke setiap endpoint IdP sebagai gantinya. Jika pod juga tidak dapat me-resolve hostname IdP, atau proxy menolak CONNECT ke alamat IP, lihat Egress khusus proxy, yang memerlukan v2.1.277 atau lebih baru.
Boot keluar dengan error izin Postgres Peran database tidak memiliki hak DDL pada skemanya Berikan peran tersebut CREATE pada skema gateway agar dapat membuat dan mengubah tabelnya saat boot
Log: remaining connection slots are reserved atau sorry, too many clients already, dari PostgreSQL. Ini muncul di peringatan postgres connection closed dari replika yang berjalan, atau di log boot replika baru. Di sana, remaining connection slots are reserved dapat mengikuti attempt 1 of 3, dan replika mungkin tetap berjalan. Replika meminta lebih banyak koneksi daripada yang tersisa di database untuk gateway, dan PostgreSQL menolak koneksi tambahan tersebut Buat totalnya muat, seperti yang dijelaskan di Menentukan ukuran connection pool: jalankan lebih sedikit replika, turunkan store.max_connections, atau naikkan max_connections database. Jika totalnya muat kecuali selama rolling update, Anda dapat sebagai gantinya meminta orchestrator Anda menghentikan replika lama sebelum memulai yang baru, jika orchestrator mendukungnya.
Log: could not connect to Postgres at boot, attempt 1 of 3, dengan alasan selain remaining connection slots are reserved Database belum dapat dijangkau saat gateway dimulai, misalnya pada instance yang baru dinyalakan dan jaringannya masih dalam proses aktif Jika gateway kemudian selesai boot, tidak ada tindakan yang diperlukan. Saat database tidak dapat dijangkau, gateway mencoba koneksi tiga kali, dengan jeda dua detik, sebelum keluar. Jika keluar dengan could not connect to Postgres, periksa store.postgres_url, termasuk bahwa URL tersebut menyebutkan satu host, dan jalur jaringan ke database. Jika percobaan mengalami timeout alih-alih ditolak, naikkan store.connect_timeout_seconds untuk memberi waktu lebih lama pada setiap percobaan.
Log: Postgres <version> is below the supported floor Database menjalankan versi PostgreSQL yang lebih lama daripada yang didukung oleh versi gateway Anda. Gateway tetap berjalan. Upgrade database. Pada PostgreSQL 11, 12, atau 13, Anda dapat sebagai gantinya meng-upgrade gateway untuk memenuhi persyaratan PostgreSQL.
/oauth/callback menampilkan "Sign-in could not be completed" Domain email ditolak, validasi id_token gagal, atau email_verified secara eksplisit bernilai false, yang selalu ditolak gateway tanpa opsi override Periksa allowed_email_domains dan bahwa IdP mengembalikan klaim email yang terverifikasi. Untuk email_verified: false, perbaiki verifikasi di sisi IdP. Jika IdP Anda mengirim email di bawah nama klaim yang berbeda, atur oidc.email_claim.
Log: token exchange failed request_id=<id>: id_token missing email claim IdP tidak menyertakan email dalam id_token secara default. Penolakan ini hanya terjadi jika allowed_email_domains diatur; tanpanya, email yang tidak ada tetap menghasilkan sesi tanpa email Konfigurasikan IdP untuk mengirim email dalam id_token. Okta: tambahkan email ke klaim ID-token pada custom authorization server. Entra: tambahkan email sebagai optional claim pada app registration. PingFederate: aktifkan OpenID Connect Policy yang mengirim email. Jika IdP menyajikan email dari endpoint userinfo tetapi tidak mau menyertakannya dalam id_token, seperti Okta org authorization server, atur oidc.userinfo_fallback: true.
Log: refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …), dan developer melihat Cloud gateway session expired setiap session.ttl_hours IdP menerima refresh token tetapi tidak mengembalikan id_token bersamanya, sehingga gateway meminta klaim pengguna ke endpoint userinfo IdP. IdP menolak access token hasil refresh di sana. Gateway menjawab temporarily_unavailable, sehingga Claude Code menyimpan refresh token tetapi tidak dapat memperbarui sesi. Versi gateway sebelum v2.1.260 mencatat baris yang sama tanpa detail (at …). Atur oidc.scope_on_refresh: true, yang tersedia di gateway v2.1.260 atau lebih baru, agar permintaan refresh meminta openid lagi. Beberapa IdP, seperti Okta, mengembalikan id_token saat refresh hanya jika diminta. Di PingFederate, aktifkan Return ID Token On Refresh Grant di bawah Applications > OAuth > OpenID Connect Policy Management sebagai gantinya. Kunci tersebut tidak mengubah perilaku PingFederate. Untuk IdP lain yang masih tidak menyertakannya, periksa apakah endpoint userinfo menerima access token yang diterbitkan oleh refresh. Sebagai solusi sementara, naikkan session.ttl_hours. Lihat Penyiapan identity provider untuk tradeoff deprovisioning.
Seorang developer melakukan sign-in, lalu setiap permintaan dari sesi tersebut gagal dengan error 431 Token sesi dalam header Authorization setiap permintaan mencantumkan grup IdP developer, sehingga untuk developer yang berada di banyak grup, total header dapat melebihi yang diterima gateway Lihat Header permintaan terlalu besar setelah sign-in untuk batas mana yang berlaku dan apa yang perlu diubah
Setiap permintaan Amazon Bedrock mengembalikan 502; log menampilkan Could not load credentials from any providers Di EC2, hop limit default IMDSv2 sebesar 1 memblokir permintaan instance-metadata dari dalam container. Boot dan /readyz tetap lolos karena AWS SDK me-resolve kredensial instance pada permintaan pertama, bukan saat client dibuat Naikkan hop limit dengan aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2, atau atur di launch template. Perubahan ini berlaku untuk setiap container di instance tersebut. Utamakan ECS task role jika tersedia, yang membaca kredensial dari endpoint ECS container-credentials dan sepenuhnya menghindari perubahan ini, atau terapkan perubahan pada instance gateway khusus untuk membatasi eksposurnya.
Log: peringatan yang berisi upstream <name>: Google issued an access token that expires in <N>s, pada upstream yang file kredensial Google-nya bertipe external_account Permintaan berhasil hingga access token tersebut kedaluwarsa, lalu gagal kecuali token yang ditunjuk oleh credential_source telah diperbarui terlebih dahulu. Jika suatu proses menulis token tersebut ke file, minta proses tersebut menulis token baru lebih dari lima menit sebelum token lama kedaluwarsa
Pada beban puncak, respons lambat dimulai atau tampak macet, atau gagal dengan 502 all upstreams failed padahal upstream dalam kondisi sehat Sebuah replika memiliki lebih banyak permintaan terbuka daripada yang dikirimkannya ke upstream sekaligus, sehingga permintaan tambahan menunggu di dalam gateway. Pada upstream provider: anthropic, permintaan yang menunggu lebih lama dari timeouts.upstream_ttfb_ms menyerah pada upstream tersebut, yang menghasilkan 502 jika tidak ada upstream berikutnya yang melayaninya. Log menampilkan peringatan yang berisi client requests are open. Tambahkan replika, atau naikkan batas pada setiap replika. Lihat Permintaan upstream bersamaan.
Pada upstream selain provider: anthropic, giliran dengan jeda thinking yang panjang gagal. Proxy di depan gateway mencatat satu permintaan yang tetap terbuka selama sekitar 12,5 menit, lalu serangkaian error 504 Claude Code mengakhiri stream yang telah mengirimkan event respons pertamanya lalu hanya membawa ping keepalive. Claude Code mengirim ulang permintaan tanpa streaming, dan setiap balasan memakan waktu lebih lama daripada timeout proxy. Naikkan CLAUDE_STREAM_IDLE_TIMEOUT_MS untuk developer Anda. Lihat Thinking panjang berakhir dengan timeout proxy.
Pada provider: anthropic, giliran dengan jeda thinking yang panjang gagal. Proxy mencatat satu permintaan terbuka selama sekitar 20 menit, lalu error 502 atau 504 Claude Code mengakhiri stream yang telah mengirimkan event respons pertamanya lalu hanya membawa ping keepalive. Claude Code mengirim ulang permintaan tanpa streaming, dan setiap balasan memakan waktu lebih lama daripada waktu tunggu gateway pada upstream, timeouts.upstream_ttfb_ms, atau timeout proxy. Naikkan CLAUDE_STREAM_IDLE_TIMEOUT_MS untuk developer Anda. Lihat Thinking panjang pada upstream Anthropic API.
Permintaan seorang developer gagal dengan API Error: 400 you aren't in a group that can use this gateway. Ask your administrator to add you to one Setiap upstream memiliki daftar groups, dan sesi developer tidak membawa satu pun grup yang tercantum. Tambahkan developer ke grup yang tercantum di IdP Anda, atau cantumkan upstream tanpa groups di urutan terakhir untuk melayani semua orang lainnya. Gateway membaca grup lagi pada refresh token developer berikutnya. Jika IdP tidak menyertakan grup dan endpoint userinfo-nya mengembalikannya, atur oidc.userinfo_fallback: true.
Error IdP: scope tidak dikenal atau tidak didukung IdP menolak scope yang tidak dikenalinya Atur oidc.scopes tepat ke daftar yang diterima IdP Anda; daftar tersebut harus menyertakan openid. Default-nya adalah openid profile email offline_access.
Sesi tidak diperbarui secara diam-diam setelah mengatur oidc.scopes offline_access terhapus dari override Tambahkan kembali offline_access jika IdP Anda mendukungnya. Tanpa refresh token, developer menjalankan ulang login browser setiap session.ttl_hours.
Browser menampilkan "This request came from another site and was blocked" Form POST lintas situs, diblokir sebagai perlindungan CSRF. Hal ini wajar untuk halaman yang di-embed atau melalui proxy Buka tautan verifikasi secara langsung
Chrome memblokir tombol Approve dengan "Refused to send form data … violates … Content Security Policy directive: form-action", tetapi halaman yang sama berfungsi di Safari atau Firefox Chrome menerapkan form-action terhadap seluruh rantai redirect. IdP Anda melakukan redirect lanjutan ke host kedua yang tidak ada dalam allowlist. Tambahkan setiap origin tambahan dalam rantai redirect ke oidc.form_action_origins. Buka Chrome DevTools → Console di halaman Approve untuk melihat origin mana yang diblokir.
Sign-in selesai di IdP tetapi callback gagal, dengan error CSP di Chrome atau "this sign-in link has expired" di Safari IdP mengembalikan kode melalui response_mode=form_post, yang secara otomatis mengirimkannya lintas origin melalui POST ke /oauth/callback. Chrome memblokirnya di bawah CSP yang ketat; Safari mengizinkan pengiriman tetapi callback hanya membaca query string. Pastikan IdP Anda mematuhi response_mode=query, yang diminta gateway secara eksplisit agar callback berupa redirect biasa
Login berfungsi secara lokal tetapi gagal di belakang ALB public_url masih menyebutkan origin http:// lokal atau internal, sehingga IdP mendapatkan redirect_uri yang salah Atur listen.public_url ke origin https:// eksternal dan daftarkan <public_url>/oauth/callback ke IdP
Developer melihat dialog kepercayaan berulang kali Sertifikat TLS berganti per replika atau per permintaan Gunakan sertifikat yang stabil di ingress, atau terminasi TLS sekali dan jalankan replika melalui HTTP biasa secara internal
CLI /login: "Could not verify the gateway's TLS certificate" atau SELF_SIGNED_CERT_IN_CHAIN Rantai TLS gateway ditandatangani oleh CA privat yang tidak ada di trust store host CLI Claude Code membaca trust store OS secara default pada binary native dan pada Node 22.15 atau lebih baru; CLAUDE_CODE_CERT_STORE mengontrol perilaku ini. Jika CA terinstal di trust store OS, pastikan developer menggunakan runtime terkini. Jika tidak, atur NODE_EXTRA_CA_CERTS ke PEM sertifikat CA sebelum menjalankan. Dialog fingerprint pada koneksi pertama tetap berlaku.
CLI /login menyelesaikan sign-in browser, lalu sesi berakhir dengan Cloud gateway sign-in was not completed dan ketidakcocokan sertifikat TLS Pada permintaan pertama setelah sign-in, gateway menyajikan sertifikat yang tidak cocok dengan fingerprint yang di-pin oleh Claude Code, sehingga Claude Code tidak menyimpan kredensial gateway. Penyebab umumnya adalah replika di belakang satu alamat yang menyajikan sertifikat berbeda, atau sesuatu di jalur jaringan yang mengintersepsi TLS. Sajikan satu sertifikat untuk hostname, misalnya dengan menerminasi TLS sekali di ingress, lalu minta developer menjalankan /login lagi. Jika sertifikat tersebut berbeda dari yang di-pin, Claude Code menampilkan dialog kepercayaan lagi dengan peringatan bahwa sertifikat telah berubah.
CLI /login berhenti dengan The gateway's TLS certificate changed during sign-in: it no longer matches the one you trusted Permintaan sign-in mencapai server yang sertifikatnya tidak cocok dengan yang diterima developer saat /login dimulai: replika di belakang satu alamat yang menyajikan sertifikat berbeda, intersepsi TLS di jalur, atau rotasi sertifikat saat sign-in sedang berlangsung. Sajikan satu sertifikat untuk hostname, lalu minta developer memulai sign-in lagi dan meninjau sertifikat baru di dialog kepercayaan.

Pesan Cloud gateway sign-in was not completed menyebutkan hostname gateway. Jika Claude Code memiliki fingerprint yang di-pin maupun yang disajikan, pesan tersebut juga menampilkan 16 karakter pertama dari masing-masing.

Jika Claude Code melaporkan couldn't load your organization's managed settings setelah sign-in gateway, Claude Code menyebutkan alasannya, melakukan restart di tempat, dan melanjutkan percakapan. Jika Claude Code tidak dapat melakukan restart, misalnya dalam sesi latar belakang, Claude Code mengakhiri sesi dan mempertahankan sign-in.

Header permintaan terlalu besar setelah sign-in

Permintaan seorang developer dapat gagal dengan error 431 setelah sign-in jika developer tersebut menjadi anggota banyak grup IdP.

Gateway menjawab 431 ketika total header suatu permintaan melebihi 256 KiB, atau melebihi limits.max_request_header_bytes jika Anda mengaturnya. Gateway tidak menulis baris log maupun event audit untuk permintaan ini. Versi gateway sebelum v2.1.284 menjawab 431 di atas 16 KiB.

Mulailah dengan yang pertama dari berikut ini yang berlaku untuk gateway Anda:

  • Gateway lebih lama dari v2.1.284: upgrade gateway
  • limits.max_request_header_bytes diatur: naikkan nilainya atau hapus kunci tersebut
  • Tidak ada yang berlaku, atau 431 tetap terjadi setelahnya: minta IdP Anda mengirim lebih sedikit grup. Penyiapan identity provider membahas cara Okta, Microsoft Entra ID, dan Google Workspace menyediakan grup

Saat Anda memangkas klaim grup, pertahankan grup yang Anda sebutkan dalam pengaturan berikut, yang menentukan akses, kebijakan, upstream, dan batas pengeluaran seorang developer:

  • oidc.allowed_groups: menentukan siapa yang dapat sign-in
  • admin.admin_groups: menentukan siapa yang dapat memanggil API admin dengan sesi gateway mereka
  • match.groups dalam managed.policies: menentukan kebijakan mana yang berlaku untuk seorang developer
  • groups pada upstream: menentukan upstream mana yang melayani seorang developer
  • Batas pengeluaran rbac_group: menentukan batas grup mana yang berlaku untuk seorang developer

Thinking panjang berakhir dengan timeout proxy

Jika upstream Anda adalah provider: anthropic, gunakan Thinking panjang pada upstream Anthropic API sebagai gantinya: Anda juga menaikkan CLAUDE_STREAM_IDLE_TIMEOUT_MS di sana, tetapi waktu dan error-nya berbeda.

Jika giliran gagal setelah thinking panjang dan proxy Anda mencatat satu permintaan terbuka selama sekitar 12,5 menit, lalu serangkaian error 504, naikkan CLAUDE_STREAM_IDLE_TIMEOUT_MS dalam kebijakan gateway. Misalnya, dengan idle timeout 240 detik pada proxy, rangkaian tersebut terdiri dari 10 permintaan, masing-masing diputus pada 240 detik.

  • Permintaan pertama: stream yang mengirimkan event respons pertamanya, message_start, lalu hanya ping selama Claude berpikir. Dengan pengaturan default, Claude Code mengakhiri stream tersebut setelah sekitar 12,5 menit.
  • 10 lainnya: permintaan yang sama, dikirim tanpa streaming lalu dicoba ulang, total 10 pengiriman secara default. Permintaan ini tidak mendapatkan ping, sehingga balasan yang lambat terkena timeout proxy.

Anda tidak memerlukan timeout proxy yang lebih lama untuk perbaikan ini. Jika Anda hanya menaikkan timeout proxy, permintaan tanpa streaming tetap gagal begitu balasan memakan waktu lebih lama daripada waktu tunggu Claude Code sendiri, yaitu 300 detik secara default.

Mengonfirmasi penyebab

Minta seorang developer mereproduksi kegagalan dengan claude --debug-file ./claude-debug.txt, lalu cari baris berikut di file tersebut:

Error streaming, falling back to non-streaming mode: Stream idle timeout - no chunks received

Jika developer Anda sudah mengatur CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK ke 1, Anda tidak melihat permintaan tanpa streaming, dan giliran berakhir dengan API Error: Stream idle timeout - no chunks received. Perbaikan yang sama berlaku.

Memilih nilai

Pilih nilai CLAUDE_STREAM_IDLE_TIMEOUT_MS yang kolom keduanya mencakup jeda thinking terpanjang Anda, atau mulai dengan 1800000 jika Anda tidak mengetahuinya. Sebuah stream dapat bertahan hanya dengan ping selama sekitar 7,5 menit lebih lama daripada nilai tersebut:

CLAUDE_STREAM_IDLE_TIMEOUT_MS Stream dapat bertahan hanya dengan ping selama
300000, default Sekitar 12,5 menit
900000 Sekitar 22,5 menit
1800000 Sekitar 37,5 menit

Jika upstream macet sementara gateway terus mengirim ping, developer Anda juga menunggu selama itu sebelum Claude Code menyerah pada stream tersebut. Koneksi yang benar-benar diam tetap berakhir setelah 5 hingga 6 menit, karena body idle timeout tidak mengikuti variabel ini.

Mengirimkan nilai dalam kebijakan

Tambahkan entri env ke setiap kebijakan dalam gateway.yaml yang sudah mengirimkan pengaturan Claude Code kepada developer yang ingin Anda cakup. Letakkan di bawah kunci code, cli, atau settings yang sudah dimiliki kebijakan tersebut. Untuk mencoba nilainya terlebih dahulu, mulailah dengan kebijakan yang cocok dengan satu grup. Lihat managed untuk cara kebijakan dicocokkan dan diwariskan. Contoh ini menambahkan entri ke kebijakan match: {} dengan kunci cli:

managed:
  policies:
    - match: {}
      cli:
        env:
          CLAUDE_STREAM_IDLE_TIMEOUT_MS: "1800000"

Dengan kunci cli, Anda mencakup sesi terminal, ekstensi IDE, dan Agent SDK. Untuk tab Code di Claude Desktop, lihat Memilih cli atau code.

Restart gateway agar membaca file yang telah diedit. Lalu minta developer me-restart Claude Code untuk mendapatkan CLAUDE_STREAM_IDLE_TIMEOUT_MS.

Thinking panjang pada upstream Anthropic API

Jika provider: anthropic adalah satu-satunya upstream untuk model tersebut dan proxy Anda mencatat satu permintaan terbuka selama sekitar 20 menit, lalu error 502 atau 504, naikkan CLAUDE_STREAM_IDLE_TIMEOUT_MS dalam kebijakan gateway.

  • Permintaan panjang: stream yang mengirimkan message_start lalu hanya ping selama Claude berpikir. Claude Code mengakhirinya setelah sekitar 20 menit dengan pengaturan default, dan lebih lama setelah Anda menaikkan variabel tersebut.
  • Error-nya: permintaan yang kemudian dikirim Claude Code tanpa streaming. Masing-masing gagal dengan 502 dari gateway, atau dengan 504 dari proxy Anda jika timeout proxy lebih pendek daripada waktu tunggu gateway. Waktu tunggu tersebut adalah timeouts.upstream_ttfb_ms, yang tidak perlu Anda naikkan untuk perbaikan ini.

Untuk mengonfirmasi penyebabnya, lihat Mengonfirmasi penyebab.

Pilih nilai yang waktunya mencakup jeda thinking terpanjang Anda: sekitar 20 menit pada default, 30 pada 900000, dan 45 pada 1800000. Lalu ikuti Mengirimkan nilai dalam kebijakan.

Terkait