OpenCode چیست؟

OpenCode یک ایجنت کدنویسی هوش مصنوعی منبع‌باز است که به‌صورت رابط ترمینال (TUI)،
اپلیکیشن دسکتاپ برای مک، ویندوز و لینوکس و افزونهٔ IDE در دسترس است. از یکپارچگی
LSP، پشتیبانی از نشست‌های متعدد، لینک‌های اشتراک‌گذاریِ نشست و سازگاری با بیش از
۷۵ ارائه‌دهندهٔ LLM بهره می‌برد. آشا در این فهرست داخلی نیست، ولی چون یک درگاه
سازگار با OpenAI است، به‌صورت «ارائه‌دهندهٔ سفارشی» به سادگی به OpenCode وصل می‌شود
و با یک کلید API به همهٔ مدل‌ها دسترسی یکپارچه می‌دهید.

هم برنامهٔ ترمینال و هم دسکتاپ، فایل opencode.json و اعتبارنامه‌های
یکسانی را می‌خوانند؛ پس یک بار اتصال آشا در هر دو رابط در دسترس است.

دریافت کلید API آشا

  • در پنل کاربری آشا ثبت‌نام یا وارد شوید.
  • به صفحهٔ کلیدهای API بروید.
  • روی «ساخت کلید جدید» کلیک کنید و آن را کپی کنید (با قالب sk-asha-… شروع می‌شود).

شروع سریع: ترمینال

گام ۱ — نصب OpenCode

Terminal
bash · curl 
curl -fsSL https://opencode.ai/install | bash

روش‌های نصب دیگر (Bun، pnpm، Yarn، Arch Linux و Windows) در مستندات نصب OpenCode
توضیح داده شده‌اند.

گام ۲ — اتصال OpenCode به آشا

آشا در فهرست ارائه‌دهنده‌های پیش‌فرض OpenCode نیست؛ آن را به‌عنوان یک «ارائه‌دهندهٔ
سفارشی سازگار با OpenAI» تعریف می‌کنیم. اول کلید را با
/connect ذخیره کنید، بعد ارائه‌دهنده را در فایل پیکربندی
معرفی کنید:

OpenCode را در پوشهٔ پروژه‌تان اجرا کنید:

Terminal
bash 
cd /path/to/your/project
opencode

دستور /connect را اجرا کنید و به پایین فهرست بروید تا
گزینهٔ Other (سایر) را پیدا کنید:

OpenCode — /command
TUI 
/connect

در این مرحله OpenCode درخواست می‌کند یک «شناسهٔ ارائه‌دهنده» (provider id) بدهید و
سپس کلید API. برای آشا از شناسهٔ asha استفاده کنید:

OpenCode — /connect
TUI 
Add credential
Select provider       → ● Other
Enter provider id     → asha
Enter your API key    → sk-asha-...

این مرحله فقط اعتبارنامه را ذخیره می‌کند (در
~/.local/share/opencode/auth.json). هنوز باید آدرس آشا و
فهرست مدل‌ها را در پیکربندی تعریف کنید — بخش «فایل پیکربندی» را ببینید.

شروع سریع: دسکتاپ

اپلیکیشن دسکتاپ پروژه‌ها و نشست‌های فعال را در تب‌ها سازمان‌دهی می‌کند و ارائه‌دهنده‌ها
را از طریق رابط تنظیمات (نه دستورات اسلش) پیکربندی می‌کند.

گام ۱ — نصب OpenCode Desktop

Terminal
bash · Homebrew 
brew install --cask opencode-desktop

یا DMG مخصوص Apple Silicon یا Intel را از صفحهٔ دانلود OpenCode بگیرید.

گام ۲ — اتصال آشا (ارائه‌دهندهٔ سفارشی)

  • OpenCode Desktop را اجرا کنید و یک پوشهٔ پروژه باز کنید.
  • از منوی File به Settings بروید و تب Providers را باز کنید.
  • روی «More providers» بزنید و «Custom OpenAI compatible providers» را انتخاب کنید.
  • در فرم جدید این فیلدها را پر کنید:
    • Provider ID: asha
    • Display name: آشا
    • Base URL: https://app.asha-ai.ir/v1
    • API key: کلید sk-asha-… خود را جای‌گذاری کنید.
  • مدل‌هایی را که می‌خواهید اضافه کنید: شناسهٔ مدل همان شناسهٔ آشا است (مثل
    deepseek/deepseek-v4-flash) و نام نمایشی دلخواه خودتان (مثل
    deepseek-v4-flash).
  • ذخیره کنید. آشا زیر «ارائه‌دهنده‌های متصل» ظاهر می‌شود.

