Cloud
Claude Code di Balik LLM Gateway: Apa yang Rusak dan Kenapa
Agustus 202613 menit baca
Tidak dengan sendirinya. Menyetel base URL saja mengalirkan request lewat gateway, tetapi login claude.ai yang tersimpan tetap menjadi kredensial aktif, sehingga batas pemakaian dan penagihannya tetap berlaku. Menambahkan kredensial gateway atau apiKeyHelper-lah yang menggantikan langganan, dan setelah itu lalu lintasnya ditagih per token kepada pemilik kredensial yang diteruskan.
Remote Control sama sekali tidak tersedia. Tool search mati secara default karena sebagian besar proxy tidak meneruskan blok tool_reference, sehingga definisi tool MCP dimuat di depan. Claude Code tidak bisa memverifikasi dukungan context 1M, jadi sesi Sonnet 5 menganggarkan 200K sampai Anda memilih entri model 1M, dan ia berhenti memeriksa syarat usage credit untuk extended context.
Dua penyebab yang mungkin. Sebelum v2.1.237, Claude Code menandai blok sistem di tengah percakapan untuk di-cache lewat gateway, dan gateway yang menghapus penanda itu membuat seluruh percakapan ditagih sebagai input tanpa cache setiap giliran. Penyebab lainnya adalah tool search yang mati, yang memuat setiap definisi tool MCP ke system prompt pada tiap request.
Tidak. Anthropic tidak mendukung pengalihan Claude Code ke model non-Claude lewat gateway mana pun, dan tidak mengesahkan, memelihara, atau mengaudit produk gateway pihak ketiga. Gateway apa pun yang mengekspos format API yang didukung akan bekerja untuk model Claude, tetapi penggantian model berada di luar yang didukung.
Terus-menerus. Claude Code menambah kemampuan pada setiap rilis, dan gateway yang tidak meneruskannya merusak fitur bersangkutan — secara senyap, untuk semua orang sekaligus. Referensi protokol gateway mendokumentasikan endpoint, header, dan pass-through fitur yang perlu dibuat benar, dan sebaiknya ada orang yang membacanya terhadap tiap rilis Claude Code.
Ringkasan Utama
Mengalirkan Claude Code lewat LLM gateway memusatkan kredensial, atribusi pemakaian, kendali biaya, dan audit logging. Ia juga mengubah perilaku: Remote Control jadi tidak tersedia, tool search mati secara default, dukungan extended context tidak bisa diverifikasi, dan gateway yang menghapus penanda cache bisa menagih seluruh percakapan Anda sebagai input tanpa cache di setiap giliran.
Sebuah tim yang saya kenal pindah ke gateway pada hari Jumat dan menghabiskan Selasa berikutnya mencoba memahami kenapa belanja token mereka kira-kira tiga kali lipat tanpa perubahan cara siapa pun bekerja. Tidak ada yang rusak. Gateway mereka diam-diam menghapus satu penanda pada satu blok request, dan setiap giliran ditagih seolah percakapan itu tidak pernah di-cache.
Gateway adalah komponen infrastruktur enterprise yang wajar dan sering memang diperlukan, dan tulisan tentangnya hampir seluruhnya berkonsentrasi pada apa yang Anda dapat. Tulisan ini separuh lainnya: perbedaan dua variabel yang menentukan siapa yang ditagih, fitur yang berhenti bekerja ketika base URL menunjuk selain Anthropic API, dan kegagalan caching yang mahal justru karena tidak terlihat.
Alasan memakainya memang kuat, dan layak dinyatakan lugas sebelum peringatannya. Gateway memberi organisasi satu tempat untuk mengelola lima hal:
Empat dari lima itu berlaku entah upstream-nya Anthropic API atau cloud provider. Yang kelima punya syarat: berpindah provider tanpa mengonfigurasi ulang mesin bergantung pada gateway yang mengekspos satu endpoint berformat Anthropic apa pun upstream-nya. Gateway yang mengekspos format milik satu provider justru mengikat setiap konfigurasi klien ke provider tersebut, dan itu diam-diam menghapus manfaat yang paling sering disebut orang saat memilihnya.
Inilah perbedaan yang paling sering saya lihat disalahpahami, dan ia menentukan baik penagihan maupun batas pemakaian. Menyetel base URL saja tidak menggantikan langganan; menambahkan kredensial menggantikannya.
# These two configurations look similar and bill completely
# differently. This is the single most important distinction
# on this page.
# 1. Base URL ONLY.
# Requests route through the gateway, but a saved claude.ai
# login stays the ACTIVE CREDENTIAL — so the subscription's
# usage limits and billing still apply.
ANTHROPIC_BASE_URL=https://gateway.internal.example.com
# 2. Base URL PLUS a gateway credential (or an apiKeyHelper).
# The credential REPLACES the subscription login for that
# session. Subscription limits no longer apply, and the
# traffic is billed per token to whoever owns the credential
# the gateway forwards.
ANTHROPIC_BASE_URL=https://gateway.internal.example.com
ANTHROPIC_AUTH_TOKEN=<the developer's gateway credential>
# A gateway passing case 1 through to Anthropic must forward the
# OAuth capability in the anthropic-beta header, or the saved
# login stops working.Selisih itu bukan kosmetik. Dengan kredensial aktif, batas pemakaian langganan berhenti berlaku dan lalu lintasnya ditagih per token kepada pemilik kredensial yang diteruskan gateway — akun Console Anda, atau akun Bedrock, Agent Platform, maupun Foundry Anda ketika gateway mengarahkannya ke sana. Tim yang menyetel kedua variabel sambil mengharapkan perilaku langganan menemukan perubahannya di sebuah tagihan, bukan di sebuah dialog.
Urutannya sama apa pun produk gateway yang Anda pilih, dan ia pendek:
Mengarahkan base URL ke host non-first-party mengubah beberapa perilaku sekaligus. Tidak satu pun menghasilkan error yang menyebut gateway sebagai penyebabnya, dan itulah yang membuat daftar ini layak disimpan:
# Features that stop working, or quietly change behaviour,
# when ANTHROPIC_BASE_URL points somewhere that is not
# api.anthropic.com:
Remote Control unavailable outright. Unset the variable to
use it. (Before v2.1.196 it was allowed.)
Tool search disabled by default, because most proxies do
not forward tool_reference blocks. Every MCP
tool definition then loads UPFRONT into the
system prompt. Set ENABLE_TOOL_SEARCH=true to
override — requests FAIL on proxies that
cannot handle it.
1M context Claude Code cannot verify support, so a
Sonnet 5 session budgets 200K. Pick the 1M
entry in the model picker to get it back.
Plan checks Claude Code stops checking usage-credit
requirements for extended context; the
gateway decides whether the request succeeds.
Auto-compaction An unrecognised model ID compacts at the
window Claude Code ASSUMES for that ID.
Cache markers See below — the expensive one.Claude Code tetap memasang cache breakpoint milik percakapan itu sendiri, jadi gateway yang meneruskannya tetap meng-cache percakapan Anda secara normal. Masalahnya ada di blok terpisah: Claude Code menambahkan konteks sistem di tengah percakapan, seperti pemberitahuan perubahan file, dan sebelum v2.1.237 ia menandai blok itu untuk di-cache lewat gateway juga. Gateway yang diam-diam menghapus penanda tersebut membuat seluruh percakapan ditagih sebagai input tanpa cache di setiap giliran.
Sejak v2.1.237, Claude Code tidak lagi menandai blok itu untuk di-cache lewat gateway, jadi ia muncul sebagai input tanpa cache pada tiap request — biaya kecil yang bisa diprediksi, bukan bencana. Itulah perilaku yang benar saat ini dan itulah perbaikan untuk kegagalan lama tersebut. Kalau Anda berada di balik gateway dan angka Anda terlihat aneh, periksa versi Claude Code sebelum mulai menyelidiki gateway-nya.
Perhatikan rasio token cache-read terhadap cache-creation, bukan belanja mutlaknya. Masalah gateway muncul sebagai creation yang tetap tinggi giliran demi giliran, dan itu sinyal jauh lebih jelas daripada tagihan bulanan serta terlihat dalam satu sesi saja. Script statusline yang membaca objek usage adalah cara termurah menjaga angka itu tetap di depan mata selama Anda menggulirkan sebuah gateway.
Gateway bukan satu-satunya cara mendapat kendali terpusat, dan alternatifnya punya pertukaran yang sungguh berbeda. Pertanyaannya adalah properti mana yang benar-benar Anda butuhkan, karena tiap pilihan mengorbankan hal yang berbeda.
Tiga cara memusatkan kendali, dan ongkos masing-masing:
| Pendekatan | Yang Anda dapat | Yang Anda korbankan |
|---|---|---|
| LLM gateway pihak ketiga | Kendali penuh, pergantian provider, audit trail milik sendiri | Fitur yang butuh Anthropic API, plus pemeliharaan permanen |
| Claude apps gateway | Sign-in SSO dan telemetri OTLP, dipelihara pihak hulu | Keluwesan lebih sedikit daripada produk yang Anda konfigurasi sendiri |
| Managed settings tanpa gateway | Kendali kebijakan dan permission tanpa apa pun untuk dioperasikan | Tanpa pemusatan kredensial maupun audit log per request |
Anthropic tidak mengesahkan, memelihara, atau mengaudit produk gateway pihak ketiga, dan tidak mendukung pengalihan Claude Code ke model non-Claude lewat gateway mana pun. Kalau bagian terakhir itu tujuan Anda, ini arsitektur yang keliru dan sebanyak apa pun kepatuhan protokol tidak akan menjadikannya arsitektur yang didukung.
Pertukaran yang paling penting bukan soal teknis melainkan organisasi: gateway itu menjadi infrastruktur yang kini dioperasikan organisasi Anda. Claude Code menambah kemampuan pada setiap rilis, dan gateway yang tidak meneruskannya akan merusak fitur yang bersangkutan. Artinya produk gateway itu harus dijaga tetap mutakhir seiring Claude Code berkembang — bukan sekali saat rollout, melainkan terus-menerus.
Referensi protokolnya ada justru untuk ini: ia mendokumentasikan endpoint, header yang harus diteruskan, dan pass-through fitur yang perlu dibuat benar oleh sebuah gateway. Siapa pun yang memiliki gateway itu sebaiknya membacanya terhadap setiap rilis Claude Code, karena mode gagalnya bukan sebuah outage. Ia sebuah fitur yang diam-diam berhenti bekerja untuk semua orang sekaligus, dan sebuah percakapan dukungan yang dibuka oleh developer dengan kalimat dulu ini bisa.
Jalankan gateway kalau Anda butuh kredensial terpusat, anggaran ditegakkan di satu tempat, atau audit log yang Anda miliki sendiri. Masuklah dengan kesadaran bahwa ia komponen yang kini Anda pelihara, bahwa segelintir fitur tidak akan tersedia di baliknya, dan bahwa mode gagalnya yang paling mahal bersifat senyap. Periksa versi Claude Code Anda lebih dulu ketika angkanya terlihat aneh, pantau rasio cache alih-alih tagihan, dan tuliskan nama seseorang sebagai penanggung jawab menjaga gateway tetap mutakhir — karena alternatifnya adalah menemukan celah itu tiga rilis kemudian.
Sumber & bacaan lanjutan