OpenHands چیست؟ آموزش نصب محلی در ویندوز با WSL و Docker

یک Agent توسعه نرم‌افزار فقط متن تولید نمی‌کند؛ ممکن است Repository را بخواند، فایل بسازد، فرمان Shell اجرا کند، Dependency نصب کند و نتیجه Test را تحلیل کند. بنابراین نصب آن با نصب یک Chat ساده فرق دارد: باید بدانیم کد کجا Mount شده، فرمان در چه محیطی اجرا می‌شود، چه Credentialهایی در دسترس است و چه عملیاتی به تأیید انسان نیاز دارد.

OpenHands پلتفرمی متن‌باز برای Agentهای توسعه نرم‌افزار است. در این راهنما نسخه محلی GUI را روی ویندوز با WSL2 و Docker راه‌اندازی می‌کنیم. ابتدا بدون پروژه حساس اجرا می‌کنیم، سپس یک Repository آزمایشی را به Sandbox متصل و تنظیم مدل و امنیت را بررسی می‌کنیم.

OpenHands چیست؟

OpenHands محیطی برای اجرای Agentهای توسعه نرم‌افزار است که می‌توانند کد را ویرایش، فرمان اجرا و ابزارهای مختلف را فراخوانی کنند. تجربه محلی شامل یک رابط وب و Agent Server است؛ Runtime کارها معمولاً در Sandbox اجرا می‌شود تا محیط قابل تکرار و محدودتر از سیستم میزبان باشد.

OpenHands خودش مدل زبانی نیست. برای تصمیم‌گیری Agent باید Provider و Model مناسب را تنظیم کنید یا از مدل محلی سازگار استفاده کنید. قدرت و هزینه، طول Context و کیفیت Tool Calling به مدل انتخابی وابسته است.

روش‌های اجرای OpenHands

برای یادگیری، Local GUI قابل مشاهده و مناسب است. Headless را زمانی استفاده کنید که Prompt، Permission، Logging و Rollback قبلاً در محیط ایزوله آزمایش شده باشند.

معماری محلی و مرز اعتماد

GUI در Browser باز می‌شود، Agent Server گفتگو و Toolها را مدیریت می‌کند و Sandbox فرمان‌ها را اجرا می‌کند. هر Volume که از Host به Container با حالت Read/Write Mount شود، از داخل Sandbox قابل تغییر است. پس Docker Sandbox خطر را کاهش می‌دهد، اما Mount گسترده می‌تواند مرز را دوباره باز کند.

• فقط Repository لازم را Mount کنید.
• Home، پوشه اسناد، SSH و Credential Store را Mount نکنید.
• پورت رابط را بی‌دلیل روی شبکه عمومی منتشر نکنید.
• Docker Socket دسترسی پرقدرتی است و باید طبق روش رسمی و روی سیستم قابل اعتماد استفاده شود.
• برای نخستین اجرا از Repository ساختگی یا Clone بدون Secret استفاده کنید.

پیش‌نیاز ویندوز

طبق مستندات رسمی، Windows به WSL2، یک Distribution مانند Ubuntu و Docker Desktop با WSL Integration نیاز دارد. Virtualization سخت‌افزار باید فعال باشد. نصب WSL یا Docker ممکن است Restart بخواهد؛ پیش از آن فایل‌های باز را ذخیره کنید.

wsl --versionwsl --statuswsl --list --verbosedocker version

Distribution باید Version 2 باشد. در Docker Desktop گزینه WSL 2 engine و Integration با Ubuntu را فعال کنید. فرمان‌های نصب و اجرای OpenHands در Windows باید داخل Terminal اوبونتوی WSL اجرا شوند، نه در Command Prompt معمولی.

بررسی Docker داخل WSL

docker versiondocker context showdocker run --rm hello-world

اگر Docker از داخل WSL دیده نمی‌شود، Integration همان Distribution را بررسی کنید. Socket را با Permission عمومی یا راه‌حل‌های موقت ناامن باز نکنید.

نصب OpenHands با uv

