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

Codex CLI ایجنت کدنویسی ترمینالی OpenAI است که با مدل‌های مختلف کار می‌کند — اما یک تغییر مهم در نسخه‌های ۲۰۲۶ آن باید بدانید: پشتیبانی از wire_api = "chat" (یعنی اتصال مستقیم به اندپوینت Chat Completions) به‌کلی حذف شده و Codex حالا فقط پروتکل Responses را می‌فهمد. مایندبیس استاندارد Chat Completions را ارائه می‌دهد؛ پس برای این اتصال یک پل کوچک لازم داریم: LiteLLM که اندپوینت Responses را می‌پذیرد و درخواست را به Chat Completions مایندبیس ترجمه می‌کند.

در این آموزش این پل را برپا می‌کنیم: یک سرویس محلی LiteLLM روی پورت ۴۰۰۰ و کانفیگ Codex که به آن وصل می‌شود.

پیش‌نیازها

  • Python 3.10+ برای نصب LiteLLM و Codex CLI نصب‌شده: npm install -g @openai/codex.
  • کلید API مایندبیس (گام صفر پایین).

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

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

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

مرحله اول: کانفیگ LiteLLM به‌عنوان پل

محیط واقعی Codex CLI — آموزش تنظیم اتصال به مایندبیس

فایل litellm-config.yaml را با این محتوا بسازید:

model_list:
  - model_name: MindBase
    litellm_params:
      model: openai/MindBase
      api_base: https://api.mindbase.ir/v1
      api_key: mb_xxxxxxxxxxxxxxxxxxxxxxxx
      use_chat_completions_api: true

مقدار use_chat_completions_api: true نقش کلیدی دارد: به LiteLLM می‌گوید برای این مدل، درخواست‌های ورودی فرمت Responses را به فرمت Chat Completions ترجمه و به مایندبیس بفرستد — دقیقاً همان پلی که Codex لازم دارد.

مرحله دوم: اجرای پل

pip install litellm
litellm --config litellm-config.yaml --port 4000

حالا یک سرویس محلی روی http://localhost:4000 دارید که هم فرمت Responses (برای Codex) و هم فرمت OpenAI را سرو می‌کند و پشتش به مایندبیس وصل است.

مرحله سوم: کانفیگ Codex CLI

فایل ~/.codex/config.toml (در ویندوز: %USERPROFILE%\.codex\config.toml) را ویرایش کنید:

model = "MindBase"
model_provider = "mindbase"

[model_providers.mindbase]
name = "MindBase via LiteLLM"
base_url = "http://localhost:4000/v1"
env_key = "MINDBASE_API_KEY"
wire_api = "responses"

نکته‌های مهم این فایل:

  • model_providers فقط در کانفیگ سطح کاربر (user-level) معتبر است؛ در کانفیگ سطح پروژه نادیده گرفته می‌شود.
  • wire_api = "responses" الزامی است؛ مقدار "chat" دیگر پذیرفته نمی‌شود و خطا می‌دهد — آموزش‌های قدیمی اینترنت هنوز همان را پیشنهاد می‌دهند.
  • base_url به پل محلی اشاره دارد (پورت ۴۰۰۰)، نه مستقیم به مایندبیس — چون ترجمه فرمت را LiteLLM انجام می‌دهد.

مرحله چهارم: کلید و اجرا

# ویندوز (PowerShell)
setx MINDBASE_API_KEY "mb_xxxxxxxxxxxxxxxxxxxxxxxx"

# لینوکس/مک (Git Bash)
export MINDBASE_API_KEY=mb_xxxxxxxxxxxxxxxxxxxxxxxx

بعد از ست‌کردن متغیر، ترمینال را یک‌بار باز کنید و اجرا کنید:

codex -m MindBase

Codex به پل LiteLLM وصل می‌شود، LiteLLM درخواست را به https://api.mindbase.ir/v1/chat/completions می‌فرستد و ایجنت با مدل MindBase مایندبیس شروع به کار می‌کند.

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

  • خطای «wire_api chat is no longer supported»: در کانفیگ، مقدار را روی "responses" بگذارید و مطمئن شوید پل LiteLLM در حال اجراست.
  • خطای ۴۰۴ روی /responses: یعنی Codex مستقیم به مایندبیس وصل شده؛ base_url باید http://localhost:4000/v1 باشد نه آدرس مایندبیس.
  • خطای ۴۰۱: کلید در متغیر MINDBASE_API_KEY درست ست نشده؛ بعد از setx، ترمینال را دوباره باز کنید. کلید را هم از پروفایل مایندبیس دوباره کپی کنید.
  • پاسخ‌ها ناقص یا قطع می‌شوند: استریم بین Codex و LiteLLM حساس است؛ اگر مشکل دیدید، نسخه LiteLLM را به‌روز کنید و تست را اول خارج از جلسه تعاملی بگیرید.

جمع‌بندی

اتصال Codex CLI به مایندبیس امروز یک‌مرحله‌ای نیست چون Codex فقط Responses می‌فهمد و مایندبیس Chat Completions ارائه می‌دهد؛ پل LiteLLM این شکاف را پر می‌کند: یک کانفیگ ۷خطی، یک سرویس محلی و یک Provider سه‌خطی در config.toml. بعد از آن، ایجنت ترمینالی OpenAI با مدل‌های مایندبیس و پرداخت ریالی اجرا می‌شود.

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

چرا دیگر نمی‌توان مستقیم با wire_api=chat وصل شد؟

OpenAI پشتیبانی Chat Completions را از Codex حذف کرده (اوایل ۲۰۲۶) و حالا فقط Responses API را می‌پذیرد؛ برای سرویس‌هایی که Chat Completions دارند، پل LiteLLM راه رسمی‌الگو است.

آیا LiteLLM باید همیشه در پس‌زمینه اجرا باشد؟

بله؛ تا وقتی با Codex کار می‌کنید سرویس روی پورت ۴۰۰۰ باید بالا باشد. می‌توانید آن را به‌عنوان سرویس سیستم عامل ثبت کنید.

آیا مدل دیگری هم می‌شود تعریف کرد؟

بله؛ در model_list برای هر مدل مایندبیس (مثلاً GLM-5.3-Max) یک بلاک مشابه اضافه کنید و در config.toml با model_provider همان نام صدا بزنید.

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

در متغیر محیطی (env_key) — همان که آموزش دادیم؛ گذاشتن کلید مستقیم داخل config.toml هم کار می‌کند ولی توصیه نمی‌شود.