كيفية استخدام OpenClaw

دليل عملي للاستفادة القصوى من وكيل الذكاء الاصطناعي المستقل في RoqueOS.

---

واجهة الوكيل

ينقسم تطبيق وكيل الذكاء الاصطناعي إلى منطقتين رئيسيتين:

• لوحة الدردشة (يسار) — حيث ترسل الرسائل وتتابع الردود
• تصور سطح المكتب (يمين) — بث مباشر لما يفعله الوكيل في الحاوية

لوحة Steps

أسفل الدردشة، تعرض لوحة Steps في الوقت الفعلي كل إجراء يقوم به الوكيل: التنقل إلى URL، النقر على عنصر، تنفيذ أمر، إلخ.

---

إنشاء جلسة

كل محادثة مع الوكيل تنشئ جلسة — حاوية Docker معزولة مع سطح مكتب Linux مخصص. للبدء:

1. افتح تطبيق وكيل الذكاء الاصطناعي في Launchpad.
2. انقر على جلسة جديدة.
3. ستتم تهيئة الحاوية (قد يستغرق الأمر 10-30 ثانية في المرة الأولى).
4. عند ظهور سطح المكتب في اللوحة اليمنى، يكون الوكيل جاهزًا.

---

إرسال المهام

أفضل الممارسات للموجهات

كن محددًا وموضوعيًا عند وصف المهمة. كلما زاد السياق الذي تقدمه، كانت النتيجة أفضل.

❌ غامض:

ابحث عن Docker

✅ محدد:

ابحث عن أهم 5 اختلافات بين Docker Compose v2 و v3،
وأنشئ ملف markdown يلخص النقاط واحفظه في /home/user/docker-comparison.md

أمثلة على المهام

البحث والتوثيق:

ادخل إلى موقع hetzner.com، وابحث عن خطط VPS المتاحة
وأنشئ جدول مقارنة بالأسعار والموارد بتنسيق CSV.

أتمتة النماذج:

املأ نموذج التسجيل في [URL] بالبيانات التالية:
الاسم: João Silva، البريد الإلكتروني: joao@exemplo.com، الخطة: أساسية

التطوير:

أنشئ سكربت Python يقوم بسحب عناوين الأخبار
من Hacker News ويحفظ أول 10 في ملف JSON.

تحليل المواقع:

ادخل إلى مستودع GitHub هذا [URL]، واقرأ README واشرح لي
ما يفعله المشروع وما هي متطلبات التثبيت.

---

الإجراءات التي ينفذها الوكيل في RoqueOS الخاص بك

RoqueClaw لا يبقى عالقًا في الحاوية المعزولة — بل يعمل مباشرة على سطح مكتب RoqueOS الخاص بك عبر CLI roqueos-cli المثبت مسبقًا في حاوية الوكيل وفي حاوية تطبيق Terminal لكل مستخدم على الخادم.

الإجراءات الـ 6 القانونية

أمر CLI	ما يفعله	مثال للموجه الذي يثيره
roqueos-cli notify "title" "msg"	إشعار على سطح المكتب	"أخبرني عند الانتهاء"
roqueos-cli open-app <id>	يفتح التطبيق في Launchpad	"افتح VS Code"
roqueos-cli open-url <url>	يفتح URL في Roque Browser	"افتح GitHub المشروع"
roqueos-cli create-file <path>	يكتب ملفًا (يقرأ stdin)	"احفظ هذا الملخص في Notes"
roqueos-cli run-terminal <cmd>	ينفذ أمرًا + يعيد الإخراج	"أرني مقدار القرص الحر لدي"
roqueos-cli show-dialog "msg"	نموذج تأكيد (يتوقف، ينتظر)	"اسأل قبل الحذف"

يمكنك أيضًا استخدام CLI مباشرة (بدون الوكيل)

يتوفر CLI في تطبيق Terminal لكل مستخدم (حاوية Ubuntu معزولة). افتح Terminal في Launchpad، اكتب roqueos-cli --help واستخدمه مباشرة.

حالات الاستخدام الشائعة:

# إشعار سريع من سكربت النسخ الاحتياطي
./backup.sh && roqueos-cli notify "النسخ الاحتياطي OK" "تم مزامنة 23 جيجابايت"

