Panduan Menhubungkan Claude Code ke API Pihak Ketiga: Konfigurasi ANTHROPIC_BASE_URL & Troubleshooting

Secara bawaan, Claude Code mengirim semua request ke API resmi Anthropic. Ketika jalur resmi tidak stabil dari jaringan Anda, atau Anda ingin mengelola key, penagihan, dan pergantian model dari satu tempat, mengarahkan Claude Code ke endpoint pihak ketiga yang kompatibel dengan Anthropic adalah solusi paling langsung. Panduan ini hanya membahas konfigurasi praktis: apa yang diubah, cara memverifikasi, dan ke mana memeriksa saat bermasalah.

Pahami dulu: Claude Code adalah "client"

Definisi: Claude Code membaca sekumpulan kecil environment variable untuk menentukan ke mana request dikirim, key apa yang dipakai, dan model mana yang dijalankan. Selama endpoint tujuan mengimplementasikan format request/response Anthropic Messages API, Claude Code bekerja dengannya persis seperti dengan API resmi — tool calling, streaming, dan sesi multi-giliran bergantung pada kompatibilitas endpoint.

Override base URL adalah kemampuan yang didokumentasikan, bukan celah. EXAIV menyediakan endpoint kompatibel Anthropic; lihat halaman setup resmi untuk versi ringkas.

Environment variable yang menentukan

Metode 1: settings.json (disarankan, permanen)

Claude Code membaca environment variable dari ~/.claude/settings.json, berlaku untuk semua session dan mudah dibakukan lintas tim. Contoh untuk EXAIV:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://exaiv.com/api/ai/v1/anthropic",
    "ANTHROPIC_API_KEY": "YOUR_EXAIV_API_KEY",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "model": "claude-opus-5-5"
}

Restart claude setelah menyimpan. Untuk membatasi pada satu proyek, letakkan struktur yang sama di .claude/settings.json pada root proyek.

Metode 2: environment variable sementara (uji cepat)

Tanpa mengubah file — export di shell saat ini:

export ANTHROPIC_BASE_URL="https://exaiv.com/api/ai/v1/anthropic"
export ANTHROPIC_API_KEY="YOUR_EXAIV_API_KEY"

# Verifikasi minimal
claude --print "say hi"

Jika menjawab, endpoint sudah aktif. Untuk permanen, dua baris export dapat ditaruh di ~/.zshrc atau ~/.bashrc — tapi itu memengaruhi semua perintah claude. Jika Anda juga punya subscription resmi, lebih baik pakai settings.json level proyek agar tidak menghabiskan credit pihak ketiga tanpa sengaja.

Di mana melihat model yang tersedia

Endpoint yang menentukan model apa yang ada. Katalog lengkap EXAIV (Claude, GPT, Gemini, DeepSeek, Kimi, dll.) ada di halaman model; ganti model lewat ANTHROPIC_MODEL atau perintah /model di sesi.

Troubleshooting: periksa dengan urutan tetap

Si yang diuntungkan dari setup pihak ketiga

Tidak semua pengguna Claude Code butuh ini. Tiga skenario dengan manfaat paling jelas:

Pengguna dengan jalur resmi yang tidak stabil. Di sebagian wilayah, mencapai endpoint resmi sering timeout — terhenti di tengah sesi coding adalah pembunuh produktivitas sungguhan. Melalui gateway kompatibel yang lebih dekat, jalur lebih pendek dan kelangsungan sesi terasa jelas membaik.

Pengguna berat. Claude Code menghabiskan token jauh lebih besar dari chat biasa — setiap tool call dan pembacaan file masuk ke context. Kalau dipakai harian, bayar sesai pakai dengan harga satuan lebih rendah bisa membuat selisih bulanan yang berarti. Hitung selisihnya dari pemakaian nyata Anda, bukan dari angka marketing pihak mana pun.

Tim yang ingin satu pintu. Ketika tim menjalankan Claude Code, Cursor, dan skrip internal sekaligus, mengarahkan semua tool ke satu gateway dengan satu set key dan satu tagihan jauh lebih mudah dikendalikan daripada akun terpisah per tool. EXAIV menyediakan endpoint kompatibel OpenAI sekaligus Anthropic — satu key menjangkau dua protokol.

Cara menghitung biaya: mulai dari paket trial

EXAIV menagih dalam credits bayar sesuai pakai: beli paket sekali, pemakaian dipotong per panggilan sesuai harga model, tanpa biaya langganan. Tier terendah adalah paket terkecil yang tertera di halaman harga — cukup untuk satu siklus validasi nyata:

1. Daftar dan buat API key di console
2. Konfigurasi Claude Code seperti di atas
3. Jalankan pekerjaan harian Anda satu-dua jam, amati kurva saldo di console
4. Ekstrapolasi ke estimasi bulanan, lalu putuskan naik paket atau tidak

Tiap model punya tarif sendiri, harga presisi ada di halaman harga secara real-time — itulah sebabnya artikel ini tidak pernah menulis angka tetap per panggilan: harga mengikuti perubahan resmi, dan halaman real-time selalu yang paling akurat.

Adopsi tim: satu konfigurasi, tanpa drift

Jebakan terbesar tim adalah tiap orang mengonfigurasi berbeda. Yang terbukti berhasil:

Commit template settings.json ke repo. Simpan file contoh tanpa key di root proyek; anggota baru tinggal salin dan isi key sendiri. Lima menit selesai.

