آموزش نصب و اجرای OpenCode روی VPS

OpenCode چیست و چه چیزی را راه‌اندازی می‌کنید

OpenCode یک ایجنت برنامه‌نویسی هوش مصنوعی متن‌باز است که برای ترمینال ساخته شده است. شما آن را در دایرکتوری پروژه اجرا می‌کنید و این ابزار کد شما را می‌خواند، تغییرات پیشنهاد می‌دهد، فایل‌ها را ویرایش می‌کند و دستورات را اجرا می‌کند؛ همه این‌ها از طریق یک رابط کاربری ترمینال (TUI) انجام می‌شود. این پروژه تحت مجوز MIT است، به بیش از 75 ارائه‌دهنده مدل متصل می‌شود و تا اکتبر 2026 با حدود 219,000 ستاره در GitHub، پرطرفدارترین ایجنت برنامه‌نویسی متن‌باز موجود است. برای اجرای OpenCode روی یک VPS، آن را تحت یک کاربر غیرمجاز (unprivileged) اختصاصی نصب می‌کنید، کلید API مدل خود را در یک فایل خصوصی قرار می‌دهید و آن را داخل tmux اجرا می‌کنید تا نشست (session) با قطع اتصال شما از بین نرود. این راهنما دقیقاً همین کار را به همین ترتیب انجام می‌دهد.

یک نکته در مورد نام‌گذاری برای جلوگیری از سردرگمی: مخزن اصلی anomalyco/opencode است که توسط تیم Anomaly (که قبلاً با نام SST شناخته می‌شد) نگهداری می‌شود و پروژه قبلاً در sst/opencode قرار داشت. یک مخزن قدیمی و نامرتبط به نام opencode-ai/opencode نیز در GitHub وجود دارد که اکنون آرشیو شده است، بنابراین مطمئن شوید که در حال مطالعه مستندات پروژه صحیح هستید. سایت رسمی opencode.ai است.

چرا OpenCode را روی یک VPS اجرا کنیم

نشست‌های کاری یک عامل کدنویسی طولانی هستند. OpenCode ممکن است چندین دقیقه صرف بازنویسی کد یا اجرای مجموعه‌ای از تست‌ها کند؛ اگر این فرآیند روی لپ‌تاپ شما اجرا شود، بستن درب لپ‌تاپ یا قطع شدن Wi-Fi باعث توقف نشست در میانه کار می‌شود. روی یک VPS و درون tmux، عامل پس از قطع اتصال شما به کار خود ادامه می‌دهد و شما می‌توانید بعداً دوباره متصل شوید و نتیجه کار را مشاهده کنید. این همان الگوی اجرای Claude Code روی VPS با استفاده از tmux است و بزرگ‌ترین بهبود در کیفیت تجربه کاربری هنگام انتقال عامل از لپ‌تاپ به سرور محسوب می‌شود.

دلیل دوم، موقعیت مکانی است. یک VPS به کدی که مستقر می‌کنید نزدیک است: مخزن کد، ابزارهای ساخت، پایگاه داده تست و اغلب محیط staging همگی در همان‌جا یا در مجاورت آن قرار دارند. عاملی که کد را ویرایش می‌کند و تست‌ها را اجرا می‌کند، روی ماشینی که تست‌ها واقعاً در آن اجرا می‌شوند، بهترین عملکرد را دارد. از آنجا که این سرور تحت کنترل شماست، می‌توانید عمداً یک محیط ایزوله برای عامل فراهم کنید که در بخش بعدی به آن می‌پردازیم.

اگر هنوز در حال انتخاب ابزار هستید، اجرای یک عامل هوش مصنوعی کدنویسی روی VPS گزینه‌های گسترده‌تری از جمله Aider و Goose را مقایسه می‌کند.

اختصاص یک کاربر مستقل به OpenCode

نقطه شروع صادقانه این است: یک coding agent فایل‌ها را ویرایش می‌کند و commandها را اجرا می‌کند. این وظیفه آن است و هم‌زمان ریسک آن نیز محسوب می‌شود. OpenCode buildها، testها و هر shell commandی را که task به آن نیاز داشته باشد اجرا می‌کند و قضاوت model خوب است، اما بی‌نقص نیست. حساب کاربری‌ای که agent با آن اجرا می‌شود، سقف دسترسی یک command مخرب را تعیین می‌کند؛ بنابراین آن را با root اجرا نکنید و از همان کاربری که سرور را مدیریت می‌کند نیز استفاده نکنید.

