Panduan kompatibilitas gateway Claude Code

• 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

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

​

Format API

​

Foundry dan Claude Platform on AWS

​

Endpoint opsional dan lalu lintas startup

• 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

​

Streaming

• Jika gateway Anda membuffer respons hingga selesai, Claude Code macet.
• Claude Code mengharapkan urutan event lengkap setiap respons, secara berurutan, hingga event message_delta dan message_stop final. Jika body berakhir dengan bersih setelah blok konten dimulai tetapi sebelum message_delta final tersebut, Claude Code memperlakukan respons sebagai koneksi yang terputus. Respons di atas mungkin tidak lengkap menjelaskan apa yang dilihat pengguna saat itu, dan Retry otomatis mengatakan kapan Claude Code mengeluarkan kembali permintaan sebagai gantinya.
• Ketika guardrail Amazon Bedrock memblokir balasan, event yang dikirim Bedrock dapat mereferensikan blok konten yang content_block_stop-nya sudah tiba, dan Claude Code bergantung pada penerimaan event tersebut sebagaimana dikirim. AWS Guardrails menjelaskan bagaimana balasan tersebut berakhir.
• Claude Code membatalkan respons streaming setelah tidak ada byte yang mencapainya lebih lama dari idle timeout streaming-nya. Selama jeda thinking yang panjang, event SSE ping dari upstream dapat menjadi satu-satunya byte pada stream, sehingga gateway yang menghapus atau membuffer event tersebut dapat memicu timeout itu di tengah respons. Gateway yang menerjemahkan dari upstream tanpa ping, seperti event stream biner Amazon Bedrock, memiliki celah yang sama kecuali gateway tersebut mengeluarkan event ping sendiri.
• Pada format Amazon Bedrock InvokeModel, Claude Code membaca respons /model/{model}/invoke-with-response-stream sebagai body biner application/vnd.amazon.eventstream yang dikembalikan Bedrock, dan tidak dapat mem-parsing-nya setelah gateway mengonversinya menjadi server-sent events atau menulis ulang header Content-Type tersebut. Kesalahan streaming di belakang gateway atau proxy menjelaskan apa yang dilihat pengguna saat itu.

​

Format mismatch dengan upstream

• 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

​

Bagaimana metode koneksi mengubah 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

​

Pengaturan untuk ID model yang tidak dikenali

• Context window: Claude Code mengasumsikan 200K, atau 1M ketika ID membawa [1m]. Untuk mendeklarasikan jendela sebenarnya, lihat Perbaiki jendela untuk gateway atau ID model kustom
• 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 penerusan fitur

​

Header permintaan

​

Header petunjuk gateway

• 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

• 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

​

Response headers

​

Blok atribusi prompt sistem

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

• 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

​

Pasangan header beta dan field body

​

Retry otomatis dan penerusan kesalahan

• Ketika 400 menyatakan bahwa nilai thinking.type enabled atau adaptive tidak didukung, Claude Code mencoba ulang sekali dengan tipe lainnya dan mempertahankan field thinking. Permintaan berikutnya ke model tersebut tetap menggunakan tipe yang telah diganti sampai Claude Code keluar. Sebelum v2.1.121, Claude Code tidak mencoba ulang, sehingga thinking.type.enabled is not supported sampai ke pengembang
• Ketika upstream menolak entri role: "system" di dalam messages, Claude Code mencoba ulang sekali tanpa pesan sistem mid-conversation tersebut dan membawa teksnya dalam pesan pengguna sebagai gantinya. Permintaan berikutnya dalam percakapan tetap menggunakan bentuk tersebut sampai pengembang menjalankan /clear atau percakapan dipadatkan
• Ketika upstream hanya menolak penanda cache_control pada pesan sistem mid-conversation, Claude Code mempertahankan pesan sistem dan mencoba ulang sekali dengan penanda dipindahkan. Penanda ditempatkan pada entri terakhir dalam messages yang bukan pesan sistem, dalam retry tersebut dan dalam permintaan berikutnya sampai Claude Code keluar
• 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 tool advisor dalam tools sebagai tipe tool yang tidak dikenali, Claude Code mencoba ulang sekali tanpa entri tersebut dan nilai anthropic-beta-nya. Permintaan berikutnya tidak menyertakan keduanya. Claude Code mengenali penolakan ini dengan respons 400 atau 422 yang pesannya menyebutkan tipe tool setelah Input tag, seperti Input tag 'advisor_20260301'. Sebelum v2.1.280, Claude Code tidak mencoba ulang penolakan ini
• Ketika upstream menolak output_config.effort atau nilai anthropic-beta-nya, gateway melihat permintaan tersebut sekali lagi tanpa keduanya. Permintaan berikutnya tidak menyertakan keduanya. Gateway Anda tidak memerlukan perubahan jika meneruskan 400 dari upstream tanpa modifikasi dan pesannya:
  • Menyebutkan output_config.effort bersama dengan Extra inputs are not permitted
  • Menyatakan bahwa model tidak mendukung parameter effort
  • Diawali dengan Unexpected value(s) dan mencantumkan effort-2025-11-24 untuk header anthropic-beta. Memerlukan v2.1.310 atau lebih baru. Pengembang yang ANTHROPIC_BETAS-nya mencantumkan nilai tersebut tetap mengirimkannya dan mendapatkan 400, jadi minta mereka menghapus entri tersebut
