آموزش اتصال API هوش مصنوعی Mindbase به Claude Code

Claude Code ایجنت کدنویسی ترمینالی آنتروپیک است که از محبوب‌ترین ابزارهای برنامه‌نویسی با AI در دنیا محسوب می‌شود. اما یک نکته فنی مهم دارد: Claude Code فقط پروتکل Anthropic Messages را می‌فهمد و سرویس‌هایی که استاندارد OpenAI را ارائه دهند — مثل مایندبیس — را به‌تنهایی نمی‌پذیرد. راه‌حل استاندارد این وضعیت، یک گیت‌وی محلی به نام claude-code-router است که بین Claude Code و مایندبیس می‌نشیند: از سمت Claude Code صحبت Anthropic می‌کند و از سمت مایندبیس صحبت OpenAI.

در این آموزش این اتصال را از صفر تا اجرای اولین دستور برپا می‌کنیم؛ و در انتها گزینه جایگزین (LiteLLM) را هم می‌بینیم.

پیش‌نیازها

  • Node.js نسخه ۲۲ به بالا (برای نصب روتر).
  • خود Claude Code نصب باشد: npm install -g @anthropic-ai/claude-code.
  • کلید API مایندبیس (گام صفر پایین).

گام صفر: دریافت API Key و Base URL از مایندبیس

قبل از هر چیز به دو مقدار نیاز دارید: کلید API و Base URL. هر دو از سایت مایندبیس قابل دریافت هستند:

  1. وارد حساب کاربری خود در mindbase.ir شوید (ثبت‌نام رایگان است).
  2. از منوی پروفایل، بخش «کلیدهای API» را باز کنید.
  3. روی «+ کلید جدید» بزنید و یک نام دلخواه بدهید؛ مثلاً ClaudeCode.
  4. مقدار کلید را کپی کنید — این کلید با پیشوند mb_ شروع می‌شود.
  5. Base URL نیز در همین صفحه نمایش داده می‌شود: https://api.mindbase.ir/v1
دریافت کلید API و Base URL از پنل کاربری مایندبیس

مرحله اول: نصب claude-code-router

محیط واقعی Claude Code — آموزش تنظیم اتصال به مایندبیس
npm install -g @musistudio/claude-code-router

این ابزار یک گیت‌وی محلی است: پنل مدیریتی روی پورت 3458 و گیت‌وی مدل روی 3456 اجرا می‌کند. Claude Code به این گیت‌وی وصل می‌شود و روتر درخواست‌ها را با فرمت OpenAI به مایندبیس می‌فرستد.

مرحله دوم: تعریف Provider مایندبیس

دو راه دارید. راه مدرن (نسخه ۳): دستور ccr ui را اجرا کنید تا پنل مدیریتی باز شود؛ از بخش Providers ← Add Provider یک Provider با مشخصات زیر بسازید: Endpoint = https://api.mindbase.ir/v1، پروتکل = OpenAI Chat Completions، کلید = mb_... و مدل = MindBase. سپس در بخش Server سرویس را Start کنید.

راه فایل‌محور (سازگار با نسخه‌های قبلی): فایل ~/.claude-code-router/config.json (در ویندوز: %APPDATA%\claude-code-router\config.json) را بسازید:

{
  "LOG": true,
  "API_TIMEOUT_MS": 600000,
  "Providers": [
    {
      "name": "mindbase",
      "api_base_url": "https://api.mindbase.ir/v1/chat/completions",
      "api_key": "mb_xxxxxxxxxxxxxxxxxxxxxxxx",
      "models": ["MindBase"]
    }
  ],
  "Router": {
    "default": "mindbase,MindBase",
    "background": "mindbase,MindBase",
    "think": "mindbase,MindBase",
    "longContext": "mindbase,MindBase"
  }
}

دو نکته ظریف که رعایت نکردنشان منشأ اکثر خطاهاست:

  • api_base_url باید URL کامل تا /chat/completions باشد، نه Base URL ساده — روتر دقیقاً به همین آدرس درخواست POST می‌زند.
  • در بخش Router، قالب «provider,model» است: mindbase,MindBase. اگر مدل دیگری هم تعریف کنید (مثل GLM-5.3-Max)، همین‌جا جایگزینش کنید.

مرحله سوم: اجرا

ccr code