گام ۳ — انتخاب مدل

از انتخابگر مدل در نمای نشست استفاده کنید یا «انتخاب مدل» را از پالت فرمان اجرا کنید
و یک مدل آشا انتخاب کنید.

اگر بلافاصله بعد از افزودن کلید، مدلی در انتخابگر ظاهر نشد، OpenCode Desktop را
کاملاً ببندید و دوباره باز کنید. فهرست مدل‌های ارائه‌دهنده هنگام راه‌اندازی خوانده
می‌شود؛ بنابراین ممکن است ارائه‌دهندهٔ تازه‌متصل‌شده تا قبل از راه‌اندازی مجدد ظاهر
نشود.

اگر قبلاً آشا را در ترمینال وصل کرده‌اید، اپلیکیشن دسکتاپ همان اعتبارنامه را به‌طور
خودکار برمی‌دارد — مستقیم به انتخاب مدل بروید.

فایل پیکربندی

آشا یک درگاه سازگار با OpenAI است و در فهرست ارائه‌دهنده‌های پیش‌فرض OpenCode نیست؛
پس باید آن را به‌صورت یک «ارائه‌دهندهٔ سفارشی سازگار با OpenAI» در فایل
opencode.json تعریف کنید. سه چیز لازم است: بستهٔ
@ai-sdk/openai-compatible به‌عنوان npm، آدرس پایهٔ آشا به‌عنوان
options.baseURL و فهرست مدل‌هایی که می‌خواهید استفاده کنید. کلید هر مدل،
همان شناسهٔ آشا است:

JSON
opencode.json 
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "asha": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Asha",
      "options": {
        "baseURL": "https://app.asha-ai.ir/v1"
      },
      "models": {
        "deepseek/deepseek-v4-flash": {
          "name": "deepseek-v4-flash"
        },
        "qwen/qwen3": {
          "name": "qwen3"
        }
      }
    }
  }
}

کلید را در این فایل نمی‌گذارید — با /connect یا تنظیمات دسکتاپ در
~/.local/share/opencode/auth.json ذخیره می‌شود و OpenCode آن را
از روی شناسهٔ ارائه‌دهنده (اینجا asha) پیدا می‌کند.

شناسهٔ مدل، همان شناسهٔ آشا است — مثل
deepseek/deepseek-v4-flash یا
qwen/qwen3. هر مدل دیگری را هم می‌توانید از
فهرست مدل‌های آشا انتخاب کنید. نام نمایشی داخل
name فقط برچسبی است که در /models می‌بینید؛ شناسهٔ
واقعی همان کلیدِ کنار آن است.

پیکربندی پروژه در opencode.json در ریشهٔ پروژه است؛ تنظیمات
سراسری کاربر در
~/.config/opencode/opencode.json. هر دو قالب، JSONC را هم
می‌پذیرند.

تعیین مدل پیش‌فرض

برای رد شدن از انتخابگر مدل هنگام شروع، کلید سراسری model را
تنظیم کنید. OpenCode شناسهٔ مدل را به‌صورت
provider_id/model_id می‌سازد، پس مدلِ آشا با پیشوند
asha/ نوشته می‌شود:

JSON
opencode.json 
{
  "$schema": "https://opencode.ai/config.json",
  "model": "asha/deepseek/deepseek-v4-flash"
}

این در TUI، اپلیکیشن دسکتاپ و opencode run یکسان اعمال می‌شود.
می‌توانید با فلگ –model / -m در هر اجرا آن را تغییر دهید.

تعیین دستی کلید API

کلیدهایی که با /connect یا تنظیمات دسکتاپ اضافه می‌شوند در
~/.local/share/opencode/auth.json ذخیره می‌شوند؛ مسیری یکسان در
مک، لینوکس و ویندوز که ترمینال و دسکتاپ مشترکاً می‌خوانند. اگر
XDG_DATA_HOME را تنظیم کرده‌اید، به همان دایرکتوری اشاره دهید.
می‌توانید فایل را مستقیم هم بنویسید:

