OpenHands چیست؟ آموزش نصب ایجنت برنامه‌نویسی و اتصال به API درواره

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

OpenHands یکی از شناخته‌شده‌ترین پروژه‌های متن‌باز در این گروه است. این ابزار مانند یک ایجنت توسعه نرم‌افزار عمل می‌کند و می‌تواند وظایفی فراتر از تولید یک قطعه کد ساده انجام دهد.

برای مثال می‌توانید به OpenHands بگویید:

این پروژه FastAPI را بررسی کن، برای endpoint ثبت سفارش قابلیت
صفحه‌بندی اضافه کن، تست‌های مربوط را بنویس و پس از اجرای pytest
خطاهای احتمالی را اصلاح کن.

OpenHands می‌تواند فایل‌های مرتبط را پیدا کند، ساختار پروژه را تحلیل کند، تغییرات لازم را اعمال کند، تست‌ها را اجرا کند و نتیجه را در اختیار توسعه‌دهنده قرار دهد.

در این مقاله یاد می‌گیرید:

• OpenHands چیست و چگونه کار می‌کند؟
• تفاوت ایجنت برنامه‌نویسی با دستیار کدنویسی چیست؟
• Agent Canvas چه کاربردی دارد؟
• چگونه OpenHands را با Docker یا uv نصب کنیم؟
• چگونه OpenHands را به API درواره متصل کنیم؟
• چگونه مدل مناسب برنامه‌نویسی را انتخاب کنیم؟
• چگونه یک وظیفه واقعی را به ایجنت بسپاریم؟
• چگونه هزینه و مصرف مدل را مدیریت کنیم؟
• خطاهای متداول OpenHands را چگونه برطرف کنیم؟

OpenHands چیست؟

OpenHands یک پلتفرم متن‌باز برای اجرای ایجنت‌های برنامه‌نویسی است. ایجنت در اینجا به نرم‌افزاری گفته می‌شود که فقط متن تولید نمی‌کند، بلکه می‌تواند برای رسیدن به یک هدف چند اقدام متوالی انجام دهد.

این اقدامات ممکن است شامل موارد زیر باشند:

• مشاهده ساختار مخزن
• خواندن فایل‌های پروژه
• جست‌وجو در کد
• ایجاد یا ویرایش فایل
• اجرای فرمان‌های ترمینال
• نصب وابستگی‌ها
• اجرای تست
• بررسی خطاهای Build
• اصلاح مجدد کد
• آماده‌کردن تغییرات برای بازبینی

نسخه‌های جدید OpenHands از محیطی به نام Agent Canvas برای مدیریت ایجنت‌ها استفاده می‌کنند. براساس مخزن رسمی OpenHands، Agent Canvas یک مرکز کنترل متن‌باز برای اجرای ایجنت‌های کدنویسی و اتوماسیون‌های توسعه نرم‌افزار است.

این پروژه با مجوز MIT منتشر شده و علاوه بر ایجنت OpenHands می‌تواند برای مدیریت بعضی ایجنت‌های سازگار دیگر نیز استفاده شود.

Agent Canvas چیست؟

Agent Canvas رابطی برای ایجاد، اجرا و مدیریت وظایف ایجنت‌های برنامه‌نویسی است. توسعه‌دهنده می‌تواند از طریق آن پروژه را انتخاب کند، مدل هوش مصنوعی را تنظیم کند، وظیفه را توضیح دهد و مراحل اجرای کار را مشاهده کند.

در یک نمای ساده، گردش کار به این شکل است:

توسعه‌دهنده
     ↓
Agent Canvas
     ↓
ایجنت OpenHands
     ↓
مدل هوش مصنوعی
     ↓
فایل‌ها و ترمینال پروژه
     ↓
تست، اصلاح و نتیجه نهایی

مدل هوش مصنوعی تصمیم می‌گیرد چه اقدامی باید انجام شود، اما OpenHands ابزارهای لازم برای مشاهده فایل، ویرایش کد و اجرای فرمان‌ها را فراهم می‌کند.

تفاوت دستیار کدنویسی و ایجنت برنامه‌نویسی

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

OpenHands برای وظایفی مناسب است که نیازمند مشاهده، اقدام، دریافت بازخورد و اصلاح هستند.

