نسخه جدید ایجنت opencode چه حرف‌هایی برای گفتن داره؟

اگر برگردیم یکم عقب تر از حدود بعد از tabnine و github copilot و وقتی میرسیم به claude code و codex همیشه جای یک agent متن باز خالی بود. در واقع امروز به یکی از مورد علاقه‌ترین agent هایی که باهاش کار کردم میرسیم یعنی opencode, این opencode coding agent harness یک پلتفرم بود که شما میتونستی بدون دردسر از هر provider ای مثل claude استفاده کنی. (در واقع اوپن‌کد دلیل این هست که کلاد لاگین اپ‌های ثانویه رو برداشته و داستانش طولانیه)

با گذشت زمان همانطور که کلی coding agent harness های مختلف اومدن و حتی رفته رفته تبدیل شدن به یک پلتفرم مثل kilo code یا cline همیشه opencode تونست خودش رو در جایگاه نسبتا بالایی توی پلتفرم‌های مختلف قرار بده و از طرفی با معرفی opencode go تونست سهم بازار خوبی رو بگیره و این یعنی داده‌های بیشتر و کاربران بیشتر.
توی این مطلب درباره اینکه نسخه جدید opencode یعنی opencode v2 چه چیز‌هایی رو اضافه کرده و چه تغییراتی داده صحبت میکنیم.

اگر میخوای توی انتخاب نسخه سریع به جواب بررسی اینه:

جواب کوتاه

• پروژه‌ی جدید: مستقیم v2.

• v1 بدون plugin سفارشی: v2 رو نصب کن، فایل config رو بازنویسی نکن، model و MCP و permissions رو روی یک repo واقعی تست کن.

• نویسنده‌ی plugin یا کسی که به server API وصل شده: باید port کنی. جابه‌جا کردن فایل کافی نیست.

• پکیچ desktop opencode با opencode v2 متفاوت هست

اگر هم میخوای به نسخه جدید یعنی opencode v2 مهاجرت کنی توجه کن که breaking changes داشته.

سه چیزی قبل از مهاجرت به نسخه جدید opencode باید حواست باشه!

راهنمای رسمی مهاجرت همین سه نقطه breaking change رو اسم می‌بره. بیرون از این سه تا، config و agent و command و skill و فایل‌های .opencode/ باید سر جاشون بمونن.

1. ۱. تغییر سیستم پلاگین‌ها (Plugin API):

   نحوه ساخت پلاگین بازنویسی شده است. حالا باید از پکیج @opencode/plugin و متد Plugin.define استفاده کنید (برخلاف نسخه ۱ که با پکیج @opencode-ai/plugin یک آبجکت از هوک‌ها برمی‌گرداند).

   ۲. ارتباط سرور و کلاینت (Server API):

   ساختار ارتباطی سرور و کلاینت تغییر کرده و پکیج رسمی جدید برای اتصال، @opencode/client است.

   ۳. یکپارچه‌سازی تنظیمات ترمینال (TUI):

   به‌جای چند فایل پراکنده tui.json، همه تنظیمات در یک فایل سراسری در آدرس ~/.config/opencode/cli.json تجمیع شده است. در نخستین اجرا، تنظیمات کلی v1 به‌طور خودکار به این فایل منتقل می‌شود و به فایل‌های قبلی دست نمی‌زند. البته فایل‌های تنظیمات اختصاصی هر پروژه منتقل نمی‌شوند، چرا که در v2 تنظیمات کلاینت کاملاً سراسری است.

نصب با curl:

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

دستور اجرایی هر دو نسخه یکسان است (opencode)؛ بنابراین به‌صورت پیش‌فرض نمی‌توانید هر دو را همزمان روی سیستم داشته باشید. با اجرای نصاب نسخه ۲، فایل اجرایی (Binary) قبلی جایگزین می‌شود. پس بهتر است قبل از نصب v2، پکیج نسخه ۱ را کاملاً حذف کنید.

اگر از npm استفاده می‌کنید، نسخه ۱ پکیج opencode-ai و نسخه ۲ پکیج @opencode/cli است. (در زمان نگارش این مطلب، آخرین نسخه‌ها به ترتیب 1.18.32 و 2.0.18 بوده‌اند که طبیعتاً با گذر زمان به‌روزرسانی می‌شوند).

منبع: راهنمای مهاجرت از V1.

