آموزش کامل OpenCode: راهنمای جامع ایجنت کدنویسی متن‌باز

OpenCode یک ایجنت کدنویسی متن‌باز است که می‌تواند مخزن را بخواند، فایل‌ها را ویرایش کند، فرمان اجرا کند، از اطلاعات Language Server استفاده کند، ابزارهای بیرونی را فراخوانی کند و کارهای محدود را به ساب‌ایجنت‌ها بسپارد. این محصول در ترمینال، اپ دسکتاپ، افزونه IDE، سرور، SDK و گردش‌کار GitHub در دسترس است. مزیت اصلی آن یک مدل انحصاری نیست؛ امکان انتخاب ارائه‌دهنده مدل و شکل‌دادن به پوسته ایجنت بر اساس گردش‌کار شماست.

این راهنما در ۱۵ مرداد ۱۴۰۵ (۶ اوت ۲۰۲۶) با مستندات رسمی OpenCode و مخزن اصلی پروژه تطبیق داده شده است. OpenCode با سرعت زیادی تغییر می‌کند. مستندات نسخه پایدار و V2 اکنون هم‌زمان وجود دارند و نام فیلدهای پیکربندی آن‌ها یکسان نیست. پیش از کپی‌کردن تنظیمات، شاخه مستندات و نسخه نصب‌شده را بررسی کنید.

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

OpenCode برای چه کسی مناسب است؟

OpenCode انتخاب مناسبی است اگر این موارد را می‌خواهید:

• ایجنت کدنویسی متن‌باز و ترمینال‌محور؛
• امکان انتخاب میان چند ارائه‌دهنده مدل؛
• رابط ترمینال، دسکتاپ، IDE، سرور، SDK و GitHub؛
• دستورهای پایدار مخزن با AGENTS.md و فایل‌های راهنمای تکمیلی؛
• ایجنت‌های plan و build، ساب‌ایجنت سفارشی، Skill، سرور MCP، پلاگین و ابزار سفارشی؛
• قواعد صریح مجوز برای ویرایش، فرمان شل، وب، Skill و واگذاری کار.

متن‌بازبودن به‌تنهایی به معنای خصوصی‌بودن نیست. ارائه‌دهنده مدل، سرورهای MCP، پلاگین‌ها، تنظیمات اشتراک‌گذاری و تله‌متری تعیین می‌کنند کد و پرامپت به کجا می‌رود. «اجرای محلی» درباره کلاینت است، نه لزوماً استنتاج مدل و تمام ابزارهای متصل.

نصب OpenCode

راهنمای رسمی فعلی برای macOS و Linux نصب‌کننده زیر را پیشنهاد می‌کند:

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

روش‌های رسمی جایگزین نیز شامل این موارد است:

npm install -g opencode-ai
brew install anomalyco/tap/opencode

برای Windows، مستندات WSL را بهترین مسیر ترمینالی می‌دانند و Chocolatey، Scoop، npm، Docker و فایل‌های release را نیز پوشش می‌دهند. فقط یک روش نصب را انتخاب و سپس باینری واقعی را بررسی کنید:

opencode --version
opencode --help

پیش از انتقال مستقیم یک نصب‌کننده به شل، URL و منبع آن را بررسی کنید. برای استقرار تیمی، نسخه را ثبت یا pin کنید و به‌روزرسانی را ابتدا روی مخزن غیرتولیدی بیازمایید.

اتصال ارائه‌دهنده مدل

OpenCode را اجرا و فرمان زیر را وارد کنید:

/connect

می‌توانید از OpenCode Zen، سرویس مدل منتخب پروژه، یا یکی از ارائه‌دهندگان پشتیبانی‌شده استفاده کنید. مدل‌ها، قیمت، قواعد داده و اندازه context مستقل از کلاینت تغییر می‌کنند؛ بنابراین به‌جای کپی نام قدیمی مدل، راهنمای زنده ارائه‌دهندگان را ببینید.

کلیدها را داخل opencode.json، پرامپت، اسکرین‌شات یا Git قرار ندهید. روش احراز هویت یا متغیر محیطی رسمی همان ارائه‌دهنده را به کار ببرید. ارائه‌دهنده‌ای را که مخزن نیاز ندارد صریحاً غیرفعال کنید تا اعتبارنامه موجود در محیط، ناخواسته آن را فعال نکند.

راه‌اندازی نخستین مخزن

دقیقاً وارد پروژه موردنظر شوید:

cd /path/to/project
git status --short --branch
opencode

سپس راهنمای پروژه را بسازید:

/init

طبق راهنمای رسمی، /init پروژه را تحلیل و AGENTS.md را در ریشه ایجاد می‌کند. پیش از commit آن را بازبینی کنید؛ این فایل باید فرمان‌ها و مرزهای واقعی تیم را ثبت کند، نه حدس‌های تولیدشده را.

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

مسیر احراز هویت را از route تا persistence توضیح بده.
فایل‌های مربوط را نام ببر و هیچ فایلی را تغییر نده.

بعد یک تغییر محدود بخواهید:

برای باگ ارسال تکراری یک تست رگرسیون بساز، مشکل را بازتولید کن،
کوچک‌ترین اصلاح را انجام بده، تست هدفمند را اجرا کن و diff نهایی را مرور کن.
وابستگی یا طرح پایگاه داده را تغییر نده.

برای بازگرداندن آخرین تغییر ایجنت از /undo و برای اعمال دوباره آگاهانه از /redo استفاده کنید. با این حال git diff را ببینید؛ undo داخل ایجنت جای کنترل نسخه را نمی‌گیرد.

انتخاب سطح مناسب

OpenCode چند سطح استفاده دارد:

• Terminal UI: رابط تمام‌صفحه و صفحه‌کلیدمحور برای مخزن محلی؛
• اپ دسکتاپ: محیط گرافیکی مستقل؛
• افزونه IDE: استفاده از انتخاب کد و وضعیت ویرایشگر؛
• سرور: اتصال کلاینت دیگر به OpenCode؛ آدرس bind و رمز را ایمن کنید؛
• SDK: ساخت session و کنترل برنامه‌ای سرور؛
• یکپارچه‌سازی GitHub: اجرای کار از issue و pull request در GitHub Actions.

اسکرین‌شات رسمی مخزن OpenCode از تجربه IDE.

تغییر سطح، نیاز به هدف روشن، مجوز محدود، تست و بازبینی را از بین نمی‌برد.

ایجنت‌های plan، build و ساب‌ایجنت‌ها

OpenCode ایجنت اصلی و ساب‌ایجنت دارد. ایجنت داخلی plan برای تحلیل بدون ویرایش عادی کد طراحی شده و build اجرای تغییر را بر عهده می‌گیرد. نقش‌های داخلی دیگری برای کاوش و نگه‌داری وجود دارند و ایجنت سفارشی را می‌توان با JSON یا Markdown تعریف کرد.

با Tab در keymap پیش‌فرض میان ایجنت‌های اصلی جابه‌جا شوید یا از منوی @ ساب‌ایجنت را مستقیم فراخوانی کنید. نمونه بازبین فقط‌خواندنی:

---
description: Review code without changing it
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff*": allow
    "git status*": allow
  webfetch: deny
---

درستی، امنیت، رگرسیون و تست‌های جاافتاده را در اولویت بگذار.
یافته‌ها را با شواهد فایل گزارش کن و فایلی را تغییر نده.

ساب‌ایجنت برای کاوش، بازبینی یا مستندسازی مستقل مناسب است. ویرایش هم‌زمان یک فایل توسط چند ایجنت را فقط با branch یا worktree جدا و قرارداد ادغام روشن انجام دهید.

نوشتن AGENTS.md مفید

AGENTS.md قرارداد پایدار مخزن است. فایل ریشه را کوتاه و دقیق نگه دارید و فقط برای زیرشاخه‌ای که واقعاً قواعد متفاوت دارد، راهنمای نزدیک‌تر اضافه کنید.

## نقشه مخزن

- `apps/web`: رابط Next.js کاربر
- `services/api`: API و قواعد مجوز
- `packages/generated`: خروجی تولیدشده؛ دستی ویرایش نشود

## اعتبارسنجی

- پس از تغییر TypeScript فرمان `npm run typecheck` اجرا شود.
- ابتدا نزدیک‌ترین تست هدفمند و بعد مجموعه مرتبط اجرا شود.
- تغییر UI در دسکتاپ و موبایل بررسی شود.

## ایمنی

- فایل `.env` و اعتبارنامه‌ها دست‌کاری نشوند.
- migration یا deployment تولید اجرا نشود.
- تغییرهای نامرتبط کاربر حفظ شوند.

از گزینه instructions می‌توانید فایل‌های contributor یا معماری موجود را بارگذاری کنید تا راهنمای طولانی در AGENTS.md تکرار نشود.

پیکربندی بدون مخلوط‌کردن نسل‌ها

