آموزش نصب، راه‌اندازی و اتصال OpenCode به API درواره؛ استفاده از مدل‌های هوش مصنوعی برای برنامه‌نویسی

OpenCode چیست؟

OpenCode یک عامل هوش مصنوعی متن‌باز برای برنامه‌نویسی است که می‌تواند داخل ترمینال، محیط دسکتاپ یا افزونه IDE اجرا شود. این ابزار به مدل‌های هوش مصنوعی متصل می‌شود، ساختار پروژه را بررسی می‌کند، فایل‌ها را می‌خواند، کد می‌نویسد، دستورات Shell را اجرا می‌کند، تست‌ها را بررسی می‌کند و برای انجام وظایف توسعه نرم‌افزار با برنامه‌نویس همکاری می‌کند.

برخلاف یک چت‌بات معمولی، OpenCode فقط درباره کد توضیح نمی‌دهد. در صورت داشتن مجوز می‌تواند مستقیما در پروژه اقدام کند:

• ساختار مخزن را تحلیل کند.
• فایل و تابع موردنظر را پیدا کند.
• باگ را بازتولید و ریشه‌یابی کند.
• فایل‌های پروژه را تغییر دهد.
• Feature جدید پیاده‌سازی کند.
• تست واحد و یکپارچه بنویسد.
• دستورات Build، Lint و Test را اجرا کند.
• خطاهای TypeScript یا کامپایل را رفع کند.
• تغییرات Git را بررسی کند.
• مستندات فنی ایجاد کند.
• از Agentها، Skills، ابزارهای سفارشی و MCP Serverها استفاده کند.

OpenCode در واقع یک AI Coding Agent است؛ یعنی مدل هوش مصنوعی را به فایل‌ها، ترمینال، ابزارهای توسعه و Context پروژه متصل می‌کند.

براساس مستندات رسمی OpenCode، این ابزار به‌صورت رابط ترمینالی، برنامه دسکتاپ و افزونه IDE ارائه می‌شود و می‌تواند با ارائه‌دهندگان مختلف مدل‌های هوش مصنوعی کار کند.

چرا OpenCode را به درواره متصل کنیم؟

OpenCode برای استدلال، تولید کد و تصمیم‌گیری به یک مدل هوش مصنوعی نیاز دارد. درواره یک API سازگار با OpenAI در اختیار توسعه‌دهندگان ایرانی قرار می‌دهد که از طریق آن می‌توان به مدل‌های مختلف دسترسی داشت.

آدرس پایه API درواره:

https://api.darvareh.ir/v1

با اتصال OpenCode به درواره می‌توانید:

• از مدل‌های مختلف برنامه‌نویسی و استدلال استفاده کنید.
• مدل پروژه را بدون تغییر اساسی در ابزار عوض کنید.
• از یک API Key واحد برای دسترسی به مدل‌های موجود استفاده کنید.
• هزینه مصرف مدل‌ها را از طریق کیف پول ریالی مدیریت کنید.
• برای وظایف مختلف، مدل‌های متفاوت انتخاب کنید.
• یک مدل قدرتمند برای کدنویسی و مدل اقتصادی‌تری برای کارهای سبک تعیین کنید.
• OpenCode را بدون نیاز به اتصال مستقیم به چند ارائه‌دهنده راه‌اندازی کنید.
• معماری خود را به یک مدل مشخص وابسته نکنید.

نکته مهم این است که OpenCode و درواره نقش‌های متفاوتی دارند. OpenCode عامل برنامه‌نویسی است و درواره زیرساخت دسترسی API به مدل‌های هوش مصنوعی را فراهم می‌کند.

برنامه‌نویس
↓
OpenCode
↓
API سازگار با OpenAI درواره
↓
مدل هوش مصنوعی انتخاب‌شده
↓
پاسخ، Tool Calling و تولید کد

پیش‌نیازهای اتصال OpenCode به درواره

پیش از شروع، موارد زیر را آماده کنید:

• یک حساب کاربری فعال در درواره
• موجودی کافی در کیف پول درواره
• یک API Key فعال
• دسترسی به ترمینال
• یک پروژه نرم‌افزاری برای آزمایش
• Git، ترجیحا برای کنترل تغییرات
• Node.js فقط در صورتی که OpenCode را با NPM نصب می‌کنید
• یک مدل مناسب برنامه‌نویسی که با قابلیت‌های موردنیاز OpenCode سازگار باشد

OpenCode برای عملکرد مناسب به یک ترمینال مدرن نیاز دارد. در ویندوز، استفاده از Windows Terminal همراه WSL معمولا تجربه بهتری ایجاد می‌کند.

مرحله اول: ثبت‌نام و ساخت API Key در درواره

ابتدا وارد وب‌سایت درواره شوید و حساب کاربری خود را ایجاد کنید.

پس از ورود:

1. کیف پول خود را شارژ کنید.
2. وارد بخش API Keys یا کلیدهای API شوید.
3. یک کلید جدید ایجاد کنید.
4. نامی مانند OpenCode Laptop برای آن انتخاب کنید.
5. در صورت وجود تنظیمات محدودیت مصرف، بودجه یا Rate Limit را مشخص کنید.
6. کلید را کپی و در محل امن نگهداری کنید.

کلید API معمولا فقط هنگام ایجاد به‌صورت کامل نمایش داده می‌شود. آن را در فایل‌های پروژه، اسکرین‌شات، مخزن Git یا پیام‌رسان‌ها قرار ندهید.

در مثال‌های این مقاله از مقدار زیر به‌عنوان کلید فرضی استفاده شده است:

YOUR_DARVAREH_API_KEY

این مقدار را باید با کلید واقعی خود جایگزین کنید.

مرحله دوم: آزمایش API درواره قبل از نصب OpenCode

قبل از متصل کردن OpenCode بهتر است مطمئن شوید API Key، کیف پول و مدل انتخاب‌شده درست کار می‌کنند.

دریافت فهرست مدل‌ها

در Linux، macOS یا WSL:

curl https://api.darvareh.ir/v1/models \
  -H "Authorization: Bearer YOUR_DARVAREH_API_KEY"

در PowerShell ویندوز:

$headers = @{
  Authorization = "Bearer YOUR_DARVAREH_API_KEY"
}

