OpenCode چیست؟ راهنمای نصب، اتصال مدل و تنظیم مجوزهای امن

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

این آزادی اگر بدون پیکربندی انجام شود، می‌تواند باعث انتخاب اشتباه مدل، ذخیره نامناسب Credential یا دادن مجوز بیش‌ازحد به عامل شود. در این راهنما OpenCode را از منبع رسمی نصب می‌کنیم، Provider را با روش توصیه‌شده متصل می‌کنیم، فایل opencode.json را می‌سازیم و دسترسی ویرایش، Bash و مسیرهای بیرون پروژه را با اصل حداقل دسترسی کنترل می‌کنیم.

چرا OpenCode اکنون موضوعی روبه‌رشد است؟

Google Trends ایران در تاریخ ۸ سپتامبر ۲۰۲۶ نشان داد میانگین علاقه ۹۰روزه به OpenCode برابر ۲۰ بوده؛ در همان مقایسه Cursor AI امتیاز ۳ و GitHub Copilot CLI داده معناداری نداشت. در بازه ۱۲ماهه، OpenCode از داده بسیار کم در ابتدای دوره به قله ۱۰۰ در هفته منتهی به ۲۳ اوت ۲۰۲۶ و سپس سطح حدود ۶۰ در هفته‌های اخیر رسید. عبارت‌های مرتبط opencode ai، opencode free، opencode go و opencode zen هم Breakout بودند.

این روند نشان می‌دهد کاربران فقط نام ابزار را جست‌وجو نمی‌کنند؛ آن‌ها دنبال نصب، مدل‌های قابل اتصال و شیوه استفاده هستند. پیشنهاد واقعی Google Search نیز عبارت فارسی «نصب open code» را نمایش داد. این سیگنال به معنی رایگان‌بودن همه مدل‌ها یا مناسب‌بودن ابزار برای هر پروژه نیست، اما نیاز رو‌به‌رشد به یک راهنمای عملی و امنیت‌محور را تأیید می‌کند.

OpenCode چگونه کار می‌کند؟

OpenCode بین مخزن شما و مدل زبانی قرار می‌گیرد. رابط TUI درخواست را دریافت می‌کند، عامل بر اساس ابزارها و مجوزهای تعریف‌شده فایل‌ها را می‌خواند و در صورت اجازه، تغییر یا فرمان اجرا می‌کند. پاسخ مدل به‌تنهایی فایل را عوض نمی‌کند؛ ابزار و Permission تعیین می‌کنند کدام اقدام خودکار، نیازمند تأیید یا کاملاً مسدود باشد.

تفاوت Agent، Provider و Model

• Agent: نقش و رفتار کاری را مشخص می‌کند؛ مانند Plan برای بررسی و Build برای اجرای تغییر.
• Provider: سرویس یا زیرساختی است که مدل را ارائه می‌کند.
• Model: موتور زبانی انتخاب‌شده در Provider است و محدودیت Context، هزینه و توانایی خاص خود را دارد.
• Permission: مرز عملیاتی عامل برای Read، Edit، Bash، Web و دسترسی بیرون Worktree است.

یکی‌گرفتن این مفاهیم باعث خطا می‌شود. اتصال یک Provider به معنی اجازه اجرای آزادانه همه فرمان‌ها نیست و انتخاب مدل قوی‌تر هم جای تست و Code Review را نمی‌گیرد.

نصب OpenCode روی Windows، macOS و Linux

مخزن رسمی چند مسیر نصب معرفی می‌کند. در Windows می‌توانید از Scoop یا Chocolatey استفاده کنید. در macOS و Linux مسیر Homebrew و در همه سیستم‌عامل‌های دارای Node.js، بسته opencode-ai قابل استفاده است. همیشه نام Package و ناشر را با مستندات رسمی تطبیق دهید؛ پروژه‌های دیگری نیز نام مشابه OpenCode دارند.

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