مستندات پایدار از JSON یا JSONC و چند منبع ادغام‌شونده استفاده می‌کنند: تنظیمات سازمانی، global، فایل پروژه opencode.json، پوشه‌های .opencode و override زمان اجرا.

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": true,
  "instructions": ["CONTRIBUTING.md", "docs/architecture.md"],
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

نکته مهم: مستندات مجوز V2 از permissions، shell و subagent استفاده می‌کنند؛ نمونه‌های پایدار V1 از permission، bash و task. این دو را ترکیب نکنید و پیش از مهاجرت نسخه باینری و مسیر مستندات را تطبیق دهید.

طراحی مجوزها پیش از افزایش خودمختاری

مجوزهای پایدار OpenCode به allow، ask یا deny ختم می‌شوند و خواندن، ویرایش، شل، پوشه بیرونی، وب، LSP، Skill، سؤال، ساب‌ایجنت و ابزار MCP را پوشش می‌دهند.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "external_directory": "deny",
    "webfetch": "ask",
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow",
      "git push*": "deny",
      "rm *": "deny"
    }
  }
}

ترتیب و wildcard در قواعد مهم است. رفتار واقعی را با فرمان بی‌خطر آزمایش کنید. allowlist شل فقط به اندازه معناشناسی تطبیق خود امن است و لزوماً نیت فرمان یا تمام مسیرهای داخل آرگومان‌ها را تحلیل نمی‌کند.

افزودن Agent Skills

OpenCode بسته‌های SKILL.md را از مسیرهای OpenCode، سازگار با Claude و .agents/skills کشف می‌کند؛ بنابراین یک Skill دقیق می‌تواند میان چند کلاینت ایجنت مشترک باشد.

فایل .opencode/skills/release-check/SKILL.md:

---
name: release-check
description: Verify a web release candidate before handoff
license: MIT
compatibility: opencode
---

## Workflow

1. وضعیت مخزن و diff کامل را بررسی کن.
2. تست هدفمند، type check و build تولید را اجرا کن.
3. مسیر تغییرکرده را در دسکتاپ و موبایل ببین.
4. شواهد، محدودیت، rollback و اقدام بعدی را گزارش کن.

بدون اختیار صریح deploy، merge یا پیام بیرونی انجام نده.

ایجنت ابتدا توضیح کوتاه Skill را می‌بیند و متن کامل را هنگام نیاز بارگذاری می‌کند. هر Skill باید یک کار، trigger مشخص و خروجی روشن داشته باشد. Skill شخص ثالث را بخشی از زنجیره تأمین اجرایی بدانید؛ ممکن است ایجنت را به فرمان شل یا سرویس بیرونی هدایت کند.

گسترش با LSP، MCP، پلاگین و ابزار سفارشی

• LSP: ناوبری symbol و diagnostic زبان؛
• MCP: اتصال داده و ابزار زنده بیرونی؛
• پلاگین: افزودن hook، ابزار، احراز هویت یا integration؛
• ابزار سفارشی: تابع type-safe برای مدل؛
• ACP: ارتباط ویرایشگر یا کلاینت سازگار با ایجنت؛
• SDK و سرور: تعبیه یا کنترل راه‌دور OpenCode.

از ابزارهای داخلی مخزن شروع کنید و فقط قابلیتی را اضافه کنید که یک حلقه دستی واقعی را حذف می‌کند. ناشر، کد، نسخه، مجوز، اعتبارنامه، مقصد داده و مسیر update هر MCP یا پلاگین را بررسی کنید. محتوای وب، issue و سند حتی از سرور مورداعتماد نیز داده نامطمئن است.

استفاده درست از GitHub

راهنمای GitHub نصب workflow را برای پاسخ به /opencode یا /oc در issue و pull request توضیح می‌دهد. ایجنت در محیط Actions اجرا و می‌تواند PR پیشنهاد کند.

اسکرین‌شات رسمی مخزن OpenCode از یک pull request ایجنتی.

این مسیر را اتوماسیون CI بدانید، نه مجوز ضمنی merge:

1. افراد مجاز به trigger محدود شوند؛
2. token کم‌اختیار و محیط محافظت‌شده باشد؛
3. نسخه OpenCode و actionهای ثالث pin شوند؛
4. محتوای fork یا ورودی نامطمئن به credential نوشتنی نرسد؛
5. branch protection، تست و بازبینی انسانی اجباری باشد؛
6. لاگ از نظر prompt injection و دسترسی بیرونی ناخواسته بررسی شود.

گردش‌کار حرفه‌ای OpenCode