مستندات رسمی Launcher مبتنی بر uv را برای تجربه محلی پیشنهاد می‌کنند. uv ابزار را از Virtual Environment پروژه جدا می‌کند. نسخه فعلی OpenHands به Python 3.12 برای این مسیر نیاز دارد؛ نسخه دقیق را همیشه در صفحه رسمی بررسی کنید.

uv --versionuv tool install openhands --python 3.12openhands --helpopenhands serve

Launcher نیازهای Docker را بررسی، Imageهای لازم را دریافت و GUI را روی localhost:3000 اجرا می‌کند. اگر پورت اشغال است، Process موجود را شناسایی کنید؛ سرویس ناشناخته را کورکورانه متوقف نکنید. برای نخستین اجرا هنوز گزینه Mount کردن Directory جاری را ندهید.

چرا فرمان Docker را از مقاله قدیمی کپی نکنیم؟

Image Tag، نام Registry و متغیرهای Runtime ممکن است با Release تغییر کنند. فرمان نسخه‌دار را از مستندات رسمی همان روز بردارید و پس از خواندن Volume، Port، Environment و Docker Socket اجرا کنید. استفاده از latest یا pull=always بدون ثبت نسخه Reproducibility را کاهش می‌دهد.

بازکردن GUI و تنظیم مدل

پس از اجرای Launcher، آدرس localhost:3000 را باز کنید. در Setup اولیه Provider، Model و Credential متناظر را تعیین می‌کنید. اگر مدل در فهرست نیست، Advanced Settings امکان نام Model و Base URL را می‌دهد.

API Key را در Screenshot، Issue یا فایل Repository نگذارید. Credential باید در Settings یا Secret Store مورد اعتماد باشد. حساب Provider را با سقف هزینه و Scope حداقلی بسازید و Usage را پایش کنید. Search Engine و MCP را فقط وقتی فعال کنید که Task به آن‌ها نیاز دارد.

مدل محلی

OpenHands می‌تواند به مدل محلی سازگار متصل شود، اما Agentic Coding به Context، Tool Calling و توان استدلال قابل توجه نیاز دارد. مدل کوچک ممکن است فرمان نادرست یا Loop طولانی بسازد. Server محلی را روی localhost نگه دارید و بدون Authentication روی LAN یا اینترنت باز نکنید. برای آماده‌سازی مدل می‌توانید آموزش Ollama در ویندوز را ببینید.

Mount کردن Repository آزمایشی

ابتدا یک Clone تمیز با Test سبز آماده کنید. سپس از ریشه همان Repository در WSL، Launcher را با mount-cwd اجرا کنید. هر فایل داخل Directory ممکن است توسط Agent خوانده یا با Mount Read/Write تغییر کند.

cd ~/projects/demo-apigit statusgit switch -c feature/openhands-demonpm testopenhands serve --mount-cwd

Mount کردن کل Drive ویندوز، Home یا پوشه اسناد ممنوع نیست از نظر فنی، اما دامنه خطر را بی‌دلیل بزرگ می‌کند. فقط پروژه هدف را متصل کنید و فایل‌های env، SSH Key و Cloud Credential را خارج نگه دارید.

نخستین Task امن

Task را کوچک و قابل آزمون تعریف کنید: «یک Test برای نام خالی اضافه کن و سپس Validation لازم را پیاده‌سازی کن؛ Dependency و Schema تغییر نکند». معیار پذیرش و فایل‌های خارج از Scope را بنویسید. از Agent بخواهید پیش از تغییر Plan را نشان دهد.

• یک Goal در هر Conversation
• فایل‌ها و Layerهای مجاز مشخص
• فرمان Test رسمی Repository
• ممنوعیت Deploy، Push و Migration
• گزارش نهایی شامل Diff و نتیجه Test

اگر Agent فرمانی برای نصب Package، حذف فایل یا تغییر Permission پیشنهاد کرد، علت و دامنه را بررسی کنید. متن داخل Repository یا صفحه وب نمی‌تواند به‌جای شما مجوز بدهد.

Sandbox چه چیزی را حل می‌کند؟