توی v2 چی عوض شده

v2 یک server پس‌زمینه مشترک برای کلاینت‌های همون کاربر بالا می‌آره. session و config و tool اونجا می‌مونن. با --standalone یک server خصوصی می‌گیری و با --server به یک URL مشخص وصل می‌شی. هر اسکریپتی که به قرارداد server نسخه‌ی v1 زده باید بره سمت API جدید.

agent اصلی و subagent

در نسخه ۲، دیگر ایجنت پیش‌فرضی به نام Scout وجود ندارد. در این نسخه، ساب‌ایجنت‌ها در یک نشست مجزا و ایزوله (Child Session) با کانتکست کاملاً تازه اجرا می‌شوند و دو شیوه اجرا دارند:

• حالت پیش‌زمینه (Foreground): والد منتظر می‌ماند تا کار ساب‌ایجنت تمام شود و خروجی را دریافت کند.

• حالت پس‌زمینه (Background): کنترل فوراً برمی‌گردد و ساب‌ایجنت در پس‌زمینه اجرا می‌شود؛ پس از اتمام کار، نتیجه به ایجنت والد اعلام خواهد شد.

همچنین عمق فراخوانی تو در توی ساب‌ایجنت‌ها به‌صورت پیش‌فرض برابر ۱ است. ضمناً ایجنت‌های سیستمی و پنهان (مثل compaction، title و summary) کاملاً خودکار عمل می‌کنند و امکان فراخوانی یا انتخاب دستی آن‌ها وجود ندارد.

حالت کدنویسی (Code Mode)

ابزار execute همان قابلیت Code Mode در پلتفرم است. این قابلیت کدهای جاوااسکریپت را داخل یک محیط ایزوله (Sandbox) اجرا می‌کند تا بتوانید چند ابزار مختلف را در یک رفت‌وبرگشت (Turn) با هم ترکیب کنید؛ این کار مانع از سرازیر شدن خروجی‌های میانی و غیرضروری به کانتکست مدل می‌شود. ران‌تایم این سندباکس به‌طور مستقیم به مواردی مثل فایل‌سیستم، import، تایمرها یا fetch دسترسی ندارد و هر ابزار تودرتو همچنان از سطح دسترسی‌ها و مجوزهای (Permissions) اختصاصی خودش پیروی می‌کند.

(منبع: مستندات ابزارهای v2)

مدیریت و فشرده‌سازی کانتکست (Compaction)

• تغییرات نسبت به v1: در نسخه ۱ مدیریت کانتکست به preserve_recent_tokens و فیلدهایی مثل tail_turns و prune متکی بود، اما در نسخه ۲ این دو فیلد آخر کاملاً نادیده گرفته می‌شوند و در صورت استفاده، سیستم هشدار (Warning) می‌دهد.

• روش v2: نسخه ۲ به‌صورت پیش‌فرض حدود ۱۵ هزار توکن اخیر را همراه با خلاصه نگه‌داری می‌کند (از طریق فیلد compaction.keep.tokens با مقدار پیش‌فرض ۱۵,۰۰۰).

• تولید خلاصه: خلاصه به‌طور پیش‌فرض توسط خود OpenCode و با مدلِ همان نشست ساخته می‌شود؛ در حالت native، خلاصه مستقیماً به اندپوینت پروایدر واگذار می‌شود که بر اساس مستندات رسمی، مختص مدل‌های ساختاریافته مانند OpenAI Responses است و برای همه مدل‌ها کاربرد ندارد.

• عملکرد و سرعت: مستندات رسمی ادعایی مبنی بر سریع‌تر بودن v2 نسبت به v1 ندارند؛ مواردی مانند ایزوله‌سازی کارهای سنگین در نشست‌های فرزند (Subagent) و پالایش خروجی‌های میانی در Code Mode صرفاً راهکارهای معماری هستند، نه یک بنچمارک مقایسه‌ای سرعت.

جدول مقایسه OpenCode v1 و v2

چه زمانی باید به نسخه ۲ مهاجرت کنیم؟

اگر کاربر عادی CLI هستید و پلاگین سفارشی ندارید، این جابه‌جایی بسیار ساده و کم‌دردسر است؛ چرا که نسخه ۲ فایل تنظیمات (Config) شما را بازنویسی نمی‌کند و مهاجرت به ساختار Native نیز کاملاً اختیاری است (حتی می‌توانید تبدیل خودکار آن به ساختار v2 را از داخل خود برنامه بخواهید).

