Panduan kompatibilitas gateway Claude Code

Jaga gateway LLM tetap kompatibel dengan Claude Code: endpoint yang dipanggilnya, header dan field body yang harus diteruskan, dan apa yang rusak saat dihapus.

Halaman ini mendokumentasikan permintaan yang dikirim Claude Code ke gateway, termasuk endpoint yang dipanggilnya, header dan field body yang harus diteruskan gateway, dan fitur mana yang berhenti berfungsi saat tidak ada. Halaman ini ditulis untuk operator yang mengonfigurasi produk gateway agar bekerja dengan Claude Code.

Gateway aplikasi Claude, gateway yang di-host sendiri oleh Anthropic, melayani referensi endpoint-nya sendiri di GET /protocol, mencakup endpoint sign-in, inference, managed settings, model discovery, dan telemetry gateway tersebut. Ini adalah dokumen terpisah dari panduan ini.

Halaman ini mencakup:

• Format API dan endpoint yang harus dilayani untuk masing-masing
• Perilaku klien berdasarkan metode koneksi: bagaimana ID model, nilai anthropic-beta, field permintaan, dan default berbeda antara format dan sign-in gateway aplikasi Claude
• Header permintaan: mana yang harus mencapai upstream dan mana yang dapat dikonsumsi gateway Anda
• Header respons: apa yang harus dikembalikan agar deteksi stall, retry, dan tampilan batas penggunaan berfungsi
• Blok atribusi prompt sistem dan bagaimana interaksinya dengan prompt caching
• Penerusan fitur: apa yang rusak saat header atau field body dihapus
• Penemuan model

Halaman ini menggunakan dua istilah untuk apa yang dilakukan gateway Anda dengan setiap header dan field body:

• Teruskan tanpa perubahan: teruskan ke upstream byte-for-byte
• Konsumsi: gateway dapat membacanya untuk routing, atribusi, atau tracing dan tidak perlu meneruskannya

Apa pun yang tidak ditandai teruskan tanpa perubahan adalah milik Anda untuk dikonsumsi atau diabaikan.

Format API

Gateway harus mengekspos setidaknya salah satu format API berikut kepada klien Claude Code. Klien memilih format dan menunjukkan Claude Code ke gateway Anda dengan variabel di kolom Selected by tabel di bawah.

Google Cloud's Agent Platform adalah endpoint Claude Google Cloud, sebelumnya Vertex AI; nama variabelnya tetap menggunakan ejaan VERTEX.

Foundry dan Claude Platform on AWS

Microsoft Foundry dan Claude Platform on AWS mengimplementasikan format Anthropic Messages. Claude Code merutekan ke mereka melalui variabel mereka sendiri, ANTHROPIC_FOUNDRY_BASE_URL dan ANTHROPIC_AWS_BASE_URL, tetapi gateway yang berada di depan salah satu dari mereka mengimplementasikan baris Anthropic Messages di atas. Gateway yang berada di depan Claude Platform on AWS juga harus meneruskan header anthropic-workspace-id, yang platform tersebut memerlukan pada setiap permintaan.

Endpoint opsional dan lalu lintas startup

Endpoint penghitungan token adalah satu-satunya yang opsional: ketika tidak ada, Claude Code kembali ke perkiraan berbasis karakter dari penggunaan konteks.

Cocokkan pada path, bukan URL lengkap:

• Permintaan inferensi posting ke /v1/messages?beta=true
• Metode Google Cloud's Agent Platform menambahkan sufiks ke path model penerbit, seperti dalam /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict

Gateway juga melihat lalu lintas startup best-effort yang dapat ditolak tanpa merusak apa pun. Gateway format Anthropic Messages menerima probe pemanasan koneksi HEAD /api/hello, yang Claude Code lewati ketika proxy HTTP atau sertifikat klien dikonfigurasi. Gateway format Amazon Bedrock menerima permintaan GET /inference-profiles?type=SYSTEM_DEFINED dan, ketika model yang dikonfigurasi adalah profil inferensi, pencarian GET /inference-profiles/{profile}.