Sandbox لایه دفاعی است، نه تضمین. نسخه Image را ثابت، Mount را محدود، Credential را کوتاه‌عمر و تأیید عملیات را فعال نگه دارید.

Confirmation و تحلیل ریسک

SDK رسمی سه Policy کلی AlwaysConfirm، NeverConfirm و ConfirmRisky را مستند می‌کند. برای یادگیری و Repository واقعی، تأیید گسترده نقطه شروع محافظه‌کارانه‌تری است. NeverConfirm فقط در محیط دورریختنی بدون Secret، شبکه حساس و Mount ارزشمند قابل دفاع است.

Security Analyzer می‌تواند سطح ریسک Action را ارزیابی کند، اما تصمیم مدل یا Analyzer جای Policy قطعی را نمی‌گیرد. فرمان Push، انتشار Package، تغییر Cloud، عملیات مالی یا حذف داده باید بیرون از خودمختاری عادی Agent بماند.

مدیریت Log و داده

Debug کامل ممکن است Prompt، Response، مسیر فایل و خروجی فرمان را ذخیره کند. DEBUG_LLM یا LOG_ALL_EVENTS را بدون نیاز در پروژه حساس فعال نکنید. Retention، Permission فایل Log و روش حذف آن را مشخص کنید. Token و PII را پیش از Logging Redact کنید.

پوشه تنظیمات و History محلی را Backup یا Sync عمومی نکنید. اگر سیستم چندکاربره است، دسترسی فایل‌ها را محدود و Session را پس از کار حساس پاک‌سازی کنید.

Workflow روزانه پیشنهادی

1. نسخه OpenHands و Image را ثبت کنید.
2. Repository تمیز و Branch جدا بسازید.
3. Test پایه را پیش از Agent اجرا کنید.
4. فقط Directory پروژه را Mount کنید.
5. Provider کم‌دسترسی و Model مشخص تنظیم کنید.
6. Task کوچک با معیار پذیرش بنویسید.
7. Plan و هر Action پرریسک را بررسی کنید.
8. Git Diff، Lint و Test را مستقل اجرا کنید.
9. Container و Port را پس از پایان ببندید.
10. Pull Request را به Review انسانی بدهید.

برای مقایسه با Workflow سبک‌تر Terminal، آموزش Aider AI را ببینید. برای اصول کلی همکاری امن با Agent نیز راهنمای وایب کدینگ امن مفید است.

خطاهای رایج

چک‌لیست پیش از استفاده روی کد واقعی

1. فقط Repository هدف با Mount دقیق در دسترس است.
2. فایل env و کلیدها داخل Workspace نیستند.
3. GUI فقط روی Interface لازم قابل دسترسی است.
4. Version ابزار و Image ثبت شده است.
5. Branch جدا و Baseline تست موجود است.
6. تأیید Actionهای حساس فعال است.
7. Provider سقف هزینه و Credential محدود دارد.
8. Log حاوی Secret یا PII نیست.
9. Diff و Test مستقل از Agent بررسی می‌شوند.
10. هیچ دسترسی Production در Sandbox وجود ندارد.

جمع‌بندی

OpenHands محیط قدرتمندی برای Agent توسعه نرم‌افزار ارائه می‌دهد، اما قدرت آن از دسترسی به فایل، Shell و شبکه می‌آید. نصب امن یعنی مرزها را قبل از Prompt تعریف کنیم: WSL2 و Docker سالم، Launcher رسمی، Image مشخص، Mount محدود، Credential کوتاه‌عمر و تأیید انسانی.

با پروژه ساختگی شروع کنید، سپس یک Repository کم‌ریسک را به Sandbox بدهید. اگر Workflow Plan، Diff، Test و Rollback پایدار شد، دامنه استفاده را مرحله‌ای گسترش دهید.

یک Repository آزمایشی بدون Secret بساز، OpenHands را بدون Mount گسترده اجرا کن و نخستین Task را فقط با یک تغییر قابل آزمون تمرین کن.

منابع رسمی

• OpenHands Quick Start
• Local Setup
• Configure GUI
• Docker Sandbox
• CLI Installation
• Security and Action Confirmation
• مخزن رسمی OpenHands