اتصال OpenCode به AvalAI

از OpenCode به‌عنوان عامل برنامه‌نویسی در پایانه استفاده کنید و پردازش مدل را به AvalAI بسپارید. با ارائه‌دهنده مشخص Chat Completions، کلید اختصاصی و درخواست تأیید برای ابزارها شروع کنید. دسترسی به فایل، فرمان‌های پوسته، افزونه‌ها و اشتراک‌گذاری را OpenCode کنترل می‌کند، نه AvalAI.

منابع در ۱۴۰۵-۰۶-۱۷ / (2026-09-08) بررسی شده‌اند. پیکربندی با مستندات رسمی OpenCode تطبیق داده شده است؛ نشست دارای کلید API اجرا نشده است.

۱. نصب و انتخاب فضای کار

ابزار رسمی را با Node.js و pnpm نصب کنید یا روش مناسب سیستم‌عامل خود را از راهنمای نصب انتخاب کنید:

bash

pnpm install -g opencode-ai
opencode --version

پیش از استفاده تیمی، نسخه‌ای را که آزموده‌اید ثبت کنید. نشست اول را در پروژه‌ای آزمایشی و بدون اسرار اجرا کنید. OpenCode می‌تواند دستورهای مخزن، پیکربندی و افزونه‌ها را بخواند؛ پیش از باز کردن مخزن ناشناس آن‌ها را بررسی کنید.

۲. افزودن پیکربندی ارائه‌دهنده

تنظیمات زیر را در ~/.config/opencode/opencode.json ادغام کنید؛ تنظیمات موجود را بازنویسی نکنید. فایل opencode.json داخل پروژه می‌تواند مقادیر سراسری را تغییر دهد، پس آن را نیز بررسی کنید.

json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "avalai/gpt-5.4-mini",
  "small_model": "avalai/gpt-5.4-mini",
  "share": "disabled",
  "permission": {
    "*": "ask",
    "external_directory": "deny"
  },
  "provider": {
    "avalai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AvalAI",
      "options": {
        "baseURL": "https://api.avalai.ir/v1"
      },
      "models": {
        "gpt-5.4-mini": {
          "name": "AvalAI GPT-5.4 mini",
          "limit": {
            "context": 272000,
            "output": 128000
          }
        }
      }
    }
  }
}

این پیکربندی از سازگارکننده رسمی @ai-sdk/openai-compatible برای /v1/chat/completions استفاده می‌کند، نه سازگارکننده Responses با نام @ai-sdk/openai. مدل اصلی و مدل کمکی هر دو مشخص‌اند تا کارهای جانبی بی‌خبر مدل دیگری انتخاب نکنند.

اطلاعات ظرفیت مدل از فهرست AvalAI در ۱۴۰۵-۰۶-۱۷ / (2026-09-08) گرفته شده است. این مقادیر ظرفیت‌اند، نه بودجه خروجی هر کار. پیش از جایگزینی مدل، به‌ویژه برای ابزارها، بینایی، اندازه زمینه و سقف خروجی، فهرست جاری مدل‌ها را بررسی کنید.

۳. ذخیره کلید و انتخاب مدل

در پوشه پروژه انتخابی opencode را اجرا کنید و سپس:

۱. فرمان /connect را وارد کنید.

۲. گزینه Other را انتخاب کنید.

۳. شناسه ارائه‌دهنده را دقیقاً مطابق پیکربندی، avalai وارد کنید.

۴. کلید اختصاصی AvalAI را در محل دریافت اعتبارنامه بچسبانید.

۵. فرمان /models را اجرا و AvalAI GPT-5.4 mini را انتخاب کنید.

ورود اعتبارنامه فقط یک راز محلی ذخیره می‌کند؛ نشانی پایه و مدل را تنظیم نمی‌کند. از محل ذخیره اعتبارنامه OpenCode و پشتیبان‌های آن محافظت کنید. کلید واقعی را در opencode.json نگذارید.

اگر از سامانه مدیریت اسرار استفاده می‌کنید، options.apiKey مقدار "{env:AVALAI_API_KEY}" را می‌پذیرد. متغیر را در اختیار فرایند OpenCode قرار دهید و یک روش مشخص برای تأمین اعتبارنامه داشته باشید.

عبارت avalai/gpt-5.4-mini انتخابگر ارائه‌دهنده و مدل در OpenCode است. درخواست ارسالی به AvalAI شناسه ساده gpt-5.4-mini را دارد. این نام‌گذاری با پیشوند درگاه 9Router یکسان نیست.