این دستور سرویس روتر را بالا می‌آورد و Claude Code را به آن وصل می‌کند. حالا پروژه‌تان را باز کنید و یک درخواست فارسی بدهید — پاسخ از مدل MindBase مایندبیس می‌آید و مصرف از انرژی حساب شما کم می‌شود. برای اعمال تغییرات بعدی در کانفیگ، ccr restart بزنید.

گزینه جایگزین: LiteLLM

اگر ترجیح می‌دهید از ابزار دیگری استفاده کنید، LiteLLM هم یک اندپوینت واقعی با فرمت Anthropic (/v1/messages) ارائه می‌دهد و می‌تواند پشت Claude Code بنشیند:

# config.yaml
model_list:
  - model_name: MindBase
    litellm_params:
      model: openai/MindBase
      api_base: https://api.mindbase.ir/v1
      api_key: mb_xxxxxxxxxxxxxxxxxxxxxxxx
litellm --config config.yaml --port 4000
export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_AUTH_TOKEN=mb_xxxxxxxxxxxxxxxxxxxxxxxx
export ANTHROPIC_MODEL=MindBase
claude

هر دو روش کار می‌کنند؛ claude-code-router چون مخصوص Claude Code ساخته شده، تنظیمات بیشتری برای ایجنت (مسیردهی مدل‌های think و longContext) در اختیارتان می‌گذارد و پیشنهاد ماست.

هشدار مهم: متغیرهای ANTHROPIC_* را مستقیم به مایندبیس ندهید

ممکن است جایی دیده باشید که می‌گویند ANTHROPIC_BASE_URL را روی سرویس دلخواه بگذارید. این متغیر فقط آدرس را عوض می‌کند؛ Claude Code همچنان درخواست‌ها را با فرمت Anthropic (/v1/messages) می‌فرستد — مسیری که مایندبیس ارائه نمی‌دهد و درخواست‌ها خطا می‌خورند. واسطه (روتر یا LiteLLM) اجباری است، نه اختیاری.

رفع مشکلات رایج

  • خطای ۴۰۴: معمولاً یعنی api_base_url را بدون /chat/completions گذاشته‌اید؛ URL کامل بدهید.
  • خطای ۴۰۱: کلید اشتباه است؛ کلید mb_ را از پروفایل مایندبیس دوباره کپی کنید.
  • تغییرات کانفیگ اثر نمی‌کند: بعد از هر تغییر ccr restart بزنید؛ در نسخه‌های جدید تنظیمات به دیتابیس محلی روتر مهاجرت می‌کند و ویرایش فایل قدیمی به‌تنهایی کافی نیست — از ccr ui استفاده کنید.
  • ایجنت ابزارها را خوب اجرا نمی‌کند: Claude Code سنگین‌ترین کاربر فراخوانی تابع است؛ مدل‌های قوی‌تر مایندبیس (MindBase یا GLM-5.3-Max) را برای آن انتخاب کنید.

جمع‌بندی

اتصال Claude Code به مایندبیس با یک واسطه انجام می‌شود: claude-code-router فرمت Anthropic را به OpenAI ترجمه می‌کند و مدل MindBase مایندبیس را به ایجنت می‌دهد. کانفیگش یک‌بار است و بعد از آن، یکی از بهترین ایجنت‌های کدنویسی دنیا روی مدل‌های مایندبیس و پرداخت ریالی اجرا می‌شود.

سوالات متداول

چرا نمی‌توانم مستقیم با ANTHROPIC_BASE_URL وصل شوم؟

چون Claude Code فقط پروتکل Anthropic صحبت می‌کند و مایندبیس فقط پروتکل OpenAI؛ برای ترجمه بین این دو به گیت‌وی واسط مثل claude-code-router یا LiteLLM نیاز دارید.

کدام مدل مایندبیس برای Claude Code مناسب‌تر است؟

مدل پیش‌فرض MindBase شروع خوبی است؛ برای کارهای پیچیده و بافتارهای طولانی، GLM-5.3-Max با پنجره یک میلیون توکن انتخاب قوی‌تری است.

آیا هزینه‌های Claude Code جداگانه دارد؟

در این روش دیگر اشتراک آنتروپیک لازم نیست؛ مصرف از انرژی پلن حساب مایندبیس شما کم می‌شود و نحوه مصرف در پنل قابل مشاهده است.

روتر باید همیشه روشن باشد؟

دستور ccr code خودش سرویس را بالا می‌آورد؛ اگر سرویس جدا اجرا می‌کنید، تا وقتی در حال کار با Claude Code هستید باید روشن بماند.