Invoke-RestMethod `
  -Uri "https://api.darvareh.ir/v1/models" `
  -Headers $headers `
  -Method Get

از مقدار فیلد id مدل موردنظر در تنظیمات OpenCode استفاده کنید. شناسه مدل باید دقیقا مطابق خروجی API یا فهرست مدل‌های درواره باشد.

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

آزمایش Chat Completions

پس از انتخاب مدل، یک درخواست آزمایشی ارسال کنید:

curl https://api.darvareh.ir/v1/chat/completions \
  -H "Authorization: Bearer YOUR_DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "یک تابع TypeScript برای اعتبارسنجی ایمیل بنویس."
      }
    ]
  }'

اگر پاسخ معتبر دریافت کردید، اتصال درواره آماده است. اگر همین درخواست خطا می‌دهد، ابتدا مشکل API Key، مدل یا کیف پول را رفع کنید و سپس سراغ تنظیم OpenCode بروید.

مرحله سوم: نصب OpenCode

روش نصب براساس سیستم‌عامل متفاوت است.

نصب OpenCode در Linux

ساده‌ترین روش، استفاده از اسکریپت رسمی نصب است:

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

پس از پایان نصب، نسخه OpenCode را بررسی کنید:

opencode --version

اگر فرمان opencode شناخته نشد، ترمینال را ببندید و دوباره باز کنید. همچنین مطمئن شوید مسیر نصب به متغیر PATH اضافه شده است.

نصب با NPM

اگر Node.js و NPM روی سیستم نصب است:

npm install -g opencode-ai

سپس:

opencode --version

نصب با Homebrew در Linux

brew install anomalyco/tap/opencode

مستندات OpenCode استفاده از Tap اختصاصی OpenCode را برای دریافت نسخه‌های به‌روزتر توصیه می‌کند.

نصب در Arch Linux

نسخه پایدار:

sudo pacman -S opencode

نسخه جدیدتر از AUR:

paru -S opencode-bin

نصب OpenCode در macOS

در macOS می‌توانید از اسکریپت رسمی استفاده کنید:

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

یا آن را با Homebrew نصب کنید:

brew install anomalyco/tap/opencode

روش NPM نیز قابل‌استفاده است:

npm install -g opencode-ai

پس از نصب:

opencode --version

نصب OpenCode در Windows

براساس مستندات رسمی، روش پیشنهادی OpenCode در ویندوز استفاده از WSL است؛ زیرا سازگاری بیشتر و عملکرد مناسب‌تری برای ابزارهای توسعه، Shell، Git و Agentها فراهم می‌کند.

روش پیشنهادی: نصب روی WSL

PowerShell را با دسترسی Administrator باز کرده و اجرا کنید:

wsl --install

پس از نصب، سیستم را Restart کنید. سپس Ubuntu یا توزیع نصب‌شده را باز کرده و OpenCode را داخل WSL نصب کنید:

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

بررسی نسخه:

opencode --version

بهتر است پروژه‌ای که با OpenCode روی آن کار می‌کنید داخل فایل‌سیستم Linux قرار داشته باشد:

~/projects/my-app

قرار دادن پروژه داخل /mnt/c/ ممکن است در بعضی پروژه‌های بزرگ، عملیات فایل و ابزارهای توسعه را کندتر کند.

نصب OpenCode با NPM در ویندوز

ابتدا Node.js را نصب کنید و سپس در PowerShell اجرا کنید:

npm install -g opencode-ai

بررسی نصب:

opencode --version

نصب با Chocolatey

choco install opencode

نصب با Scoop

scoop install opencode

دستورهای رسمی و روش‌های پشتیبانی‌شده نصب را می‌توانید در راهنمای نصب OpenCode بررسی کنید.

مرحله چهارم: اتصال API Key درواره به OpenCode

درواره یک API سازگار با OpenAI ارائه می‌دهد. بنابراین باید آن را در OpenCode به‌عنوان Custom Provider تعریف کنیم.

برای این کار دو بخش لازم است:

1. ذخیره Credential یا API Key
2. تعریف Provider، Base URL و مدل‌ها در opencode.json

توصیه می‌شود شناسه Provider را دقیقا darvareh انتخاب کنید.

روش اول: ذخیره API Key با دستور /connect

ابتدا وارد پوشه پروژه شوید:

cd /path/to/your/project

OpenCode را اجرا کنید:

opencode

در رابط OpenCode دستور زیر را وارد کنید:

/connect

در فهرست Providerها به انتهای لیست بروید و گزینه Other را انتخاب کنید.

برای Provider ID مقدار زیر را وارد کنید:

darvareh

سپس API Key درواره را Paste کنید.

بسیار مهم است که Provider ID واردشده در /connect دقیقا با کلید Provider در فایل opencode.json یکسان باشد:

"provider": {
  "darvareh": {}
}

OpenCode اطلاعات Credential را در مسیر زیر نگهداری می‌کند:

~/.local/share/opencode/auth.json

براساس راهنمای Custom Provider در OpenCode، برای سرویس‌های OpenAI-compatible باید از گزینه Other استفاده کرد، یک Provider ID اختصاصی ساخت و سپس همان شناسه را در فایل پیکربندی به کار برد.

روش دوم: اتصال از طریق CLI

بدون ورود به رابط تعاملی نیز می‌توانید سیستم مدیریت Credential را اجرا کنید:

opencode auth login

در فهرست ارائه‌دهندگان، گزینه مربوط به Custom Provider یا Other را انتخاب کنید، شناسه را darvareh بگذارید و API Key را وارد کنید.

برای مشاهده Credentialهای ثبت‌شده می‌توانید از فرمان‌های Auth نسخه نصب‌شده OpenCode استفاده کنید:

opencode auth

کلید API را مستقیما در خروجی ترمینال، Log یا فایل اشتراکی چاپ نکنید.

مرحله پنجم: ساخت فایل opencode.json

در ریشه پروژه، فایلی با نام زیر ایجاد کنید:

opencode.json

ساختار پروژه به این صورت خواهد بود:

my-project/
├── opencode.json
├── AGENTS.md
├── package.json
├── src/
└── ...

یک تنظیم پایه برای درواره:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "darvareh": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Darvareh",
      "options": {
        "baseURL": "https://api.darvareh.ir/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "Darvareh Coding Model"
        }
      }
    }
  },
  "model": "darvareh/YOUR_MODEL_ID"
}

مقدار YOUR_MODEL_ID را در هر دو محل با شناسه دقیق مدل جایگزین کنید.

برای مثال، اگر شناسه مدل در کاتالوگ درواره به‌صورت زیر باشد:

provider/model-name

پیکربندی به شکل زیر خواهد بود:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "darvareh": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Darvareh",
      "options": {
        "baseURL": "https://api.darvareh.ir/v1"
      },
      "models": {
        "provider/model-name": {
          "name": "Coding Model"
        }
      }
    }
  },
  "model": "darvareh/provider/model-name"
}

بخش اول مقدار model، شناسه Provider در OpenCode است:

darvareh

بخش بعدی، شناسه واقعی مدل در API درواره است:

provider/model-name

بنابراین اضافه شدن darvareh/ در تنظیم OpenCode به این معنا نیست که شناسه ارسالی به API نیز لزوما تغییر می‌کند. OpenCode از این ساختار برای تفکیک Provider و Model استفاده می‌کند.

توضیح اجزای تنظیمات درواره

گزینه npm

"npm": "@ai-sdk/openai-compatible"

این گزینه به OpenCode می‌گوید برای اتصال به Provider از Adapter سازگار با OpenAI استفاده کند.

طبق مستندات فعلی OpenCode:

• برای APIهای مبتنی بر /v1/chat/completions از @ai-sdk/openai-compatible استفاده می‌شود.
• برای Provider یا مدلی که مشخصا با /v1/responses کار می‌کند، ممکن است @ai-sdk/openai لازم باشد.

برای اتصال عمومی OpenCode به مسیر Chat Completions درواره، تنظیم زیر انتخاب مناسب است:

@ai-sdk/openai-compatible

گزینه name

"name": "Darvareh"

نامی است که در رابط OpenCode نمایش داده می‌شود و تأثیری بر درخواست API ندارد.

گزینه baseURL

"baseURL": "https://api.darvareh.ir/v1"

این مقدار باید دقیقا آدرس پایه API درواره باشد.

این مقادیر اشتباه هستند:

https://api.darvareh.ir
https://api.darvareh.ir/v1/chat/completions
https://darvareh.ir/v1

مقدار صحیح:

https://api.darvareh.ir/v1

Adapter مسیر /chat/completions را در زمان ارسال درخواست به Base URL اضافه می‌کند. بنابراین نباید آن را داخل baseURL بنویسید.

گزینه models

"models": {
  "YOUR_MODEL_ID": {
    "name": "Darvareh Coding Model"
  }
}

این بخش مدل‌هایی را مشخص می‌کند که در Model Picker نمایش داده می‌شوند. کلید هر مدل باید شناسه واقعی آن در درواره باشد، اما name می‌تواند یک عنوان خوانا و دلخواه باشد.

گزینه model

"model": "darvareh/YOUR_MODEL_ID"

این گزینه مدل پیش‌فرض OpenCode را تعیین می‌کند.

تعریف چند مدل درواره در OpenCode

می‌توانید چند مدل را هم‌زمان تعریف کنید:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "darvareh": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Darvareh",
      "options": {
        "baseURL": "https://api.darvareh.ir/v1"
      },
      "models": {
        "FIRST_MODEL_ID": {
          "name": "مدل اصلی برنامه‌نویسی"
        },
        "SECOND_MODEL_ID": {
          "name": "مدل استدلال پیشرفته"
        },
        "THIRD_MODEL_ID": {
          "name": "مدل سریع و اقتصادی"
        }
      }
    }
  },
  "model": "darvareh/FIRST_MODEL_ID",
  "small_model": "darvareh/THIRD_MODEL_ID"
}

مدل اصلی در این بخش تعیین می‌شود:

"model": "darvareh/FIRST_MODEL_ID"

مدل سبک‌تر:

"small_model": "darvareh/THIRD_MODEL_ID"

OpenCode می‌تواند از small_model برای بعضی وظایف سبک مانند تولید عنوان استفاده کند. این کار در صورت انتخاب مدل مناسب، هزینه را کاهش می‌دهد.

تعیین Context Window و حداکثر خروجی

برای Custom Provider، می‌توانید محدودیت Context و Output هر مدل را تعریف کنید:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "darvareh": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Darvareh",
      "options": {
        "baseURL": "https://api.darvareh.ir/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "Darvareh Coding Model",
          "limit": {
            "context": 128000,
            "output": 16384
          }
        }
      }
    }
  },
  "model": "darvareh/YOUR_MODEL_ID"
}

اعداد بالا صرفا نمونه هستند. مقادیر context و output را مطابق مشخصات واقعی مدل در درواره وارد کنید.

تعریف مقدار اشتباه و بزرگ‌تر از ظرفیت واقعی مدل، ظرفیت مدل را افزایش نمی‌دهد و ممکن است باعث ارسال درخواست نامعتبر یا مدیریت نادرست Context شود.

روش امن‌تر: استفاده از متغیر محیطی

اگر نمی‌خواهید Credential را از طریق /connect ذخیره کنید، می‌توانید API Key را در یک متغیر محیطی قرار دهید.

Linux، macOS و WSL

برای Session فعلی:

export DARVAREH_API_KEY="YOUR_DARVAREH_API_KEY"

سپس OpenCode را از همان ترمینال اجرا کنید:

opencode

تنظیم Provider:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "darvareh": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Darvareh",
      "options": {
        "baseURL": "https://api.darvareh.ir/v1",
        "apiKey": "{env:DARVAREH_API_KEY}"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "Darvareh Coding Model"
        }
      }
    }
  },
  "model": "darvareh/YOUR_MODEL_ID"
}

برای دائمی کردن متغیر، آن را براساس Shell خود در یکی از فایل‌های زیر قرار دهید:

~/.bashrc
~/.zshrc
~/.profile

سپس تنظیمات Shell را دوباره بارگذاری کنید:

source ~/.bashrc

PowerShell ویندوز

برای Session فعلی:

$env:DARVAREH_API_KEY = "YOUR_DARVAREH_API_KEY"

برای ثبت در حساب کاربری ویندوز:

[Environment]::SetEnvironmentVariable(
  "DARVAREH_API_KEY",
  "YOUR_DARVAREH_API_KEY",
  "User"
)

پس از اجرای فرمان دوم، یک پنجره جدید PowerShell باز کنید.

OpenCode از الگوی زیر برای خواندن متغیر محیطی در فایل Config پشتیبانی می‌کند:

"{env:DARVAREH_API_KEY}"

اگر متغیر تعریف نشده باشد، مقدار آن به رشته خالی تبدیل می‌شود و درخواست احتمالا با خطای Authentication مواجه خواهد شد. اطلاعات بیشتر در مستندات Config و Variables در OpenCode آمده است.

تنظیمات سراسری یا Project-specific

OpenCode می‌تواند تنظیمات را از چند محل دریافت کند.

تنظیم سراسری

برای استفاده از درواره در تمام پروژه‌ها:

~/.config/opencode/opencode.json

در ویندوز مبتنی بر WSL نیز این مسیر داخل Home لینوکس قرار می‌گیرد.

مزیت:

• فقط یک بار Provider را تعریف می‌کنید.
• تمام پروژه‌ها به مدل‌های درواره دسترسی دارند.
• نگهداری تنظیمات ساده‌تر است.

تنظیم مخصوص پروژه

فایل زیر را در ریشه پروژه قرار دهید:

./opencode.json

مزیت:

• مدل و مجوزها برای هر پروژه جدا می‌شوند.
• تیم می‌تواند تنظیمات مشترک داشته باشد.
• پروژه‌های حساس می‌توانند محدودیت سخت‌گیرانه‌تری اعمال کنند.

OpenCode فایل‌های Config را با یکدیگر Merge می‌کند. تنظیمات Project-specific می‌توانند گزینه‌های متعارض تنظیمات سراسری را Override کنند. ترتیب و مسیرهای پیکربندی در مستندات رسمی Config توضیح داده شده است.

پیشنهاد عملی

Provider، Base URL و مدل‌های عمومی را در Config سراسری قرار دهید:

~/.config/opencode/opencode.json

قواعد، مدل پیش‌فرض، Agentها و Permissionهای خاص هر پروژه را در خود پروژه نگهداری کنید.

API Key را وارد Git نکنید.

مرحله ششم: انتخاب مدل در OpenCode

پس از ساخت Config، OpenCode را اجرا کنید:

opencode

سپس دستور زیر را وارد کنید:

/models

باید Provider درواره و مدل‌هایی که در opencode.json تعریف کرده‌اید نمایش داده شوند.

مدل موردنظر را انتخاب کنید. اگر Provider یا مدل نمایش داده نشد، موارد زیر را بررسی کنید:

• Provider ID در /connect برابر darvareh باشد.
• کلید darvareh در Config دقیقا همین نام را داشته باشد.
• فایل opencode.json JSON معتبر باشد.
• نام پکیج @ai-sdk/openai-compatible درست نوشته شده باشد.
• بخش models خالی نباشد.
• شناسه مدل درست باشد.
• OpenCode پس از تغییر Config دوباره اجرا شده باشد.

همچنین می‌توانید هنگام اجرای OpenCode مدل را با Flag مشخص کنید:

opencode --model "darvareh/YOUR_MODEL_ID"

فرم کوتاه:

opencode -m "darvareh/YOUR_MODEL_ID"

براساس مستندات CLI اوپن‌کد، فرمت انتخاب مدل در خط فرمان provider/model است.

مرحله هفتم: ورود به پروژه و اجرای OpenCode

وارد پوشه پروژه شوید:

cd ~/projects/my-app

اگر پروژه Git ندارد، بهتر است ابتدا آن را راه‌اندازی کنید:

git init
git add .
git commit -m "Initial project state before OpenCode"

سپس OpenCode را اجرا کنید:

opencode

پیش از سپردن تغییرات مهم به Agent، داشتن Commit سالم بسیار مهم است. در این حالت می‌توانید تغییرات ایجادشده را با Git مقایسه و در صورت نیاز بازگردانی کنید.

مرحله هشتم: اجرای /init و ساخت AGENTS.md

در اولین اجرای OpenCode داخل پروژه، دستور زیر را وارد کنید:

/init

OpenCode ساختار پروژه را بررسی و فایلی با نام زیر ایجاد می‌کند:

AGENTS.md

این فایل Context دائمی پروژه را در اختیار Agent قرار می‌دهد. اطلاعاتی مانند معماری، دستورات، قواعد کدنویسی و محدودیت‌ها را می‌توان در آن ثبت کرد.

نمونه AGENTS.md:

# Project Guidelines

## Architecture

- Backend: Node.js and Fastify
- Frontend: React and TypeScript
- Database: PostgreSQL
- ORM: Prisma
- Tests: Vitest
- Package manager: pnpm

## Commands

- Install dependencies: `pnpm install`
- Run development: `pnpm dev`
- Run tests: `pnpm test`
- Run typecheck: `pnpm typecheck`
- Run lint: `pnpm lint`
- Build: `pnpm build`

## Coding Rules

- TypeScript strict mode must remain enabled.
- Do not use `any` unless explicitly justified.
- Reuse existing services before creating new abstractions.
- Validate all public API inputs.
- Never expose stack traces to API clients.
- Database schema changes require a migration.
- Add tests for every bug fix.

## Security

- Never read or print `.env` values.
- Never commit API keys or secrets.
- Do not execute destructive database commands.
- Do not modify production configuration without approval.

## Workflow

1. Inspect the relevant code before proposing changes.
2. Explain the root cause of bugs.
3. Create a short implementation plan.
4. Make the smallest safe change.
5. Run focused tests.
6. Run typecheck and lint.
7. Summarize modified files and remaining risks.

بهتر است AGENTS.md در Git ثبت شود:

git add AGENTS.md
git commit -m "Add OpenCode project instructions"

این فایل باعث می‌شود رفتار Agent میان اعضای تیم و Sessionهای مختلف سازگارتر باشد.

استفاده از OpenCode برای شناخت پروژه

برای شروع، از OpenCode بخواهید فقط پروژه را تحلیل کند و تغییری ایجاد نکند:

ساختار این پروژه را بررسی کن و توضیح بده:
1. نقطه ورود برنامه کجاست؟
2. احراز هویت چگونه کار می‌کند؟
3. دسترسی به پایگاه داده در کدام لایه انجام می‌شود؟
4. تست‌ها چگونه سازمان‌دهی شده‌اند؟
5. پنج ریسک فنی اصلی پروژه چیست؟

فعلا هیچ فایلی را تغییر نده.

برای اشاره مستقیم به یک فایل از @ استفاده کنید:

منطق احراز هویت در @src/server/auth.ts را بررسی کن و جریان کامل آن را توضیح بده.

کلید @ امکان جست‌وجوی فایل‌های پروژه را فراهم می‌کند.

استفاده از Plan Mode و Build Mode

OpenCode دارای حالت برنامه‌ریزی و اجرا است.

Plan Mode

در Plan Mode، Agent پروژه را بررسی می‌کند و برنامه پیاده‌سازی می‌سازد، اما نباید فایل‌ها را تغییر دهد.

با کلید Tab میان حالت‌ها جابه‌جا شوید.

برای Featureهای بزرگ ابتدا Plan بخواهید:

می‌خواهیم قابلیت بازیابی رمز عبور را اضافه کنیم.

قبل از هر تغییری:
- معماری احراز هویت را بررسی کن.
- فایل‌های درگیر را مشخص کن.
- تغییرات دیتابیس را توضیح بده.
- ریسک‌های امنیتی را بنویس.
- تست‌های لازم را تعیین کن.
- یک برنامه مرحله‌به‌مرحله ارائه بده.

فعلا کد را تغییر نده.

پس از بررسی و اصلاح Plan، به Build Mode برگردید:

برنامه تأیید است. مراحل را اجرا کن، تست‌ها را بنویس و در پایان typecheck و تست‌های مرتبط را اجرا کن.

این روش احتمال تغییرات غیرضروری و برداشت اشتباه Agent را کاهش می‌دهد.

نمونه Prompt مناسب برای رفع باگ

Prompt ضعیف:

این باگ را درست کن.

Prompt حرفه‌ای‌تر:

پس از منقضی شدن Access Token، درخواست‌های هم‌زمان باعث می‌شوند
Refresh Token چند بار استفاده شود و بعضی درخواست‌ها با 401 شکست بخورند.

وظیفه:
1. جریان Refresh Token را در Backend و Frontend بررسی کن.
2. ابتدا مشکل را بازتولید یا علت آن را با شواهد مشخص کن.
3. راه‌حل پیشنهادی را قبل از تغییر کد توضیح بده.
4. کوچک‌ترین تغییر امن را اعمال کن.
5. برای درخواست‌های هم‌زمان تست اضافه کن.
6. تست‌های مرتبط و typecheck را اجرا کن.
7. هیچ API عمومی را بدون ضرورت تغییر نده.
8. در پایان، فایل‌های تغییرکرده و ریسک‌های باقی‌مانده را گزارش کن.

هرچه هدف، محدودیت و معیار پذیرش روشن‌تر باشد، نتیجه OpenCode قابل‌اعتمادتر خواهد بود.

نمونه Prompt برای ساخت Feature

یک Endpoint برای دریافت تاریخچه ورودهای کاربر اضافه کن.

الزامات:
- Route: GET /api/account/login-history
- فقط کاربر احراز هویت‌شده به داده‌های خودش دسترسی داشته باشد.
- Pagination با cursor پیاده‌سازی شود.
- حداکثر page size برابر 100 باشد.
- IP در خروجی Mask شود.
- Response با Zod اعتبارسنجی شود.
- ساختارهای موجود پروژه را دنبال کن.
- تست دسترسی غیرمجاز، Pagination و مالکیت داده اضافه کن.
- Migration را فقط در صورت نیاز ایجاد کن.
- در پایان lint، typecheck و تست‌های مرتبط را اجرا کن.

ابتدا پروژه را بررسی و Plan ارائه کن. تا قبل از تأیید، فایل‌ها را تغییر نده.

اجرای غیرتعاملی OpenCode

برای اجرای یک درخواست مستقیم از CLI:

opencode run "ساختار پروژه را تحلیل کن و نقاط ورود اصلی را توضیح بده."

انتخاب مدل مشخص:

opencode run \
  --model "darvareh/YOUR_MODEL_ID" \
  "تغییرات فعلی Git را بررسی و مشکلات احتمالی را گزارش کن."

این قابلیت برای Automation، بررسی‌های CI یا اسکریپت‌های توسعه مفید است. اما در محیط CI باید Permissionها، Secrets و محدوده عملیات را بسیار دقیق کنترل کنید.

ادامه Session قبلی

برای ادامه آخرین Session:

opencode --continue

فرم کوتاه:

opencode -c

OpenCode می‌تواند Session مشخصی را نیز ادامه دهد؛ اما پیش از ادامه یک Session قدیمی مطمئن شوید وضعیت فایل‌های پروژه، Branch و وابستگی‌ها با Context آن Session ناسازگار نشده باشد.

بازگردانی و تکرار تغییرات

اگر تغییر OpenCode مناسب نبود، در رابط تعاملی از دستور زیر استفاده کنید:

/undo

برای بازگرداندن عملی که Undo شده است:

/redo

امکان استفاده چندباره از /undo وجود دارد. بااین‌حال، Git همچنان باید مرجع اصلی کنترل نسخه باشد.

قبل از قبول نتیجه Agent موارد زیر را بررسی کنید:

git status
git diff

سپس تست‌های پروژه را شخصا اجرا کنید.

تنظیم Permissionها در OpenCode

یک Agent برنامه‌نویسی ممکن است بتواند فایل بخواند، کد تغییر دهد و فرمان Shell اجرا کند. دادن دسترسی نامحدود می‌تواند خطرناک باشد.

Permissionهای مناسب باید براساس پروژه تعریف شوند:

• خواندن فایل‌های سورس: معمولا مجاز
• ویرایش فایل‌ها: با کنترل
• اجرای تست و Lint: مجاز
• نصب Package: نیازمند بررسی
• دستورات Git مخرب: ممنوع
• دسترسی به .env: ممنوع
• اتصال شبکه: محدود
• اجرای Deployment: نیازمند تأیید
• اجرای Migration روی Production: ممنوع
• حذف فایل یا داده: نیازمند تأیید

از اجرای OpenCode با دسترسی Administrator یا Root خودداری کنید، مگر اینکه دلیل فنی مشخصی وجود داشته باشد.

Flag زیر Permissionهایی را که صراحتا Deny نشده‌اند به‌صورت خودکار تأیید می‌کند:

opencode --auto

استفاده از آن برای پروژه‌های حساس، محیط Production یا مخزن‌هایی که Secrets دارند توصیه نمی‌شود. Auto-approve سرعت را افزایش می‌دهد، اما مرحله بازبینی انسانی را حذف می‌کند.

ساخت Agent اختصاصی

OpenCode امکان ساخت Agent با Prompt، مدل و Permission اختصاصی را فراهم می‌کند:

opencode agent create

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

مشاهده Agentها:

opencode agent list

نمونه کاربردها:

• Agent بررسی امنیت
• Agent رفع باگ
• Agent تولید تست
• Agent مستندسازی
• Agent بررسی Migration
• Agent تحلیل Performance

برای Agent حساس، اصل Least Privilege را رعایت کنید؛ یعنی فقط ابزارهایی را فعال کنید که واقعا برای وظیفه لازم‌اند.

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

یک مدل مناسب OpenCode باید در چند حوزه عملکرد خوبی داشته باشد:

• درک پروژه‌های بزرگ
• تولید کد صحیح
• استدلال چندمرحله‌ای
• پیروی از دستورالعمل
• استفاده از Tool Calling
• اصلاح کد براساس خطای ابزار
• تولید خروجی ساختاریافته
• حفظ Context طولانی
• کار با زبان‌ها و فریم‌ورک‌های پروژه

قوی‌ترین مدل همیشه بهترین انتخاب اقتصادی نیست.

بهتر است چند مدل در opencode.json تعریف و آن‌ها را با وظایف واقعی پروژه مقایسه کنید.

معیارهای مقایسه:

• درصد موفقیت در Build
• تعداد خطاهای TypeScript
• تعداد دورهای اصلاح
• زمان پاسخ
• تعداد Tool Call
• میزان تغییرات غیرضروری
• مصرف توکن
• هزینه نهایی
• توانایی رعایت AGENTS.md

تنظیم Timeout برای درخواست‌های طولانی

بعضی عملیات برنامه‌نویسی یا مدل‌های استدلالی به زمان بیشتری نیاز دارند. می‌توانید Timeout را در Provider تنظیم کنید:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "darvareh": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Darvareh",
      "options": {
        "baseURL": "https://api.darvareh.ir/v1",
        "timeout": 600000
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "Darvareh Coding Model"
        }
      }
    }
  },
  "model": "darvareh/YOUR_MODEL_ID"
}

در این مثال Timeout برابر ۶۰۰ هزار میلی‌ثانیه یا ۱۰ دقیقه است. مقدار بسیار بالا ممکن است تشخیص اتصال معیوب را به تأخیر بیندازد؛ بنابراین آن را فقط براساس رفتار واقعی مدل تنظیم کنید.

فایل Config پیشنهادی کامل

نمونه زیر یک نقطه شروع مناسب است:

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": true,
  "provider": {
    "darvareh": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Darvareh",
      "options": {
        "baseURL": "https://api.darvareh.ir/v1",
        "apiKey": "{env:DARVAREH_API_KEY}",
        "timeout": 600000
      },
      "models": {
        "MAIN_MODEL_ID": {
          "name": "Darvareh Main Coding Model",
          "limit": {
            "context": 128000,
            "output": 16384
          }
        },
        "FAST_MODEL_ID": {
          "name": "Darvareh Fast Model",
          "limit": {
            "context": 64000,
            "output": 8192
          }
        }
      }
    }
  },
  "model": "darvareh/MAIN_MODEL_ID",
  "small_model": "darvareh/FAST_MODEL_ID"
}

مقادیر زیر را براساس کاتالوگ واقعی درواره تغییر دهید:

MAIN_MODEL_ID
FAST_MODEL_ID
context
output

اگر API Key را قبلا با /connect ثبت کرده‌اید، نیازی نیست apiKey را در Config قرار دهید:

"options": {
  "baseURL": "https://api.darvareh.ir/v1",
  "timeout": 600000
}

تست نهایی اتصال OpenCode به درواره

پس از انجام تنظیمات:

opencode

دستور /models را اجرا و مدل درواره را انتخاب کنید:

/models

سپس یک درخواست فقط‌خواندنی ارسال کنید:

بدون تغییر هیچ فایلی، زبان‌ها و فریم‌ورک‌های این پروژه را شناسایی کن.
سپس دستورات احتمالی نصب، توسعه، Build و Test را گزارش بده.

اگر پاسخ دریافت شد، یک تست Tool Calling انجام دهید:

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

در مرحله بعد اجازه اجرای یک فرمان کم‌خطر بدهید:

دستور typecheck موجود در package.json را اجرا کن و خطاها را خلاصه کن.
هیچ فایلی را تغییر نده.

در نهایت یک تغییر کوچک و قابل‌بازگشت آزمایش کنید:

یک خطای ساده مستندات را در README اصلاح کن.
قبل از تغییر، Diff پیشنهادی را توضیح بده.

پس از تغییر:

git diff

در داشبورد درواره نیز بخش مصرف API را بررسی کنید تا مطمئن شوید درخواست‌ها با API Key موردنظر ثبت و هزینه از کیف پول کسر شده است.

خطای Provider در /models نمایش داده نمی‌شود

دلایل احتمالی:

• فایل Config در مسیر اشتباه قرار دارد.
• JSON دارای خطای Syntax است.
• Provider IDها یکسان نیستند.
• مدل در بخش models تعریف نشده است.
• OpenCode پس از تغییر Config Restart نشده است.
• نام provider یا models اشتباه نوشته شده است.

تنظیم حداقلی را آزمایش کنید:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "darvareh": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Darvareh",
      "options": {
        "baseURL": "https://api.darvareh.ir/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "Test Model"
        }
      }
    }
  }
}

سپس /models را دوباره اجرا کنید.

خطای 401 Unauthorized

خطای 401 معمولا به Authentication مربوط است.

بررسی کنید:

• API Key کامل کپی شده باشد.
• ابتدا یا انتهای کلید فاصله وجود نداشته باشد.
• کلید حذف، غیرفعال یا Suspend نشده باشد.
• Provider ID ذخیره‌شده با Config یکسان باشد.
• متغیر DARVAREH_API_KEY در همان محیطی تعریف شده باشد که OpenCode اجرا می‌شود.
• در WSL، متغیر محیطی Windows به‌صورت خودکار همان متغیر Linux نیست.
• مقدار apiKey به رشته خالی تبدیل نشده باشد.

بررسی وجود متغیر بدون نمایش کلید:

if [ -n "$DARVAREH_API_KEY" ]; then
  echo "DARVAREH_API_KEY is set"
else
  echo "DARVAREH_API_KEY is missing"
fi

کلید را با echo کامل چاپ نکنید، مخصوصا هنگام Screen Sharing یا ضبط ترمینال.

خطای 402 یا Insufficient Funds

این خطا معمولا نشان می‌دهد موجودی کیف پول برای اجرای درخواست کافی نیست یا کلید به‌دلیل موجودی غیرفعال شده است.

راهکار:

1. وارد داشبورد درواره شوید.
2. موجودی کیف پول را بررسی کنید.
3. کیف پول را شارژ کنید.
4. وضعیت API Key را بررسی کنید.
5. درخواست را دوباره ارسال کنید.

مدل‌های دارای Context بزرگ یا خروجی طولانی می‌توانند هزینه بیشتری داشته باشند. برای کنترل مصرف، Context غیرضروری را وارد Agent نکنید و مدل را متناسب با وظیفه انتخاب کنید.

خطای 404 یا Not Found

دلایل متداول:

• Base URL اشتباه است.
• مسیر /v1 حذف شده است.
• مسیر کامل Chat Completions داخل baseURL قرار گرفته است.
• Adapter نامناسب انتخاب شده است.

مقدار صحیح:

"baseURL": "https://api.darvareh.ir/v1"

برای Chat Completions:

"npm": "@ai-sdk/openai-compatible"

خطای Model Not Found

علت اصلی، وارد کردن شناسه اشتباه مدل است.

فهرست مدل‌ها را دوباره دریافت کنید:

curl https://api.darvareh.ir/v1/models \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

سپس مقدار دقیق id را در بخش models قرار دهید.

این دو مقدار باید با یکدیگر هماهنگ باشند:

"models": {
  "EXACT_MODEL_ID": {}
}

"model": "darvareh/EXACT_MODEL_ID"

خطای 429 Too Many Requests

این خطا نشان‌دهنده عبور از Rate Limit یا محدودیت مصرف است.

راهکارها:

• چند ثانیه صبر کرده و دوباره تلاش کنید.
• اجرای هم‌زمان Agentها را کاهش دهید.
• Rate Limit کلید درواره را بررسی کنید.
• تعداد درخواست‌های موازی را کم کنید.
• حلقه‌های Tool Calling غیرضروری را متوقف کنید.
• برای هر Agent یک API Key با محدودیت مناسب بسازید.
• Retry را با Exponential Backoff انجام دهید.

Retry فوری و بدون فاصله می‌تواند وضعیت را بدتر کند.

OpenCode پاسخ می‌دهد اما فایل‌ها را تغییر نمی‌دهد

موارد زیر را بررسی کنید:

• OpenCode در Plan Mode نباشد.
• Agent انتخاب‌شده مجوز Edit داشته باشد.
• پروژه یا فایل Read-only نباشد.
• Permission و Policy پروژه عملیات ویرایش را Deny نکرده باشد.
• درخواست شما صراحتا اجازه پیاده‌سازی داده باشد.

برای انتقال از Plan به Build Mode از Tab استفاده کنید.

مدل متن تولید می‌کند اما Tool Calling درست کار نمی‌کند

همه مدل‌ها برای Agentic Coding و Tool Calling مناسب نیستند.

نشانه‌های ناسازگاری:

• مدل به‌جای فراخوانی ابزار، نحوه اجرای آن را توضیح می‌دهد.
• آرگومان Tool ناقص یا JSON نامعتبر است.
• یک ابزار چند بار بدون دلیل اجرا می‌شود.
• مدل نتیجه ابزار را نادیده می‌گیرد.
• درخواست‌های ساده وارد حلقه می‌شوند.
• فایل‌های خیالی گزارش می‌شوند.

راهکار:

• مدل سازگارتر با Tool Calling انتخاب کنید.
• مدل دیگری از کاتالوگ درواره آزمایش کنید.
• Prompt و AGENTS.md را دقیق‌تر کنید.
• تعداد ابزارهای فعال را کاهش دهید.
• Context بسیار بزرگ را کوچک‌تر کنید.
• برای وظایف پیچیده مدل استدلالی قوی‌تری انتخاب کنید.

OpenCode در Windows فایل‌ها را کند بررسی می‌کند

اگر پروژه در WSL اجرا می‌شود اما فایل‌ها در درایو Windows قرار دارند، ممکن است عملیات فایل کند شود.

به‌جای:

/mnt/c/Users/Name/project

پروژه را داخل Home توزیع Linux نگهداری کنید:

~/projects/project

سپس پروژه را از طریق قابلیت Remote WSL در IDE باز کنید.

خطای Certificate، DNS یا Network

اتصال را مستقل از OpenCode بررسی کنید:

curl -I https://api.darvareh.ir

سپس Endpoint مدل‌ها را آزمایش کنید:

curl https://api.darvareh.ir/v1/models \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

اگر curl نیز شکست می‌خورد، مشکل احتمالا در DNS، Proxy، Firewall، گواهی سیستم یا اتصال شبکه است، نه Config داخلی OpenCode.

اگر فقط OpenCode مشکل دارد، Proxyهای محیطی، نسخه OpenCode و تنظیم baseURL را بررسی کنید.

افزایش امنیت استفاده از OpenCode

OpenCode در صورت دریافت مجوز می‌تواند عملیات واقعی روی پروژه انجام دهد. بنابراین باید مانند یک ابزار توسعه قدرتمند با آن برخورد کنید.

API Key را وارد Git نکنید

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

"apiKey": "sk-real-secret-key"

روش مناسب:

"apiKey": "{env:DARVAREH_API_KEY}"

یا استفاده از /connect.

در .gitignore موارد حساس را اضافه کنید:

.env
.env.*
!.env.example

برای OpenCode یک API Key جدا بسازید

به‌جای استفاده از کلید مشترک تمام سرویس‌ها، یک کلید اختصاصی ایجاد کنید:

OpenCode - Amir Laptop

مزایا:

• مصرف OpenCode جداگانه قابل‌اندازه‌گیری است.
• در صورت افشا فقط همان کلید لغو می‌شود.
• می‌توان بودجه و Rate Limit اختصاصی تعیین کرد.
• تشخیص رفتار غیرعادی ساده‌تر است.

از دسترسی Root استفاده نکنید

OpenCode را با کاربر عادی اجرا کنید. اجرای Agent با Root دامنه خسارت یک فرمان اشتباه را افزایش می‌دهد.

فایل‌های حساس را از دسترس Agent دور نگه دارید

نمونه فایل‌های حساس:

.env
id_rsa
*.pem
production-secrets.json
database-backup.sql
terraform.tfstate

صرف نوشتن یک دستور در Prompt که «Secrets را نخوان» کافی نیست. Permission فایل و محیط اجرا نیز باید محدود باشد.

تغییرات را قبل از Commit بازبینی کنید

همیشه اجرا کنید:

git status
git diff

سپس:

npm test
npm run lint
npm run typecheck

دستورهای واقعی پروژه ممکن است متفاوت باشند.

اجرای Production را به Agent نسپارید

بدون تأیید انسانی اجازه اجرای این موارد را ندهید:

database migration
deployment
kubectl apply
terraform apply
package publish
git push
git force push
secret rotation
production restart

کاهش هزینه استفاده از OpenCode با درواره

Agentهای برنامه‌نویسی معمولا چندین درخواست متوالی به مدل ارسال می‌کنند. هر Tool Call، نتیجه ابزار و ادامه استدلال می‌تواند Context را بزرگ‌تر کند.

برای کنترل هزینه:

• برای هر وظیفه Session جداگانه بسازید.
• Context نامرتبط را وارد مکالمه نکنید.
• از مدل اقتصادی برای پرسش‌های ساده استفاده کنید.
• مدل قوی را برای باگ‌ها و Refactorهای پیچیده نگه دارید.
• ابتدا محدوده فایل‌ها را مشخص کنید.
• از Agent نخواهید بدون هدف کل Repository را بخواند.
• خروجی دستورات بسیار بزرگ را محدود کنید.
• Logهای طولانی را خلاصه یا فیلتر کنید.
• برای OpenCode یک API Key با بودجه مشخص بسازید.
• small_model را برای عملیات سبک تنظیم کنید.
• قبل از اجرای دوباره، علت شکست قبلی را بررسی کنید.
• Sessionهای بسیار طولانی را پس از خلاصه‌سازی به Session جدید منتقل کنید.

Prompt زیر می‌تواند مصرف غیرضروری را کاهش دهد:

فقط فایل‌های مرتبط با این خطا را بررسی کن.
قبل از خواندن فایل‌های بیشتر، دلیل نیاز به آن‌ها را مشخص کن.
خروجی دستورات را به بخش مرتبط محدود کن و از بررسی کل مخزن خودداری کن.

Workflow پیشنهادی حرفه‌ای برای OpenCode

برای کارهای روزمره از این فرایند استفاده کنید.

۱. وضعیت Git را پاک نگه دارید

git status

تغییرات فعلی را Commit یا Stash کنید.

۲. پروژه را با OpenCode باز کنید

opencode

۳. مدل مناسب را انتخاب کنید

/models

۴. برای کار پیچیده وارد Plan Mode شوید

کلید Tab را فشار دهید و مسئله، محدودیت‌ها و معیار پذیرش را توضیح دهید.

۵. Plan را بررسی کنید

مطمئن شوید Agent:

• فایل‌های درست را پیدا کرده است.
• معماری پروژه را رعایت می‌کند.
• تغییرات غیرضروری پیشنهاد نمی‌دهد.
• ریسک‌های امنیتی را می‌بیند.
• تست مناسب تعریف کرده است.

۶. اجازه پیاده‌سازی بدهید

به Build Mode برگردید و اجرای Plan را تأیید کنید.

۷. نتیجه ابزارها را بررسی کنید

خطاهای Test، Lint و Typecheck را نادیده نگیرید.

۸. Diff را شخصا بازبینی کنید

git diff --stat
git diff

۹. تست نهایی را اجرا کنید

حتی اگر Agent می‌گوید تست‌ها موفق بوده‌اند، فرمان‌های مهم را در محیط خود اجرا کنید.

۱۰. تغییرات را Commit کنید

git add .
git commit -m "Implement requested feature"

آیا می‌توان OpenCode را جایگزین برنامه‌نویس کرد؟

OpenCode می‌تواند سرعت تحلیل، تولید کد، تست‌نویسی و رفع خطا را افزایش دهد، اما نباید خروجی آن بدون بازبینی وارد Production شود.

مدل ممکن است:

• API غیرواقعی استفاده کند.
• رفتار یک کتابخانه را اشتباه برداشت کند.
• تست ناقص بنویسد.
• Edge Case را نادیده بگیرد.
• آسیب‌پذیری امنیتی ایجاد کند.
• تغییر غیرضروری انجام دهد.
• خروجی موفق ابزار را نادرست تفسیر کند.
• با اطمینان، توضیح اشتباه ارائه دهد.

بهترین استفاده از OpenCode، همکاری میان Agent و توسعه‌دهنده است:

انسان: هدف، معماری، محدودیت و تصمیم نهایی
OpenCode: تحلیل، جست‌وجو، اجرا، تولید و اصلاح
ابزارها: تست، Lint، Build و اعتبارسنجی
Git: ثبت و کنترل تغییرات
درواره: دسترسی API به مدل‌های هوش مصنوعی

جمع‌بندی

OpenCode یک AI Coding Agent متن‌باز و قدرتمند است که می‌تواند مستقیما داخل ترمینال و پروژه نرم‌افزاری کار کند. با اتصال آن به API درواره، توسعه‌دهندگان ایرانی می‌توانند از طریق یک رابط سازگار با OpenAI به مدل‌های مختلف برنامه‌نویسی و استدلال دسترسی داشته باشند.

مراحل اصلی اتصال عبارت‌اند از:

1. ثبت‌نام و شارژ کیف پول درواره
2. ساخت API Key اختصاصی
3. نصب OpenCode
4. اجرای /connect
5. انتخاب Other
6. تعریف Provider ID با مقدار darvareh
7. ساخت opencode.json
8. تنظیم Base URL روی https://api.darvareh.ir/v1
9. استفاده از @ai-sdk/openai-compatible
10. تعریف شناسه مدل‌های درواره
11. انتخاب مدل با /models
12. اجرای /init و تکمیل AGENTS.md
13. آزمایش تحلیل، Tool Calling و ویرایش فایل
14. کنترل مصرف، Permissionها و تغییرات Git

برای شروع، در درواره حساب کاربری ایجاد کنید، یک API Key اختصاصی بسازید و با Config ارائه‌شده در این راهنما، OpenCode را به مدل موردنظر خود متصل کنید.

سوالات متداول

OpenCode چیست؟

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

آیا OpenCode در ویندوز نصب می‌شود؟

بله. می‌توان آن را با NPM، Chocolatey یا Scoop نصب کرد. بااین‌حال، مستندات رسمی OpenCode استفاده از WSL را برای تجربه بهتر در ویندوز پیشنهاد می‌کنند.

Base URL درواره در OpenCode چیست؟

آدرس صحیح:

https://api.darvareh.ir/v1

آیا باید /chat/completions را به Base URL اضافه کنیم؟

خیر. Base URL فقط باید تا /v1 باشد. Adapter مربوط به OpenAI-compatible مسیر Chat Completions را اضافه می‌کند.

برای اتصال درواره از چه پکیجی استفاده کنیم؟

برای مدل‌هایی که از مسیر /v1/chat/completions استفاده می‌کنند:

@ai-sdk/openai-compatible

Provider ID درواره چه باشد؟

پیشنهاد می‌شود از مقدار زیر استفاده کنید:

darvareh

این مقدار باید در /connect و opencode.json کاملا یکسان باشد.

API Key را کجا وارد کنیم؟

می‌توانید آن را با /connect در Credential Store اوپن‌کد ذخیره کنید یا از متغیر محیطی و عبارت زیر استفاده کنید:

"apiKey": "{env:DARVAREH_API_KEY}"

چگونه مدل درواره را در OpenCode انتخاب کنیم؟

مدل را در بخش models فایل opencode.json تعریف کرده و سپس دستور زیر را اجرا کنید:

/models

چگونه شناسه دقیق مدل را پیدا کنیم؟

از فهرست مدل‌های درواره یا Endpoint زیر استفاده کنید:

GET https://api.darvareh.ir/v1/models

آیا OpenCode می‌تواند فایل‌های پروژه را تغییر دهد؟

بله، اگر Agent و Permissionهای فعال اجازه ویرایش داشته باشند و OpenCode در Build Mode باشد.

تفاوت Plan Mode و Build Mode چیست؟

در Plan Mode، Agent پروژه را بررسی و برنامه ارائه می‌کند. در Build Mode می‌تواند با دریافت مجوز فایل‌ها را تغییر دهد و ابزارها را اجرا کند.

فایل AGENTS.md چیست؟

فایلی برای ثبت معماری، دستورات، قواعد کدنویسی، محدودیت‌های امنیتی و Workflow پروژه است. OpenCode با دستور /init می‌تواند نسخه اولیه آن را ایجاد کند.

آیا باید opencode.json را وارد Git کنیم؟

اگر فایل شامل تنظیمات عمومی و بدون Secret است، می‌توان آن را Commit کرد. API Key واقعی نباید داخل آن قرار بگیرد. برای کلید از Environment Variable یا Credential Store استفاده کنید.

علت خطای 401 چیست؟

معمولا API Key اشتباه، غیرفعال یا در محیط فعلی تعریف نشده است. ناهماهنگی Provider ID میان /connect و Config نیز می‌تواند باعث مشکل احراز هویت شود.

علت خطای Model Not Found چیست؟

شناسه مدل در opencode.json با شناسه واقعی مدل در API درواره مطابقت ندارد. مقدار دقیق id را از Endpoint مدل‌ها دریافت کنید.

آیا تمام مدل‌ها برای OpenCode مناسب‌اند؟

خیر. برای تجربه مناسب باید مدلی انتخاب شود که در تولید کد، پیروی از دستورالعمل و Tool Calling عملکرد قابل‌قبولی داشته باشد.

مقالات مرتبط

• AI Agent و Agent Skills چیست؟ راهنمای کامل ساخت عامل هوش مصنوعی
• بهترین مدل‌های هوش مصنوعی برای برنامه‌نویسی کدام‌اند؟
• آموزش اتصال Roo Code به API درواره
• آموزش اتصال Cline به API درواره
• آموزش اتصال OpenClaw به API درواره
• آموزش اتصال Cursor به مدل‌های هوش مصنوعی
• آموزش استفاده از Claude Code با APIهای سفارشی
• آموزش اتصال Cherry Studio به API درواره
• آموزش اتصال Chatbox، Jan و LobeChat به API درواره
• Function Calling چیست؟ آموزش اتصال مدل هوش مصنوعی به ابزارها
• راهنمای کامل OpenAI-compatible API
• API هوش مصنوعی چیست و چگونه از آن استفاده کنیم؟
• محاسبه و کاهش هزینه API هوش مصنوعی