اتصال 9Router به چابکان

9Router چیست؟

9Router یک gateway و router محلی برای اتصال ابزارهای AI به چند provider است. این برنامه یک endpoint سازگار با OpenAI روی سیستم شما ایجاد می‌کند و درخواست ابزارهایی مانند Codex، Cline، Continue و Roo Code را به provider یا مدل انتخابی می‌فرستد.

تفاوت 9Router با Kilo Code یا Claude Code این است که 9Router خودش محیط برنامه‌نویسی یا coding agent نیست. این ابزار میان کلاینت و provider قرار می‌گیرد و می‌تواند چند اتصال، alias، گزارش مصرف و مسیرهای fallback را مدیریت کند.

معماری اتصال چابکان از طریق 9Router

در اتصال مستقیم، ابزار API Key چابکان را دریافت می‌کند. در اتصال از طریق 9Router دو ارتباط جدا وجود دارد:

ابزار AI
  │ Base URL محلی + کلید 9Router
  ▼
9Router روی localhost:20128
  │ Base URL چابکان + کلید sk-chbk-...
  ▼
https://ai.chabokan.net/v1 → مدل انتخابی

بنابراین کلید endpoint محلی 9Router را با API Key چابکان اشتباه نگیرید. 9Router کلید چابکان را به‌عنوان credential اتصال upstream نگه می‌دارد و برای کلاینت‌های خود کلید جدا ارائه می‌کند.

چه زمانی استفاده از 9Router مناسب است؟

• چند ابزار باید از یک endpoint محلی مشترک استفاده کنند؛
• می‌خواهید providerها یا مدل‌ها را بدون تغییر config همه کلاینت‌ها مدیریت کنید؛
• به alias، combo یا fallback میان چند اتصال نیاز دارید؛
• می‌خواهید مصرف ابزارهای مختلف را در dashboard محلی ببینید.

اگر فقط یک ابزار را به یک مدل وصل می‌کنید، اتصال مستقیم به چابکان ساده‌تر و دارای یک لایه کمتر است. 9Router را زمانی اضافه کنید که قابلیت routing آن واقعاً بخشی از نیاز شما باشد.

۱. پیش‌نیازها

• Node.js نسخه ۲۰ یا جدیدتر؛
• یک سرویس فعال و دارای اعتبار در چابکان؛
• API Key مجزا با پیشوند sk-chbk-؛
• Model ID دقیق از پنل یا /v1/models؛
• دسترسی به پورت محلی پیش‌فرض 20128.

ابتدا آزمون مستقیم چابکان را اجرا کنید. اگر endpoint مستقیم کار نکند، افزودن router خطا را پیچیده‌تر می‌کند.

۲. نصب و اجرای 9Router

9Router را به‌صورت global نصب و اجرا کنید:

npm install -g 9router
9router

سپس dashboard را باز کنید:

http://localhost:20128

در نصب فعلی ممکن است dashboard با رمز اولیه راه‌اندازی شود. پیش از افزودن هر credential، رمز پیش‌فرض را از Settings تغییر دهید. اگر پورت را هنگام اجرا تغییر داده‌اید، در همه URLهای این صفحه همان پورت را جایگزین کنید.

۳. افزودن چابکان به‌عنوان upstream

1. وارد dashboard محلی 9Router شوید.

2. صفحه Providers را باز کنید.

3. گزینه افزودن connection یا provider جدید را انتخاب کنید.

4. نوع OpenAI Compatible را انتخاب کنید.

5. مقادیر زیر را وارد کنید:

   فیلد	مقدار
   Name	Chabokan AI
   Prefix	chabokan
   API Type	Chat یا chat_completions
   Base URL	https://ai.chabokan.net/v1
   API Key	کلید فعال چابکان
   Default Model	Model ID دقیق پنل

6. تست connection را اجرا کنید.

7. فقط پس از موفق‌شدن تست، connection را فعال کنید.

نام دقیق بعضی فیلدها ممکن است میان نسخه‌های 9Router متفاوت باشد، اما مفهوم آن‌ها ثابت است: فرمت OpenAI، آدرس /v1 چابکان، کلید upstream و مدل پیش‌فرض.

مسیر endpoint

اگر فرم Base URL می‌خواهد، https://ai.chabokan.net/v1 را وارد کنید. فقط زمانی URL کامل .../chat/completions را بنویسید که فیلد صراحتاً Endpoint URL نام داشته باشد. افزودن مسیر کامل در فیلد Base URL ممکن است مسیر را دوبار بسازد.

۴. بررسی مدل از endpoint محلی

API Key مربوط به endpoint خود 9Router را از dashboard بردارید و در environment قرار دهید:

export NINEROUTER_API_KEY="کلید-endpoint-محلی-9router"

مدل‌های قابل route را ببینید:

