آموزش اتصال API هوش مصنوعی Mindbase به OpenCode و OpenClaw
در دنیای ایجنتهای متنباز دو نام پرتکرار هستید که گاهی با هم اشتباه گرفته میشوند: OpenCode ایجنت کدنویسی ترمینالی (TUI) است و OpenClaw دستیار شخصی خودمیزبان که روی تلگرام، واتساپ، دیسکورد و دهها پلتفرم دیگر برای شما عامل اجرا میکند. خوبی مشترک هر دو: هر دو با Providerهای باز-سازگار (OpenAI Compatible) کار میکنند و مایندبیس با چند خط کانفیگ به هر دو وصل میشود.
در این آموزش اول OpenCode را کامل وصل میکنیم و بعد همان الگو را برای OpenClaw میبینیم.
پیشنیازها
- OpenCode نصب شده باشد:
npm i -g @opencode/cli@latestیا نصب با اسکریپت رسمی opencode.ai. - برای OpenClaw: نصب طبق openclaw.ai (اسکریپت رسمی لینوکس/مک/WSL2 یا پاورشل ویندوز).
- کلید API مایندبیس (گام صفر پایین).
گام صفر: دریافت API Key و Base URL از مایندبیس
قبل از هر چیز به دو مقدار نیاز دارید: کلید API و Base URL. هر دو از سایت مایندبیس قابل دریافت هستند:
- وارد حساب کاربری خود در mindbase.ir شوید (ثبتنام رایگان است).
- از منوی پروفایل، بخش «کلیدهای API» را باز کنید.
- روی «+ کلید جدید» بزنید و یک نام دلخواه بدهید؛ مثلاً
OpenCode. - مقدار کلید را کپی کنید — این کلید با پیشوند
mb_شروع میشود. - Base URL نیز در همین صفحه نمایش داده میشود:
https://api.mindbase.ir/v1
بخش اول: اتصال OpenCode
ساخت Provider در opencode.json
فایل opencode.json را در ریشه پروژه (یا سراسری در ~/.config/opencode/opencode.json) بسازید:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"mindbase": {
"npm": "@ai-sdk/openai-compatible",
"name": "MindBase",
"options": {
"baseURL": "https://api.mindbase.ir/v1",
"apiKey": "mb_xxxxxxxxxxxxxxxxxxxxxxxx"
},
"models": {
"MindBase": {
"name": "MindBase",
"limit": { "context": 110000, "output": 8192 }
}
}
}
},
"model": "mindbase/MindBase"
}
دو نکته تعیینکننده در این فایل:
- مقدار
npmحتماً باید@ai-sdk/openai-compatibleباشد. پکیج@ai-sdk/openaiمعمولی به اندپوینت Responses میزند که مایندبیس ندارد — شایعترین علت خطای ۴۰۴. baseURLبا/v1؛ خود SDK مسیر/chat/completionsرا اضافه میکند.
اجرا و انتخاب مدل
opencode # اجرای TUI
/models # انتخاب mindbase/MindBase داخل جلسه
opencode --model mindbase/MindBase # اجرا با مدل مشخص
مقدار limit.context را مطابق پنجره بافتار مدل بگذارید (برای MindBase مقدار ۱۱۰ هزار) تا OpenCode مصرف بافتار را درست نمایش دهد؛ برای مدلهای GLM-5.3 این عدد تا یک میلیون میرسد.
بخش دوم: اتصال OpenClaw
OpenClaw همان الگوی Provider را در فایل ~/.openclaw/openclaw.json میخواهد، با یک تفاوت در نام فیلدها:
{
"agents": {
"defaults": { "model": { "primary": "mindbase/MindBase" } }
},
"models": {
"providers": {
"mindbase": {
"baseUrl": "https://api.mindbase.ir/v1",
"apiKey": "${MINDBASE_API_KEY}",
"api": "openai-completions",
"models": [{ "id": "MindBase", "name": "MindBase" }]
}
}
}
}
نکتهها:
apiباید"openai-completions"باشد؛ مقدار دیگر (anthropic-messages) به مسیرهای Anthropic میزند که مایندبیس ندارد.- مقدار
${MINDBASE_API_KEY}از متغیر محیطی خوانده میشود — کلید را بیرون از فایل کانفیگ نگه دارید:export MINDBASE_API_KEY=mb_.... - بعد از تغییر فایل، OpenClaw را ریاستارت کنید.
تست نهایی
- در OpenCode یک پروژه باز کنید و بگویید: «ساختار پروژه را بررسی کن و خلاصه کن» — پاسخ باید از MindBase بیاید.
- در OpenClaw یک پیام از تلگرام/دیسکورد بدهید و عامل را روی مدل مایندبیس ببینید.
رفع مشکلات رایج
- خطای ۴۰۴ در OpenCode: پکیج Provider اشتباه است؛ فقط
@ai-sdk/openai-compatibleبه مسیر Chat Completions میزند. - خطای ۴۰۴ در OpenClaw: مقدار
apiرا چک کنید؛ بایدopenai-completionsباشد و baseUrl با/v1. - خطای ۴۰۱: کلید اشتباه است؛ از پروفایل مایندبیس دوباره کپی کنید و در OpenClaw مطمئن شوید متغیر محیطی قبل از اجرا ست شده.
- ابزارها در ایجنت اجرا نمیشوند: مدلهای خیلی سبک فراخوانی تابع را خوب پشتیبانی نمیکنند؛ MindBase یا GLM-5.3 را انتخاب کنید.
جمعبندی
هر دو ابزار با یک الگوی مشابه به مایندبیس وصل میشوند: Provider سفارشی با Base URL باز-سازگار https://api.mindbase.ir/v1، کلید mb_ و مدل MindBase. OpenCode برای کدنویسی ترمینالی و OpenClaw برای دستیار شخصی چندپلتفرمی — هر دو با مدلهای مایندبیس و بدون واسطه اجرا میشوند.
سوالات متداول
OpenCode و OpenClaw چه فرقی دارند؟
OpenCode ایجنت کدنویسی ترمینالی است (جایگزین Claude Code/Codex با متنباز کامل) و OpenClaw دستیار شخصی خودمیزبان که در پیامرسانها به شما پاسخ میدهد. هر دو Provider باز-سازگار میپذیرند.
چرا در OpenCode پکیج openai معمولی کار نمیکند؟
چون آن پکیج بهسمت اندپوینت Responses API میرود؛ مایندبیس Chat Completions ارائه میدهد و پکیج openai-compatible دقیقاً برای همین سناریو ساخته شده است.
کلید API در OpenClaw کجا امنتر است؟
در متغیر محیطی با سینتکس ${VAR} در openclaw.json — همان که در آموزش دیدید؛ فایل کانفیگ بدون کلید میماند و در گیت هم امن است.
میتوان چند مدل مایندبیس را همزمان تعریف کرد؟
بله؛ در OpenCode داخل models چند شناسه اضافه کنید و در OpenClaw آرایه models را با چند id پر کنید؛ بعد در جلسه با /models جابجا شوید.