Keluarkan key per orang, jangan dipakai bersama. Tiap anggota memakai key sendiri dengan pemakaian terlihat di console. Masalah mudah ditelusuri, dan offboarding cukup mencabut satu key tanpa mengganggu yang lain.

Pisahkan konteks dengan wrapper script. Jika anggota juga punya subscription resmi, buat skrip alias yang menunjuk ke config level proyek agar kuota resmi dan pihak ketiga tidak saling terpakai.

Dasar keamanan

API key adalah dompen. Empat aturan dasar:

• Key tidak pernah masuk git. File config berisi key asli dikeluarkan dari version control; di repo hanya ada template
• Rotasi berkala. Buat ulang key di console secara berkala dan cabut yang lama; curiga bocor, ganti segera
• Hak akses minimum. Jangan tempel key di log CI, kode frontend, atau chat
• Pantau anomali. Jika laju penurunan saldo menyimpang dari biasanya, cabut key dulu, selidiki kemudian

Referensi cepat setup per OS

Selebihnya — pemetaan model, urutan troubleshooting, praktik keamanan — identik di semua platform.

Mengapa pemetaan tier lebih penting dari yang dikira

Claude Code tidak hanya memanggil model utama pilihan Anda. Di latar belakang ia menembak banyak request kecil — meringkas output tool, menulis commit message, pencarian cepat — dan request-request itu diberi tag tier Sonnet atau Haiku. Jika endpoint Anda tidak memiliki model default untuk tier tersebut, panggilan gagal atau fallback secara tak terduga.

Itulah yang diselesaikan ANTHROPIC_DEFAULT_SONNET_MODEL dan ANTHROPIC_DEFAULT_HAIKU_MODEL: mengarahkan request bertag tier ke model yang benar-benar tersedia di endpoint. Pola paling sederhana dan stabil adalah mengeset keduanya sama dengan model utama Anda; memetakan tier Haiku ke model yang lebih murah adalah optimasi umum setelah semuanya stabil. Logika yang sama berlaku di gateway: cek halaman model untuk tahu apa yang ada, lalu petakan tier ke model yang Anda yakin tersedia.

Tuning timeout dan jaringan

Dua variabel menyelesaikan hampir semua keluhan konektivitas:

• API_TIMEOUT_MS — giliran agen yang kompleks bisa sah memakan waktu berapa menit; timeout klien yang terlalu pendek membunuh request yang sebenarnya berhasil. Jika giliran terpotong tanpa pesan error, naikkan nilainya.
• Proxy tumpang tindih — jika shell Anda juga menyetel HTTP_PROXY/HTTPS_PROXY, request bisa berputar lewat proxy lokal sebelum mencapai gateway. Ketika base URL sudah benar tapi koneksi tetap gagal, uji dengan variabel proxy dilepas sebelum mengubah hal lain.

Keduanya tidak wajib secara bawaan — keduanya kenop pertama yang perlu diputar ketika konfigurasi benar tetapi jalur jaringan salah.

Studi kasus troubleshoot nyata

Pola kegagalan paling umum, dari awal sampai akhir, agar Anda bisa mencocokkan kasus sendiri:

Seorang developer mengedit settings.json, menjalankan claude --print "say hi", dan menerima 401 authentication_error. Naluri bilang endpoint-nya salah. Yang dilakukan justru checklist:

1. Environment variables — key di settings.json sudah benar, tetapi developer tadi juga sempat export ANTHROPIC_API_KEY lama di shell yang sama. Variabel shell menang atas settings.json; key basi itulah yang terkirim. unset ANTHROPIC_API_KEY lalu coba lagi — panggilan kini mengembalikan teks
2. Base URL — tidak ada yang perlu diperbaiki; sudah benar dari awal
3. Key — key-nya sendiri sah sejak awal; ia hanya tertutup (shadowed)
4. Model ID — model utama yang dikonfigurasi ada di endpoint; tetapi tugas latar yang merujuk model Sonnet bawaan gagal. Memetakan ANTHROPIC_DEFAULT_SONNET_MODEL ke model utama yang sama menghapus error terakhir
5. Jaringan — tidak pernah sampai; masalah ada di lapisan satu dan tiga

Total waktu dari frustrasi ke setup berfungsi: sekitar empat menit, begitu checklist menggantikan terkaan. Pelajarannya umum: setiap lapisan entah bekerja entah menunjuk lapisan berikutnya — jangan pernah mendebug dua lapisan sekaligus.

Satu kebiasaan yang menyelamatkan waktu: uji endpoint dulu, bukan kliennya

Sebelum menyentuh konfigurasi apa pun, buktikan dulu endpoint-nya hidup dengan curl telanjang — tanpa Claude Code, tanpa SDK:

curl https://exaiv.com/api/ai/v1/anthropic/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-opus-5-5","max_tokens":32,"messages":[{"role":"user","content":"hi"}]}'

Jika curl ini menjawab, seluruh persoalan menyempit menjadi konfigurasi klien. Jika gagal, Anda tahu masalahnya di key atau jaringan — bukan di Claude Code. Satu menit pengujian ini menghemat berjam-jam menebak-nebak.

FAQ

Bacaan terkait

• Halaman setup Claude Code — versi ringkas di situs
• Referensi Anthropic Messages API — format request/response
• Harga — harga model real-time