# افتح VS Code مباشرة من shell عند انتهاء البناء
yarn build && roqueos-cli open-app vscode

# Cron يحذر عندما يتجاوز القرص 80%
0 9 * * * df -h | awk '$5+0 > 80 {system("roqueos-cli notify \"القرص ممتلئ\" \"" $6 " " $5 "\"")}'

# سكربت Python يكتب مباشرة في ملفات المستخدم
echo "$(date): meeting notes" | roqueos-cli create-file "/home/user/notes/reuniao-$(date +%F).md"

# حاوية Plex تخطر عند انتهاء الترميز
# (داخل حاوية Plex، إذا شاركت شبكة roqueos-server)
roqueos-cli notify "Plex" "اكتمل ترميز 4K للفيلم X"

تثبيت الحاويات عبر اللغة الطبيعية (القوة الخفية)

الإجراء الأكثر استخدامًا من الوكيل: تثبيت تطبيقات Docker مباشرة من الكتالوج عبر roqueos-cli → API الخادم → appsService.installApp.

تقول: "ثبت Nextcloud بـ 2 جيجابايت RAM وافتحه عندما يكون جاهزًا"

يفعل الوكيل (تراه مباشرة عبر VNC):

1. يحدد nextcloud في الكتالوج
2. يستدعي roqueos-cli → POST /apps/install مع appId: nextcloud, memory: 2048
3. ينتظر بدء الحاوية + healthcheck
4. يستدعي roqueos-cli open-url http://localhost:<المنفذ_المخصص>
5. يخطر "Nextcloud جاهز، تسجيل الدخول الأولي admin/admin"

نفس API المتجر المرئي للتطبيقات — فقط دون الحاجة للتنقل/النقر. مفيد لـ:

• إعداد ضخم: "ثبت Plex و Sonarr و Radarr و Bazarr و qBittorrent. اضبط الجميع لاستخدام تخزين /media."
• مجموعة كاملة: "أنشئ مجموعة LAMP مع MariaDB و phpMyAdmin"
• استرداد: "أعد تثبيت جميع التطبيقات التي كانت لدي قبل التعطل"

---

إدارة الجلسات

الجلسات النشطة

جميع الجلسات النشطة مدرجة في أعلى التطبيق. يمكنك:

• استئناف جلسة سابقة بالنقر عليها
• إنهاء جلسة لتحرير موارد الخادم

حد الجلسات المتزامنة

افتراضيًا، يسمح الخادم بحد أقصى 3 جلسات متزامنة (قابل للتكوين عبر AGENT_MAX_SESSIONS). أنهِ الجلسات التي لم تعد تستخدمها لتوفير RAM.

---

لقطة شاشة وملء الشاشة

• لقطة شاشة — انقر على أيقونة الكاميرا لالتقاط الحالة الحالية لسطح مكتب الوكيل
• ملء الشاشة — وسّع تصور سطح المكتب لملء الشاشة لمتابعة المهام المرئية بشكل أفضل

---

القيود المعروفة

• يعمل الوكيل في بيئة معزولة — لا يملك وصولاً مباشرًا إلى ملفاتك المحلية ما لم تقدم المعلومات عبر الدردشة
• المهام التي تتطلب تسجيل الدخول إلى الحسابات (البريد الإلكتروني، الشبكات الاجتماعية) تحتاج منك تقديم بيانات الاعتماد أثناء المحادثة
• مهلة افتراضية للجلسة هي 30 دقيقة من الخمول — قد تحتاج المهام الطويلة جدًا إلى تفاعل دوري

---

استكشاف الأخطاء وإصلاحها

الوكيل لا يستجيب

1. تحقق من أن الخادم متصل: curl http://localhost:27021/health
2. تأكد من أن مفتاح API مكون بشكل صحيح
3. أنهِ الجلسة الحالية وأنشئ واحدة جديدة

سطح المكتب لا يظهر في اللوحة

قد لا تزال الحاوية قيد التهيئة. انتظر 30 ثانية وأعد تحميل التطبيق.

ردود بطيئة أو غير مكتملة

قد تكون مشكلة rate limit من موفر AI. انتظر بضع لحظات ثم حاول مرة أخرى، أو قلل من تعقيد المهمة.