OpenHands چه کاربردهایی دارد؟

توسعه قابلیت جدید

می‌توانید شرح یک قابلیت را همراه با معیارهای پذیرش در اختیار ایجنت قرار دهید. OpenHands ساختار پروژه را بررسی می‌کند و تغییرات لازم را در فایل‌های مرتبط انجام می‌دهد.

رفع خطا

ایجنت می‌تواند Stack Trace، تست ناموفق و کد مربوط را بررسی کند و برای رفع علت اصلی خطا تلاش کند.

نوشتن تست

OpenHands می‌تواند تست واحد، تست یکپارچه یا تست رگرسیون بنویسد و آن‌ها را اجرا کند.

بازآرایی کد

برای تقسیم کلاس‌های بزرگ، حذف کد تکراری، بهبود نام‌گذاری یا انتقال منطق به یک سرویس مستقل می‌توان از ایجنت کمک گرفت.

به‌روزرسانی وابستگی‌ها

ایجنت می‌تواند نسخه وابستگی را تغییر دهد، خطاهای ناشی از تغییر نسخه را بررسی کند و بخش‌های ناسازگار کد را اصلاح کند.

آماده‌کردن مستندات

پس از تغییر API یا قابلیت‌های برنامه، می‌توان از OpenHands خواست فایل README و مثال‌های استفاده را نیز به‌روزرسانی کند.

بررسی Issueهای نرم‌افزاری

یک Issue کامل شامل شرح مسئله، رفتار فعلی، رفتار مورد انتظار و معیارهای پذیرش می‌تواند مستقیماً به یک وظیفه اجرایی برای ایجنت تبدیل شود.

آیا OpenHands رایگان و متن‌باز است؟

کد اصلی OpenHands به‌صورت متن‌باز و تحت مجوز MIT در GitHub منتشر شده است. بنابراین می‌توانید نسخه متن‌باز را روی سیستم یا سرور خود اجرا کنید.

بااین‌حال، اجرای OpenHands معمولاً به یک مدل زبانی نیاز دارد. اگر از مدل‌های ارائه‌شده از طریق API استفاده کنید، هزینه براساس مصرف مدل محاسبه خواهد شد.

با استفاده از API درواره می‌توانید:

• یک کلید API دریافت کنید.
• هزینه را به‌صورت ریالی پرداخت کنید.
• مدل‌های مختلف را آزمایش کنید.
• بدون تغییر معماری اصلی، مدل را تعویض کنید.
• مصرف درخواست‌ها را مشاهده کنید.
• از یک آدرس پایه سازگار با OpenAI استفاده کنید.

پیش‌نیازهای نصب OpenHands

روش نصب به سیستم‌عامل و نوع اجرا بستگی دارد. برای اجرای محلی معمولاً به موارد زیر نیاز دارید:

• Docker Desktop یا Docker Engine
• حداقل ۴ گیگابایت حافظه RAM
• Python 3.12 برای نصب با uv
• Git
• یک پروژه برنامه‌نویسی
• کلید API درواره
• شناسه مدل هوش مصنوعی

براساس راهنمای رسمی نصب OpenHands، اجرای محلی در macOS، Linux و Windows با WSL2 امکان‌پذیر است.

برای پروژه‌های متوسط و اجرای هم‌زمان ابزارها، حافظه بیشتر از حداقل اعلام‌شده تجربه مناسب‌تری ایجاد می‌کند.

نصب OpenHands در ویندوز

برای اجرای OpenHands در ویندوز، استفاده از WSL2 و Docker Desktop پیشنهاد می‌شود.

ابتدا PowerShell را با دسترسی Administrator باز کنید:

wsl --install -d Ubuntu

پس از پایان نصب، سیستم را در صورت نیاز راه‌اندازی مجدد کنید. سپس وضعیت WSL را بررسی کنید:

wsl --version

نسخه پیش‌فرض باید WSL2 باشد.

در Docker Desktop موارد زیر را فعال کنید:

• گزینه Use the WSL 2 based engine
• گزینه Enable integration with my default WSL distro

سپس Ubuntu را از منوی Start اجرا کنید. دستورهای نصب و اجرای OpenHands باید داخل ترمینال Ubuntu اجرا شوند.

نصب OpenHands در Linux و macOS با uv

