Claude Code Router 3.1.1: इंस्टॉल, रूटिंग और समस्या समाधान

आप Claude Code को DeepSeek, OpenRouter, Gemini, Kimi, Z.AI/GLM या किसी अन्य compatible endpoint से चलाना चाहते हैं, लेकिन आपके सामने वाली गाइड अभी भी config.json और ccr code का उपयोग करती है। या UI खुल जाती है, पर 127.0.0.1:3456 वाला gateway शुरू नहीं होता। यह गाइड मौजूदा 3.1.1 workflow के अनुसार installation से लेकर verified Claude Code profile तक जाती है और हर सामान्य failure के लिए अलग troubleshooting path देती है।

पहले version देखें: 3.1.1 अब हाथ से लिखे config.json पर आधारित नहीं है

Providers, Routing और Agent Profiles को पुराने JSON block की जगह Web UI से सेट करें। 26 सितंबर 2026 तक npm का latest tag 3.1.1 पर है। मौजूदा package मुख्य configuration को config.sqlite में रखता है और running gateway के लिए gateway.config.json generate करता है, जैसा कि npm registry metadata और मौजूदा project README में बताया गया है।

इस version difference से दो आम उलझनें भी स्पष्ट होती हैं। मौजूदा CLI reference agent को ccr <profile-name-or-id> से चलाती है; उसमें ccr code listed नहीं है। gateway.config.json भी generated file है, जिसे primary config मानकर हाथ से maintain नहीं करना चाहिए। यदि कोई tutorial config.json या ccr code कहता है, तो पहले उसका CCR version देखें; incompatible command को तुरंत PATH problem न मानें।

Node.js, upstream provider और Claude Code पहले तैयार रखें

आपको Node.js 22 या नया version, किसी upstream model service का access और local Claude Code installation चाहिए। CCR requests route करता है; वह Claude Code install नहीं करता, और API access Claude.ai या Claude Max subscription के बराबर नहीं है।

पहले Node.js जाँचें:

node --version

यदि major version 22 से कम है, तो आगे बढ़ने से पहले Node.js update करें। Upstream के रूप में OpenRouter, DeepSeek, Gemini, Moonshot/Kimi या Z.AI जैसे built-in preset चुन सकते हैं, या supported OpenAI-compatible अथवा Anthropic-compatible protocol वाला custom endpoint जोड़ सकते हैं।

npm CLI इंस्टॉल करें और configuration से पहले command verify करें

Global install के तुरंत बाद help command चलाएँ। इससे npm या PATH की समस्या को Provider या Routing की समस्या से अलग किया जा सकता है।

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

Update या uninstall करने के लिए:

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

npm package हटाने से local configuration या databases अपने आप नहीं मिटते। macOS/Linux पर data directory ~/.claude-code-router और Windows पर %APPDATA%\claude-code-router है।

इस क्रम में configure करें: Provider → Check Connection → Client Key → Routing → Server → Profile → end-to-end test

Conditions या fallback जोड़ने से पहले एक default route को सफलतापूर्वक चलाएँ। यदि कई Providers, rewrites, retries और fallbacks एक साथ जोड़ेंगे, तो 401, गलत Model ID और protocol mismatch को अलग-अलग पहचानना कठिन होगा।

Management UI खोलें:

ccr ui

Management UI का default http://127.0.0.1:3458 है और model gateway का default http://127.0.0.1:3456। CCR द्वारा print या open की गई authenticated URL का उपयोग करें। यदि 3458 busy है, तो CCR कोई अगला management port चुनकर वास्तविक address दिखा सकता है।

1. Providers में upstream जोड़ें

Preset उपलब्ध हो तो उसे चुनें; custom endpoint केवल आवश्यकता पर लें। Providers → Add Provider में service चुनें, उसी provider की API Key दर्ज करें, सही protocol चुनें और आपके account में वास्तव में उपलब्ध Model ID जोड़ें।

Model के marketing नाम से protocol का अनुमान न लगाएँ। Anthropic Messages, OpenAI Chat/Responses और Gemini के request formats अलग हैं। Base URL, protocol और Model ID upstream की मौजूदा documentation से मेल खाने चाहिए।

Provider save करने के बाद Check Connection चलाएँ। यह केवल upstream configuration की connectivity जाँचता है; इससे Claude Code → CCR gateway → Routing → Provider वाला पूरा path साबित नहीं होता।

2. API Keys में CCR client key बनाएँ

CCR client key और management token अलग credentials हैं। Management token Web UI और RPC API की सुरक्षा करता है; client key Claude Code से gateway पर भेजी गई model requests को authenticate करती है। ccr_web_token वाली management URL को password की तरह रखें और उसे logs, tickets या chats में paste न करें।

3. Conditions और fallback से पहले default route बनाएँ

Default route में Check Connection पास कर चुका एक Provider और उसी Provider का एक model चुनें। Route save करें, लेकिन अभी Claude Code request न भेजें; पहले gateway start करें और Agent Profile बनाएँ।

