Claude Code Router: Perutean Multi-Model untuk Pengodean yang Efisien

Saat saya mulai sering menggunakan Claude Code, saya cepat menyadari dua hal: kualitasnya sangat baik, dan tagihannya mencerminkan hal itu. Setiap permintaan, entah itu docstring tiga baris atau refaktor arsitektur penuh, tetap menghantam endpoint Anthropic yang sama dengan tarif yang sama. 

Seiring waktu, ketergantungan pada satu vendor bukan hanya menekan biaya; itu juga menambah risiko. Ini juga berarti batas laju pada satu model bisa menghentikan seluruh alur kerja Anda.

Claude Code Router (CCR) menangani kedua masalah tersebut secara langsung. Ini adalah proxy open-source yang mencegat permintaan Claude Code Anda sebelum mencapai penyedia mana pun, lalu mengarahkan ulang setiap permintaan ke model backend yang paling masuk akal untuk tugas itu. 

Dalam tutorial ini, saya akan memandu Anda melalui penyiapan lengkap: memasang router, mengonfigurasi jalur perutean multi-penyedia, dan memperkuat sistem untuk penggunaan operasional harian. Untuk mengikuti, siapkan kunci API dari penyedia yang ingin Anda gunakan (DeepSeek, Gemini, OpenRouter, atau backend lain yang didukung) dan buka terminal Anda. Mari mulai.

Untuk inspirasi tentang LLM baru dan keunggulannya, lihat panduan kami tentang model-model terbaru ini:

• GPT-5.4
• GPT-5.3 Instant
• Gemini 3.1
• Claude Sonnet 4.6
• Claude Opus 4.6
• Qwen3.5
• MiniMax M2.5

Apa Itu Claude Code Router?

Sebelum masuk ke penyiapan, ada baiknya memahami apa sebenarnya CCR dan mengapa ia bekerja seperti itu. Jika Anda belum pernah bekerja dengan Claude Code, pastikan membaca terlebih dahulu Panduan Praktis Claude Code 2.1 kami.

Claude Code Router adalah gerbang proxy lokal. Saat Anda meluncurkannya, ia terikat ke sebuah port di mesin Anda (127.0.0.1:3456 secara default) dan menempatkan dirinya di antara klien Claude Code Anda dan penyedia LLM eksternal mana pun. Dari perspektif Claude Code, ia hanya berbicara dengan endpoint lokal. Di balik layar, CCR memutuskan secara real time ke mana permintaan itu sebenarnya pergi.

Masalah inti yang dipecahkan adalah ketergantungan pada satu vendor. Ketika semuanya melewati satu penyedia, Anda mewarisi semua batasan penyedia tersebut: 

• Tingkat harga
• Batas laju
• Batas jendela konteks 

CCR menghilangkan itu dengan memungkinkan Anda mendefinisikan aturan perutean yang secara otomatis mengganti model berdasarkan jenis tugas, jumlah token, atau logika kustom apa pun yang Anda tulis. Pemindaian file latar belakang tidak memerlukan model yang sama dengan sesi penalaran Plan Mode, dan dengan CCR, permintaan tersebut tidak akan menggunakan model yang sama.

Yang membedakan CCR dari API penyedia langsung atau agregator berbasis cloud adalah tempat ia berjalan. 

Karena proxy dijalankan secara lokal, payload permintaan Anda tidak pernah melewati layanan agregasi pihak ketiga sebelum mencapai tujuannya. Anda juga mendapatkan kontrol terperinci atas transformasi permintaan, termasuk memodifikasi header, menghapus field cache, dan membatasi token, melalui sistem transformer yang sepenuhnya berjalan di mesin Anda. 

Bagi saya, model eksekusi lokal inilah yang membuat CCR benar-benar praktis, bukan sekadar solusi cerdik: hasilnya adalah penyiapan yang lebih hemat biaya, lebih tangguh, dan lebih privat daripada mengarahkan semuanya melalui satu vendor cloud.

Arsitektur dan Prasyarat Claude Code Router

Dengan gambaran jelas tentang apa yang dilakukan CCR, mari lihat cara kerjanya di balik layar dan apa yang Anda perlukan sebelum memasangnya.

Model konseptual inti

Memahami arsitektur CCR membuat konfigurasi jauh lebih mudah untuk dipahami, dan menurut saya pola proxy ini cepat dipahami begitu Anda melihat ujung ke ujung. 

