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

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

OpenCode یک ایجنت برنامه‌نویسی هوش مصنوعی متن‌باز است که برای ترمینال ساخته شده است. شما آن را در دایرکتوری پروژه اجرا می‌کنید؛ این ابزار کد شما را می‌خواند، تغییرات پیشنهاد می‌دهد، فایل‌ها را ویرایش می‌کند و دستورات را اجرا می‌نماید؛ همه این‌ها از طریق یک رابط کاربری ترمینال (TUI) انجام می‌شود. این پروژه تحت مجوز MIT منتشر شده، به بیش از 75 ارائه‌دهنده مدل متصل می‌شود و تا اواسط سال 2026 با حدود 165,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

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

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

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

پروژه‌هایی که می‌خواهید عامل روی آن‌ها کار کند را در مسیر /home/opencode نگه دارید و آن‌ها را توسط همان کاربر clone کنید. به این حساب کاربری هیچ‌گونه دسترسی sudo ندهید. اگر عامل یک دستور مخرب اجرا کند، فقط می‌تواند آنچه متعلق به همین حساب است را تخریب کند؛ این دقیقاً همان منطقی است که در اجرای سرویس‌ها با کاربر فاقد دسترسی ویژه وجود دارد. همچنین همیشه داخل یک مخزن git کار کنید، زیرا مخزن باعث می‌شود هر ویرایش اشتباه، به یک git revert تبدیل شود و نه از دست رفتن کامل داده‌ها.

نصب OpenCode

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

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

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

opencode --version

اگر مدیریت بسته را ترجیح می‌دهید و Node.js از قبل روی سیستم موجود است، روش npm همان ابزار را به‌صورت سیستمی نصب می‌کند که باینری opencode را برای همه کاربران در PATH قرار می‌دهد:

sudo npm install -g opencode-ai

در هر دو حالت، بررسی یکسان است: opencode --version یک شماره نسخه چاپ می‌کند. خطای command not found پس از اجرای اسکریپت نصب به این معنی است که shell فعلی هنوز PATH به‌روزرسانی‌شده را نخوانده است، بنابراین از سیستم خارج شده و دوباره با کاربر 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-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 دو عامل (agent) ارائه می‌دهد که با کلید Tab بین آن‌ها جابه‌جا می‌شوید: Build، عامل پیش‌فرض با دسترسی کامل، و Plan، که قابلیت ایجاد تغییرات را غیرفعال می‌کند. یک وظیفه جدید را در حالت Plan شروع کنید، اجازه دهید کد را بخواند و رویکردی پیشنهاد دهد، و تنها زمانی که با طرح موافق بودید به Build سوئیچ کنید. روی سرور، یک بررسی اولیه فقط‌خواندنی (read-only) یک بیمه ارزان‌قیمت است. Claude Code همین تصمیم را به جای عامل‌ها، در قالب حالت‌های دسترسی (permission modes) تعریف می‌کند و تغییر آن به حالت خودکار به عنوان پیش‌فرض ارزش مطالعه دارد اگر از هر دو ابزار استفاده می‌کنید، زیرا حالتی که یک نشست در آن شروع می‌شود، تعیین می‌کند که یک عامل نظارت‌نشده تا چه حد می‌تواند تغییرات ایجاد کند.

شعاع انفجار، صادقانه

یک عامل کدنویسی غیرفعال نیست، بنابراین به‌طور واضح بیان کنید که این پیکربندی شامل چه چیزی هست و چه چیزی نیست. این پیکربندی شامل احتمال آسیب به فایل‌ها است: کاربر opencode فقط مالک دایرکتوری home خود است و نه هیچ جای دیگر، بنابراین ویرایش‌ها و حذف‌ها در همان مرز متوقف می‌شوند. این پیکربندی شامل احتمال افشای اعتبارنامه‌ها است: کلید در یک فایل با دسترسی 600 و در یک حساب کاربری قرار دارد. این پیکربندی شامل آنچه حساب کاربری به‌طور قانونی مجاز به انجام آن است نمی‌شود، بنابراین اگر دایرکتوری پروژه حاوی اعتبارنامه‌های استقرار (deploy) محیط production باشد، عامل می‌تواند از آن‌ها استفاده کند؛ این موارد را به‌طور کامل از حساب کاربری عامل دور نگه دارید.