Pemeriksaan ketersediaan fast mode tidak pernah muncul dalam log gateway: ia memanggil api.anthropic.com secara langsung daripada mengikuti ANTHROPIC_BASE_URL, jadi pada jaringan yang memblokir egress langsung ke api.anthropic.com, fast mode dapat melaporkan kesalahan konektivitas sementara inferensi melalui gateway terus bekerja. Pemeriksaan keamanan domain WebFetch juga memanggil api.anthropic.com secara langsung. Gunakan fast mode di belakang proxy dan gateway LLM mencakup variabel yang memulihkannya.

Streaming

Alirkan respons inferensi. Claude Code membaca aliran saat tiba, jadi jika gateway Anda membuffer respons lengkap sebelum meneruskannya, Claude Code macet.

Ketika klien berbicara format Amazon Bedrock, teruskan body respons InvokeModelWithResponseStream dan header Content-Type: application/vnd.amazon.eventstream tanpa modifikasi, dan jangan konversi aliran ke server-sent events. Lihat Streaming errors behind a gateway or proxy.

Teruskan ping keep-alive juga. Pada koneksi melalui ANTHROPIC_BASE_URL atau ANTHROPIC_AWS_BASE_URL, Claude Code menghitung setiap byte yang gateway Anda teruskan, termasuk event SSE ping dan baris komentar, dan membatalkan aliran yang diam selama 300 detik secara default. Ping upstream adalah satu-satunya lalu lintas selama jeda pemikiran panjang, jadi jika gateway Anda menghapus atau membuffer mereka, Claude Code membatalkan aliran selama jeda tersebut; Automatic retries mencakup apa yang dilaporkan aliran yang dibatalkan berdasarkan seberapa jauh respons telah maju. Upstream yang tidak mengirim ping sama sekali, seperti event-stream biner Amazon Bedrock, meninggalkan jeda tersebut tanpa apa pun untuk diteruskan. Ketika menerjemahkan dari upstream seperti itu, keluarkan event ping Anda sendiri selama celah senyap. Gateway yang dicapai melalui ANTHROPIC_BEDROCK_BASE_URL, ANTHROPIC_VERTEX_BASE_URL, atau ANTHROPIC_FOUNDRY_BASE_URL tidak dibungkus oleh watchdog tingkat byte ini, bahkan ketika mereka meneruskan format Anthropic Messages; di sana, timeout idle 5 menit membatalkan aliran senyap sebagai gantinya, dan pada koneksi ANTHROPIC_BEDROCK_BASE_URL Anda dapat menambahkan watchdog byte dengan CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK.

Format mismatch dengan upstream

Format mana yang digunakan klien menentukan apa yang diterima gateway Anda. Mode kegagalan umum adalah ketidaksesuaian antara format yang dikirim klien ke gateway Anda dan format yang diterima penyedia upstream di belakangnya.

• Ketika klien berbicara format Amazon Bedrock atau Google Cloud's Agent Platform, Claude Code mengirim hanya subset dari set kemampuan penuhnya yang diterima penyedia tersebut
• Ketika klien berbicara format Anthropic Messages, Claude Code mengirim set lengkap, bahkan jika gateway Anda meneruskan ke upstream Amazon Bedrock atau Google Cloud's Agent Platform

Menjembatani perbedaan itu adalah pekerjaan gateway Anda. Feature pass-through menjelaskan apa yang rusak ketika tidak.

Jika upstream Anda adalah Amazon Bedrock atau Google Cloud's Agent Platform, Anda dapat menghindari penjembatanan dengan mengekspos format penyedia tersebut sebagai gantinya. Route to a cloud provider through a gateway menunjukkan konfigurasi klien untuk format tersebut.

Bagaimana metode koneksi mengubah perilaku klien