1. بازرسی: مخزن، branch، status، دستورها و مسیرها را تأیید کنید.
2. بازتولید: تست شکست‌خورده، لاگ، اسکرین‌شات یا سناریوی قطعی بسازید.
3. برنامه: برای تغییر مبهم یا پرریسک از plan استفاده کنید.
4. مرزبندی: فایل مجاز، اقدام ممنوع و نقطه تأیید را بنویسید.
5. ساخت: فقط پس از روشن‌شدن قرارداد به build بروید.
6. اعتبارسنجی: تست هدفمند، رگرسیون و QA واقعی UI/Runtime را اجرا کنید.
7. بازبینی: diff کامل و بازبین فقط‌خواندنی جدا داشته باشید.
8. تحویل: شواهد، ریسک باقیمانده و اقدام بیرونی انجام‌نشده را دقیق بگویید.

موفقیت را با تعداد خط نسنجید؛ تکمیل پذیرفته‌شده، نرخ قبولی تست در تلاش اول، اصلاح بازبین، رگرسیون، خروج از محدوده، زمان، هزینه و revert مهم‌ترند.

رفع اشکال

برای آزمایش providerهای فعلی، مقایسه مستند qwen3.8-max-preview، glm-5.2 و deepseek-v4-flash را ببینید. OpenCode پوسته مناسبی برای provider سازگار است، اما از /connect و مستندات زنده استفاده کنید و تنظیم کلاینت دیگر را کپی نکنید.

مدلی دیده نمی‌شود: /connect، اعتبارنامه، تنظیم enabled/disabled و وضعیت و نام فعلی مدل‌ها را بررسی کنید.

AGENTS.md یا Skill بارگذاری نمی‌شود: پوشه کاری، مرز Git worktree، نام دقیق، frontmatter، مسیر کشف و مجوز را تطبیق دهید.

قاعده مجوز خلاف انتظار است: ابتدا مطمئن شوید مستندات پایدار یا V2 را می‌خوانید؛ سپس ترتیب و wildcard را با یک مورد بی‌خطر تست کنید.

اپ دسکتاپ به سرور WSL وصل نمی‌شود: راهنمای رسمی WSL، host و port را بررسی و پیش از bind خارج localhost متغیر OPENCODE_SERVER_PASSWORD را تنظیم کنید.

ایجنت موفقیت اعلام کرده ولی برنامه خراب است: diff، خروجی فرمان و رفتار runtime منبع حقیقت‌اند. مشکل را دوباره بازتولید و لایه واقعی را بررسی کنید.

پرسش‌های رایج

آیا OpenCode رایگان است؟

کلاینت متن‌باز است؛ استنتاج مدل، OpenCode Zen، سرویس میزبانی‌شده یا ابزار ثالث ممکن است هزینه جدا داشته باشد.

آیا مدل محلی پشتیبانی می‌شود؟

OpenCode از چند ارائه‌دهنده و endpointهای سازگار با OpenAI پشتیبانی می‌کند. کیفیت مدل محلی را با وظایف واقعی مخزن و قابلیت tool use بسنجید.

آیا AGENTS.md و Agent Skills دارد؟

بله. /init فایل AGENTS.md می‌سازد و سیستم Skill فعلی مسیرهای OpenCode، Claude و .agents/skills را می‌شناسد.

آیا متن‌بازبودن OpenCode آن را ایمن می‌کند؟

شفافیت کد برای بازبینی مفید است، اما ایمنی به تنظیمات، ارائه‌دهنده، اختیار شل و فایل، افزونه، credential و شیوه کار اپراتور وابسته است.

OpenCode، Qwen Code، Antigravity، Codex یا Claude Code؟

OpenCode برای پوسته باز و چندارائه‌دهنده‌ای؛ Qwen Code برای اکوسیستم سریع ایجنت و مدل Qwen؛ Google Antigravity برای پلتفرم مشترک ترمینال و visual گوگل؛ Codex برای اکوسیستم یکپارچه محلی، cloud، app و توسعه OpenAI؛ و Claude Code برای ترمینال، دسکتاپ، وب، agent team و Agent SDK آنتروپیک مناسب‌اند. ابزارها را با معیار پذیرش مخزن خود بسنجید.

یادداشت منابع

بازبینی‌شده در ۱۵ مرداد ۱۴۰۵ / ۶ اوت ۲۰۲۶:

• راهنمای شروع OpenCode
• پیکربندی
• ایجنت‌ها و ساب‌ایجنت‌ها
• مجوزها
• مجوزهای V2
• Agent Skills
• یکپارچه‌سازی GitHub
• مخزن رسمی OpenCode