نقاط چالش و مواردی که باید دقت کنید:

• پلاگین‌های اختصاصی: اگر پلاگین سفارشی دارید، باید آن را با متد Plugin.define بازنویسی کنید. در دوره گذار، یک پکیج می‌تواند هم‌زمان متد server() برای v1 و setup() برای v2 را پیاده‌سازی کند، اما هوک‌ها خودکار ترجمه نمی‌شوند (ورودی آبجکت v1 از نسخه 1.18.29 به بعد پشتیبانی می‌شود).

• اسکریپت‌های سرور: هر اسکریپتی که با Server API نسخه ۱ ارتباط دارد، باید با ساختار نسخه جدید بازنویسی شود.

• فایل‌های راهنما و دستورالعمل: اگر از CLAUDE.md استفاده می‌کردید، محتوای آن را به AGENTS.md انتقال دهید؛ زیرا v2 تنها فایل AGENTS.md را می‌شناسد.

• ابزارهای بررسی کد (LSP): اگر به LSP داخلی نسخه قبل وابسته بودید، بهتر است از ابزارهای بومی پروژه (مانند linter، کامپایلر یا ابزارهای typecheck) استفاده کنید.

• تداخل در نصب: به دلیل یکسان بودن نام دستور (opencode)، هر دو نسخه نمی‌توانند همزمان روی مسیر سیستم (PATH) فعال باشند. قبل از نصب v2، حتماً نسخه ۱ را حذف کنید.

• قوانین و ساختار دسترسی‌ها (Permissions): ساختار دسترسی‌ها در v2 یک آرایه مرتب از action، resource و effect است:

  • نام bash به shell، دسترسی task به subagent و دسترسی‌های write و patch به edit تغییر کرده‌اند.

  • قوانین از بالا به پایین ارزیابی می‌شوند و آخرین قانونِ منطبق برنده است؛ بنابراین همیشه استثناها را بعد از قانون کلی بنویسید.

• سیاست‌های سازمانی (experimental.policies): این قوانین شرایط را سخت‌گیرانه‌تر می‌کنند و حتی با تأیید دستی در محیط TUI نیز دور زده نمی‌شوند.

توصیه نهایی: اگر پلاگین حیاتی شما هنوز به نسخه جدید منتقل نشده است، فعلاً روی نسخه ۱ بمانید. همچنین توجه داشته باشید که نسخه ۱ را به فایل‌های تنظیمی که کاملاً مختص v2 هستند متصل نکنید، زیرا هر دو نسخه مسیرهای یکسانی را می‌خوانند.

مدل را با خود برنامه اشتباه نگیرید!

یکی از سوءتفاهم‌های رایج این است که کاربر تصور می‌کند برای رفتن به نسخه ۲ حتماً باید اشتراک OpenCode Go بخرد یا برعکس. واقعیت این است که OpenCode صرفاً موتور و بستر اجرایی (Harness) شماست، در حالی که Go فقط یک اشتراک ارائه‌دهنده مدل برای دسترسی به مدل‌های متن‌باز است. بنابراین اجباری به ارتقا ندارید؛ شما می‌توانید اشتراک Go را هم روی v1، هم روی v2 و حتی روی ابزارهایی مثل Cursor و Claude Code فعال کنید.

همچنین حواستان باشد که Zen با Go یکی نیست:

• Zen: سیستمی بر پایه پرداخت به‌ازای مصرف (Pay-as-you-go) است و برای استفاده باید مدام حساب‌تان را شارژ کنید (مثلاً شارژ اعتباری ۲۰ دلاری).

• Go: یک اشتراک ماهانه ثابت (حدود ۱۰ دلار) است که امکان تمدید یا لغو دلخواه دارد. در حال حاضر پیکسول اشتراک Go را ارائه می‌دهد، نه سرویس Zen.

لیست مدل‌ها ثابت نیست!

مدل‌های ارائه‌شده در پنل Go مدام در حال به‌روزرسانی هستند؛ مثلاً مدل‌هایی مثل Kimi K3، DeepSeek V4.1 Flash، GLM-5.3-Flash یا GPT 6 Luna در مقاطع مختلف اضافه یا جایگزین می‌شوند. بنابراین لیست مدل‌ها را قطعی فرض نکنید و پیشنهاد می‌کنیم موقع خرید، هم صفحه رسمی Go و هم مشخصات محصول در سایت پیکسول را چک کنید تا ببینید در آن لحظه چه مدل‌هایی فعال هستند.