روش پیشنهادی مستندات رسمی برای رابط محلی OpenHands، استفاده از uv است.

ابتدا uv را طبق راهنمای رسمی آن نصب کنید و سپس بنویسید:

uv tool install openhands --python 3.12

برای اجرای رابط OpenHands:

openhands serve

اگر می‌خواهید پوشه فعلی پروژه در اختیار OpenHands قرار گیرد:

openhands serve --mount-cwd

پس از اجرا، آدرس نمایش‌داده‌شده در ترمینال را در مرورگر باز کنید.

برای به‌روزرسانی OpenHands:

uv tool upgrade openhands --python 3.12

نصب با pip

اگر Python 3.12 یا نسخه سازگار را دارید، می‌توانید از pip نیز استفاده کنید:

pip install openhands
openhands serve

استفاده از uv وابستگی‌های OpenHands را بهتر از محیط پروژه اصلی جدا می‌کند.

نصب Agent Canvas

نسخه جدید Agent Canvas امکان مدیریت ایجنت‌های محلی و راه دور را فراهم می‌کند. برای نصب مستقیم آن به Node.js و uv نیاز دارید.

npm install -g @openhands/agent-canvas
agent-canvas

رابط Agent Canvas معمولاً از طریق آدرس زیر در دسترس خواهد بود:

http://localhost:8000

این روش ایجنت را مستقیماً روی سیستم اجرا می‌کند. برای جداکردن محیط اجرای ایجنت از سیستم اصلی، می‌توانید از روش Docker استفاده کنید.

اجرای Agent Canvas با Docker

ابتدا پوشه‌ای برای پروژه‌ها ایجاد کنید:

export PROJECTS_PATH="$HOME/projects"
mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"

سپس Agent Canvas را اجرا کنید:

docker run -it --rm \
  -p 8000:8000 \
  -v "$HOME/.openhands:/home/openhands/.openhands" \
  -v "${PROJECTS_PATH}:/projects" \
  ghcr.io/openhands/agent-canvas:1.20.0

پس از اجرا، رابط را باز کنید:

http://localhost:8000/canvas

نسخه‌های OpenHands و Agent Canvas مرتب تغییر می‌کنند. پیش از استفاده عملی، فرمان و شماره نسخه فعلی را در مخزن رسمی OpenHands بررسی کنید.

تمام پروژه‌هایی که می‌خواهید ایجنت به آن‌ها دسترسی داشته باشد باید داخل مسیر تعیین‌شده قرار بگیرند:

~/projects/
├── shop-api/
├── customer-dashboard/
└── mobile-backend/

اتصال OpenHands به API درواره

آدرس پایه API درواره عبارت است از:

https://api.darvareh.ir/v1

پس از اجرای OpenHands، وارد بخش تنظیمات مدل شوید. نام گزینه‌ها ممکن است با توجه به نسخه کمی متفاوت باشد، اما تنظیمات اصلی شامل Provider، Model، API Key و Base URL هستند.

مقادیر را به شکل زیر وارد کنید:

مقدار YOUR_MODEL_ID را با شناسه دقیق مدل موردنظر جایگزین کنید.

برای مثال ساختار شناسه مدل باید به شکل زیر باشد:

openai/MODEL_ID

پیشوند openai/ به لایه مدیریت مدل OpenHands اعلام می‌کند که درخواست باید با فرمت سازگار با OpenAI ارسال شود.

براساس مستندات پیکربندی مدل OpenHands، Base URL از بخش تنظیمات پیشرفته قابل تعیین است و OpenHands می‌تواند از مدل‌های پشتیبانی‌شده توسط LiteLLM استفاده کند.

برای دریافت کلید و شناسه مدل‌های فعلی، به مستندات API درواره مراجعه کنید.

تنظیم مدل سفارشی در رابط OpenHands

اگر مدل موردنظر در فهرست آماده نمایش داده نمی‌شود:

1. وارد Settings شوید.
2. بخش LLM را باز کنید.
3. تنظیمات Advanced را فعال کنید.
4. در Custom Model شناسه مدل را با پیشوند openai/ وارد کنید.
5. Base URL درواره را وارد کنید.
6. کلید API را ثبت کنید.
7. تنظیمات را ذخیره کنید.
8. یک گفت‌وگوی جدید ایجاد کنید.