برخلاف یک عامل gateway مانند OpenClaw، برنامه OpenCode یک برنامه ترمینال تعاملی است، نه یک daemon. این برنامه هیچ پورتی را برای گوش دادن باز نمی‌کند و سرویس طولانی‌مدتی ندارد، بنابراین نیازی به نوشتن unit برای systemd یا بستن پورت در فایروال برای خودِ عامل نیست. محدودسازی در سطح حساب کاربری و دایرکتوری پروژه اعمال می‌شود، به همین دلیل است که بخش اول این راهنما مهم‌ترین بخش آن است.

محیط پیرامونی آن همچنان به مراقبت‌های استاندارد نیاز دارد، زیرا یک VPS کدنویسی همچنان یک سرور عمومی محسوب می‌شود: استفاده از SSH فقط با کلید و غیرفعال کردن ورود root، همان‌طور که در سخت‌سازی SSH روی یک VPS آمده است، یک فایروال با سیاست پیش‌فرض deny و به‌روزرسانی‌های روتین. همچنین خروجی‌های عامل را بازبینی کنید. diffهای تولیدشده توسط آن را پیش از push کردن بخوانید، درست همان‌طور که یک pull request از یک مشارکت‌کننده جدید را بررسی می‌کنید، زیرا شما کسی هستید که نتیجه را مستقر (deploy) می‌کنید.

در نهایت، خودِ ابزار را به‌روز نگه دارید. OpenCode به‌طور مرتب نسخه جدید منتشر می‌کند و به‌روزرسانی‌ها شامل اصلاحاتی هستند که برای برنامه‌ای که دستورات را روی سرور شما اجرا می‌کند، اهمیت دارند. برای به‌روزرسانی از همان مسیری استفاده کنید که با آن نصب کرده‌اید: اسکریپت نصب را دوباره با کاربر opencode اجرا کنید، یا اگر از طریق npm نصب کرده‌اید، دستور sudo npm update -g opencode-ai را اجرا کنید، سپس نسخه جدید را با opencode --version تأیید کنید. یک دقیقه نگهداری در هر چند وقت یک‌بار، ارزان‌تر از عیب‌یابی رفتارهایی است که در یک نسخه چند ماه قدیمی، قبلاً اصلاح شده‌اند.

FAQ

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

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

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

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

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

اگر آن را محدود کنید، قابل مدیریت است. یک کاربر بدون امتیاز (unprivileged) اختصاصی بدون دسترسی sudo برای OpenCode ایجاد کنید، پروژه‌های آن را در git نگه دارید تا هر ویرایش قابل بازگشت باشد، کلید API را در فایلی با مجوز 600 ذخیره کنید و پیش از آنکه به عامل Build اجازه تغییر چیزی بدهید، از عامل Plan برای بررسی اولیه فقط-خواندنی استفاده کنید. در این صورت عامل فقط می‌تواند به آنچه متعلق به حساب کاربری خودش است آسیب بزند و بقیه سرور خارج از دسترس باقی می‌ماند.

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

OpenCode متن‌باز (MIT) است و به ارائه‌دهنده خاصی وابسته نیست؛ این ابزار از طریق یک رابط واحد به بیش از 75 ارائه‌دهنده مدل، از جمله مدل‌های محلی، متصل می‌شود. Claude Code عامل ترمینالی اختصاصی Anthropic است که حول مدل‌های خود Anthropic ساخته شده است. اگر به ابزاری نیاز دارید که در میان ارائه‌دهندگان مختلف کار کند یا به دنبال یک پشته کاملاً خود-میزبانی‌شده (self-hosted) با مدل محلی هستید، OpenCode گزینه مناسبی است؛ هر دو روی VPS داخل tmux و با همان تنظیمات کاربر بدون امتیاز، به‌خوبی اجرا می‌شوند.