Cara pengembang terhubung ke gateway Anda menentukan ID model mana, nilai anthropic-beta mana, dan bidang permintaan mana yang dikirim Claude Code, serta default mana yang diterapkannya. Gateway Anda melihat salah satu dari tiga perilaku klien:

• Format Amazon Bedrock atau Agent Platform: pengembang menetapkan CLAUDE_CODE_USE_BEDROCK=1 dengan ANTHROPIC_BEDROCK_BASE_URL, atau CLAUDE_CODE_USE_VERTEX=1 dengan ANTHROPIC_VERTEX_BASE_URL, menunjuk ke gateway Anda. Claude Code menggunakan ID model, bidang permintaan, dan default penyedia tersebut.
• Format Anthropic Messages: pengembang menetapkan ANTHROPIC_BASE_URL ke gateway Anda. Claude Code memperlakukan gateway sebagai Claude API dan tidak dapat mengetahui upstream mana yang Anda teruskan.
• Masuk ke gateway aplikasi Claude: pengembang masuk ke gateway aplikasi Claude. Gateway tersebut berbicara dalam format Anthropic Messages tetapi dapat merutekan ke upstream apa pun, jadi Claude Code hanya mengirimkan nilai anthropic-beta dan asumsi kemampuan model yang juga diterima Amazon Bedrock dan Agent Platform.

Permintaan dan default menurut metode koneksi

Tabel di bawah membandingkan tiga metode koneksi, satu perilaku per baris. Tabel ini menghilangkan Microsoft Foundry dan Claude Platform di AWS, yang juga menggunakan format Anthropic Messages tetapi yang Claude Code jangkau melalui variabel mereka sendiri. Untuk itu, lihat halaman Microsoft Foundry dan Claude Platform di AWS.

Untuk fitur yang didukung setiap koneksi dan telemetri yang dikirimnya ke Anthropic secara default, lihat Feature availability dan Default behaviors by API provider.

Pengaturan untuk ID model yang tidak dikenali

Dua pengaturan sisi klien mengubah apa yang diasumsikan Claude Code untuk ID model yang tidak dikenalinya, terlepas dari metode koneksi mana yang digunakan pengembang:

• Context window: Claude Code mengasumsikan 200K, atau 1M ketika ID membawa [1m]. Untuk mendeklarasikan jendela sebenarnya, lihat Correct the window for a gateway or custom model ID
• Capabilities: untuk memberikan alias gateway kemampuan model di belakangnya, petakan ID Anthropic model tersebut ke alias Anda dengan entri modelOverrides dalam pengaturan yang Anda distribusikan. Untuk tempat variabel ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES berlaku, lihat feature pass-through

Header permintaan

Claude Code menyertakan header ini pada permintaan API. Nama header tidak peka huruf besar-kecil di kawat. Teruskan anthropic-version dan anthropic-beta tanpa perubahan, ditambah anthropic-workspace-id ketika upstream adalah Claude Platform on AWS; sisanya gateway dapat konsumsi untuk routing, atribusi, dan tracing, dan tidak perlu diteruskan.

ID subagent dihasilkan segar untuk setiap spawn. Agen rekan kerja, anggota bernama dari tim agen, menggunakan kembali ID berbasis nama yang stabil di seluruh reconnections. Dalam kedua kasus ID mengidentifikasi agen, bukan orang atau perangkat, jadi jangan perlakukan header ID agen sebagai pengidentifikasi pengguna.

Jika pengembang Anda menetapkan ANTHROPIC_CUSTOM_HEADERS, header tersebut muncul pada permintaan juga.

Header petunjuk gateway

Claude Code juga dapat mengirim petunjuk routing: fakta per-permintaan yang dapat digunakan gateway atau router untuk menjadwalkan, cache, atau mengatribusikan permintaan. Memerlukan Claude Code v2.1.273 atau lebih baru.

Apakah permintaan membawanya tergantung pada tempat Claude Code mengirimnya:

• Koneksi langsung ke API Anthropic: dikirim secara default
• URL dasar kustom: nonaktif secara default, karena proxy yang menolak header yang tidak dikenal akan gagal permintaan. Untuk menerimanya, atur CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 untuk pengembang Anda, misalnya di blok env dari pengaturan terkelola
• Backend lainnya, termasuk Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, dan Claude Platform on AWS: dikirim hanya ketika CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 diatur

Mengatur CLAUDE_CODE_GATEWAY_HINT_HEADERS ke 0 menghentikan header pada setiap koneksi.

Header hanya membawa apa yang baris di bawah daftar: kosakata tetap, nama alat, dan durasi, tidak pernah teks prompt atau konten file. Setiap nilai adalah ASCII yang dapat dicetak.

Sebelum mengurai x-claude-code-prev-tool-durations, periksa bagaimana Claude Code membangun nilai dan apa yang ditinggalkannya:

• Entri: satu per panggilan alat yang berjalan, dalam urutan hasilnya dikumpulkan, dalam milidetik utuh
• Cap: Claude Code mengirim paling banyak 32 entri dan 4 KB, menyimpan entri pertama
• Encoding: nama alat dikodekan persen, mencakup %, ;, =, koma, spasi, dan karakter apa pun di luar ASCII yang dapat dicetak
• Parsing: pisahkan pada ;, kemudian pada =, dan dekode setiap nama
• Ketiadaan: panggilan compaction, permintaan samping, dan permintaan pertama prompt baru tidak membawanya. Jangan baca header yang hilang sebagai giliran yang tidak menjalankan alat
• Waktu: masing-masing mengecualikan prompt izin dan hooks, dan panggilan alat paralel masing-masing melaporkan waktu mereka sendiri, jadi entri tidak menambah hingga celah antara permintaan

Teruskan sebagai daftar terbuka

Perlakukan header dan field body sebagai daftar terbuka, bukan daftar tertutup. Claude Code mendapatkan kemampuan di seluruh rilis, dan mereka tiba sebagai nilai anthropic-beta baru, field body permintaan baru, dan kadang-kadang header anthropic-* atau x-claude-code-* baru.

Ketika meneruskan ke upstream format Anthropic, teruskan header permintaan anthropic-* dan field body permintaan melalui tanpa perubahan daripada allowlist yang Anda lihat hari ini. Gateway yang disematkan ke daftar yang diamati menghapus header atau field kemampuan berikutnya dan merusaknya pada rilis yang memperkenalkannya.

Pengecualiannya adalah upstream non-Anthropic seperti Amazon Bedrock atau Google Cloud's Agent Platform, di mana menjembatani perbedaan skema adalah pekerjaan gateway; lihat penerusan fitur.

Response headers

Claude Code membaca response headers ini untuk mendeteksi stalled streams, untuk memutuskan apakah dan kapan harus retry, dan untuk menampilkan usage limits. Tabel ini mencantumkan apa yang harus dikembalikan untuk masing-masing. Juga forward error response bodies tanpa modifikasi, sehingga capability-rejection recovery Claude Code dapat mencocokkan wording error upstream.

Blok atribusi prompt sistem

Claude Code menambahkan blok atribusi pendek ke prompt sistem yang berisi versi klien dan sidik jari yang berasal dari percakapan. Endpoint api.anthropic.com menghapus blok sebelum memproses ketika tiba tidak berubah sebagai blok sistem pertama, jadi tidak mempengaruhi prompt caching pihak pertama. Upstream lain apa pun menerimanya sebagai bagian dari prompt.

Strip bersifat posisional, jadi hanya berfungsi ketika gateway meneruskan array system tanpa perubahan. Untuk menjaga blok keluar dari prompt tanpa kehilangan konten sistem lainnya:

• Teruskan array system persis seperti yang diterima, menjaga blok tetap pertama: menambahkan blok sistem lain, mengurutkan ulang array, atau mengonversinya menjadi string tunggal mengalahkan strip, dan blok kemudian mencapai model dan kunci cache prompt.
• Jaga blok dalam entri array-nya sendiri: endpoint memperlakukan blok yang digabungkan yang dimulai dengan header atribusi sebagai atribusi sepenuhnya dan menghapus semua yang digabungkan ke dalamnya, termasuk sisa prompt sistem.
• Jika gateway Anda harus membentuk ulang konten sistem, atur CLAUDE_CODE_ATTRIBUTION_HEADER=0 sehingga Claude Code menghilangkan blok. Anthropic dan endpoint Claude penyedia cloud membacanya untuk atribusi, jadi hilangkan di klien daripada menghapusnya atau memindahkannya di gateway.

Variabel ada untuk kompatibilitas gateway dan caching pihak ketiga, bukan sebagai kontrol privasi: pada koneksi langsung permintaan lengkap sudah pergi ke Anthropic API bagaimanapun. Ketika keduanya berlaku, Claude Code menjaga blok pada permintaan pengklasifikasi mode otomatis bahkan ketika Anda menetapkan variabel ke 0:

• Permintaan pergi ke api.anthropic.com, dengan ANTHROPIC_BASE_URL tidak diatur atau menamai host itu dan tidak ada penyedia pihak ketiga yang dipilih.
• Kredensial aktif bukan profil Anthropic atau kredensial federasi.

Permintaan pengklasifikasi melewati sisa prompt sistem Claude Code, jadi pada permintaan tersebut blok adalah satu-satunya penanda dalam body permintaan yang mengidentifikasinya sebagai lalu lintas Claude Code. Ketika salah satu kondisi gagal, melalui gateway LLM, pada penyedia pihak ketiga, atau dengan profil atau kredensial federasi aktif, menetapkan 0 menghapus blok dari permintaan pengklasifikasi juga. Sebelum v2.1.229, pengecualian ini tidak ada: menetapkan 0 menghapus blok dari permintaan pengklasifikasi tersebut, dan ketika API menolak permintaan yang tidak teridentifikasi, mode otomatis gagal pada setiap tindakan yang dikirimnya ke pengklasifikasi.

Dari Claude Code v2.1.181, blok stabil untuk seumur hidup percakapan ketika permintaan merutekan melalui URL dasar kustom, jadi cache prompt gateway-side yang dikunci pada body permintaan lengkap bekerja tanpa menonaktifkannya, dan penyedia apa pun yang gateway Anda teruskan menerima awalan prompt yang stabil. Sebelum v2.1.181 blok menyertakan token per-permintaan yang mengubah awal prompt sistem pada setiap permintaan. Pada versi tersebut, atur CLAUDE_CODE_ATTRIBUTION_HEADER=0 ketika gateway Anda melakukan salah satu dari ini:

• Mengimplementasikan cache prompt yang dikunci pada body permintaan.
• Meneruskan permintaan ke penyedia pihak ketiga seperti Amazon Bedrock, Microsoft Foundry, atau Agent Platform Google Cloud, dalam format Anthropic Messages atau format penyedia sendiri, di mana awalan yang berubah mengurangi reuse cache prompt pada penyedia itu.

Penerusan fitur

Claude Code memperlakukan gateway ANTHROPIC_BASE_URL sebagai endpoint format Anthropic dan mengirimkannya header beta dan field body permintaan yang dikirimkannya ke api.anthropic.com, kecuali set kecil diagnostik dan default yang disediakan untuk koneksi langsung, seperti default streaming alat berbutir halus yang tercakup di bawah. Set tersebut bervariasi menurut rilis, jadi jangan bergantung pada isinya.

Kemampuan yang menambahkan field body memasangkannya dengan header beta, dan pasangan bepergian bersama. Gateway yang menghapus header sambil melewatkan body, atau meneruskan body format Anthropic ke upstream dengan skema berbeda, menghasilkan kesalahan 400 keras; hanya ketika kedua bagian tidak ada bersama-sama fitur mati diam-diam. Gateway yang menulis ulang atau menyunting body permintaan untuk inspeksi konten memecah pasangan dengan cara yang sama seperti penghapusan, jadi inspeksi tanpa memodifikasi. Tabel mencatat di mana fitur menyimpang dari pasangan.