برخلاف یک agent پس‌زمینه، OpenCode تعاملی است؛ بنابراین کاربر آن باید shell واقعی و home directory داشته باشد:

sudo useradd --create-home --shell /bin/bash opencode
sudo -iu opencode

پروژه‌هایی را که می‌خواهید OpenCode روی آن‌ها کار کند، زیر /home/opencode و با clone کردن توسط همان کاربر نگه دارید. هیچ sudo rightsی به این حساب ندهید. اگر agent یک command مخرب اجرا کند، فقط می‌تواند چیزهایی را از بین ببرد که مالکیتشان متعلق به همین حساب است؛ این همان منطقی است که در اجرای سرویس‌ها با کاربر غیرمجاز وجود دارد. همچنین داخل یک git repository کار کنید و پیش از سپردن task به agent commit بگیرید، زیرا در این حالت یک ویرایش نامناسب روی workی که commit شده است، با git revert یا git restore قابل بازگشت است، نه آن‌که به از دست رفتن work منجر شود. تغییراتی که هرگز commit نکرده‌اید محافظت نمی‌شوند.

نصب OpenCode

این پروژه چندین روش نصب را مستند کرده است که دو مورد از آن‌ها برای سرور مناسب هستند. اسکریپت نصب سریع‌ترین روش است و اجرای آن به عنوان کاربر opencode باعث می‌شود همه چیز در دایرکتوری home همان کاربر باقی بماند:

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

روال معمول curl | bash در اینجا نیز مانند هر جای دیگری صدق می‌کند: روی سروری که برایتان اهمیت دارد، ابتدا اسکریپت را دانلود کنید، آن را بخوانید و سپس اجرا کنید. پس از نصب، یک shell جدید باز کنید تا تغییرات PATH که توسط نصب‌کننده اعمال شده است، اثر کند، سپس باینری را بررسی کنید:

opencode --version

اگر ترجیح می‌دهید از یک مدیریت بسته استفاده کنید و Node.js از قبل روی سیستم موجود است، روش npm همان ابزار را در پیشوند سراسری (global prefix) npm نصب می‌کند:

sudo npm install -g opencode-ai

با وجود یک Node.js سیستمی، آن پیشوند معمولاً /usr/local یا /usr است که دایرکتوری bin آن در PATH هر کاربری قرار دارد. یک مدیریت نسخه یا یک پیشوند سفارشی، باینری را در جای دیگری قرار می‌دهد، بنابراین اگر نیاز دارید opencode توسط کاربر opencode پیدا شود، ابتدا npm prefix -g را اجرا کنید.

در هر صورت، بررسی یکسان است: opencode --version یک شماره نسخه را چاپ می‌کند. مشاهده command not found پس از نصب اسکریپت به این معنی است که shell فعلی هنوز PATH به‌روزرسانی شده را نخوانده است، بنابراین از سیستم خارج شده و دوباره به عنوان کاربر opencode وارد شوید.

هر دو دستور، سری 1.x از OpenCode را نصب می‌کنند که همچنان نسخه‌های جدید ارائه می‌دهد (نسخه 1.19.3 در 16 اکتبر 2026) و این راهنما همان سری را توصیف می‌کند. OpenCode 2 اکنون به عنوان یک نصب جداگانه از https://opencode.ai/v2/install یا بسته npm @opencode/cli منتشر شده است و متفاوت عمل می‌کند: یک سرور پس‌زمینه مشترک برای هر حساب کاربری، نشست‌ها، مجوزها و اجرای ابزارها را مدیریت می‌کند و ترمینال به آن متصل می‌شود. راهنمای مهاجرت آن توصیه می‌کند قبل از نصب نسخه 2، نصب 1.x که از طریق مدیریت بسته انجام شده را حذف کنید، زیرا هر دو از دستور opencode استفاده می‌کنند.

قرار دادن کلید API در یک فایل خصوصی

OpenCode برای هر ارائه‌دهنده مدلی که استفاده می‌کنید به یک کلید نیاز دارد؛ از آنجا که این کلید می‌تواند منجر به کسر هزینه از حساب شما شود، با آن مانند یک رمز عبور رفتار کنید. فایلی ایجاد کنید که فقط کاربر opencode امکان خواندن آن را داشته باشد، مجوز آن را روی 600 تنظیم کنید و کلید را به‌جای تایپ کردن در دستورات (که باعث ذخیره شدن آن در تاریخچه shell می‌شود)، در آن فایل نگه دارید:

install -m 600 /dev/null ~/opencode.env
nano ~/opencode.env

متغیر مربوط به ارائه‌دهنده خود را در آن قرار دهید، برای مثال ANTHROPIC_API_KEY=... یا معادل آن برای ارائه‌دهنده خود، زیرا OpenCode متغیرهای محیطی استاندارد ارائه‌دهندگان را شناسایی می‌کند. پیش از اجرای agent، فایل را در shell خود بارگذاری کنید:

set -a; source ~/opencode.env; set +a

OpenCode یک جایگزین تعاملی نیز دارد: دستور /connect در داخل TUI، شما را برای افزودن یک ارائه‌دهنده راهنمایی می‌کند و اعتبارنامه را در مسیر ~/.local/share/opencode/auth.json در پوشه خانگی کاربر ذخیره می‌نماید. اگر از این روش استفاده می‌کنید، با دستور chmod 600 ~/.local/share/opencode/auth.json خصوصی بودن فایل را تأیید کنید. هر دو روش کلید را از خط فرمان شما دور نگه می‌دارند؛ یکی را انتخاب کرده و همان را ادامه دهید.

اجرای OpenCode درون tmux

استفاده از tmux دلیل اصلی ارزشمند بودن راه‌اندازی VPS است، زیرا یک نشست (session) در tmux حتی پس از قطع اتصال SSH شما به فعالیت خود ادامه می‌دهد. یک نشست جدید ایجاد کنید، به دایرکتوری پروژه خود بروید و عامل (agent) را اجرا کنید:

tmux new -s opencode
cd ~/my-project
opencode

شما باید رابط کاربری متنی (TUI) را ببینید که یک خط فرمان در پایین و نام پروژه شما در محیط برنامه نمایش داده می‌شود. یک وظیفه را با زبان ساده به آن محول کنید تا شروع به خواندن فایل‌ها و پیشنهاد تغییرات کند. هر زمان که خواستید از محیط خارج شوید، با فشردن Ctrl-b و سپس d نشست را detach کنید؛ در این حالت عامل حتی با بستن لپ‌تاپ شما به کار خود ادامه می‌دهد. برای اتصال مجدد در زمان دیگر از دستور زیر استفاده کنید:

tmux attach -t opencode

نشست، گفتگو و هر وظیفهٔ در حال اجرا دقیقاً در همان وضعیتی که رها کرده بودید باقی می‌مانند. این وضعیت در برابر قطع اتصال مقاوم است، اما با راه‌اندازی مجدد (reboot) سرور از بین می‌رود؛ بنابراین پس از reboot باید یک نشست جدید tmux را به همان روش قبلی ایجاد کنید. هیچ محدودیتی برای باز کردن یک پنجره دوم در tmux و اجرای یک عامل دیگر در کنار عامل اول وجود ندارد، هرچند نشست‌های OpenCode مستقل از یکدیگر باقی می‌مانند، در حالی که نشست‌های Claude Code روی یک سرور می‌توانند برای یکدیگر پیام ارسال کنند که روش متفاوتی برای تقسیم یک کار به دو بخش است.

اتصال به یک مدل

OpenCode نسبت به ارائه‌دهنده مدل بی‌طرف است. این ابزار از AI SDK و کاتالوگ Models.dev برای پشتیبانی از بیش از 75 ارائه‌دهنده استفاده می‌کند، بنابراین همان ابزار با Anthropic، OpenAI، Google و ده‌ها مورد دیگر، از جمله سرورهای محلی، کار می‌کند. روش سریع، استفاده از دستور /connect در داخل TUI است که ارائه‌دهندگان را لیست کرده و اعتبارنامه‌ها را مدیریت می‌کند. برای تنظیماتی که بتوانید آن را commit و بازتولید کنید، یک فایل opencode.json در ریشه پروژه قرار دهید و مدل را به عنوان provider/model-id تنظیم کنید:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5"
}

مدلی را انتخاب کنید که ارائه‌دهنده شما همچنان آن را سرویس‌دهی می‌کند: Anthropic در 15 ژوئن 2026 مدل claude-sonnet-4-20250514 را بازنشسته کرد، بنابراین پیکربندی‌هایی که هنوز از آن نام می‌برند، با خطا مواجه می‌شوند.

