Claude Code Router — arahkan Claude Code ke model apa pun, atau lewati router sepenuhnya

Sebagian besar orang yang mencari Claude Code Router menginginkan salah satu dari dua hal yang berbeda: merutekan Claude Code di antara beberapa provider model, atau sekadar menjalankan Claude Code di tempat yang lebih murah daripada harga daftar Anthropic. Hanya yang pertama memerlukan router. Claude Code membaca ANTHROPIC_BASE_URL secara native, jadi yang kedua hanya memerlukan tiga variabel lingkungan dan sama sekali tidak memerlukan perangkat lunak tambahan.

Panduan ini mencakup kedua jalur tersebut, dengan nama variabel yang persis, jebakan kredensial yang menghasilkan 401 diam-diam, dan daftar jujur tentang hal-hal yang berhenti berfungsi di balik gateway apa pun. Jika Anda baru-baru ini membaca tulisan CCR lain, langsung buka Option B terlebih dahulu: config.json yang disuruh diedit oleh artikel-artikel tersebut bukan lagi konfigurasi yang dibaca router.

Yang mana yang sebenarnya Anda perlukan?

Router adalah layanan lokal: satu proses tambahan yang harus dijalankan, dikonfigurasi, dan terus diperbarui — dan, sejak 2026, berupa aplikasi desktop dengan UI sendiri, bukan file yang Anda edit. Biaya ini sepadan ketika Anda benar-benar memerlukan perutean multi-provider, pencatatan biaya per permintaan, atau pemilihan model di tingkat subagent. Biaya ini tidak sepadan jika URL dasar sudah mencukupi.

Opsi A — mengganti URL dasar (tanpa instalasi)

Kunavo menyediakan Anthropic Messages API native di /v1/messages, yaitu endpoint yang dipanggil Claude Code. Arahkan ke sana:

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...              # create at kunavo.com/app/keys
export ANTHROPIC_MODEL=claude-sonnet-5             # exact slug — see the table below
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5     # the opus alias and plan mode (v2.1.280+)
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5   # the sonnet alias; Sonnet 5.5 is not on Kunavo
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5   # background tasks

ANTHROPIC_BASE_URL hanya merupakan origin—Claude Code sendiri menambahkan /v1/messages, jadi jangan sertakan path. Pertahankan baris model: default bawaan Claude Code dan alias opus-nya sama-sama mengarah ke Opus terbaru, dan jika Kunavo belum menyediakan model tersebut, permintaan pertama mengembalikan 404. Alias sonnet meminta Sonnet 5.5, yang tidak disediakan Kunavo, sehingga tanpa baris ANTHROPIC_DEFAULT_SONNET_MODEL /model sonnet, fase eksekusi opusplan dan setiap subagen yang ditetapkan ke model: sonnet semuanya mengembalikan 404. Alias opus dipatok ke Opus 5.5 (claude-opus-5-5), yang memerlukan Claude Code v2.1.280 atau yang lebih baru—jalankan claude update jika versi Anda lebih lama. Dapatkan key dari dasbor setelah mendaftar dan mengisi saldo sebesar $10; key tersebut hanya ditampilkan sekali.

Variabel kredensial mana — dan mengapa penting

Claude Code mengirimkan dua variabel kredensial dalam header HTTP yang berbeda, dan kunci di header yang tidak dibaca server akan gagal dengan 401:

Pilih ANTHROPIC_AUTH_TOKEN karena satu alasan konkret: ANTHROPIC_API_KEY memerlukan persetujuan satu kali dalam sesi interaktif, dan kunci yang pernah Anda tolak akan diabaikan setelahnya tanpa prompt — kegagalan membingungkan ketika variabel jelas sudah disetel tetapi jelas tidak digunakan. Penemuan model tidak menentukan hal ini di Kunavo. Penemuan model gateway Claude Code hanya mengirim token bearer ketika ANTHROPIC_AUTH_TOKEN disetel dan menggunakan x-api-key sebagai fallback, sedangkan endpoint /v1/models Kunavo membaca kunci dari salah satu header.

Membuatnya tetap berlaku

Ekspor shell hanya berlaku untuk terminal tersebut dan apa pun yang dijalankan dari sana — editor yang dibuka dari dock tidak akan melihatnya, begitu pula agen latar belakang. Masukkan nilainya ke file pengaturan agar berlaku untuk semuanya:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Gunakan ~/.claude/settings.json untuk semua proyek. Jangan pernah menaruh kunci di .claude/settings.json milik proyek — file tersebut akan di-commit.

