آموزش اتصال 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. هر دو از سایت مایندبیس قابل دریافت هستند:

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

بخش اول: اتصال OpenCode

محیط واقعی 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 را ری‌استارت کنید.

تست نهایی

  1. در OpenCode یک پروژه باز کنید و بگویید: «ساختار پروژه را بررسی کن و خلاصه کن» — پاسخ باید از MindBase بیاید.
  2. در 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 جابجا شوید.