نمونه:

Provider: OpenAI
Model: openai/YOUR_MODEL_ID
Base URL: https://api.darvareh.ir/v1
API Key: YOUR_DARVAREH_API_KEY

اگر OpenHands درباره ناشناخته‌بودن مدل هشدار داد، ابتدا یک درخواست ساده آزمایشی ارسال کنید. بعضی مدل‌های سفارشی در فهرست داخلی OpenHands ثبت نشده‌اند، اما از طریق رابط سازگار با OpenAI کار می‌کنند.

پیکربندی با config.toml

OpenHands از فایل config.toml برای تعریف تنظیمات مدل پشتیبانی می‌کند. نمونه ساده:

[llm]
model = "openai/YOUR_MODEL_ID"
api_key = "YOUR_DARVAREH_API_KEY"
base_url = "https://api.darvareh.ir/v1"
temperature = 0.0
num_retries = 4
retry_min_wait = 5
retry_max_wait = 30

برای محیط عملی بهتر است کلید API را مستقیماً داخل فایل قابل ثبت در Git قرار ندهید و آن را از تنظیمات محیط اجرا یا رابط OpenHands دریافت کنید.

دمای پایین برای وظایف برنامه‌نویسی معمولاً خروجی باثبات‌تری ایجاد می‌کند:

temperature = 0.0

OpenHands امکان تعریف چند پیکربندی نام‌گذاری‌شده را نیز دارد. براساس راهنمای Custom LLM Configurations، هر پیکربندی می‌تواند مدل، Base URL، محدودیت توکن و تنظیمات Retry متفاوتی داشته باشد.

نمونه:

[llm]
model = "openai/YOUR_STRONG_MODEL_ID"
base_url = "https://api.darvareh.ir/v1"
temperature = 0.0

[llm.fast]
model = "openai/YOUR_FAST_MODEL_ID"
base_url = "https://api.darvareh.ir/v1"
temperature = 0.0
max_output_tokens = 4000

از مدل اقتصادی‌تر می‌توان برای بررسی ساختار مخزن و تغییرات ساده استفاده کرد. مدل قوی‌تر برای تحلیل معماری، رفع خطاهای پیچیده و وظایف طولانی مناسب‌تر است.

انتخاب مدل مناسب برای OpenHands

ایجنت برنامه‌نویسی به مدلی نیاز دارد که فقط در تولید کد خوب نباشد، بلکه بتواند ابزارها را درست فراخوانی و نتیجه هر مرحله را تحلیل کند.

مدل مناسب باید در موارد زیر عملکرد قابل قبولی داشته باشد:

• پیروی از دستورهای چندمرحله‌ای
• استفاده از ابزارها
• تولید JSON یا فراخوانی ابزار معتبر
• تحلیل Stack Trace
• درک ساختار چندفایلی
• اصلاح کد براساس خروجی تست
• حفظ هدف در گفت‌وگوهای طولانی
• تصمیم‌گیری درباره اقدام بعدی

مدل ارزان اما ضعیف ممکن است با تکرار فرمان‌ها، تغییرات اشتباه یا ناتمام‌گذاشتن وظیفه در نهایت هزینه بیشتری ایجاد کند.

برای ارزیابی، چند وظیفه واقعی و ثابت تعریف کنید:

1. پیدا‌کردن علت یک تست ناموفق
2. اضافه‌کردن اعتبارسنجی به API
3. نوشتن تست رگرسیون
4. بازآرایی یک ماژول
5. به‌روزرسانی مستندات
6. اجرای Build و اصلاح خطاها

سپس کیفیت، زمان انجام، تعداد درخواست‌ها و هزینه مدل‌ها را مقایسه کنید.

آموزش عملی OpenHands با یک پروژه واقعی

فرض کنید یک API فروشگاهی با FastAPI دارید:

shop-api/
├── app/
│   ├── main.py
│   ├── models.py
│   ├── schemas.py
│   ├── services/
│   │   └── orders.py
│   └── routes/
│       └── orders.py
├── tests/
│   └── test_orders.py
├── requirements.txt
└── README.md

هدف این است که قابلیت لغو سفارش اضافه شود.

مرحله اول: آماده‌کردن پروژه

وارد پوشه پروژه شوید:

cd ~/projects/shop-api

وضعیت Git را بررسی کنید:

git status

یک Branch جدید بسازید:

git switch -c feature/cancel-order

تست‌های فعلی را اجرا کنید:

pytest

بهتر است پیش از شروع وظیفه مطمئن شوید تست‌های موجود عبور می‌کنند.

مرحله دوم: بازکردن پروژه در OpenHands

در Agent Canvas پروژه shop-api را انتخاب و یک گفت‌وگوی جدید ایجاد کنید.

مرحله سوم: نوشتن دستور دقیق

قابلیت لغو سفارش را به این پروژه FastAPI اضافه کن.

نیازمندی‌ها:
- مسیر جدید POST /orders/{order_id}/cancel باشد.
- فقط مالک سفارش بتواند آن را لغو کند.
- فقط سفارش دارای وضعیت pending قابل لغو باشد.
- لغو مجدد یک سفارش لغوشده نباید وضعیت را تغییر دهد.
- سفارش ارسال‌شده قابل لغو نباشد.
- ساختار فعلی route، service و schema حفظ شود.
- تست‌های موفق، دسترسی غیرمجاز، سفارش ناموجود و وضعیت نامعتبر نوشته شوند.
- پس از تغییر، pytest را اجرا کن.
- اگر تستی ناموفق شد، علت را بررسی و اصلاح کن.
- در پایان فایل‌های تغییرکرده و نتیجه تست‌ها را خلاصه کن.

این دستور چند ویژگی مهم دارد:

• هدف دقیق است.
• endpoint مشخص شده است.
• قوانین کسب‌وکار تعریف شده‌اند.
• محدودیت معماری مشخص است.
• تست‌های مورد انتظار تعیین شده‌اند.
• خروجی نهایی قابل ارزیابی است.

مرحله چهارم: مشاهده روند اجرا

OpenHands ممکن است اقداماتی مانند موارد زیر انجام دهد:

1. مشاهده ساختار پروژه
2. خواندن Routeهای سفارش
3. بررسی مدل وضعیت سفارش
4. مطالعه تست‌های فعلی
5. اضافه‌کردن منطق لغو
6. اضافه‌کردن endpoint
7. نوشتن تست‌ها
8. اجرای pytest
9. بررسی خطاها
10. اصلاح کد
11. اجرای دوباره تست‌ها
12. ارائه گزارش نهایی

مرحله پنجم: بررسی تغییرات

پس از پایان وظیفه بنویسید:

git diff

سپس تست‌ها را خارج از جلسه ایجنت نیز اجرا کنید:

pytest

اگر پروژه Linter دارد:

ruff check .

یا برای پروژه JavaScript:

npm run lint
npm test
npm run build

چگونه برای OpenHands پرامپت بنویسیم؟

پرامپت ایجنت باید بیشتر شبیه یک Issue کامل نرم‌افزاری باشد تا یک سؤال کوتاه.

ساختار پیشنهادی:

هدف:
چه چیزی باید ساخته یا اصلاح شود؟

وضعیت فعلی:
برنامه اکنون چگونه رفتار می‌کند؟

رفتار مورد انتظار:
خروجی درست چیست؟

محدودیت‌ها:
چه بخش‌هایی نباید تغییر کنند؟

معیار پذیرش:
چگونه می‌توان موفقیت را بررسی کرد؟

فرمان‌های کنترل:
کدام تست، Lint یا Build باید اجرا شود؟

گزارش نهایی:
ایجنت در پایان چه اطلاعاتی ارائه کند؟

نمونه پرامپت رفع خطا

در endpoint ورود، کاربران دارای ایمیل با حروف بزرگ نمی‌توانند
وارد حساب شوند؛ درحالی‌که همان ایمیل با حروف کوچک کار می‌کند.

ابتدا علت را پیدا کن و توضیح کوتاهی ارائه بده. سپس کوچک‌ترین
تغییر ممکن را اعمال کن. ایمیل باید در یک محل استاندارد نرمال‌سازی
شود و رفتار سایر endpointها تغییر نکند.

یک تست رگرسیون اضافه کن و فقط تست‌های authentication را اجرا کن.
در پایان فایل‌های تغییرکرده و نتیجه تست را گزارش بده.

نمونه پرامپت Refactor