Saat Anda menjalankan CCR, ia mencegat semua permintaan keluar dari terminal Anda sebelum mencapai endpoint Anthropic default. Untuk setiap permintaan, CCR akan:

1. Memeriksa permintaan.
2. Menerapkan aturan perutean Anda.
3. Mentranformasikan payload ke format yang diharapkan penyedia target.
4. Meneruskannya. 

Respons kembali dengan cara yang sama, diubah kembali ke format yang diharapkan Claude Code, sehingga klien tidak pernah tahu ada yang berubah.

Mekanisme kunci dalam intersepsi itu adalah perutean berbasis tugas. CCR mengklasifikasikan permintaan masuk berdasarkan jenisnya dan memetakannya ke model yang sesuai. Berikut cara kategori tugas utama berperilaku dalam praktik:

Setiap jenis tugas mendapatkan alat yang tepat, dan tidak ada yang membutuhkan intervensi manual setelah dikonfigurasi. Berdasarkan pengalaman saya, rute background memberi pengembalian paling cepat: permintaan pemindaian file yang senyap itu terjadi terus-menerus selama sesi pengodean, dan sebelum CCR, saya tidak menyadari betapa cepatnya biaya itu diam-diam menumpuk.

Prasyarat penting

Sebelum memasang CCR, pastikan hal-hal berikut sudah siap:

• Node.js v18 atau lebih baru sebagai lingkungan runtime

• npm sebagai manajer paket

• Claude Code terpasang secara global (npm install -g @anthropic-ai/claude-code)

• Setidaknya satu backend model, baik kunci API dari penyedia eksternal yang didukung (DeepSeek, Gemini, OpenRouter, Groq, Volcengine, SiliconFlow, dan lainnya), atau instance Ollama lokal dengan model yang sudah diunduh, jika Anda ingin sepenuhnya menghindari penyedia eksternal

Anda tidak perlu memiliki akun di semua penyedia sejak awal. Satu backend yang berfungsi sudah cukup untuk menyelesaikan tutorial ini, dan Anda bisa menambahkannya nanti.

Untuk perbandingan Claude Code dengan salah satu alternatif terpopulernya, saya menyarankan membaca artikel kami tentang OpenClaw vs Claude Code.

Tutorial Langkah Demi Langkah: Menyiapkan Claude Code Router

Sekarang konsep dan prasyarat sudah jelas, mari bangun penyiapannya selangkah demi selangkah.

Pasang dan jalankan router

Dengan prasyarat siap, Anda bisa memasang CCR secara global dengan npm. Namun, di Linux, Anda mungkin menemui kesalahan perizinan saat memasang paket global karena npm mencoba menulis ke /usr/lib/node_modules yang dimiliki root. Perbaikan yang disarankan adalah mengarahkan ulang direktori global npm ke folder yang sudah Anda miliki, bukan menjalankan perintah dengan sudo:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Agar perubahan PATH itu permanen, tambahkan baris export ke ~/.bashrc atau ~/.zshrc lalu muat ulang shell Anda. Kemudian pasang CCR:

npm install -g @musistudio/claude-code-router

Ini membuat CLI ccr tersedia secara global di shell Anda. Selanjutnya, jalankan layanan router:

ccr start

CCR terikat ke http://127.0.0.1:3456 secara default. Setelah Anda melihat layanan terikat ke port tersebut pada output startup, proxy siap menerima permintaan.

Konfigurasikan penyedia dasar

Semua konfigurasi CCR berada di ~/.claude-code-router/config.json. Sebelum menyambungkan banyak penyedia, saya menyarankan mulai dengan satu penyedia yang sudah terbukti untuk mengisolasi variabel dan memastikan baseline berfungsi.

OpenRouter adalah titik awal yang baik, dan ini yang pertama saya gunakan setiap kali menyiapkan CCR di mesin baru. Anda mendapatkan akses ke puluhan model, termasuk beberapa yang bertingkat gratis, melalui satu kunci API, sehingga ideal untuk membuat lapisan perutean berfungsi sebelum berkomitmen ke penyedia tertentu. Anda bisa mendaftar dan mengambil kunci di OpenRouter.

Berikut konfigurasi minimal menggunakan OpenRouter:

{
  "Providers": [
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "YOUR_OPENROUTER_API_KEY",
      "models": ["openai/gpt-oss-120b:free"],
      "transformer": {
        "use": ["openrouter"]
      }
    }
  ],
  "Router": {
    "default": "openrouter,openai/gpt-oss-120b:free"
  }
}

