نصب و اجرای OpenCode روی VPS

OpenCode چیست و چه چیزی را در حال راه‌اندازی هستید

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

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

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

جلسات یک عامل کدنویسی (coding agent) طولانی هستند. OpenCode ممکن است چندین دقیقه را صرف بازنویسی کد (refactor) یا اجرای مجموعه تست‌ها کند. اگر این فرآیند روی لپ‌تاپ شما اجرا شود، بستن درب لپ‌تاپ یا قطع شدن اتصال Wi-Fi باعث توقف عملیات در میانه کار می‌شود. اما اگر روی یک VPS و داخل tmux اجرا شود، عامل پس از قطع اتصال شما به کار خود ادامه می‌دهد و شما می‌توانید بعداً با اتصال مجدد (reattach)، نتایج کار را مشاهده کنید. این دقیقاً مشابه الگوی running Claude Code on a VPS with tmux است و بزرگترین مزیت برای راحتی کار در انتقال عامل از لپ‌تاپ به سرور محسوب می‌شود.

دلیل دوم، محل قرارگیری است. یک VPS به کدی که مستقر (deploy) می‌کنید بسیار نزدیک است: مخزن کد (repository)، ابزارهای ساخت (build tools)، پایگاه داده تست و اغلب محیط Staging همگی در آنجا یا در نزدیکی آن قرار دارند. عاملی که کد را ویرایش کرده و تست‌ها را اجرا می‌کند، بهترین عملکرد را روی همان سیستمی دارد که تست‌ها در آن اجرا می‌شوند. همچنین، چون این سیستم یک سرور تحت کنترل شماست، می‌توانید آگاهانه یک محیط ایزوله و محدود برای عامل فراهم کنید که در بخش بعدی به آن پرداخته شده است.

اگر هنوز در حال انتخاب ابزار هستید، مقاله running a coding AI agent on a VPS ابزارهای مختلف از جمله Aider و Goose را با هم مقایسه می‌کند.

اختصاص یک کاربر مجزا به OpenCode

واقعیت این است: یک عامل کدنویسی (coding agent) فایل‌ها را ویرایش و دستورات را اجرا می‌کند. این وظیفه آن است و در عین حال، ریسک کار نیز همین‌جاست. OpenCode فرآیندهای ساخت (builds)، تست‌ها و هر دستور shell که برای انجام وظیفه لازم باشد را اجرا می‌کند؛ قضاوت مدل خوب است اما کامل نیست. سطح دسترسی حسابی که عامل با آن اجرا می‌شود، سقفِ میزان آسیب یک دستور اشتباه است؛ بنابراین، آن را با کاربر root اجرا نکنید و با کاربری که مدیریت سرور را بر عهده دارد نیز اجرا نکنید.

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

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

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

Install OpenCode

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

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

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

opencode --version

اگر از package manager استفاده می‌کنید و Node.js قبلاً روی سیستم نصب شده است، روش npm ابزار را به صورت system-wide نصب می‌کند. در این حالت، binary مربوط به opencode برای تمام کاربران در PATH قرار می‌گیرد:

sudo npm install -g opencode-ai

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

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

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

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 در home کاربر ذخیره می‌کند. اگر از این روش استفاده کردید، با دستور chmod 600 ~/.local/share/opencode/auth.json از خصوصی بودن فایل اطمینان حاصل کنید. هر دو روش از قرارگیری key در خط فرمان جلوگیری می‌کنند؛ یکی را انتخاب کرده و از آن روش ثابت بمانید.

Start OpenCode inside tmux

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

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

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

tmux attach -t opencode

session، گفتگو و هر وظیفه در حال اجرا، دقیقاً در همان وضعیتی که رها کرده بودید باقی می‌مانند. این وضعیت در برابر قطع اتصال مقاوم است، اما در صورت ریبوت شدن سرور از بین می‌رود؛ بنابراین پس از ریبوت، باید یک session جدید در tmux را به همان روش قبلی ایجاد کنید.

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

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، که agent پیش‌فرض با دسترسی کامل است، و Plan، که قابلیت اعمال تغییرات را غیرفعال می‌کند. یک تسک جدید را در حالت Plan شروع کنید، اجازه دهید کد را بخواند و یک رویکرد پیشنهاد دهد، و تنها زمانی به حالت Build جابجا شوید که با برنامه موافق باشید. در یک سرور، استفاده از حالت read-only در مرحله اول، یک راهکار امن و کم‌هزینه است.

محدوده آسیب (Blast Radius)

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

برخلاف یک عامل دروازه‌ای (gateway agent) مانند OpenClaw، برنامه OpenCode یک برنامه ترمینال تعاملی است، نه یک daemon. این برنامه هیچ پورت شنودکننده‌ای (listening port) باز نمی‌کند و هیچ سرویس با مدت‌زمان اجرای طولانی ندارد؛ بنابراین نیازی به نوشتن unit برای systemd و یا بستن پورت در firewall برای خودِ عامل نیست. محدودسازی (containment) در سطح حساب کاربری و دایرکتوری پروژه انجام می‌شود، به همین دلیل است که بخش اول این راهنما مهم‌ترین بخش است.

با این حال، همچنان باید به این محیط توجه ویژه‌ای داشت، زیرا یک VPS مخصوص کدنویسی همچنان یک سرور عمومی است: استفاده از SSH فقط با کلید (key-only) و غیرفعال کردن ورود root، مشابه آنچه در SSH hardening on a VPS آمده است، استفاده از firewall با سیاست default-deny، و به‌روزرسانی‌های منظم. همچنین خروجی عامل را بررسی کنید. قبل از push کردن، diffها را بخوانید؛ دقیقاً همان‌طور که یک pull request از یک مشارکت‌کننده جدید را می‌خوانید، زیرا شما مسئول استقرار (deploy) نتیجه نهایی هستید.

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

FAQ

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

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

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

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

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

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

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

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