curl --fail-with-body http://localhost:20128/v1/models \
  -H "Authorization: Bearer $NINEROUTER_API_KEY"

مدل custom معمولاً با prefix انتخابی نمایش داده می‌شود؛ برای مثال اگر prefix برابر chabokan و شناسه upstream برابر openai/gpt-4o-mini باشد، شناسه route می‌تواند به شکل زیر باشد:

chabokan/openai/gpt-4o-mini

به خروجی واقعی /v1/models تکیه کنید و نام را حدس نزنید. نسخه‌های مختلف 9Router ممکن است نمایش providerهای custom را تغییر دهند.

۵. تست کامل مسیر

Model ID برگشتی از مرحله قبل را در درخواست قرار دهید:

export NINEROUTER_MODEL="chabokan/openai/gpt-4o-mini"

curl --fail-with-body http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $NINEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$NINEROUTER_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"فقط بنویس: اتصال برقرار است\"}]}"

برای تأیید کامل، درخواست باید هم در log محلی 9Router و هم در گزارش درخواست‌های سرویس چابکان دیده شود.

۶. اتصال ابزارها به 9Router

پس از موفق‌شدن تست، در کلاینت‌های OpenAI-compatible این مقادیر را وارد کنید:

تنظیم ابزار	مقدار
Provider	OpenAI Compatible
Base URL	http://localhost:20128/v1
API Key	کلید endpoint ساخته‌شده توسط 9Router
Model	شناسه دقیق خروجی /v1/models محلی

این الگو برای Cline، Continue، Roo Code، OpenCode و Kilo Code قابل استفاده است. در راهنمای ابزار مقصد، Base URL و کلید مستقیم چابکان را با مقادیر محلی جدول بالا جایگزین کنید.

ابزاری که روی دستگاه یا کانتینر دیگری اجرا می‌شود به localhost رایانه شما دسترسی ندارد. برای چنین معماری‌ای 9Router باید روی آدرس شبکه‌ای محافظت‌شده و قابل دسترس deploy شود؛ endpoint محلی را بدون TLS، authentication و محدودیت شبکه روی اینترنت عمومی منتشر نکنید.

۷. Combo و fallback

پس از اینکه اتصال ساده با یک مدل موفق شد، می‌توانید در dashboard یک Combo بسازید و چند مدل یا provider را به‌ترتیب قرار دهید. سپس نام Combo را به‌عنوان model در کلاینت انتخاب کنید.

پیش از فعال‌کردن fallback بررسی کنید:

• مدل جایگزین context و tool calling موردنیاز agent را دارد؛
• تفاوت کیفیت یا ساختار tool call باعث شکست workflow نمی‌شود؛
• سقف مصرف هر upstream مشخص است؛
• داده مجاز است به تمام providerهای موجود در زنجیره ارسال شود.

fallback فقط دسترس‌پذیری را تغییر نمی‌دهد؛ ممکن است مقصد پردازش داده، هزینه و رفتار مدل نیز عوض شود.

۸. امنیت 9Router

• برای 9Router یک API Key اختصاصی چابکان با سقف مصرف بسازید.
• dashboard را با رمز قوی محافظت کنید.
• پوشه داده محلی 9Router را مانند secret store در نظر بگیرید و از Git یا backup عمومی دور نگه دارید.
• پورت 20128 را فقط روی loopback یا شبکه مورداعتماد در دسترس قرار دهید.
• logها را از نظر prompt، پاسخ و اطلاعات حساس بازبینی کنید.
• کلید چابکان را مستقیماً به کلاینت‌هایی که از مسیر router استفاده می‌کنند ندهید.

۹. عیب‌یابی

نشانه	لایه مشکل	بررسی
تست provider با 401 شکست می‌خورد	چابکان → 9Router	API Key چابکان را بررسی کنید
تست provider با 404 شکست می‌خورد	تنظیم upstream	Base URL و Model ID را اصلاح کنید
/v1/models محلی خطای 401 می‌دهد	ابزار → 9Router	از کلید endpoint خود 9Router استفاده کنید
مدل در selector دیده نمی‌شود	catalog نسخه 9Router	شناسه خروجی /v1/models را دستی وارد کنید
مدل پیدا نشد	prefix یا route	شناسه کامل prefixدار را از endpoint محلی کپی کنید
درخواست در 9Router هست ولی در چابکان نیست	routing	فعال‌بودن connection و انتخاب مدل را بررسی کنید
چت کار می‌کند ولی agent نه	قابلیت مدل	tool calling و context مدل upstream را آزمایش کنید

برای تشخیص، همیشه دو smoke test جدا انجام دهید: اول درخواست مستقیم به چابکان و سپس همان درخواست از endpoint محلی 9Router.

منابع رسمی: مستندات 9Router، شروع سریع، الگوی اتصال OpenAI-compatible