آموزش اتصال 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. هر دو از سایت مایندبیس قابل دریافت هستند:
- وارد حساب کاربری خود در mindbase.ir شوید (ثبتنام رایگان است).
- از منوی پروفایل، بخش «کلیدهای API» را باز کنید.
- روی «+ کلید جدید» بزنید و یک نام دلخواه بدهید؛ مثلاً
Codex. - مقدار کلید را کپی کنید — این کلید با پیشوند
mb_شروع میشود. - Base URL نیز در همین صفحه نمایش داده میشود:
https://api.mindbase.ir/v1
مرحله اول: کانفیگ LiteLLM بهعنوان پل
فایل 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 هم کار میکند ولی توصیه نمیشود.