Streaming alat berbutir halus adalah salah satu default koneksi langsung: itu dimatikan secara default setiap kali permintaan merutekan melalui URL dasar kustom, dan gateway menerimanya ketika pengembang menetapkan CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1.

Variabel ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES mendeklarasikan kemampuan model hanya dalam konfigurasi penyedia: CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_USE_FOUNDRY, dan CLAUDE_CODE_USE_MANTLE. Mereka tidak memiliki efek di belakang gateway ANTHROPIC_BASE_URL.

Retry otomatis dan penerusan kesalahan

Apa yang Claude Code lakukan setelah penolakan upstream tergantung pada apa yang ditolak:

• Ketika upstream menolak field thinking, pesan sistem mid-conversation, atau penanda cache_control pada pesan tersebut, Claude Code mengulangi permintaan dan menonaktifkan kemampuan yang ditolak untuk sisa percakapan
• Ketika upstream menolak tanda tangan pemikiran, termasuk dengan 400 yang pesannya mengatakan blok bound to a different conversation, Claude Code menghapus blok pemikiran sebelumnya dari permintaan, mengulangi, dan menjaganya keluar dari setiap permintaan kemudian. Respons baru masih menyertakan pemikiran
• Ketika gateway atau upstream-nya menolak entri alat advisor dalam tools sebagai tipe alat yang tidak dikenali, Claude Code mengulangi permintaan sekali tanpa entri tersebut dan nilai anthropic-beta-nya. Permintaan kemudian ke URL dasar tersebut meninggalkan advisor keluar sampai Claude Code keluar, dan /advisor tidak tersedia untuk pengembang untuk waktu itu. Claude Code mengenali penolakan ini dengan respons 400 atau 422 yang pesannya menyebutkan tipe alat setelah Input tag, seperti Input tag 'advisor_20260301'. Sebelum v2.1.280, Claude Code tidak mengulangi penolakan ini
• Claude Code tidak mengulangi penolakan manajemen konteks atau field skema alat, jadi kesalahan 400 tersebut mencapai pengembang

Penolakan bound to a different conversation berasal dari pemeriksaan preserved thinking API, yang gagal ketika konten system, tools, atau messages sebelumnya berbeda dari permintaan yang menghasilkan pemikiran. Gateway yang menulis ulang konten apa pun dari itu dapat menyebabkan penolakan itu sendiri; Libraries, proxies, and gateways mencakup apa yang harus dilewatkan tanpa perubahan.

Logika retry cocok dengan kata-kata kesalahan upstream, jadi teruskan body respons kesalahan tanpa modifikasi. Gateway yang membungkus kesalahan upstream dalam amplop miliknya sendiri memecah jalur pemulihan, bahkan ketika mempertahankan kode status, kecuali pesan amplop membawa token capability_rejected: yang stabil. Gateway aplikasi Claude mengganti token tersebut untuk kata-kata kesalahan penyedia cloud, misalnya capability_rejected: prompt_too_long.

Nonaktifkan kemampuan pra-rilis

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 menghentikan Claude Code dari mengirim kemampuan pra-rilis dan field body mereka pada setiap penyedia, termasuk manajemen konteks dan field alat beta. Variabel tidak mempengaruhi penalaran adaptif, yang dipilih oleh model daripada oleh beta. Itu tidak pernah menekan kemampuan OAuth yang diperlukan autentikasi langganan.

Pada Claude Code v2.1.227 atau lebih baru, organisasi Anda dapat menjaga pencarian alat MCP tetap aktif di bawah variabel ini melalui pengaturan terkelola. Apa yang Claude Code kirimkan dengan override tersebut berlaku tergantung pada cara Anda terhubung:

• Pada koneksi langsung, atau melalui gateway yang diatur dengan ANTHROPIC_BASE_URL, Claude Code terus mengirim header beta pencarian alat, field alat defer_loading, dan blok tool_reference, dan menghapus sisanya
• Pada penyedia cloud, atau masuk melalui gateway aplikasi Claude, override tidak memiliki efek

