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

​

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

​

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

​

Retry otomatis dan penerusan kesalahan

• 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

​

Nonaktifkan kemampuan pra-rilis

• 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

​

Penemuan model

​

Ketika penemuan berjalan

• 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

​

Permintaan dan respons

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

{
  "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 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”.

​

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