npm i -g opencode-ai@latestopencode --versioncd ~/projects/sample-appgit status --shortopencode

چرا بررسی Git قبل از اجرا مهم است؟

اگر Worktree از قبل تغییرات ثبت‌نشده داشته باشد، تشخیص اینکه کدام خط را عامل تغییر داده دشوار می‌شود. خروجی git status --short را ثبت کنید، تغییرات خودتان را Commit کنید یا دست‌کم Diff اولیه را نگه دارید. سپس اولین درخواست را خواندنی تعریف کنید: «ساختار پروژه را توضیح بده؛ هیچ فایل یا تنظیمی را تغییر نده».

اتصال Provider و انتخاب Model

OpenCode از Providerهای متعدد و بعضی مدل‌های محلی پشتیبانی می‌کند. روش رسمی برای افزودن Credential فرمان /connect در رابط ابزار است. Credentialها در فایل اشتراک‌گذاری‌شده پروژه قرار نمی‌گیرند؛ مستندات مسیر ذخیره احراز هویت کاربر را جدا از opencode.json معرفی می‌کند. هرگز API Key واقعی را داخل مخزن، Screenshot، Issue یا نمونه تنظیمات قرار ندهید.

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

• دسترسی قانونی و جغرافیایی سرویس برای تیم
• هزینه ورودی و خروجی و امکان محدودکردن بودجه
• سیاست نگه‌داری داده و استفاده از محتوای پروژه
• اندازه Context و کیفیت مدل برای زبان پروژه
• پایداری API، Rate Limit و نیاز به Proxy سازمانی
• امکان اجرای Local برای کد حساس، با پذیرش محدودیت سخت‌افزار

عبارت «OpenCode Free» در Trends رشد دارد، اما خود OpenCode متن‌باز بودن رابط را تضمین می‌کند، نه رایگان‌بودن همه Providerها. هزینه و سهمیه به مدل انتخابی وابسته است. صفحه قیمت و شرایط Provider را همان روز راه‌اندازی بررسی کنید و سقف مصرف تعیین کنید.

ساخت فایل opencode.json با مجوزهای حداقلی

فایل تنظیمات پروژه باید در Version Control قابل بازبینی باشد، اما نباید Secret داشته باشد. مثال زیر همه عملیات را به‌طور پیش‌فرض روی ask نگه می‌دارد، خواندن و جست‌وجوی داخل پروژه را آزاد می‌کند، ویرایش را نیازمند تأیید می‌گذارد و دسترسی به مسیر بیرون پروژه را مسدود می‌کند. برای Bash نیز فقط فرمان‌های خواندنی مشخص بدون تأیید مجاز شده‌اند.

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

الگوی Bash را متناسب با Runner و دستورات واقعی خود محدود کنید. اجازه bash: allow برای همه فرمان‌ها، نصب بسته، انتشار یا تغییر داده را هم بدون توقف ممکن می‌کند. در تیم حرفه‌ای، قواعد مشترک را Code Review کنید و قواعد محلی حساس را از مخزن عمومی بیرون نگه دارید.

معنای allow، ask و deny

allow اقدام را بدون تأیید اجرا می‌کند، ask پیش از اقدام سؤال می‌پرسد و deny آن را مسدود می‌کند. قاعده عمومی را محافظه‌کارانه بنویسید و فقط استثناهای کم‌خطر را آزاد کنید. حالت Auto درخواست‌هایی را که در وضعیت ask هستند خودکار تأیید می‌کند، اما denyهای صریح همچنان برقرار می‌مانند. برای مخزن ناشناس یا محیط Production از Auto شروع نکنید.

Plan و Build؛ مسیر امن برای اولین وظیفه