Beberapa hal penting di sini:

• api_base_url harus mengarah ke endpoint chat completions penuh milik penyedia, bukan hanya domain dasarnya.

• transformer menentukan adapter payload bawaan mana yang harus digunakan CCR, karena tiap penyedia mengharapkan format permintaan yang berbeda. Transformer menangani translasi itu secara senyap.

• Router.default menetapkan model fallback untuk permintaan apa pun yang tidak cocok dengan aturan yang lebih spesifik, menggunakan sintaks provider,model.

Demi keamanan, hindari menuliskan kunci langsung di file. CCR mendukung interpolasi variabel lingkungan: ganti YOUR_OPENROUTER_API_KEY dengan $OPENROUTER_API_KEY dan ekspor variabel tersebut di shell Anda. Interpolasi bekerja secara rekursif di seluruh konfigurasi, sehingga pola ini berskala rapi saat Anda menambah lebih banyak penyedia.

Hubungkan Claude Code ke proxy

Dengan konfigurasi siap, meluncurkan Claude Code melalui router cukup satu perintah:

ccr code

Itu saja. ccr code menjalankan layanan proxy dan meluncurkan Claude Code secara bersamaan, dengan lingkungan yang sudah dikonfigurasi otomatis. Anda tidak perlu menjalankan ccr start terlebih dahulu.

Untuk memverifikasi perutean aktif, periksa folder ~/.claude-code-router/logs/. File bernama ccr-*.log di sana menandakan proxy telah mulai dan menerima permintaan. Anda bisa menayangkannya untuk melihat permintaan secara real time:

tail -f ~/.claude-code-router/logs/$(ls -t ~/.claude-code-router/logs/ | head -1)

Log Claude Code Router

Ada dua hal yang perlu diketahui tentang verifikasi. Header Claude Code selalu menampilkan model Claude default saat ini, terlepas dari model mana yang sedang digunakan CCR untuk merutekan, karena itu mencerminkan sesi akun Anthropic Anda, bukan backend aktif. Jika Anda bertanya kepada model "model apa Anda?", model juga akan menjawab “Claude Sonnet 4.6”, karena itulah yang diminta klien Claude Code untuk diidentifikasi. Keduanya bukan sinyal yang andal.

Sesi Claude Code Router

Log adalah satu-satunya sumber kebenaran. Cari field "model" pada entri respons. Jika Anda melihat nama model yang dikonfigurasi di sana, misalnya, "model":"openai/gpt-oss-120b:free", berarti perutean berfungsi.

Jika Anda ingin menjadikan CCR persisten agar bisa menggunakan perintah claude langsung tanpa ccr code, tambahkan ini ke ~/.bashrc or ~/.zshrc Anda:

eval "$(ccr activate)"

Pastikan ccr start dijalankan lebih dulu dalam kasus itu, karena activate hanya menetapkan variabel lingkungan dan tidak menjalankan layanan itu sendiri.

Terapkan perutean multi-penyedia

Setelah baseline terverifikasi, mari perluas konfigurasi untuk merutekan jenis tugas yang berbeda ke penyedia yang berbeda. Berikut konfigurasi Router yang lebih lengkap:

{
  "Router": {
    "default": "deepseek,deepseek-chat",
    "background": "ollama,qwen2.5-coder:latest",
    "think": "deepseek,deepseek-reasoner",
    "longContext": "openrouter,google/gemini-2.5-pro-preview",
    "longContextThreshold": 60000,
    "webSearch": "gemini,gemini-2.5-flash"
  }
}

Setiap kunci memetakan kategori tugas ke pasangan "provider,model":

• Rute background menangani permintaan pemindaian file dan pengumpulan konteks. Ini aman diarahkan ke model Ollama lokal, sehingga tetap gratis, dan inilah perubahan tunggal yang paling memangkas tagihan API bulanan saya. 

• Rute think menangkap tugas Plan Mode dan penalaran kompleks, di mana model seperti deepseek-reasoner sepadan dengan biayanya. 

• Rute longContext aktif secara otomatis ketika permintaan melebihi longContextThreshold token (default 60.000), mengalihkan ke model berkapasitas tinggi tanpa perlu pengalihan manual. 

• Untuk webSearch, perhatikan bahwa model itu sendiri harus mendukung penelusuran web secara native. Jika Anda merutekan melalui OpenRouter, Anda juga perlu menambahkan sufiks :online ke nama model (misalnya, "anthropic/claude-3.5-sonnet:online").