منطق محاسبه مبلغ نهایی سفارش در route، service و invoice تکرار شده است.
آن را به یک سرویس مشترک منتقل کن.

خروجی عمومی API نباید تغییر کند.
نام فیلدهای JSON ثابت بمانند.
پیش از تغییر، تست‌های مرتبط را پیدا کن.
پس از Refactor تمام تست‌های سفارش و صورتحساب را اجرا کن.
از تغییر نام یا قالب‌بندی فایل‌های غیرمرتبط خودداری کن.

نمونه پرامپت نوشتن تست

برای کلاس PaymentService تست واحد بنویس.
درگاه واقعی پرداخت نباید فراخوانی شود و باید Mock شود.

سناریوها:
- پرداخت موفق
- پاسخ نامعتبر درگاه
- Timeout
- تکرار callback
- مبلغ ناهماهنگ

ابتدا الگوی تست‌های موجود پروژه را بررسی کن و همان سبک را رعایت کن.

چه وظایفی را نباید یک‌جا به ایجنت بدهیم؟

یک دستور بسیار بزرگ مانند نمونه زیر نتیجه قابل پیش‌بینی ایجاد نمی‌کند:

کل پروژه را بررسی کن، همه خطاها را رفع کن، معماری را بهتر کن،
تست بنویس، رابط کاربری را تغییر بده و مستندات را کامل کن.

بهتر است کار به وظایف مستقل تقسیم شود:

1. اصلاح اعتبارسنجی سفارش
2. نوشتن تست‌های سفارش
3. بازآرایی سرویس سفارش
4. به‌روزرسانی مستندات API
5. بررسی عملکرد Queryها

هر وظیفه باید خروجی و معیار پذیرش مشخص داشته باشد.

کنترل هزینه OpenHands

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

از وظایف محدود شروع کنید

ابتدا یک خطای کوچک یا قابلیت مشخص را انتخاب کنید. پروژه کامل را بدون هدف روشن به ایجنت نسپارید.

مدل مناسب کار را انتخاب کنید

برای جست‌وجوی ساده، تغییر متن یا اصلاح کوچک از مدل اقتصادی استفاده کنید. برای معماری، Debug پیچیده و تغییر چندفایلی سراغ مدل قوی‌تر بروید.

معیار توقف تعریف کنید

در پرامپت مشخص کنید:

اگر پس از دو تلاش تست همچنان ناموفق بود، تغییر بیشتری اعمال نکن
و علت احتمالی و اطلاعات موردنیاز را گزارش بده.

این کار از تکرار بی‌پایان تلاش‌ها جلوگیری می‌کند.

تست‌های مرتبط را اجرا کنید

در مراحل اولیه به‌جای اجرای تمام تست‌های پروژه، مجموعه مرتبط را اجرا کنید:

pytest tests/test_orders.py

پس از تأیید تغییر، کل تست‌ها اجرا شوند:

pytest

مصرف را در پنل بررسی کنید

گزارش مصرف درواره کمک می‌کند تعداد درخواست‌ها و هزینه وظایف مختلف را با یکدیگر مقایسه کنید.

برای اطلاعات بیشتر، مقاله محاسبه هزینه API هوش مصنوعی را مطالعه کنید.

تنظیم Retry و مدیریت خطای Rate Limit

OpenHands در صورت دریافت خطای 429 می‌تواند درخواست را دوباره ارسال کند. تنظیمات مربوط به Retry در فایل config.toml قابل تعریف هستند:

[llm]
num_retries = 4
retry_min_wait = 5
retry_max_wait = 30
retry_multiplier = 2

معنای این تنظیمات:

• num_retries: تعداد تلاش مجدد
• retry_min_wait: حداقل فاصله انتظار
• retry_max_wait: حداکثر فاصله انتظار
• retry_multiplier: ضریب افزایش زمان انتظار

افزایش بیش از حد تعداد Retry ممکن است زمان و هزینه یک وظیفه ناموفق را بیشتر کند.

خطاهای رایج اتصال OpenHands به API درواره

خطای 401 یا Unauthorized

موارد زیر را بررسی کنید:

• کلید API کامل و معتبر باشد.
• کلید در فیلد API Key وارد شده باشد.
• فاصله اضافی ابتدا یا انتهای کلید وجود نداشته باشد.
• حساب دارای اعتبار کافی باشد.