Verifikasi sebelum mempercayainya

Uji endpoint secara langsung terlebih dahulu, agar kegagalan mengarah ke konfigurasi, bukan ke Claude Code:

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

# A response starting with {"id":"msg_ means the URL and key both work.
# 401 -> the key is in the wrong header; see "Which credential variable" below.

Kemudian jalankan claude dari shell yang sama dan jalankan /status. Baris Anthropic base URL yang menampilkan api.kunavo.com dan baris Auth token yang menyebut variabel Anda mengonfirmasi bahwa kedua bagian aktif.

Tetapkan model kustom — pilih slug secara eksplisit

Kunavo menyelesaikan slug model dengan pencocokan persis dan tidak membuat alias untuk nama dengan akhiran tanggal, sehingga claude-sonnet-4-5-20250929 mengembalikan 404 sementara claude-sonnet-5 berhasil. Selalu tetapkan ANTHROPIC_MODEL alih-alih mengandalkan default bawaan:

Variabel alias memungkinkan perutean per tugas tanpa router: ANTHROPIC_DEFAULT_OPUS_MODEL digunakan oleh alias opus dan mode plan, ANTHROPIC_DEFAULT_SONNET_MODEL digunakan oleh sonnet dan fase eksekusi opusplan, sedangkan ANTHROPIC_DEFAULT_HAIKU_MODEL digunakan oleh haiku serta pekerjaan latar belakang Claude Code, yaitu pembuatan ringkasan dan judul. Saat menggunakan Kunavo, dua pengaturan terakhir wajib karena jika tidak dipatok, aliasnya meminta ID model yang tidak disediakan Kunavo (Sonnet 5.5 dan Haiku 5.5 sejak v2.1.293). Arahkan pengaturan Haiku ke claude-haiku-4-5 agar pekerjaan latar belakang itu juga tidak menggunakan model utama. (ANTHROPIC_SMALL_FAST_MODEL adalah ejaan pengaturan yang sama dan sudah tidak digunakan lagi.)

Opsional: tampilkan setiap model di pemilih

Tetapkan CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 (Claude Code v2.1.129+) dan Claude Code akan meminta GET /v1/models saat startup, lalu menambahkan hasilnya ke pemilih /model berlabel Dari gateway. Kunavo menyediakan endpoint tersebut, sehingga setiap model Claude yang diaktifkan akan muncul dan /model menjadi menu langsung, bukan daftar yang Anda kelola secara manual. Kedua variabel kredensial dapat digunakan untuk ini — lihat di atas.

Opsi B — claude-code-router, sebagaimana benar-benar berfungsi sekarang

Mulailah dari sini, karena hampir semua hal yang ditulis tentang CCR menjelaskan versi yang sudah tidak ada. Router dahulu berupa file JSON dan perintah ccr code. Sekarang router merupakan control plane lokal dengan aplikasi desktop, UI manajemen, log permintaan, dan gateway model — dan config.json yang ditampilkan setiap tutorial tidak lagi mengonfigurasinya.

CCR menyimpan konfigurasi runtime-nya di ~/.claude-code-router/config.sqlite (%APPDATA%\claude-code-router\config.sqlite di Windows). config.json lama dibaca sekali, sebagai sumber migrasi, ketika belum ada konfigurasi SQLite. Setelah proses pertama itu, mengeditnya tidak memengaruhi konfigurasi yang sedang berjalan — tanpa error dan tanpa peringatan. Blok Providers yang Anda tempel dengan cermat sama sekali bukan konfigurasi.

Ini juga berlaku untuk halaman ini sebelum 2026-09-06: cuplikan JSON yang dahulu ada di sini salah, dan jenis kesalahan ini dapat menghabiskan waktu sore karena tidak ada yang memberi tahu bahwa file tersebut diabaikan. Konfigurasi sekarang dilakukan di UI (atau, untuk pencadangan, Settings → Export data — jangan menyalin file SQLite aktif saat CCR sedang berjalan).

Instal dan jalankan

CCR tersedia dalam dua cara: aplikasi desktop dari GitHub Releases (tray, pembaruan otomatis, integrasi desktop) dan CLI npm untuk deployment tanpa headless atau deployment yang diawasi. Keduanya menggunakan direktori konfigurasi yang sama.

# CCR ships as a desktop app (GitHub Releases) or an npm CLI. Both read the
# same ~/.claude-code-router directory. The CLI needs Node.js 22+.
npm install -g @musistudio/claude-code-router
ccr ui        # management UI on :3458, model gateway on :3456

