OpenHands — وكيل الذكاء الاصطناعي الذي يعمل في الطرفية بدلًا عنك
يقوم OpenHands على بنية بسيطة: خادم ويب يُنسّق وكيلًا أو أكثر من وكلاء نماذج اللغة الكبيرة، يعمل كل منهم داخل حاوية Docker مؤقتة معزولة. يمتلك الوكيل صدفة (shell) وصلاحية الوصول إلى نظام الملفات، واتصالًا بواجهة برمجة تطبيقات GitHub، وحلقة استدلال تتناوب بين قراءة الكود والتخطيط والتنفيذ.
يقيس معيار SWE-bench Verified قدرة الوكيل على حل مشكلات GitHub الحقيقية دون مساعدة بشرية. في أبريل 2025، حقق OpenHands مقترنًا بـ Claude Sonnet نسبة 60.6% على هذا المعيار في مسار واحد، و66.4% مع خمس محاولات ونموذج ناقد. تحت رخصة MIT المفتوحة، يمكنك استضافته وتعديله ودمجه في أدواتك الداخلية دون قيود تجارية. الإصدار v1.23.0 صدر في 23 سبتمبر 2026 ويتضمن دعم خوادم MCP البعيدة ومزامنة Git لمشرفي المنظمات.
ما يستطيع OpenHands فعله بمفرده
- إصلاح خطأ موثق: يقرأ الوكيل مشكلة GitHub، يحدد الكود المعطوب، يكتب الإصلاح، يشغّل الاختبارات الحالية ويفتح طلب سحب مع رسالة commit توضيحية.
- إضافة مجموعة اختبارات: انطلاقًا من وحدة غير مغطاة، يُنشئ الوكيل اختبارات وحدة أو تكامل متوافقة مع الإطار الموجود (pytest أو PHPUnit أو Jest…).
- إعادة هيكلة الكود: استخراج دالة، إعادة تسمية المتغيرات لاتباع الاتفاقيات، نقل وحدة نحو بنية أكثر وضوحًا.
- إكمال التوثيق: إنشاء أو تحديث docstrings وملفات README وأمثلة استخدام واجهة برمجة التطبيقات انطلاقًا من الكود المصدري.
- تحليل مستودع غير مألوف: إنتاج تقرير هيكلي، تحديد التبعيات الحرجة، رسم خرائط تدفق البيانات بين الوحدات.
- فتح وصف طلب سحب: إنشاء العنوان وجسم طلب السحب مع شرح التغييرات والاختبارات الناجحة وتعليمات المراجعة للفريق.
المتطلبات الرقمية قبل التثبيت
OpenHands هو منسق خفيف الوزن، لكنه يُنشئ حاويات sandbox لكل مهمة. تتفاوت المتطلبات بحسب نموذج اللغة الكبيرة المختار.
الحد الأدنى من الأجهزة (واجهة برمجة سحابية — Claude أو GPT-4 أو Gemini):
- ذاكرة RAM: 4 جيجابايت كحد أدنى، 8 جيجابايت للمهام المتزامنة
- معالج: 2 vCPU كحد أدنى، 4 vCPU لتجربة سلسة
- تخزين: 20 جيجابايت حرة (صور Docker ومساحات عمل المشاريع)
- نظام التشغيل: Linux مع Docker 24+ (يُنصح بـ Ubuntu 22.04 LTS أو Debian 12)
الأجهزة عند الدمج مع Ollama (نموذج محلي):
- ذاكرة RAM: 16 جيجابايت كحد أدنى
- ذاكرة GPU: اختيارية لكن يُوصى بها بشدة — بدون GPU يكون الاستدلال أبطأ 10 إلى 30 مرة
- تخزين: 40 جيجابايت حرة (نماذج Ollama و Docker)
إصدارات البرامج:
- Docker Engine 24.0 أو أحدث (تحقق بـ docker --version)
- Docker Compose v2 (مضمّن في Docker Desktop وDocker Engine 24+)
- Linux kernel 5.4+ (مطلوب لعزل sandbox)
تثبيت OpenHands على VPS في 8 خطوات
تثبيت Docker Engine على خادم VPS
على Ubuntu 22.04 أو Debian 12، ثبّت Docker بالسكريبت الرسمي:
curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER newgrp dockerتحقق من التثبيت:
docker --version docker compose versionإنشاء دليل العمل
أنشئ مجلدًا مخصصًا لـ OpenHands وبياناته الدائمة:
mkdir -p /opt/openhands/.openhands cd /opt/openhandsيخزن مجلد
.openhands الإعدادات الدائمة: مفاتيح API وسجل المحادثات وإعدادات الوكيل.تشغيل OpenHands مع Docker
شغّل OpenHands بالأمر الرسمي:
docker run -it --rm --pull=always \ -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:latest \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /opt/openhands/.openhands:/.openhands \ -p 127.0.0.1:3000:3000 \ --add-host host.docker.internal:host-gateway \ --name openhands-app \ docker.all-hands.dev/all-hands-ai/openhands:latestيضمن
--pull=alwaysتشغيل أحدث صورة مستقرة. OpenHands متاح علىhttp://localhost:3000.بديل: النشر باستخدام Docker Compose
لإدارة أبسط، أنشئ ملف
compose.ymlفي/opt/openhands:services: openhands: image: docker.all-hands.dev/all-hands-ai/openhands:latest container_name: openhands-app pull_policy: always ports: - "127.0.0.1:3000:3000" volumes: - /var/run/docker.sock:/var/run/docker.sock - ./.openhands:/.openhands extra_hosts: - host.docker.internal:host-gateway restart: unless-stoppedشغّل المجموعة:
docker compose up -d docker compose logs -fضبط نموذج اللغة في الواجهة
افتح
http://localhost:3000(أو نطاقك بـ HTTPS). عند الإطلاق الأول، يطلب OpenHands:1. مزود نموذج اللغة: اختر
AnthropicأوOpenAIأوGoogleأوopenai-compatibleلـ Ollama
2. النموذج:claude-sonnet-4-5(أفضل نسبة جودة/تكلفة) أوclaude-opus-4-5للمهام المعقدة
3. مفتاح API: الصق مفتاح Anthropic أو OpenAIتُحفظ هذه الإعدادات في
~/.openhands/config.tomlوتستمر عبر عمليات إعادة التشغيل.ربط OpenHands بـ GitHub
لتمكين OpenHands من استنساخ المستودعات الخاصة وقراءة المشكلات وفتح طلبات السحب، أعدّ رمز وصول شخصي من GitHub:
1. على GitHub: الإعدادات ← أدوات المطور ← رموز الوصول الشخصية ← رموز دقيقة الضبط
2. امنح الأذونات:Contents(قراءة/كتابة)،Pull requests(قراءة/كتابة)،Issues(قراءة)
3. في واجهة OpenHands: الإعدادات ← Git ← الصق الرمزإعداد الوكيل العكسي Nginx مع HTTPS
لا تعرّض المنفذ 3000 مباشرة أبدًا. استخدم Nginx كوكيل عكسي:
server { listen 443 ssl; server_name openhands.your-domain.com; ssl_certificate /etc/letsencrypt/live/openhands.your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/openhands.your-domain.com/privkey.pem; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_http_version 1.1; proxy_read_timeout 600s; } }احصل على الشهادة:
certbot --nginx -d openhands.your-domain.comاختبار أول مهمة
افتح الواجهة، الصق رابط مشكلة GitHub (مثل
https://github.com/your-org/your-repo/issues/42) في حقل المهمة وانقر ابدأ.سيقوم OpenHands بـ:
1. قراءة المشكلة والتخطيط للنهج
2. استنساخ المستودع في sandbox
3. استكشاف الكود وكتابة التعديلات
4. تشغيل الاختبارات (pytestأوnpm test…)
5. عرض ملخص واقتراح فتح طلب سحب
ضبط الواجهة الخلفية للذكاء الاصطناعي: Claude أو GPT-4 أو Ollama
يدعم OpenHands أي مزود متوافق مع واجهة برمجة OpenAI، فضلًا عن المزودين الأصليين Anthropic وGoogle وAzure. اختيار النموذج هو العامل الأكبر تأثيرًا على جودة النتائج.
Claude Sonnet (Anthropic) — الموصى به للإنتاج
يقدم claude-sonnet-4-5 أفضل نسبة جودة/تكلفة لهندسة البرمجيات الوكيلية. تتيح له نافذة سياق 200,000 رمز تحليل قواعد بيانات ضخمة دون تقسيم. توقع إنفاق بضعة سنتات من الدولار لكل مهمة بحسب التعقيد. اضبط LLM_MODEL=anthropic/claude-sonnet-4-5.
Claude Opus (Anthropic) — للمهام المعقدة
يقدم claude-opus-4-5 أداءً أفضل على المشكلات المعمارية وإعادة الهيكلة الشاملة، لكن بتكلفة أعلى 5 إلى 10 أضعاف من Sonnet. احتفظ به للمهام التي تتخطى قدرات Sonnet.
Ollama (نموذج محلي) — للسيادة الكاملة
إذا كان كودك حساسًا أو تريد صفر اعتماد خارجي، اربط OpenHands بـ Ollama على الخادم نفسه. اضبط LLM_BASE_URL=http://host.docker.internal:11434 وLLM_MODEL=openai/qwen2.5-coder:32b. نماذج qwen2.5-coder 32B تحقق أفضل النتائج بين النماذج المفتوحة الأوزان على معايير البرمجة.
متغيرات البيئة الرئيسية:
LLM_MODEL=anthropic/claude-sonnet-4-5
LLM_API_KEY=sk-ant-...
AGENT=CodeActAgentتأمين docker.sock — وكيل المقبس والوضع الجذري الخالي. تركيب /var/run/docker.sock داخل حاوية يعادل منح وصول جذري كامل للآلة المضيفة. ثمة نهجان لتقليص سطح الهجوم:
الخيار 1 — وكيل المقبس (Tecnativa/docker-socket-proxy): ضع وكيلًا يصفّي استدعاءات واجهة Docker API. لا يحتاج OpenHands إلا إلى POST /containers/create وGET /containers/{id}/json وPOST /containers/{id}/start وDELETE /containers/{id}. يحجب الوكيل كل شيء آخر.
services:
socket-proxy:
image: tecnativa/docker-socket-proxy
environment:
CONTAINERS: 1
POST: 1
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
restart: unless-stopped
openhands:
image: docker.all-hands.dev/all-hands-ai/openhands:latest
environment:
- DOCKER_HOST=tcp://socket-proxy:2375
depends_on:
- socket-proxy
restart: unless-stoppedالخيار 2 — Docker Rootless: شغّل Docker في وضع rootless. يصبح المقبس حينئذٍ في /run/user/1000/docker.sock ومملوك لمستخدمك. اختراق هذا المقبس لا يتجاوز صلاحيات ذلك المستخدم. فعّله بـ dockerd-rootless-setuptool.sh install.
حالات استخدام عملية
الحالة 1 — حل مشكلة GitHub موثقة
الصق رابط مشكلة جيدة التوثيق في OpenHands. يقرأ الوكيل المشكلة، يبحث عن الملفات المعنية، يكتب الإصلاح، يشغّل مجموعة الاختبارات ويقترح فتح طلب سحب. بالنسبة للأخطاء المعزولة ذات التوثيق الجيد، يكون معدل النجاح مرتفعًا دون تدخل بشري.
الحالة 2 — توليد اختبارات لوحدة غير مغطاة
حدد الوحدة المستهدفة: اكتب اختبارات وحدة للوحدة src/payments/stripe.py بهدف تغطية 80% باستخدام pytest. يجب أن تستخدم المحاكاة unittest.mock. يحلل الوكيل الوحدة، يحدد الحالات الحدية، وينشئ مجموعة اختبارات متسقة مع الأنماط الموجودة.
الحالة 3 — تحليل مستودع مفتوح المصدر قبل تفريعه
قبل دمج تبعية أو تفريع مشروع، اسأل OpenHands: حلّل المستودع https://github.com/org/repo. حدد التبعيات الحرجة ونقاط الاقتران الشديد والاختبارات المفقودة وثغرات CVE المعروفة في التبعيات المباشرة.
الحالة 4 — تحديث تبعية رئيسية
عمليات ترحيل الإصدارات الرئيسية (Django 4 إلى 5، React 18 إلى 19) تمس ملفات كثيرة. يمكن لـ OpenHands قراءة سجل التغييرات الرسمي وتطبيق التحديثات الميكانيكية وإعادة تشغيل الاختبارات لتحديد ما يحتاج إلى انتباه يدوي.
استكشاف الأخطاء — الأخطاء الشائعة
permission denied while trying to connect to the Docker daemon socket
المستخدم الذي يشغّل OpenHands ليس في مجموعة docker. صحّح بـ:
sudo usermod -aG docker $USER && newgrp dockerContainer exited with OOM kill (exit code 137)
nفدت ذاكرة sandbox. زد RAM المتاحة على VPS أو قلل المهام المتزامنة. أضف --memory=4g إلى حاوية sandbox.
LLM timeout after 120s
على قواعد بيانات كبيرة، يرسل الوكيل سياقات ضخمة. زد LLM_TIMEOUT في الإعدادات أو قلل نطاق المهمة.
No such container: openhands-sandbox-xxx
أُزيلت حاوية sandbox بين إجراءين. أعد تشغيل المهمة من البداية — OpenHands لا يستأنف المهام المقطوعة بإعادة تشغيل Docker.
Rate limit exceeded
أضف LLM_NUM_RETRIES=5 وLLM_RETRY_MIN_WAIT=30 في الإعدادات ليعيد OpenHands المحاولة تلقائيًا.
OpenHands مقابل Codex السحابي مقابل Devin
مرّر الجدول أفقيًا
| المعيار | OpenHands على خادم خاص | GitHub Copilot Workspace | Devin (Cognition) |
|---|---|---|---|
| التكلفة الشهرية | 0$ (+ تكلفة واجهة برمجة اللغة) | 19$/شهر (Copilot Pro) | 500$/شهر (خطة الفريق) |
| الكود المُرسَل خارجيًا | لا (الكود يبقى على VPS) | نعم (GitHub/Microsoft) | نعم (Cognition) |
| نموذج LLM قابل للضبط | نعم (Claude أو GPT أو Ollama…) | لا (نموذج Microsoft) | لا (نموذج Cognition) |
| نتيجة SWE-bench Verified | 66.4% (5 محاولات، Claude) | غير منشور | ~49% (آخر نشر) |
| الرخصة | MIT (مفتوح المصدر) | مملوكة | مملوكة (SaaS) |
| VPS مطلوب | نعم (4 جيجابايت RAM كحد أدنى) | لا | لا |
| الاستقلالية الكاملة (PR تلقائية) | نعم | جزئية | نعم |