خطای 404 یا Model Not Found

شناسه مدل را با فهرست فعلی مدل‌های درواره تطبیق دهید:

openai/YOUR_MODEL_ID

Base URL نیز باید دقیقاً این مقدار باشد:

https://api.darvareh.ir/v1

خطای Connection Error

ابتدا دسترسی به endpoint را با یک درخواست ساده بررسی کنید:

curl https://api.darvareh.ir/v1/models \
  -H "Authorization: Bearer YOUR_DARVAREH_API_KEY"

اگر درخواست بیرون OpenHands موفق است، Base URL و تنظیمات Provider داخل OpenHands را بررسی کنید.

خطای malformed JSON یا Tool Call

مدل انتخاب‌شده ممکن است در فراخوانی ابزار عملکرد مناسبی نداشته باشد. در این حالت:

• مدل قوی‌تری انتخاب کنید.
• Temperature را کاهش دهید.
• وظیفه را کوچک‌تر کنید.
• دستور را شفاف‌تر بنویسید.
• قابلیت Tool Calling مدل را بررسی کنید.

متوقف‌شدن ایجنت در یک حلقه

برای ایجنت حد تلاش تعیین کنید:

اگر راه‌حل دوم نیز ناموفق بود، اجرای بیشتر را متوقف کن و
گزارشی از اقدام‌ها، خطاها و پیشنهاد مرحله بعد ارائه بده.

اجرا‌نشدن Docker در ویندوز

موارد زیر را بررسی کنید:

wsl --version
docker version

سپس مطمئن شوید WSL Integration در Docker Desktop فعال است و فرمان OpenHands داخل ترمینال Ubuntu اجرا می‌شود.

دیده‌نشدن پوشه پروژه

پروژه باید داخل مسیری باشد که هنگام اجرای Docker Mount شده است:

-v "${PROJECTS_PATH}:/projects"

اگر پروژه خارج از این مسیر باشد، ایجنت آن را مشاهده نخواهد کرد.

OpenHands بهتر است یا Aider؟

هر دو ابزار متن‌باز هستند، اما نوع تعامل آن‌ها متفاوت است.

برای اصلاح سریع چند فایل، Aider ساده‌تر است. برای وظیفه‌ای که شامل تحلیل، اجرای فرمان، تست و چند دور اصلاح می‌شود، OpenHands ساختار ایجنت‌محورتری ارائه می‌کند.

گردش کار پیشنهادی برای تیم‌های برنامه‌نویسی

برای استفاده کنترل‌شده از OpenHands می‌توان این فرایند را اجرا کرد:

1. وظیفه به شکل Issue نوشته شود.
2. معیارهای پذیرش مشخص شوند.
3. یک Branch جدا ساخته شود.
4. تست‌های فعلی اجرا شوند.
5. ایجنت فقط به مخزن موردنیاز متصل شود.
6. مدل متناسب با پیچیدگی کار انتخاب شود.
7. OpenHands تغییرات را اعمال و تست کند.
8. توسعه‌دهنده Diff را بررسی کند.
9. تست، Lint و Build دوباره اجرا شوند.
10. تغییرات از طریق Pull Request بازبینی شوند.

OpenHands می‌تواند زمان اجرای کار را کاهش دهد، اما بررسی انسانی کد و نتیجه نهایی همچنان بخش اصلی فرایند توسعه است.

پرسش‌های متداول

OpenHands چیست؟

OpenHands یک پلتفرم متن‌باز برای اجرای ایجنت‌های برنامه‌نویسی است. این ایجنت‌ها می‌توانند فایل‌ها را بررسی و ویرایش کنند، فرمان‌های ترمینال را اجرا کنند و براساس نتیجه تست‌ها کار را ادامه دهند.

OpenHands همان OpenDevin است؟

OpenHands ادامه پروژه‌ای است که پیش‌تر با نام OpenDevin شناخته می‌شد. نام و معماری پروژه در طول توسعه تغییر کرده و نسخه‌های جدید از Agent Canvas و Agent Server استفاده می‌کنند.

Agent Canvas چیست؟

Agent Canvas رابط مدیریت ایجنت‌های کدنویسی، محیط‌های اجرایی و اتوماسیون‌های توسعه نرم‌افزار است.