۴. ابتدا چت و سپس یک ابزار را بیازمایید

ابتدا این درخواست را بفرستید:

text

Reply with exactly: AvalAI connected
Do not use tools or read files.

سپس نام یک فایل غیرحساس را بدهید و بخواهید آن را بخواند و یک تابع را توضیح دهد. فقط همان خواندن مورد انتظار را تأیید کنید. بررسی کنید پاسخ به محتوای واقعی فایل اشاره دارد.

پاسخ متنی فقط پردازش مدل را ثابت می‌کند. خواندن موفق فایل مسیر جداگانه عامل و ابزار را نیز می‌آزماید. پیش از فعال‌کردن تغییرات، تمرین کوچک عامل برنامه‌نویسی را انجام دهید.

پیکربندی برای ابزارها تأیید می‌خواهد و دسترسی بیرون پوشه کاری را رد می‌کند. با --auto شروع نکنید و تأیید خودکار را فعال نکنید؛ این گزینه رفتار قواعد ask را تغییر می‌دهد. مجوزها و دستورها جای محیط ایزوله سیستم‌عامل را نمی‌گیرند؛ فضای کار آزمایشی و اعتبارنامه با کمترین دسترسی لازم داشته باشید.

۵. قابلیت‌های اختیاری را جدا بررسی کنید

ابزارها: به فراخوانی تابع در مدل، ساختار سازگار و مجوز تأییدشده OpenCode نیاز دارند.
بینایی: پشتیبانی مدل و قالب ورودی تصویر باید سازگار باشند؛ جداگانه بیازمایید.
Responses: سازگارکننده دیگری دارد. برای رفع خطای نامرتبط احراز هویت، سازگارکننده را تغییر ندهید.
Embeddings، تصویر، صدا، جستجوی وب و MCP: پیکربندی ارائه‌دهنده زبانی این خدمات یا اعتبارنامه‌هایشان را خودکار تنظیم نمی‌کند.
9Router: در صورت نیاز ارائه‌دهنده‌ای جدا بسازید؛ نشانی پایه، کلید سمت کاربر و شناسه دارای پیشوند آن متفاوت‌اند. راه‌اندازی 9Router را ببینید.

عیب‌یابی

نشانه	بررسی
ارائه‌دهنده در `/models` نیست	بخش `provider.avalai.models` وجود داشته باشد و شناسه اعتبارنامه با ارائه‌دهنده برابر باشد.
`401` / `403`	کلید اختصاصی و دسترسی حساب را بررسی کنید؛ فایل اعتبارنامه را نمایش ندهید.
`404`	نشانی پایه دقیقاً یک `/v1` داشته باشد و سازگارکننده Chat Completions انتخاب شده باشد.
مدل یا مجوز غیرمنتظره	پیکربندی پروژه، نمایه‌ها، افزونه‌ها یا تنظیمات مدیریتی ممکن است مقادیر سراسری را تغییر دهند.
فراخوانی ابزار به‌صورت متن	قابلیت فراخوانی تابع، سازگارکننده و یک ابزار ساده فقط‌خواندنی را بررسی کنید.
خطای زمینه یا خروجی	ظرفیت‌های فهرست مدل را دوباره ببینید؛ زمینه را کم و نشستی تازه با دامنه محدود شروع کنید.
مصرف زیاد	حلقه‌های عامل و مدل کمکی درخواست اضافه دارند. مصرف AvalAI را ببینید؛ برآورد محلی صورتحساب نیست.

منابع رسمی و گام بعد

این راهنما سازگاری سرتاسری AvalAI را برای همه نسخه‌ها، مدل‌ها یا افزونه‌های OpenCode ثابت نمی‌کند. پیش از استفاده از مخزن شرکت، آزمایشی کم‌خطر انجام دهید. هنگام بررسی مستندات بسته‌ای نصب، کلیدی ذخیره، ابزاری اجرا یا درخواست پولی ارسال نشده است.

اتصال OpenCode به AvalAI ​

۱. نصب و انتخاب فضای کار ​

۲. افزودن پیکربندی ارائه‌دهنده ​

۳. ذخیره کلید و انتخاب مدل ​

۴. ابتدا چت و سپس یک ابزار را بیازمایید ​

۵. قابلیت‌های اختیاری را جدا بررسی کنید ​

عیب‌یابی ​

منابع رسمی و گام بعد ​