نصب OpenCode و پیکربندی OmniProxy

OpenCode یک دستیار کدنویسی متن‌باز است که به شما امکان می‌دهد از ترمینال، IDE یا دسکتاپ کد بنویسید. این برنامه کد یا زمینه (context) شما را ذخیره نمی‌کند، که آن را برای پروژه‌های حساس به حریم خصوصی مناسب می‌سازد. build برای اصلاح پروژه استفاده می‌شود، در حالی که plan به‌طور پیش‌فرض فقط خواندنی است و برای درک کدهای ناآشنا و برنامه‌ریزی تغییرات قبل از اعمال آن‌ها مفید است. می‌توانید سرویس مدل را بر اساس نیازهای خود انتخاب کنید.

قبل از شروع

اسکریپت نصب ساده‌ترین گزینه است. شما به یک ترمینال مدرن نیاز دارید—یک برنامه ترمینال که بتواند دستورات را اجرا کرده و با فایل‌های پروژه کار کند—مانند WezTerm، Alacritty، Ghostty یا Kitty. در ویندوز، WSL ترجیح داده می‌شود. این محیط لینوکس را در ویندوز با عملکرد و قابلیت‌های کامل‌تر فراهم می‌کند.

ساده‌ترین

اسکریپت نصب

• curl opencode.ai/install
• استفاده مستقیم در macOS و لینوکس
• WSL در ویندوز توصیه می‌شود

macOS لینوکس

Homebrew tap

• anomalyco/tap/opencode
• بیشتر از فرمول به‌روزرسانی می‌شود
• بسته‌ای برای Arch نیز موجود است

ویندوز بومی

مدیریت بسته

• choco یا scoop
• یا نصب جهانی با npm
• همچنین می‌توانید آن را از Releases دانلود کنید

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

نصب و اجرای اولیه

ساده‌ترین دستور نصب این است:

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

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

• Node.js: npm install -g opencode-ai. Bun، pnpm و Yarn نیز دستورات نصب جهانی مربوطه را دارند؛ به صفحه معرفی در انتهای این راهنما مراجعه کنید.
• Homebrew در macOS و لینوکس: brew install anomalyco/tap/opencode. از این tap استفاده کنید زیرا بیشتر از brew install opencodeکه توسط تیم Homebrew نگهداری می‌شود، به‌روزرسانی می‌شود.
• Arch Linux: استفاده کنید sudo pacman -S opencode برای نسخه پایدار، یا بسته AUR opencode-bin برای نسخه جدیدتر.
• ویندوز: استفاده کنید choco install opencode یا scoop install opencode. همچنین می‌توانید از npm install -g opencode-aiاستفاده کنید. فایل‌های باینری را نیز می‌توان از Releases دانلود کرد. پشتیبانی از نصب با Bun در ویندوز هنوز در حال انجام است.

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

cd /path/to/project
opencode

هنگام استفاده برای اولین بار، می‌توانید اجرا کنید /init. این دستور پروژه را تحلیل کرده و AGENTS.md را در ریشه پروژه ایجاد می‌کند. این فایل را می‌توان در Git کامیت کرد تا پروژه این دستورالعمل‌ها را حفظ کند.

دریافت مقادیر اتصال از OmniProxy

baseURL: https://your-omniproxy-origin.example/v1
API Key: <YOUR_OMNIPROXY_API_KEY>
Model ID: Copy from the current OmniProxy model list

baseURL آدرس سرویس است، API Key اعتبار دسترسی است و Model ID نام کامل مدل است.

هنگام استفاده از /v1/chat/completions، بسته npm را روی @ai-sdk/openai-compatibleتنظیم کنید. Chat Completions نوعی رابط درخواست چت است. فقط زمانی به @ai-sdk/openai سوئیچ کنید که مدل از /v1/responsesاستفاده می‌کند. هنگامی که OmniProxy از طریق نقطه پایانی chat completions استفاده می‌شود، بسته سازگاری را حفظ کنید.

کل شناسه مدل را از لیست فعلی OmniProxy کپی کنید، شامل هرگونه اسلش. در تاریخ 2026-10-09، دو شناسه مرجع عبارت بودند از claude-sonnet-5-5 و gpt-6-luna. gpt-6-luna از Chat Completions پشتیبانی می‌کند؛ فراخوانی تابع از طریق Chat Completions تنها زمانی پشتیبانی می‌شود که reasoning_effort برابر با noneباشد. شناسه‌ای که در لیست نیست را کپی نکنید.

وارد کردن پیکربندی ابزار

یک ارائه‌دهنده (Provider) را می‌توان مجموعه‌ای از مقادیر پیکربندی دانست که OpenCode برای اتصال به سرویس مدل استفاده می‌کند. مستندات ارائه‌دهنده، سرویس سازگار با OpenAI که تحت /connect لیست نشده است را به عنوان یک ارائه‌دهنده سفارشی در نظر می‌گیرد. یک سرویس سازگار با OpenAI از همان فرمت درخواست استفاده می‌کند و می‌تواند توسط همان نوع کلاینت فراخوانی شود.

1. اجرا کنید /connect در OpenCode و به Other بروید.
2. یک شناسه ارائه‌دهنده وارد کنید. مثال زیر از omniproxyاستفاده می‌کند. شناسه‌ای را انتخاب کنید که به خاطر سپردن آن آسان باشد زیرا باید از همان شناسه در فایل پیکربندی استفاده کنید.
3. کلید API OmniProxy را وارد کنید. این مرحله فقط اعتبارنامه را ذخیره می‌کند؛ آدرس و مدل‌ها همچنان باید به opencode.jsonاضافه شوند. اعتبارنامه در ~/.local/share/opencode/auth.jsonذخیره می‌شود.
4. ایجاد یا اصلاح کنید opencode.json در دایرکتوری پروژه:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniproxy": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniProxy",
      "options": {
        "baseURL": "https://your-omniproxy-origin.example/v1"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" },
        "gpt-6-luna": { "name": "GPT-6 Luna" }
      }
    }
  }
}