JSON
~/.local/share/opencode/auth.json 
{
  "asha": {
    "type": "api",
    "key": "sk-asha-your-key-here"
  }
}

مسیریابی ارائه‌دهنده

مسیریابی و failover بین زیرساخت‌ها برای هر مدل در داخل آشا انجام می‌شود؛ OpenCode فقط
درخواست را به آدرس پایهٔ آشا می‌فرستد و آشا انتخاب زیرساخت را بر عهده می‌گیرد. پس
نیازی به تنظیم گزینه‌های مسیریابی (مثل options.provider) در
پیکربندی OpenCode نیست.

چرا OpenCode و آشا؟

دسترسی به صدها مدل

بین هر مدلی که در فهرست مدل‌های آشا هست جابه‌جا شوید —
Anthropic، OpenAI، Google و DeepSeek — بدون اینکه برای هر ارائه‌دهنده کلید جداگانه
مدیریت کنید.

جابه‌جایی بین زیرساخت‌ها (Failover)

اگر یک زیرساخت در دسترس نباشد یا نرخ محدود شود، آشا به‌طور خودکار به دیگری مسیریابی
می‌کند و نشست کدنویسی شما قطع نمی‌شود.

کنترل‌های سازمانی

برای تیم‌ها، آشا مدیریت بودجه را متمرکز می‌کند: سقف هزینه بگذارید، اعتبار تخصیص دهید و
مصرف همهٔ توسعه‌دهندگانِ در حال استفاده از OpenCode را از داشبورد فعالیت آشا زیر نظر
بگیرید.

انعطاف در مدل

با دستور /models، انتخابگر مدل دسکتاپ یا پیکربندی، مدل را عوض
کنید — بدون نیاز به تنظیم دوبارهٔ کلیدها یا endpointها.

رفع خطا

خطاهای احراز هویت

مطمئن شوید کلید را درست با /connect (یا تنظیمات Providers دسکتاپ)
تنظیم کرده‌اید. با opencode auth list مطمئن شوید اعتبارنامه
ذخیره شده است. کلید را در پنل کاربری آشا هم بررسی کنید.

مدل پیدا نمی‌شود

مدلی که به provider.asha.models اضافه کرده‌اید را با نام انتخابی
/models پیدا کنید. اگر نیست، OpenCode را کاملاً ببندید و دوباره
باز کنید تا پیکربندی دوباره خوانده شود. در کلید سراسری
model، پیشوند ارائه‌دهندهٔ asha/ را فراموش
نکنید (مثال: asha/deepseek/deepseek-v4-flash).

خطای «Model not found» هنگام اجرا

شناسهٔ مدلِ خواسته‌شده را با شناسه‌ای که در
provider.asha.models تعریف کرده‌اید و با
فهرست مدل‌های آشا مقایسه کنید — باید دقیقاً یکی باشند.

بعد از اتصال مدلی نیست

برای ارائه‌دهندهٔ سفارشی، مدل‌ها از قبل بارگذاری نمی‌شوند؛ هر مدلی را که می‌خواهید باید
خودتان در provider.asha.models اضافه کنید. بعد از آن OpenCode را
کاملاً ببندید و دوباره باز کنید.

مدل در انتخابگر نیست

آن را زیر provider.asha.models در پیکربندی اضافه کنید و OpenCode
را دوباره باز کنید.

حریم خصوصی

آشا کدِ منبعِ پرامپت‌های شما را در پرامپت‌لِگ‌زنگ ثبت نمی‌کند مگر اینکه خودتان ثبت
پرامپت را فعال کنید. برای جزئیات به سیاست حریم خصوصی مراجعه کنید.

جمع‌بندی

OpenCode و آشا ترکیبی بی‌دردسر برای ایجنت کدنویسی است: یک کلید، فهرست کامل مدل‌ها،
جابه‌جایی خودکار بین زیرساخت‌ها و بودجهٔ متمرکز برای تیم. برای دیدن همهٔ مدل‌ها و
قیمت‌ها به مدل‌های آشا سر بزنید.