Untuk ketahanan terhadap batas laju, fitur custom router CCR memungkinkan Anda mendefinisikan logika fallback dalam JavaScript. Buat file di path pilihan Anda, rujuk di konfigurasi dengan "CUSTOM_ROUTER_PATH": "/path/to/custom-router.js", lalu ekspor fungsi async yang mengembalikan string "provider,model" atau null untuk kembali ke aturan default:

module.exports = async function router(req, config) {
  // Primary logic here. Return null to fall back to config-defined rules.
  return null;
};

Di sinilah Anda akan menerapkan logika retry-on-rate-limit, misalnya, dengan mendeteksi respons 429 dan secara otomatis mengalihkan ke penyedia sekunder. Setelah perubahan konfigurasi apa pun, ingat untuk memulai ulang layanan agar diterapkan:

ccr restart

Mengoperasikan dan Memecahkan Masalah Claude Code Router

Setelah perutean berjalan, fokus bergeser ke menjaga sistem tetap dapat diamati, aman, dan mudah di-debug saat terjadi masalah.

Pantau penggunaan dan tetapkan anggaran

CCR menyediakan dua sistem logging terpisah yang perlu diketahui:

• Log tingkat server mencakup permintaan HTTP, panggilan API, dan event server. Log ini ditulis ke ~/.claude-code-router/logs/ dalam file bernama ccr-*.log. Inilah log yang paling sering Anda gunakan.

• Log tingkat aplikasi menangkap keputusan perutean dan ditulis ke ~/.claude-code-router/claude-code-router.log, meski file ini mungkin tidak selalu ada tergantung penyiapan dan konfigurasi tingkat log Anda.

Meninjau log server secara rutin memberi gambaran jelas rute mana yang dipicu, model mana yang dipanggil, dan apakah ada kesalahan dari penyedia. 

Untuk visibilitas waktu nyata, CCR juga menyertakan alat statusline (tersedia mulai v1.0.40) yang bisa Anda aktifkan melalui ccr ui. Setelah aktif, alat ini menampilkan status perutean saat ini langsung di terminal saat Claude Code berjalan, menunjukkan sekilas model mana yang menangani setiap permintaan.

Di sisi anggaran, pagar pembatas paling efektif adalah konfigurasi perutean Anda sendiri. Dengan memastikan rute background dan default mengarah ke model yang lebih murah atau lokal, Anda mencegah model premium dipanggil untuk tugas bernilai rendah. Cadangkan think dan longContext untuk model yang sepadan biayanya, dan pertahankan ambang token untuk longContext setinggi yang dapat ditoleransi alur kerja Anda. 

Menurut pengalaman saya, disiplin pada level konfigurasi ini lebih andal daripada pemantauan reaktif karena mencegah pemborosan sebelum terjadi, bukan menangkapnya sesudahnya.

Amankan kredensial dan kontrol akses

Manajemen kredensial perlu perhatian khusus, terutama saat daftar penyedia Anda tumbuh. Aturan yang saya ikuti sederhana:

• Jangan pernah menyimpan kunci API mentah ke config.json jika file itu dilacak dalam version control. Selalu gunakan interpolasi variabel lingkungan dengan sintaks "$PROVIDER_API_KEY", dan ekspor kunci dari profil shell atau pengelola rahasia.

• Biarkan proxy di localhost untuk penyiapan pengembang individual. Jika Anda tidak menetapkan APIKEY di konfigurasi, CCR secara otomatis memaksa server hanya terikat ke 127.0.0.1, mencegah akses eksternal pada mesin atau jaringan bersama.

• Tetapkan APIKEY untuk penerapan tim jika Anda perlu membuka host ke 0.0.0.0. Setiap klien yang terhubung ke router harus menyertakan kunci itu di header Authorization: Bearer atau x-api-key.

• Nonaktifkan atau kurangi logging jika Anda merutekan kode sensitif. Logging aktif secara default ("LOG": true). Setel "LOG": false untuk menghentikan penulisan payload permintaan ke disk, atau "LOG_LEVEL": "warn" untuk menekan keluaran debug yang verbose.

Cara praktis menerapkannya adalah menyimpan semua kunci API Anda di profil shell dan mereferensikannya via sintaks $VAR_NAME di config.json. Dengan begitu, file konfigurasi itu sendiri tidak mengandung rahasia dan aman untuk dibagikan atau dikontrol versinya.