5. اجرا کنید /models. ارائه‌دهنده سفارشی و مدل‌های آن در لیست ظاهر می‌شوند.

شناسه وارد شده تحت /connect باید با کلید در opencode.jsonمطابقت داشته باشد. کلید مخفی واقعی را در این فایل قرار ندهید. اگر از /connectاستفاده نمی‌کنید، می‌توانید از نحو متغیر محیطی در options.apiKeyاستفاده کنید، مانند {env:VARIABLE_NAME}. در آزمایش مورخ 2026-10-09 با OpenCode 1.18.34، قرار دادن کلید مستقیماً در options.apiKey پروژه بدون استفاده از /connect نیز با موفقیت متصل شد. اگر درگاه کلید را اعتبارسنجی نکند، این مقدار می‌تواند یک رشته جای‌نگهدار باشد که فقط روی دستگاه محلی استفاده می‌شود. کلیدهای تحت models باید از شناسه‌های کامل لیست استفاده کنند.

کلید

/connect

• انتخاب Other در پایین
• شناسه ارائه‌دهنده خود را انتخاب کنید
• ذخیره شده در auth.json

پروژه

opencode.json

• کلید ارائه‌دهنده باید از همان نام استفاده کند
• استفاده از بسته npm سازگار
• baseUrl با /v1 ختم می‌شود

انتخاب

/models

• مدل در لیست ظاهر می‌شود
• قبل از پرسیدن سوال یکی را انتخاب کنید
• استفاده از شناسه از لیست درگاه

تأیید با یک وظیفه واقعی

ابتدا یک وظیفه واقعی را از دایرکتوری پروژه اجرا کنید. فرمت ارجاع مدل Provider ID/model IDاست؛ هرگونه اسلش در شناسه مدل را حفظ کنید:

opencode run --model omniproxy/claude-sonnet-5-5 --auto "Explain what a file you specify does. Do not modify the file."

--auto به این اجرا اجازه می‌دهد از ابزارهایی مانند ابزارهای خواندن فایل استفاده کند. در آزمایش مورخ 2026-10-09 با OpenCode 1.18.34، محتویات فایل مشخص شده را با موفقیت خواند. اولین اجرا حدود دو دقیقه طول کشید.

برای استفاده تعاملی، اجرا کنید opencode، سپس یک مدل را با /modelsانتخاب کنید. می‌توانید از @ برای جستجوی فایل‌ها استفاده کنید. از opencode auth list برای تأیید اعتبارنامه ذخیره شده از طریق /connectاستفاده کنید، سپس سوابق درخواست OmniProxy را بررسی کنید تا منبع و شناسه مدل را تأیید کنید.

راه‌اندازی

opencode راه‌اندازی می‌شود

• ابتدا cd به پروژه
• auth list شناسه را نشان می‌دهد
• فایل پیکربندی در پروژه است

وظیفه

کد را خواند

• درباره یک فایل خاص بپرسید
• توضیح آن را بررسی کنید
• اگر اشتباه است از /undo استفاده کنید

لاگ‌ها

در درگاه قابل مشاهده است

• منبع OpenCode است
• شناسه مدل مطابقت دارد
• کلید را کامیت نکنید

خطاهای رایج

• OmniProxy تحت /modelsظاهر نمی‌شود: بررسی کنید که شناسه وارد شده تحت /connect با کلید در opencode.jsonمطابقت داشته باشد، npm روی @ai-sdk/openai-compatibleتنظیم شده باشد و baseURL با /v1ختم شود.
• اعتبارنامه گم شده است: اجرا کنید opencode auth list. ارائه‌دهندگانی مانند Bedrock که به متغیرهای محیطی متکی هستند اینجا ظاهر نمی‌شوند؛ یک ارائه‌دهنده سفارشی پیکربندی شده از طریق /connect باید قابل مشاهده باشد.
• عملکرد ویندوز ناقص است: از اسکریپت نصب داخل WSL استفاده کنید.
• شناسه مدل نامعتبر است: دوباره آن را از لیست فعلی OmniProxy کپی کنید و کلید مربوطه را تحت modelsبه‌روزرسانی کنید.
• درخواست‌ها به نقطه پایانی اشتباه می‌روند: برای chat completions، @ai-sdk/openai-compatible را حفظ کنید. بسته را برای رابط Responses تغییر ندهید مگر اینکه آن مدل در OmniProxy واقعاً از /v1/responses استفاده کند.

استفاده کند.

مراجع رسمی

برای نصب، به معرفی OpenCode مراجعه کنید. برای ارائه‌دهندگان سفارشی، به ارائه‌دهندگان مراجعه کنید. برای شناسه‌های مدل استفاده شده در مثال‌ها، به نمای کلی مدل Claude و GPT-6 Luna مراجعه کنید.

هر جایگاه را با مقادیر از پیکربندی OmniProxy خود جایگزین کنید. هرگز یک کلید واقعی را منتشر نکنید.

یک نتیجه ذخیره شده یا HTTP 200 به تنهایی سازگاری کامل عامل را اثبات نمی‌کند. منبع و مدل را در گزارش درخواست OmniProxy بررسی کنید.

منابع رسمی · OpenCode ↗