اگه مدل رو جدا از harness می‌خری، مسیر زنده‌ی پیکسول این‌هاست:

• خرید اشتراک Cursor اگه IDE می‌خوای

• Codex داخل ChatGPT برای Claude Code و OpenCode و Hermes

• Claude Code با اشتراک Claude

• محصول Kimi اگه Kimi رو می‌خوای، نه فقط مدل داخل Go

• Grok Build برای خط xAI

• Gemini Pro

ترمینال و هاست کنار همین کار: Warp، Railway Hobby، n8n. بقیه‌ی ابزار کدنویسی توی ابزار کدنویسی AI و اشتراک هوش مصنوعی.

چک‌لیست گام‌به‌گام مهاجرت به v2

برای اینکه جابه‌جایی بی‌دردسری داشته باشید، این مراحل را قدم‌به‌قدم بروید:

1. پشتیبان‌گیری از داده‌ها: قبل از هر کاری، از فایل‌ها و دیتای محلی نسخه قبلی یک بک‌آپ بگیرید؛ چون مستندات رسمی انتقال کامل تاریخچه جلسات (Session History) را تضمین نمی‌کنند.

2. حذف پکیج قبلی: پکیج قدیمی v1 را کاملاً حذف کنید و سپس نسخه ۲ را مطابق دستورالعمل رسمی نصب کنید.

3. تست روی یک پروژه واقعی: کلید مدل، دسترسی‌ها (Permissions)، پروتکل MCP و پلاگین‌ها را روی یک ریپازیتوری تستی بالا بیاورید و عملکردشان را بسنجید.

4. به‌روزرسانی پلاگین‌ها و سرور: اگر پلاگین اختصاصی نوشته‌اید یا اسکریپتی دارید که به Server API وصل می‌شود، آن‌ها را با ساختار نسخه ۲ هماهنگ و پورت کنید.

5. تبدیل کانفیگ (کاملاً اختیاری): وقتی از کارکرد سیستم مطمئن شدید، در صورت تمایل می‌توانید ساختار تنظیمات را به فرمت Native نسخه ۲ ببرید.

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

   (البته اگر در ادامه به ابزارهایی مثل JetBrains AI در IntelliJ، CommandCode یا ساخت سریع پروتوتایپ با Bolt نیاز داشتید، هرکدام جریان کاری خودشان را دارند و جایگزین خود برنامه OpenCode محسوب نمی‌شوند).

سوال‌های پرتکرار

آیا همین الان به v2 مهاجرت کنم؟

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

آیا Desktop v2 همان OpenCode v2 است؟

خیر. نام Desktop v2 صرفاً مربوط به پوسته و ظاهر نسخه دسکتاپ در به‌روزرسانی‌های نسخه ۱ بود؛ در حالی که OpenCode v2 یک بازنویسی بنیادین در کل معماری پلتفرم است.

آیا Go همان Zen است؟

خیر. Zen سیستمی اعتباری و مصرفی است، اما Go یک اشتراک ماهانه با هزینه ثابت است. خدمات پیکسول هم بر پایه ارائه اشتراک Go متمرکز است.

آیا برای استفاده از Go حتماً باید به نسخه ۲ ارتقا دهم؟

اصلاً. Go فقط یک ارائه‌دهنده مدل است و ربطی به نسخه نرم‌افزار شما ندارد؛ حتی می‌توانید کلید آن را در ابزارهایی مثل Cursor یا Claude Code نیز استفاده کنید.

تکلیف چت‌ها و سشن‌های قدیمی نسخه ۱ چه می‌شود؟

راهنمای رسمی تضمین نمی‌دهد که تمام تاریخچه سشن‌ها سالم منتقل شود؛ پس حتماً پیش از نصب v2، از داده‌های محلی‌تان کپی بردارید.

منابع رسمی

• سند OpenCode v2

• Migrate from V1

• سند OpenCode

• صفحه‌ی OpenCode Go

• صفحه‌ی OpenCode Zen

• کاتالوگ زنده‌ی پیکسول

مطالب نزدیک: Pi Agent چیست، Prime Agent، بررسی Kimi K3.