آیا OpenHands روی ویندوز نصب می‌شود؟

بله. روش پیشنهادی برای ویندوز استفاده از WSL2 و Docker Desktop است.

آیا OpenHands به کارت گرافیک نیاز دارد؟

برای استفاده از مدل‌های API به کارت گرافیک نیاز ندارید. پردازش مدل روی زیرساخت ارائه‌دهنده انجام می‌شود. کارت گرافیک بیشتر زمانی اهمیت دارد که بخواهید مدل را به‌صورت محلی اجرا کنید.

آیا OpenHands از API سازگار با OpenAI پشتیبانی می‌کند؟

بله. می‌توانید Provider، مدل، API Key و Base URL سفارشی را در تنظیمات LLM مشخص کنید.

چگونه OpenHands را به درواره متصل کنیم؟

مقادیر زیر را در تنظیمات مدل وارد کنید:

Model: openai/YOUR_MODEL_ID
Base URL: https://api.darvareh.ir/v1
API Key: YOUR_DARVAREH_API_KEY

بهترین مدل برای OpenHands چیست؟

بهترین مدل به نوع پروژه، پیچیدگی وظیفه، کیفیت Tool Calling، سرعت و بودجه بستگی دارد. چند مدل را روی وظایف واقعی و یکسان مقایسه کنید.

چرا هزینه OpenHands از یک درخواست چت بیشتر است؟

زیرا ایجنت ممکن است برای مشاهده پروژه، تصمیم‌گیری، ویرایش، اجرای تست و اصلاح خطا چندین درخواست جداگانه برای مدل ارسال کند.

آیا OpenHands خودش Commit می‌سازد؟

نوع رفتار Git به نسخه، Agent و تنظیمات گردش کار بستگی دارد. حتی اگر ایجنت Commit ایجاد کند، باید Diff و پیام Commit پیش از Merge بررسی شوند.

جمع‌بندی

OpenHands یک ایجنت برنامه‌نویسی متن‌باز است که می‌تواند فراتر از تولید کد عمل کند. این ابزار پروژه را بررسی می‌کند، فایل‌ها را تغییر می‌دهد، فرمان اجرا می‌کند، نتیجه تست را می‌خواند و برای تکمیل یک هدف چند مرحله متوالی انجام می‌دهد.

برای اتصال OpenHands به درواره کافی است در تنظیمات LLM این مقادیر را وارد کنید:

Provider: OpenAI Compatible
Model: openai/YOUR_MODEL_ID
Base URL: https://api.darvareh.ir/v1
API Key: YOUR_DARVAREH_API_KEY

برای استفاده موفق:

1. وظیفه را دقیق و محدود تعریف کنید.
2. معیارهای پذیرش بنویسید.
3. کار را در یک Branch جدا انجام دهید.
4. مدل مناسب Tool Calling انتخاب کنید.
5. تست و Lint را جزئی از دستور قرار دهید.
6. برای تلاش‌های ناموفق حد توقف تعیین کنید.
7. Diff و نتیجه نهایی را بررسی کنید.
8. هزینه هر نوع وظیفه را اندازه‌گیری کنید.

برای دریافت کلید API، مشاهده مدل‌های موجود و شروع اتصال می‌توانید به مستندات API درواره مراجعه کنید.

مقالات مرتبط

• برنامه‌نویسی با هوش مصنوعی و ابزارهای متن‌باز
• ساخت ایجنت هوش مصنوعی با Python و FastAPI
• راهنمای کامل API سازگار با OpenAI
• آموزش Docker و Docker Compose
• رفع خطا و دیباگ کد با هوش مصنوعی
• تولید تست نرم‌افزار با هوش مصنوعی
• محاسبه هزینه API هوش مصنوعی

منابع

• مستندات رسمی OpenHands
• راهنمای نصب محلی OpenHands
• راهنمای پیکربندی مدل در OpenHands
• تنظیم مدل‌های سفارشی OpenHands
• مخزن OpenHands در GitHub
• مستندات API درواره

این مقاله صرفاً با هدف آموزش و اطلاع‌رسانی تهیه شده است. پیش از استفاده عملی، مستندات رسمی سرویس‌ها و صفحه سلب مسئولیت را مطالعه کنید.