Step 6 का end-to-end request सफल होने के बाद ही Routing में conditions, retries, request rewrites या ordered fallback जोड़ें। एक बार में एक behavior जोड़ें और फिर test करें। Fallback model को task के tools, context और protocol को भी support करना चाहिए; केवल chat कर सकने से दो models interchangeable नहीं हो जाते।

4. Server में gateway शुरू और verify करें

UI खुलना इस बात का प्रमाण नहीं कि 3456 gateway usable है। Server में gateway start करें और वहाँ दिखाई गई client-facing URL नोट करें। Default http://127.0.0.1:3456 है; CCR जो actual URL दिखाए, वही उपयोग करें। Startup fail होने पर foreground mode में error देखें:

ccr serve

Foreground output से port conflict, incomplete Provider, missing model और local file permission problem को अलग करना आसान होता है।

5. Claude Code के लिए Agent Profile बनाएँ और enable करें

मौजूदा CLI Claude Code को enabled Agent Profile से शुरू करती है। Agent Profiles में Claude Code profile बनाएँ और default route वाला model चुनें, जिसका Provider Check Connection पास कर चुका है; फिर save और enable करें। CCR mode में Claude Code Server में दिखाए गए CCR gateway (default http://127.0.0.1:3456) से जुड़ता है, upstream Provider URL से नहीं। Profile का नाम कोई भी रख सकते हैं, जैसे Claude - Review।

नाम या ID से शुरू करें:

ccr "Claude - Review"

Claude Code के arguments को -- के बाद रखें, ताकि CCR उन्हें अपनी options न समझे:

ccr "Claude - Review" cli -- --model sonnet

Claude - Review की जगह अपने वास्तविक profile का नाम या ID लिखें।

6. Claude Code से request भेजें, फिर Logs देखें

अब पहली वास्तविक end-to-end जाँच करें। Started Profile से Claude Code में एक सरल request भेजें, फिर Logs में देखें कि अपेक्षित Provider और model चुने गए और request सफल रही।

Provider का Check Connection केवल upstream connection जाँचता है। यह actual request CCR client key, gateway, Routing, Agent Profile और model call को भी verify करता है।

ccr start, ui, serve और stop का अंतर समझें

सामान्य उपयोग के लिए ccr ui या ccr start, और diagnosis के लिए ccr serve चुनें।

Command	कब उपयोग करें	व्यवहार
ccr start	Persistent background service	Detached management service और gateway शुरू करता है, फिर authenticated management URL print करता है
ccr ui	Local interactive setup	Existing background service reuse या start करके UI खोलता है
ccr serve	Troubleshooting या process supervisor	Foreground में चलता है, इसलिए startup और request errors दिखते रहते हैं; ccr web इसका alias है
ccr stop	Background settings फिर से बनाना	start या ui से शुरू detached service को रोकता है

start, ui और serve में --host, --port, --open/--no-open और --gateway/--no-gateway उपलब्ध हैं। यहाँ --port preferred management port है, model gateway की 3456 port नहीं।

“ccr: command not found” को Node और npm global bin से ठीक करें

बार-बार reinstall करने से पहले runtime और global prefix verify करें। चलाएँ:

node --version
npm prefix -g

Node.js कम से कम 22 होना चाहिए और npm का global executable directory current shell के PATH में होना चाहिए। Installation के बाद नया terminal खोलें, क्योंकि कुछ shells command locations cache करती हैं।

यदि desktop app भी installed है, तो वह related command ccr-app देती है। यहाँ documented npm package ccr install करता है; केवल ccr-app मिलने से npm CLI का PATH सही साबित नहीं होता।

127.0.0.1:3456 पर listen न करने वाले gateway को ठीक करें

पहले तय करें कि gateway start नहीं हुआ या port किसी अन्य process ने ले रखी है। 3458 पर working UI, 3456 के बारे में कुछ नहीं बताती।

macOS/Linux पर:

lsof -nP -iTCP:3456 -sTCP:LISTEN

Windows पर:

netstat -ano | findstr :3456

यदि stale CCR process या कोई अन्य program port का owner है, तो रोकने से पहले PID पहचानें। फिर ccr serve चलाएँ, Server में वापस जाएँ और gateway फिर start करने से पहले Provider, model और client key की मौजूदगी जाँचें।

401, model not found और protocol errors को तीन mappings से ठीक करें

Credentials, protocol और Model ID को इसी क्रम में जाँचें। सामान्य गलतियों में management token को client key समझना, CCR client key को upstream Provider में डालना या Anthropic-compatible endpoint को OpenAI-compatible route से call करना शामिल है।

यह क्रम अपनाएँ:

1. Claude Code, CCR को CCR client key से authenticate करे, ccr_web_token से नहीं।
2. Provider entry में upstream service की अपनी API Key हो।
3. चुना गया protocol endpoint से मेल खाए।
4. Routed Model ID उस provider और account के लिए उपलब्ध हो।
5. Logs अपेक्षित Provider और model resolve करे।

केवल Claude Code का अंतिम error message न देखें। CCR Logs बता सकते हैं कि failure client authentication, route resolution, upstream authentication या model request में हुआ।

Missing profile और पुराने options वाले background service को ठीक करें

केवल enabled Agent Profiles launch हो सकते हैं। Name matching case-insensitive है और sanitized names स्वीकार किए जाते हैं, पर ambiguous नाम होने पर profile ID जरूरी है। Generated launcher missing हो तो profile दोबारा save करें।

Reuse किया गया background process नए host, port या gateway options नहीं अपनाता। उसे रोककर फिर बनाएँ:

ccr stop
ccr start --host 127.0.0.1 --port 3458

इसी कारण command सफल दिख सकती है, लेकिन service पुराने settings पर चलती रहती है।

केवल एक endpoint हो तो सीधे ANTHROPIC_BASE_URL सरल है

एक Anthropic-compatible endpoint, एक मुख्य model और बिना conditional routing, fallback, shared logs या multiple profiles के direct setup आमतौर पर छोटा है। Provider की Claude Code documentation के अनुसार ANTHROPIC_BASE_URL, authentication variable और model mapping सेट करें; local gateway जोड़ना आवश्यक नहीं है।

इनमें से कोई स्थिति हो तो CCR अधिक उपयुक्त है:

• आप DeepSeek, OpenRouter, Gemini, Kimi, Z.AI या custom endpoints के बीच switch करते हैं;
• अलग tasks या profiles को अलग models चाहिए;
• retries, conditional routing, rewrites या ordered fallback चाहिए;
• resolved routes, status, tokens, latency और errors एक जगह देखने हैं;
• कई clients को एक local gateway साझा करना है।

स्थिति	प्राथमिक विकल्प
एक स्थिर Anthropic-compatible endpoint	Direct ANTHROPIC_BASE_URL
कई providers, models या profiles	CCR
हर request की route visibility चाहिए	CCR
केवल एक service से सबसे जल्दी जुड़ना है	Direct शुरू करें; workflow बढ़ने पर CCR अपनाएँ

Compatible endpoint उदाहरण: CCR में BetterToken जोड़ना

BetterToken custom Anthropic-compatible Provider का एक उदाहरण है, एकमात्र विकल्प नहीं। CCR Providers में https://bettertoken.ai को upstream API endpoint/Base URL field में भरें—Claude Code Base URL में नहीं—और /v1 न जोड़ें। Protocol में स्पष्ट रूप से Anthropic Messages चुनें, फिर अपनी BetterToken API Key और मौजूदा उपलब्ध Model ID भरें। Provider save करके Check Connection चलाएँ।

CCR उपयोग करते समय Claude Code Server में दिखाए गए CCR gateway से जुड़ता है, जिसका default http://127.0.0.1:3456 है। Agent Profile शुरू करके request भेजें और Logs में पुष्टि करें कि route अपेक्षित BetterToken model तक गया। इस mode में Claude Code को सीधे https://bettertoken.ai पर point न करें, वरना CCR bypass हो जाएगा।

केवल तब, जब आप जानबूझकर CCR छोड़कर इस एक Endpoint से सीधे जुड़ रहे हों, BetterToken Claude Code documentation के अनुसार macOS/Linux पर Base URL सेट करें:

export ANTHROPIC_BASE_URL="https://bettertoken.ai"

PowerShell पर:

$env:ANTHROPIC_BASE_URL="https://bettertoken.ai"

इस direct mode में authentication variable और model mapping फिर भी current documentation से ही लें। Claude Code में OpenAI-compatible Base URL https://www.bettertoken.ai/v1 का उपयोग न करें।

Local credentials सुरक्षित रखें और सही तरीके से backup लें

Remote access जानबूझकर न चाहिए तो management listener को 127.0.0.1 पर रखें। Remote access के लिए firewall या private network और trusted reverse proxy पर TLS उपयोग करें। CCR client keys बनाए बिना gateway को बाहरी network पर expose न करें।

Upstream credentials, logs और runtime databases CCR की local data directory में होते हैं। CCR द्वारा लिखते समय config.sqlite को edit या copy न करें। UI export उपयोग करें या filesystem backup से पहले CCR रोकें।

केवल UI नहीं, पूरा request path verify करें

Success का अर्थ है कि Claude Code request ने अपेक्षित route लिया और सामान्य response मिला। जाँचें:

• node --version 22 या नया दिखाए;
• ccr --help चले;
• Providers में कम से कम एक upstream ने Check Connection पास किया हो;
• API Keys में CCR client key हो;
• Server running gateway और उसकी client-facing URL दिखाए (default http://127.0.0.1:3456);
• Agent Profile save और enable हो;
• ccr <profile-name-or-id> Claude Code शुरू करे;
• Claude Code से actual request भेजी गई हो और Logs अपेक्षित Provider, model और successful status दिखाए;
• हर नई route या fallback के बाद फिर test किया गया हो।

इस क्रम से installation, authentication, Routing और agent launch अलग layers बने रहते हैं। Failure होने पर आप जिम्मेदार layer ठीक कर सकते हैं, बजाय CCR फिर install करने या पुराने config.json को अनुमान से बदलने के।