# Configure the provider and an Agent Config profile in that UI, then launch
# Claude Code through the profile by name:
ccr "Claude Code - Kunavo"        # npm CLI
ccr-app "Claude Code - Kunavo"    # the desktop app's own launcher

# There is no 'ccr code' in the current command reference. The service commands
# are start / ui / stop / serve / web; everything else is a profile name.

Menambahkan Kunavo memerlukan satu entri provider — Providers → Add provider, preset Other / custom API endpoint, endpoint https://api.kunavo.com, kunci sk-kn- Anda — dan satu profil Agent Config → Add profile → Claude Code. Versi langkah demi langkah per bidang, termasuk Check Connection dan penemuan model, tersedia di halaman integrasi Claude Code Router. Bagian selanjutnya membahas hal-hal yang tidak dicakup halaman tersebut: kredensial, ekonomi, dan mode kegagalan.

Tiga kredensial, dan kredensial mana yang menyebabkan 401

Ini adalah penyebab paling umum konfigurasi yang sebenarnya berfungsi tampak rusak. CCR memiliki tiga rahasia terpisah dan masing-masing mengautentikasi hop yang berbeda:

Port pairing juga sering menjebak pengguna: manajemen secara default menggunakan 127.0.0.1:3458 dan gateway model menggunakan 127.0.0.1:3456. URL dasar yang diarahkan ke 3458 mencapai UI, bukan gateway. (Docker sengaja menyatukan keduanya di balik satu endpoint Nginx, sehingga instruksi Docker terlihat berbeda.) UI yang dapat dijangkau bukan berarti gateway berfungsi: periksa /health pada alamat gateway, dan pastikan Server menampilkan Running.

Peta per tier adalah inti persoalannya

Claude Code tidak meminta model, melainkan tier — loop utama menginginkan Sonnet atau Opus, sedangkan pekerjaan latar belakang (subagent, pencarian, ringkasan, judul percakapan) menginginkan model kecil yang cepat. Profil Claude Code di Agent Config menampilkan semua itu sebagai bidang terpisah: Model default serta override opsional Fable, Opus, Sonnet, dan Haiku, yang masing-masing menerima nilai Provider/model. Biarkan tier kosong dan Claude Code akan memilihnya.

Baca tabel tersebut sebelum menyalin pemetaan tier orang lain, karena pemisahan yang jelas adalah tuas pertama: claude-sonnet-5 berbiaya 50% lebih rendah daripada claude-opus-5-5 di Kunavo ($1,40 / $7,00 dibandingkan dengan $2,80 / ). Tuas kedua adalah tier Haiku: dengan harga $0,70 / $3,50, biayanya 2× lebih murah daripada Sonnet 5, dan tier ini membawa volume yang tidak pernah Anda lihat—setiap subagen, setiap proses triase file, setiap judul yang dibuat. claude-sonnet-4-6 bukan lagi Sonnet murah: dengan harga $2,10 / $10,50, biayanya 50% lebih tinggi daripada Sonnet 5, sehingga cuplikan di atas menetapkan ANTHROPIC_MODEL=claude-sonnet-5.

Perutean subagent — hal yang tidak dapat dilakukan peta tier

Override tier mematok semua subagent ke satu model. CCR dapat bekerja lebih terperinci: ketika permintaan Claude Code cocok dengan rute bawaan, CCR menyisipkan daftar model yang tersedia ke dalam deskripsi alat Agent / Task, lalu Claude Code mengawali prompt setiap agen yang dibuat dengan tag yang menyebut model yang diinginkannya:

<CCR-SUBAGENT-MODEL>provider/model</CCR-SUBAGENT-MODEL>

CCR menghapus tag tersebut dan merutekan permintaan itu sebagaimana mestinya, sehingga subagent pencarian dapat berjalan di Haiku sementara subagent peninjauan berjalan di Opus, dipilih per tugas, bukan dipatok. Pengalihannya mudah terlewat: mekanisme ini nonaktif hingga setidaknya satu model memiliki Description di halaman Models. Tanpa deskripsi, CCR tidak menyisipkan apa pun dan setiap subagent diam-diam kembali ke default profil. Tulis deskripsi berdasarkan kecocokan tugas — “code search, file triage, cheap parallel subagents” untuk Haiku, “architecture analysis, high-risk review” untuk Opus. Jika berfungsi, log permintaan menampilkan builtin:claude-code-subagent sebagai alasan rute.

Pilihan protokol, dan biaya yang ditimbulkannya pada cache