Jika Anda ragu apakah suatu kunci bocor ke log, periksa dulu pengaturan level log. Beralih ke "LOG_LEVEL": "warn" adalah cara tercepat untuk mengurangi apa yang ditulis ke disk tanpa mematikan logging sepenuhnya.

Pemecahan masalah kegagalan perutean umum

Saat terjadi kegagalan, urutan diagnostik berlapis menghemat banyak waktu. Menurut saya, sebaiknya mulai dari lapisan terluar lalu bergerak ke dalam.

Langkah 1: Pastikan proxy berjalan 

Jalankan ccr code dan cari konfirmasi startup layanan. Jika port ditempati atau layanan gagal dimulai, Anda akan melihat error connection refused di Claude Code. 

Periksa log server di ~/.claude-code-router/logs/ untuk detail. Kegagalan startup paling sering disebabkan konflik port atau file config.json yang tidak valid.

Langkah 2: Pastikan nama model cocok

Kesalahan konfigurasi paling umum adalah ketidakcocokan antara nama model di Providers dan yang ada di Router. Keduanya harus identik. 

Jika berbeda, CCR mengirim permintaan tanpa field model, dan Anda akan melihat error Missing model in request body. Setelah memperbaiki konfigurasi, selalu jalankan ccr restart untuk memuat ulang.

Langkah 3: Periksa pengaturan di sisi penyedia

Jika nama model sudah benar tetapi permintaan tetap gagal dengan 404, periksa pengaturan akun penyedia Anda. OpenRouter, misalnya, memiliki kebijakan privasi default yang memblokir model gratis mengirim data ke penyedia pihak ketiga. Anda akan melihat error seperti No endpoints found matching your data policy. 

Perbaikannya adalah membuka pengaturan privasi OpenRouter Anda dan mengaktifkan penggunaan model gratis. Penyedia lain mungkin memiliki toggle tingkat akun serupa yang layak diperiksa jika Anda mengalami error 4xx yang tidak terduga.

Langkah 4: Periksa konfigurasi transformer

Jika permintaan mencapai penyedia tetapi responsnya salah format atau panggilan tool gagal, masalahnya biasanya transformer yang hilang atau salah. Cocokkan penyedia Anda dengan daftar transformer bawaan dan pastikan yang benar ada di array "use".

Dalam banyak kasus, menjalani keempat langkah ini secara berurutan akan cepat mengisolasi masalah. Log server menangkap permintaan keluar dan respons mentah dari penyedia, memberikan semua yang Anda butuhkan untuk memahami di mana kegagalan terjadi.

Penutup

Kini Anda memiliki infrastruktur perutean multi-penyedia yang berjalan di atas Claude Code. Tugas latar belakang diarahkan ke model lokal yang cepat, pekerjaan berat penalaran diarahkan ke model khusus, dan permintaan ber-konteks panjang ditangani penyedia berkapasitas tinggi—semuanya otomatis berdasarkan aturan yang Anda kendalikan. 

Manfaat langsungnya adalah biaya API yang lebih rendah, tidak ada satu titik kegagalan akibat batas laju, dan fleksibilitas untuk mengganti penyedia tanpa menyentuh alur kerja Anda.

Agar penyiapan tetap efisien dari waktu ke waktu, tinjau log perutean Anda secara berkala. Log server akan menunjukkan rute mana yang paling sering dipicu dan apakah model mahal terpanggil untuk tugas yang sebenarnya bisa ditangani alternatif yang lebih murah. Menyesuaikan longContextThreshold dan aturan fallback berdasarkan penggunaan nyata jauh lebih efektif daripada menentukannya sekali lalu membiarkannya.

Terakhir, jika pekerjaan Anda melibatkan kode proprieter, saya sangat menyarankan merutekan permintaan tersebut ke LLM lokal melalui Ollama. Ini yang saya lakukan untuk pekerjaan klien yang melibatkan kode yang belum dirilis. Menambahkannya sebagai penyedia kurang dari satu menit, dan kueri paling sensitif Anda tidak pernah keluar dari mesin Anda.

Bagi Anda yang ingin meningkatkan kemampuan pengembangan aplikasi AI, saya sangat merekomendasikan mendaftar ke jalur keterampilan AI Engineering with LangChain. Konten pengajarannya bersifat AI-native, memberi Anda akses ke tutor pribadi yang mengajarkan keterampilan yang tepat untuk menjadi profesional sejati dalam merekayasa alur kerja AI.