معرفی OpenCode برای کدنویسی راحت‌تر با Agent هوش مصنوعی

OpenCode یک ایجنت کدنویسی هوش‌مصنوعی متن‌باز است که به‌صورت CLI ترمینالی، اپلیکیشن دسکتاپ و افزونه IDE عرضه شده و نسخه دسکتاپ آن روی ویندوز فعلاً در مرحله بتا قرار دارد.

نصب دسکتاپ روی ویندوز

نسخه دسکتاپ OpenCode برای ویندوز به‌صورت فایل نصبی از صفحه Releases یا آدرس opencode.ai/download در دسترس است. راه دیگر نصب از طریق Scoop است که با اجرای دستورات زیر در PowerShell انجام می‌شود:

scoop bucket add extras
scoop install extras/opencode-desktop

توجه کنید این نسخه دسکتاپ روی هسته همان موتور CLI کار می‌کند، پس تمام کانفیگ‌ها و امکاناتی که در ادامه توضیح می‌دهم عیناً روی نسخه دسکتاپ هم اعمال می‌شوند.

اتصال به مدل هوش‌مصنوعی

بعد از نصب، باید حداقل یک ارائه‌دهنده مدل (Provider) وصل کنید. ساده‌ترین راه استفاده از OpenCode Zen است که مجموعه‌ای از مدل‌های تست‌شده توسط تیم OpenCode را ارائه می‌دهد:

• در محیط چت دستور /connect را اجرا کنید
• گزینه opencode را انتخاب و به opencode.ai/auth بروید
• ثبت‌نام کرده و کلید API را کپی و در برنامه Paste کنید
  اگر ترجیح می‌دهید، می‌توانید هر ارائه‌دهنده دیگری (OpenAI، Anthropic، Google، OpenRouter و غیره) را هم به همین روش وصل کنید.

راه‌اندازی اولین پروژه

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

حالت Plan در برابر Build

یکی از مهم‌ترین امکانات OpenCode، دو حالت کاری است که با کلید Tab بین آن‌ها سوییچ می‌کنید:

• حالت Plan توانایی تغییر فایل را غیرفعال می‌کند و فقط پیشنهاد اجرا می‌دهد؛ مناسب برای بررسی امن قبل از اعمال تغییرات
• حالت Build تغییرات واقعی را روی فایل‌ها اعمال می‌کند
  بهترین روش کار این است که ابتدا در Plan درخواست‌تان را دقیق توضیح دهید (مثل صحبت با یک برنامه‌نویس جونیور در تیم)، فیدبک بدهید، و بعد با Tab به Build سوییچ کنید تا تغییرات واقعاً پیاده شوند.

بازگردانی تغییرات (Undo/Redo)

اگر نتیجه تغییرات دلخواه‌تان نبود، با دستور /undo می‌توانید تغییرات را برگردانید و دوباره پرامپت خود را اصلاح کنید؛ برای بازگرداندن مجدد تغییرات لغو‌شده هم دستور /redo وجود دارد.

اشتراک‌گذاری مکالمه

با فعال‌سازی گزینه Share می‌توانید مکالمه فعلی با OpenCode را با تیم‌تان به اشتراک بگذارید؛ این کار یک لینک می‌سازد و آن را در کلیپ‌بورد کپی می‌کند. حالت‌های موجود برای این ویژگی عبارتند از:

• manual: نیاز به اجرای دستور /share برای هر بار اشتراک‌گذاری (پیش‌فرض)
• auto: اشتراک‌گذاری خودکار مکالمات جدید
• disabled: غیرفعال کامل قابلیت اشتراک‌گذاری

فایل کانفیگ و محل‌های آن

OpenCode از JSON یا JSONC (JSON با کامنت) برای کانفیگ استفاده می‌کند و می‌توانید فایل کانفیگ را در چند مکان مختلف قرار دهید که با هم ادغام می‌شوند، نه جای‌گزین یکدیگر:

ترتیب اولویت	مسیر	کاربرد
1. Remote	.well-known/opencode	تنظیمات پیش‌فرض سازمانی
2. Global	~/.config/opencode/opencode.json	تنظیمات کاربر در سطح کل سیستم
3. Custom	متغیر محیطی OPENCODE_CONFIG	بازنویسی سفارشی
4. Project	opencode.json در ریشه پروژه	تنظیمات مخصوص پروژه، بالاترین اولویت استاندارد
5. .opencode/	پوشه پروژه	ایجنت‌ها، دستورات، پلاگین‌ها
6. Inline	متغیر محیطی OPENCODE_CONFIG_CONTENT	بازنویسی هنگام اجرا
7-8. Managed	مسیرهای مدیریتی سازمانی (مثل %ProgramData%\opencode روی ویندوز)	تنظیمات اجباری غیرقابل‌تغییر

تنظیمات مدل و ارائه‌دهنده‌ها

از طریق کلیدهای provider، model و small_model می‌توانید مدل اصلی و مدل کم‌هزینه برای وظایف سبک (مثل تولید عنوان) را تعیین کنید. هر ارائه‌دهنده گزینه‌های timeout (زمان‌سنج درخواست، پیش‌فرض 300000 میلی‌ثانیه)، chunkTimeout و setCacheKey را می‌پذیرد. همچنین می‌توانید با disabled_providers یا enabled_providers فهرست سفید/سیاه ارائه‌دهنده‌ها را مشخص کنید.

مجوزها (Permissions)

به‌طور پیش‌فرض OpenCode تمام عملیات را بدون نیاز به تأیید کاربر اجرا می‌کند. برای امنیت بیشتر می‌توانید با کلید permission مشخص کنید که ابزارهایی مثل edit یا bash نیاز به تأیید دستی داشته باشند:

{
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

ایجنت‌ها، دستورات و Skills

OpenCode امکان تعریف ایجنت‌های تخصصی از طریق کلید agent یا فایل‌های Markdown در .opencode/agents/ را می‌دهد و می‌توانید ایجنت پیش‌فرض را با default_agent تعیین کنید. دستورات سفارشی (Commands) هم از طریق کلید command یا فایل‌های Markdown در .opencode/commands/ قابل تعریف‌اند تا کارهای تکراری را به یک دستور کوتاه تبدیل کنید. Skillها هم دفترچه‌های راهنمای قابل‌فراخوانی برای انجام وظایف پیچیده و تکراری هستند که ایجنت می‌تواند در حین کار از آن‌ها استفاده کند.

سرورهای MCP و پلاگین‌ها

با کلید mcp می‌توانید سرورهای Model Context Protocol را وصل کنید تا ابزارهای بیرونی (مثل دسترسی به دیتابیس یا سرویس‌های دیگر) در اختیار ایجنت قرار گیرد؛ پلاگین‌ها هم که در .opencode/plugins/ یا از طریق npm بار می‌شوند، امکان افزودن ابزار و هوک‌های سفارشی به OpenCode را می‌دهند.

فرمترها و LSP

از طریق کلید formatter می‌توانید فرمترهای کد را فعال یا سفارشی کنید (اگر این کلید را حذف کنید، فرمترها غیرفعال باقی می‌مانند)، و به همین ترتیب lsp برای فعال‌سازی سرورهای Language Server Protocol جهت تشخیص خطا و تکمیل کد استفاده می‌شود.

سرور و حالت وب

با دستورات opencode serve و opencode web می‌توانید OpenCode را به‌صورت سرور اجرا کنید؛ تنظیمات آن شامل port، hostname، فعال‌سازی mdns برای کشف روی شبکه محلی (مثلاً دسترسی از تبلت) و cors برای کلاینت‌های مرورگری است.

قالب‌ها، کلیدهای میانبر و تنظیمات TUI

برای تنظیمات مخصوص رابط ترمینالی (TUI) از فایل جدا ~/.config/opencode/tui.json استفاده می‌شود، جایی که می‌توانید تم (Theme)، keybinds سفارشی (که فقط با کلیدهای پیش‌فرض ادغام می‌شود، نه جای‌گزین کامل آن) و اعلان‌های دسکتاپ (attention.enabled) را تنظیم کنید.

Snapshot، Autoupdate و Compaction

OpenCode به‌صورت پیش‌فرض از سیستم Snapshot برای امکان Undo/Redo استفاده می‌کند، اما برای پروژه‌های بزرگ یا با ساب‌ماژول‌های زیاد که باعث کندی می‌شود، می‌توانید آن را با کلید snapshot غیرفعال کنید. کلید autoupdate هم به‌روزرسانی خودکار را کنترل می‌کند (مقدار "notify" فقط اعلان می‌دهد بدون نصب خودکار)، و کلید compaction نحوه فشرده‌سازی خودکار حافظه گفتگو هنگام پر شدن Context را مدیریت می‌کند.

متغیرها در فایل کانفیگ

برای امنیت بیشتر بهتر است کلید‌های API را مستقیم داخل کانفیگ ننویسید. OpenCode امکان جایگزینی با {env:VARIABLE_NAME} برای متغیرهای محیطی و {file:path/to/file} برای محتوای یک فایل را می‌دهد؛ این روش برای نگه‌داشتن اطلاعات حساس جدا از فایل کانفیگ اصلی مناسب است:

{
  "provider": {
    "openai": {
      "apiKey": "{env:OPENAI_API_KEY}"
    }
  }
}