Set kemampuan Claude Code mengirim tumbuh di seluruh rilis. Untuk string header beta saat ini, lihat referensi header beta; uji gateway Anda terhadap rilis Claude Code baru daripada menyematkan ke daftar yang diamati.

Penemuan model

Ketika ANTHROPIC_BASE_URL menunjuk ke gateway yang mengekspos format Anthropic Messages, Claude Code dapat menanyakan endpoint /v1/models gateway pada startup dan menambahkan model yang dikembalikan ke pemilih /model. Jika Anda atau administrator Anda menetapkan replaceBuiltInOptions dalam lineup modelPicker, Claude Code menyembunyikan model yang ditemukan dari pemilih.

Pengembang mengaktifkannya dengan menetapkan CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, di lingkungan mereka sendiri atau melalui pengaturan terkelola. Penemuan dimatikan secara default sehingga gateway yang didukung oleh kunci API bersama tidak menampilkan setiap model yang dapat diakses kunci kepada setiap pengguna.

Ketika penemuan berjalan

Penemuan hanya berlaku untuk format Anthropic Messages. Ini tidak berjalan ketika:

• Variabel penyedia CLAUDE_CODE_USE_* apa pun diatur, bahkan jika ANTHROPIC_BASE_URL juga diatur
• ANTHROPIC_BASE_URL tidak diatur atau menunjuk ke api.anthropic.com

Penemuan masih berjalan ketika lalu lintas nonessential dimatikan, karena permintaan hanya pergi ke gateway Anda. Sebelum v2.1.257, penemuan tidak berjalan saat lalu lintas nonessential dimatikan.

Permintaan dan respons

Permintaan adalah GET /v1/models?limit=1000 dengan timeout 3 detik secara default, dan pengalihan apa pun diperlakukan sebagai kegagalan sehingga kredensial tidak dapat bocor ke target pengalihan. Gateway yang merespons lebih lambat dari timeout, atau yang mengalihkan /v1/models, bahkan http ke https, gagal penemuan diam-diam; sajikan endpoint langsung di URL dasar yang dikonfigurasi.

Untuk memberikan gateway yang lambat waktu lebih lama, atur CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS. Variabel memerlukan Claude Code v2.1.269 atau lebih baru.

Claude Code mengirim permintaan penemuan dengan kedua header kredensial di bawah dan menghilangkan header yang nilainya tidak diselesaikan. Mengirim kedua header memerlukan Claude Code v2.1.248 atau lebih baru. Versi sebelumnya mengirim hanya Authorization ketika ANTHROPIC_AUTH_TOKEN diatur dan hanya x-api-key sebaliknya.

• Authorization: ANTHROPIC_AUTH_TOKEN sebagai token bearer, jika tidak nilai apiKeyHelper sebagai token bearer. Dalam hal ini Claude Code menunggu helper mengembalikan sebelum mengirim permintaan.
• x-api-key: kunci API yang diselesaikan Claude Code, seperti ANTHROPIC_API_KEY. Ketika nilai helper adalah satu-satunya kredensial, header ini juga membawanya, sehingga nilai tiba di kedua header.

Claude Code juga mengirim header apa pun dari ANTHROPIC_CUSTOM_HEADERS. Ketika header kustom memiliki nilai non-kosong, Claude Code mengirimnya sebagai pengganti header built-in dengan nama yang sama, mencocokkan nama secara case-insensitive.

Ketika nilai header kredensial tidak diselesaikan, Claude Code melewati penemuan dan menulis baris [gatewayDiscovery] skipped ke log debug dari sesi claude --debug. Jika Anda menyediakan kredensial hanya melalui ANTHROPIC_CUSTOM_HEADERS, Claude Code masih melewati penemuan.

Claude Code membaca id, display_name opsional, dan description opsional dari setiap entri dalam array data respons:

{
  "data": [
    {
      "id": "claude-sonnet-4-6",
      "display_name": "Claude Sonnet 4.6",
      "description": "Default model for everyday coding tasks"
    },
    { "id": "claude-opus-4-8" }
  ]
}

Claude Code menyimpan entri ketika id nya berisi claude atau anthropic di mana saja dalam string, cocok case-insensitive, dan mengabaikan sisanya. ID dengan awalan penyedia seperti vertex_ai/claude-sonnet-4-6 atau bedrock/anthropic.claude-sonnet-4-5 melewati filter; ID yang tidak berisi substring apa pun tidak. Sebelum v2.1.223, Claude Code menyimpan entri hanya ketika id nya dimulai dengan claude atau anthropic, yang menyembunyikan ID dengan awalan penyedia.

Entri pemilih dan caching

Pemilih adalah daftar model interaktif yang terbuka ketika pengembang menjalankan /model di Claude Code. Setiap entri yang ditemukan menggunakan display_name sebagai namanya ketika gateway mengirim satu yang berbeda dari id. Jika tidak, entri menampilkan nama model ketika Claude Code mengenali id, dan id ketika tidak. Misalnya, entri dengan id my-gateway-claude-sonnet-4-6 dan tidak ada display_name muncul sebagai Sonnet 4.6.

Penemuan menambahkan hanya model yang diizinkan oleh pengaturan terkelola availableModels.

Setiap entri juga menampilkan description model, runtuh menjadi satu baris. Entri tanpa description membaca "From gateway" sebagai gantinya. Sebelum v2.1.257, setiap entri yang ditemukan membaca "From gateway".

ID yang ditemukan tidak mendapatkan barisnya sendiri ketika cocok dengan baris yang sudah ada di pemilih:

• ID yang sama: ID yang ditemukan cocok persis dengan ID baris yang ada, atau dua ID adalah ejaan dari versi Fable yang sama.
• Model yang sama dengan alias built-in: ketika ID eksplisit yang ditemukan menamai model yang alias built-in saat ini diselesaikan, pemilih menampilkan hanya baris alias. Misalnya, sementara sonnet diselesaikan ke claude-sonnet-5, claude-sonnet-5 yang ditemukan runtuh ke baris sonnet, dan claude-sonnet-4-6 yang ditemukan masih mendapatkan barisnya sendiri. Sebelum v2.1.197, Claude Code tidak melipat ID ini ke baris built-in, jadi claude-sonnet-5 juga mendapatkan barisnya sendiri "From gateway".

Hasil di-cache ke ~/.claude/cache/gateway-models.json, atau %USERPROFILE%\.claude\cache\gateway-models.json di Windows, dan disegarkan pada setiap startup. Jika Anda menetapkan CLAUDE_CONFIG_DIR, cache berada di bawah direktori itu sebagai gantinya. Jika permintaan gagal atau gateway tidak mengimplementasikan /v1/models, pemilih kembali ke daftar cache dari startup sebelumnya atau ke daftar model built-in. Jika gateway Anda melayani model Claude di bawah alias yang tidak cocok dengan filter penemuan, pengembang dapat menambahkan alias tersebut secara manual dengan variabel konfigurasi model.

Sumber daya terkait

Untuk sisa set dokumentasi gateway dan referensi API yang mendasarinya:

• Ikhtisar gateway: apa itu gateway dan cara memilih antara gateway aplikasi Claude dan produk lainnya
• Gateway LLM lainnya: cara meluncurkan gateway yang dijalankan organisasi Anda dan cara berinteraksinya dengan langganan claude.ai
• Meluncurkan gateway LLM untuk organisasi Anda: daftar periksa admin yang menggunakan panduan ini
• Menghubungkan Claude Code ke gateway LLM: konfigurasi per-pengembang dan tabel pemecahan masalah
• Referensi header beta: set nilai anthropic-beta saat ini
• Messages API: format API yang diimplementasikan gateway format Anthropic