یک مدل محلی نیز از طریق همین فایل کار می‌کند، زیرا هر سرور سازگار با OpenAI می‌تواند به عنوان یک ارائه‌دهنده معرفی شود. اگر مدلی را با Ollama روی همان VPS سرویس‌دهی می‌کنید، پیکربندی به API محلی آن اشاره می‌کند و نام مدل همان چیزی است که ollama list روی سیستم شما نشان می‌دهد:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://127.0.0.1:11434/v1" },
      "models": { "your-model-name": { "name": "Local coding model" } }
    }
  }
}

یک عادت داخلی وجود دارد که ارزش پذیرش از همان روز اول را دارد. OpenCode دو ایجنت ارائه می‌دهد که با کلید Tab بین آن‌ها جابه‌جا می‌شوید: Build، ایجنت پیش‌فرض با دسترسی کامل، و Plan، یک ایجنت محدود برای تحلیل که بدون پرسش، از ویرایش فایل‌ها در خارج از دایرکتوری طرح (plan) خودداری می‌کند. البته Plan کاملاً فقط‌خواندنی (read-only) نیست، زیرا همچنان می‌تواند دستورات shell را اجرا کند و یک دستور shell می‌تواند فایل‌ها را تغییر دهد. یک کار جدید را در Plan شروع کنید، اجازه دهید کد را بخواند و رویکردی پیشنهاد دهد، و تنها زمانی که با طرح موافق بودید به Build سوئیچ کنید. اگر می‌خواهید آن مرحله اول واقعاً فقط‌خواندنی باشد، ویرایش‌ها و دستورات shell را برای Plan در opencode.json مسدود کنید، زیرا OpenCode مقدار deny را به عنوان مسدودکننده عمل در نظر می‌گیرد، در حالی که ask فقط از شما تأییدیه می‌خواهد:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": { "edit": "deny", "bash": "deny" }
    }
  }
}

روی یک سرور، مرحله اولی که نتواند چیزی را تغییر دهد، یک بیمه ارزان‌قیمت است. Claude Code همین تصمیم را به عنوان حالت‌های مجوز (permission modes) به جای ایجنت‌ها مطرح می‌کند و تغییر آن به حالت خودکار به عنوان پیش‌فرض ارزش خواندن دارد اگر از هر دو ابزار استفاده می‌کنید، زیرا حالتی که یک نشست در آن شروع می‌شود، تعیین می‌کند که یک ایجنت بدون نظارت چقدر می‌تواند تغییر ایجاد کند.

محدودهٔ آسیب، بدون تعارف

یک coding agent غیرفعال نیست؛ بنابراین باید دقیقاً روشن کنید این setup چه چیزهایی را پوشش می‌دهد و چه چیزهایی را نه. این setup از فایل‌ها در برابر آسیب محافظت می‌کند: کاربر opencode مالک home خودش است و به هیچ مسیر دیگری دسترسی مالکیتی ندارد؛ بنابراین ویرایش‌ها و حذف‌ها در همان مرز متوقف می‌شوند. این setup از credentialها در برابر exposure محافظت می‌کند: key در یک فایل با mode 600 و متعلق به یک account قرار دارد. اما این setup جلوی کارهایی را که account به‌صورت قانونی می‌تواند انجام دهد نمی‌گیرد. بنابراین اگر project directory شامل credentialهای production deploy باشد، agent می‌تواند از آن‌ها استفاده کند؛ این credentialها را کاملاً خارج از account مربوط به agent نگه دارید.

برخلاف یک gateway agent مانند OpenClaw، برنامهٔ OpenCode 1.x یک برنامهٔ تعاملی terminal است، نه یک daemon. به‌صورت پیش‌فرض هیچ listening portی باز نمی‌کند؛ فقط flagهای --port، --hostname یا --mdns باعث می‌شوند TUI روی یک پورت به درخواست‌ها گوش دهد. همچنین سرویس بلندمدتی اجرا نمی‌کند؛ بنابراین برای خود agent نیازی به نوشتن unit برای systemd یا firewall کردن یک پورت وجود ندارد. OpenCode 2 این وضعیت را با shared background server تغییر می‌دهد؛ بنابراین پیش از migration دوباره این نکته را بررسی کنید. containment در اینجا بر اساس user account و project directory است و به همین دلیل نخستین بخش این راهنما بیشترین اهمیت را دارد.