عامل Plan برای تحلیل و برنامه‌ریزی طراحی شده و ویرایش فایل را به‌صورت پیش‌فرض انجام نمی‌دهد. عامل Build برای پیاده‌سازی دسترسی بیشتری دارد. در مخزن تازه ابتدا با Plan از ابزار بخواهید معماری، تست‌ها، وابستگی‌ها و ریسک تغییر را توضیح دهد. بعد از تأیید برنامه به Build بروید و یک تغییر کوچک با معیار پذیرش دقیق بسپارید.

1. از تمیزبودن Worktree و وجود نسخه پشتیبان مطمئن شوید.
2. در حالت Plan، محدوده و فایل‌های احتمالی تغییر را مشخص کنید.
3. تست‌های موجود را پیش از تغییر اجرا و نتیجه را ثبت کنید.
4. یک تغییر کوچک و قابل بازگشت به Build بدهید.
5. هر درخواست Permission را بر اساس اثر واقعی فرمان بررسی کنید.
6. پس از پایان، Diff، تست و رفتار امنیتی را خودتان بازبینی کنید.

ریسک‌های مهم و خطاهای رایج

کپی API Key در opencode.json

این فایل ممکن است Commit شود؛ بنابراین کلید واقعی را در آن ننویسید. Credential را با جریان رسمی /connect یا سازوکار Secret مورد تأیید سازمان وارد کنید. اگر کلیدی تصادفاً Commit شد، حذف آن از آخرین Commit کافی نیست؛ کلید را فوراً باطل و جایگزین کنید و تاریخچه را طبق سیاست امنیتی پاک‌سازی کنید.

اعتماد به دستورهای داخل README یا Issue

عامل ممکن است متن مخزن، مستندات یا داده آزمایشی را به‌عنوان Context بخواند. یک دستور مخرب در فایل به معنی اجازه شما نیست. درخواست‌هایی برای ارسال فایل، اجرای اسکریپت دانلودشده، خاموش‌کردن Permission یا افشای Environment Variable را مستقل بررسی کنید. برای مخزن ناشناس، حالت Plan و deny برای Web و External Directory شروع امن‌تری است.

انتخاب مدل صرفاً بر اساس رایگان‌بودن

مدل رایگان یا ارزان ممکن است Context کمتر، محدودیت Rate یا عملکرد ضعیف‌تری روی کد شما داشته باشد. یک سناریوی کوچک شامل توضیح معماری، نوشتن تست و اصلاح باگ را با داده غیرحساس آزمایش کنید. هزینه، کیفیت و سیاست داده را کنار هم بسنجید و سپس مدل تیم را استاندارد کنید.

چه زمانی OpenCode انتخاب مناسبی است؟

OpenCode برای تیمی مناسب است که Provider Choice، تنظیمات قابل Version Control و عامل ترمینالی می‌خواهد و آماده است مسئولیت پیکربندی مجوز و مدل را بپذیرد. اگر سازمان به یک سرویس کاملاً مدیریت‌شده با پشتیبانی قراردادی، کنترل مرکزی و فرایند تأیید از پیش آماده نیاز دارد، باید گزینه‌های دیگر را نیز ارزیابی کند.

اگر می‌خواهید تجربه نصب و Permission آن را با ابزار دیگری مقایسه کنید، راهنمای نصب Claude Code در ویندوز؛ Native و WSL 2 را بخوانید. معیار مقایسه را روی Workflow واقعی بگذارید: کیفیت Diff، سرعت تست، کنترل دسترسی، هزینه قابل پیش‌بینی و امکان بازگشت از تغییر.

جمع‌بندی

OpenCode یک عامل کدنویسی متن‌باز با امکان انتخاب Provider و Model است، اما ارزش واقعی آن زمانی آشکار می‌شود که مرزهای عملیات را آگاهانه تعریف کنید. نصب را فقط از منبع رسمی انجام دهید، Credential را وارد مخزن نکنید، کار را از Agent نوع Plan شروع کنید و برای Edit، Bash و مسیرهای بیرون پروژه قواعد صریح بنویسید.

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