CCR memeriksa endpoint dan memilih protokol wire. Berikan origin dasar https://api.kunavo.com dan CCR akan menggunakan Anthropic Messages; berikan https://api.kunavo.com/v1 dan CCR akan menggunakan format OpenAI-compatible. Kedua permukaan aktif dengan kunci yang sama, dan Anda dapat mengganti deteksi otomatis di pengaturan Advanced.

Pilih format Anthropic Messages. Format ini mempertahankan cache_control di wire, sehingga caching prompt mencapai model dan input yang di-cache ditagihkan sebesar 10% dari tarif input (cara kerjanya) — pada loop agen yang mengirim ulang awalan stabil di setiap langkah, ini merupakan penghematan tunggal terbesar yang tersedia. Catatan pentingnya: router di dalam jalur tetap mengedit permintaan: CCR menghapus pesan sistem header penagihan yang disisipkan Claude Code, dan menambahkan daftar model ke deskripsi alat ketika perutean subagent aktif. Keduanya berada sebelum titik pemisah cache Anda, sehingga setiap perubahan pada konten tersebut menimbulkan satu cache miss sementara awalan baru dipanaskan. Setelah itu stabil — tetapi ini adalah alasan nyata mengapa Opsi A sedikit lebih baik dalam caching daripada Opsi B, selain lebih sedikit yang harus dijalankan.

Meski begitu, caching prompt tetap mencapai model pada format yang kompatibel dengan OpenAI. Pada prompt yang panjang, Kunavo menetapkan sendiri breakpoint cache pada rute tersebut: pada prompt sistem, pada definisi alat, dan pada pesan terakhir begitu percakapan berisi giliran asisten. cache_control yang datang pada pesan atau definisi alat tetap dipertahankan.

Penanganan kegagalan: mencoba ulang versus beralih ke target cadangan

Default on failure di halaman Routing layak ditetapkan sebelum Anda membutuhkannya. Retry mengirim ulang ke model yang sama pada 408, 409, 429, dan 5xx, dengan mematuhi Retry-After dan, jika tidak ada, menerapkan backoff eksponensial dari 1s hingga batas 30s. Fallback targets menelusuri daftar model cadangan yang berurutan dan dipicu oleh setiap 4xx atau 5xx, dengan asumsi bahwa model tidak ditemukan atau penolakan provider mungkin hanya memengaruhi target saat ini. Aturan individual dapat mengganti pengaturan global. Ketika fallback berjalan, respons menyertakan x-ccr-fallback-attempts dan x-ccr-fallback-model agar Anda dapat mengetahuinya setelah kejadian.

Verifikasi bahwa CCR benar-benar berada di jalur

Jalankan Claude Code dari profil, kirim satu pesan, lalu buka Request logs di CCR. Baris tersebut menampilkan request model (yang diminta Claude Code), resolved provider, dan resolved model (tujuan permintaan) — ketiganya menjadi bukti. Di dalam CLI, /model mencantumkan model yang diekspos CCR. Jika Claude Code membalas tetapi tidak ada baris log, Anda menjalankan Claude Code sendiri, bukan melalui CCR, dan cakupan profil adalah Only opened from CCR.

Biaya sesi coding

Claude Code mengirim ulang system prompt, percakapan, dan konteks file terbaru pada setiap langkah, sehingga tarif per token cepat terakumulasi. Dengan tarif Kunavo untuk claude-sonnet-5:

Itu kira-kira 30% lebih murah untuk model utama, sebelum prompt caching. Tarif lengkap tersedia di panduan harga Claude API, dan kalkulator biaya menggunakan jumlah token Anda sendiri.

Yang masih berfungsi — dan yang tidak

Mengarahkan Claude Code ke gateway apa pun mengubah beberapa hal. Daftarnya singkat dan perlu diketahui sebelum Anda berkomitmen:

Pada baris terakhir tersebut: penghitungan token adalah satu-satunya endpoint yang ditandai opsional oleh spesifikasi gateway milik Anthropic, dan Claude Code memperkirakan penggunaan konteks secara lokal ketika endpoint tersebut tidak tersedia. Kunavo saat ini tidak menyediakan /v1/messages/count_tokens, sehingga angka /context Anda merupakan perkiraan, bukan jumlah yang tepat. Tidak ada yang menurun selain angka tersebut — kompaksi otomatis dan sesi itu sendiri tidak terpengaruh.

Pemecahan masalah

Jalur URL dasar

…dan ketika router berada di jalur

Perbaikan berdasarkan setiap error untuk API itu sendiri tersedia di halaman pemecahan masalah invalid API key dan rate limit.

Pertanyaan umum