• Ketika upstream menolak field context_management atau nilai anthropic-beta-nya, gateway melihat permintaan tersebut sekali lagi tanpa keduanya. Permintaan berikutnya tidak menyertakan keduanya. Claude Code mengenali penolakan ini dari pesannya, misalnya pesan yang berisi context_management: Extra inputs are not permitted. Sebelum v2.1.304, Claude Code tidak mencoba ulang penolakan ini
• Ketika 400 menolak nilai anthropic-beta lain dengan menyebutkan namanya, gateway melihat permintaan tersebut sekali lagi tanpa nilai itu jika retry mencakup nilai tersebut
• Ketika upstream menolak field tool beta selain defer_loading, seperti strict, kesalahan 400 mencapai pengembang. Sebelum itu terjadi, gateway dapat melihat permintaan tersebut lagi tanpa field pencarian tool. Untuk berhenti mengirim field semacam itu, minta pengembang mengatur CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

​

Retry tanpa nilai beta yang ditolak

• Kalimat API: kalimat Unexpected value(s) yang mencantumkan nilai tersebut untuk header anthropic-beta
• Token beta_header:: capability_rejected: beta_header: diikuti oleh nilai tersebut, sebuah token capability_rejected:

• Nilai yang memiliki retry sendiri, seperti advisor atau pencarian tool: gateway melihat retry milik kemampuan tersebut sebagai gantinya
• Nilai yang tidak dikenali Claude Code: nilai yang diatur pengembang melalui ANTHROPIC_BETAS tetap ada pada setiap permintaan, sehingga permintaan pengembang terus gagal dengan 400. Minta pengembang menghapus entri tersebut
• invalid beta flag tanpa keterangan lain: Claude Code menebak nilai mana yang ditolak upstream. Jika permintaan membawa nilai yang ditebaknya, gateway melihat permintaan tersebut lagi tanpa nilai itu. Jika 400 tetap mencapai pengembang, minta gateway Anda menyebutkan nilai yang ditolak dalam salah satu bentuk tersebut

​

Berapa lama nilai beta yang ditolak tetap dikecualikan

​

Retry tanpa pencarian tool

​

Nonaktifkan kemampuan pra-rilis

• Manajemen konteks dan field body context_management-nya
• Field skema tool beta, seperti strict dan defer_loading. Field tool standar name, description, input_schema, dan cache_control tetap ada
• Field output terstruktur output_config.format. Memerlukan Claude Code v2.1.287 atau lebih baru
• Field output_config.task_budget
• MCP Tool Search, sehingga setiap tool MCP dimuat di awal kecuali organisasi Anda tetap mengaktifkannya melalui pengaturan terkelola

• Nilai anthropic-beta untuk konteks diperluas, interleaved thinking, dan upaya, yang juga diterima oleh penyedia cloud
• Field tingkat atas output_config.effort. Retry otomatis dan penerusan kesalahan membahas upstream yang menolaknya
• Field thinking penalaran adaptif, yang tidak memiliki header beta
• Entri role: "system" yang membawa pesan sistem mid-conversation
• Nilai anthropic-beta OAuth yang diperlukan autentikasi langganan
• Nilai header dan field body yang ditambahkan sendiri oleh pengembang melalui ANTHROPIC_BETAS atau CLAUDE_CODE_EXTRA_BODY

• Pada koneksi langsung tanpa konfigurasi HIPAA, 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
• Pada penyedia cloud, atau masuk melalui gateway aplikasi Claude, override tidak memiliki efek
• Dalam sesi yang mendapatkan konfigurasi HIPAA, override tidak memiliki efek dan pencarian alat tetap nonaktif

​

Penemuan model

​

Kapan penemuan berjalan

• Variabel penyedia CLAUDE_CODE_USE_* mana pun ditetapkan, meskipun ANTHROPIC_BASE_URL juga ditetapkan
• ANTHROPIC_BASE_URL tidak ditetapkan atau mengarah ke api.anthropic.com

​

Permintaan dan respons

• Authorization: ANTHROPIC_AUTH_TOKEN sebagai bearer token, jika tidak ada maka nilai apiKeyHelper sebagai bearer token.
• x-api-key: kunci API yang di-resolve oleh Claude Code, seperti ANTHROPIC_API_KEY. Ketika nilai helper adalah satu-satunya kredensial, header ini juga membawanya, sehingga nilai tersebut tiba di kedua header.

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

​

Entri pemilih dan caching

• ID yang sama: ID yang ditemukan sama persis dengan ID baris yang sudah ada, atau kedua ID merupakan ejaan dari versi Fable yang sama.
• Model yang sama dengan alias bawaan: ketika ID eksplisit yang ditemukan menyebut model yang saat ini di-resolve oleh alias bawaan, pemilih hanya menampilkan baris alias. Misalnya, selama sonnet di-resolve ke claude-sonnet-5-5, claude-sonnet-5-5 yang ditemukan digabungkan ke dalam baris sonnet, sedangkan claude-sonnet-5 yang ditemukan tetap mendapatkan barisnya sendiri.

​

Sumber daya terkait

• 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