خود سروری که agent روی آن اجرا می‌شود همچنان به مراقبت استاندارد نیاز دارد، چون یک coding VPS همچنان یک public server است: SSH فقط با key، غیرفعال‌بودن root login، مطابق سخت‌سازی SSH در VPS، firewall با سیاست default-deny و updateهای منظم. خروجی agent را نیز بررسی کنید. پیش از push کردن diffها، آن‌ها را بخوانید؛ درست مانند زمانی که pull request یک contributor تازه‌وارد را بررسی می‌کنید، چون deploy نتیجه بر عهدهٔ شماست.

در پایان، خود tool را به‌روز نگه دارید. OpenCode مرتب release می‌شود و updateها fixهای مهمی برای برنامه‌ای دارند که روی سرور شما command اجرا می‌کند. برای update، همان روشی را استفاده کنید که با آن نصب را انجام دادید: install script را دوباره با کاربر opencode اجرا کنید، یا اگر از طریق npm نصب کرده‌اید sudo npm update -g opencode-ai را اجرا کنید؛ سپس نسخهٔ جدید را با opencode --version تأیید کنید. هر دو روش شما را روی خط 1.x نگه می‌دارند؛ مهاجرت به OpenCode 2 فرایندی جداگانه است. گاهی یک دقیقه برای maintenance، از عیب‌یابی رفتاری که یک build چندماه‌قدیمی قبلاً آن را اصلاح کرده است ارزان‌تر تمام می‌شود.

FAQ

آیا OpenCode می‌تواند به‌جای یک API پولی از یک مدل محلی استفاده کند؟

بله. OpenCode هر سرور سازگار با OpenAI را به‌عنوان یک provider در نظر می‌گیرد؛ بنابراین مدلی که Ollama روی همان VPS ارائه می‌کند نیز کار می‌کند: provider را در opencode.json با baseURL محلی و نام مدلی که Ollama گزارش می‌دهد تعریف کنید. نکته مهم سخت‌افزار است، زیرا مدلی که برای کار واقعی برنامه‌نویسی کیفیت کافی داشته باشد به حافظه قابل‌توجهی نیاز دارد. بنابراین پیش از دانلود مدل، سرور را متناسب با آن انتخاب کنید.

چگونه OpenCode را پس از بستن لپ‌تاپم همچنان در حال اجرا نگه دارم؟

آن را داخل tmux روی VPS اجرا کنید. agent را با tmux new -s opencode در یک session نام‌گذاری‌شده اجرا کنید، با Ctrl-b و سپس d از session جدا شوید؛ session پس از پایان اتصال SSH شما همچنان روی سرور اجرا می‌شود. هر زمان خواستید با tmux attach -t opencode دوباره به آن متصل شوید؛ conversation و هر task در حال اجرا همچنان باقی می‌مانند. reboot سرور session را پایان می‌دهد، بنابراین پس از reboot یک session جدید شروع کنید.

آیا اجازه‌دادن به OpenCode برای اجرای commandها روی VPS امن است؟

اگر آن را محدود کنید، مدیریت‌پذیر است. یک user اختصاصی بدون دسترسی sudo و با سطح دسترسی محدود به OpenCode بدهید، پروژه‌های آن را در git نگه دارید و پیش از هر task commit کنید تا بتوانید یک ویرایش نادرست را rollback کنید، API key را در فایلی با mode 600 ذخیره کنید و پیش از آن‌که اجازه دهید Build agent چیزی را تغییر دهد، برای بررسی اولیه از Plan agent استفاده کنید. اگر می‌خواهید این بررسی کاملاً فقط‌خواندنی باشد، ویرایش‌ها و shell commandها را برای Plan روی deny تنظیم کنید. در این حالت agent فقط می‌تواند به مواردی آسیب بزند که متعلق به account خودش هستند و بخش‌های دیگر سرور خارج از دسترس آن باقی می‌مانند.

تفاوت OpenCode و Claude Code چیست؟

OpenCode متن‌باز (MIT) و مستقل از provider است و از طریق یک interface واحد به بیش از 75 model provider، از جمله providerهای محلی، متصل می‌شود. Claude Code، terminal agent اختصاصی Anthropic است که بر مبنای modelهای Anthropic ساخته شده است. اگر می‌خواهید از یک ابزار برای providerهای متعدد استفاده کنید یا یک stack کاملاً self-hosted با model محلی داشته باشید، OpenCode گزینه مناسب‌تری است؛ هر دو ابزار روی VPS و داخل tmux به‌خوبی اجرا می‌شوند و می‌توانند از همان setup مربوط به user بدون دسترسی‌های ممتاز استفاده کنند.