Langsung ke konten utama
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 ketika tidak ada. Halaman ini ditulis untuk operator yang mengonfigurasi produk gateway agar bekerja dengan Claude Code. Gateway Claude apps gateway yang berjalan melayani versi yang dapat dibaca mesin dari kontrak ini di GET /protocol, mencakup persyaratan penerusan yang sama ditambah endpoint spesifik Claude apps gateway untuk SSO sign-in, pengiriman managed-settings, dan telemetri. Claude apps gateway berjalan dari binary claude yang sama dengan CLI, jadi Claude apps gateway quickstart adalah jalur tercepat ke instance yang berjalan dari mana Anda dapat mengambil spesifikasinya.
Halaman ini mencakup: 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 satu dari format API berikut ke klien Claude Code. Format mana yang digunakan Claude Code ditentukan oleh konfigurasi klien: variabel di kolom Dipilih oleh tabel di bawah menunjukkan Claude Code ke gateway Anda dalam format tersebut. Google Cloud’s Agent Platform adalah endpoint Claude Google Cloud, sebelumnya Vertex AI; nama variabelnya tetap mempertahankan 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 memperkirakan penggunaan konteks secara lokal. Permintaan inferensi diposting ke /v1/messages?beta=true, jadi cocokkan pada path, bukan URL lengkap. 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 upaya terbaik yang dapat ditolak tanpa merusak apa pun: probe konektivitas HEAD /, dan pada gateway format Amazon Bedrock permintaan GET /inference-profiles?type=SYSTEM_DEFINED.

​
Streaming

Respons inferensi harus streaming. Claude Code mengonsumsi server-sent events saat tiba, jadi gateway yang membuffer respons lengkap sebelum meneruskannya menghentikan klien.

​
Ketidakcocokan format dengan upstream

Format mana yang digunakan klien menentukan apa yang diterima gateway Anda. Mode kegagalan umum adalah ketidakcocokan 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. Penerusan fitur menjelaskan apa yang rusak ketika tidak ada.

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

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

​
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.
Permintaan yang mencapai endpoint tanpa dimodifikasi tidak terpengaruh. 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. Sebelum v2.1.181 blok menyertakan token per-permintaan; pada versi tersebut, atur CLAUDE_CODE_ATTRIBUTION_HEADER=0 jika gateway Anda mengimplementasikan cache seperti 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

Claude Code retry secara otomatis setelah beberapa penolakan upstream dan menonaktifkan kemampuan yang ditolak untuk sisa percakapan. Penolakan field thinking, dari tanda tangan pemikiran, dan dari pesan sistem mid-conversation semuanya pulih dengan cara ini. Penolakan manajemen konteks dan field skema alat tidak retry; kesalahan 400 tersebut mencapai pengembang. 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.

​
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. Ini tidak mempengaruhi penalaran adaptif, yang dipilih oleh model daripada oleh beta, dan tidak pernah menekan kemampuan OAuth yang diperlukan autentikasi langganan. 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. 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. Ini memerlukan Claude Code v2.1.129 atau lebih baru.

​
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
  • Lalu lintas nonessential dinonaktifkan, melalui CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC atau kebijakan organisasi

​
Permintaan dan respons

Permintaan adalah GET /v1/models?limit=1000 dengan timeout 3 detik, dan pengalihan apa pun diperlakukan sebagai kegagalan sehingga kredensial tidak dapat bocor ke target pengalihan. Gateway yang merespons lambat atau mengalihkan /v1/models, bahkan http ke https, gagal penemuan diam-diam; sajikan endpoint langsung di URL dasar yang dikonfigurasi. Permintaan penemuan mengirim tepat satu header kredensial:
  • ANTHROPIC_AUTH_TOKEN sebagai token bearer, ketika diatur
  • Jika tidak, kunci API yang diselesaikan, termasuk nilai apiKeyHelper, di header x-api-key
Ini berbeda dari permintaan inferensi, yang mengirim nilai helper di kedua header. Gateway yang mengautentikasi /v1/models harus menerima x-api-key untuk deployment helper. Header apa pun dari ANTHROPIC_CUSTOM_HEADERS juga disertakan. Claude Code membaca id dan display_name opsional dari setiap entri dalam array data respons, dan mengabaikan entri yang id tidak dimulai dengan claude atau anthropic:

​
Entri pemilih dan caching

Pemilih adalah daftar model interaktif yang terbuka ketika pengembang menjalankan /model di Claude Code. Setiap entri yang ditemukan diberi label “Dari gateway” dan menggunakan display_name ketika disediakan. Pengaturan terkelola availableModels membatasi apa yang dapat ditambahkan penemuan. ID yang ditemukan dilewati ketika cocok persis dengan baris yang sudah ada di pemilih, atau ketika ID yang ditemukan dan yang ada keduanya diselesaikan ke Fable. Mulai dari Claude Code v2.1.197, ID eksplisit yang ditemukan juga dilipat ke entri built-in ketika keduanya diselesaikan ke model yang sama. Baris built-in dikunci pada alias seperti sonnet, jadi ID eksplisit yang ditemukan dari model yang alias saat ini diselesaikan, seperti claude-sonnet-5, runtuh ke baris sonnet, sementara ID yang alias tidak diselesaikan, seperti claude-sonnet-4-6, masih menambahkan baris “Dari gateway” miliknya sendiri di samping entri built-in. Hasil di-cache ke ~/.claude/cache/gateway-models.json, atau %USERPROFILE%\.claude\cache\gateway-models.json di Windows, dan disegarkan pada setiap startup. 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. Untuk sisa set dokumentasi gateway dan referensi API yang mendasarinya: