الأدوات وPlugin

كل ما يفعله الوكيل خارج إنشاء النص يحدث عبر الأدوات. الأدوات هي الطريقة التي يقرأ بها الوكيل الملفات، ويشغّل الأوامر، ويتصفح الويب، ويرسل الرسائل، ويتفاعل مع الأجهزة.

# الأدوات وSkills وplugins

يحتوي OpenClaw على ثلاث طبقات تعمل معًا:

# الأدوات المدمجة

تأتي هذه الأدوات مع OpenClaw وهي متاحة دون تثبيت أي plugins:

الأداة	ما تفعله	الصفحة
exec / process	تشغيل أوامر الصدفة، وإدارة العمليات الخلفية	Exec, موافقات Exec
code_execution	تشغيل تحليل Python عن بُعد داخل صندوق رمل	تنفيذ الكود
browser	التحكم في متصفح Chromium (التنقل، النقر، لقطة الشاشة)	المتصفح
web_search / x_search / web_fetch	البحث في الويب، والبحث في منشورات X، وجلب محتوى الصفحات	الويب, جلب الويب
read / write / edit	إدخال/إخراج الملفات في مساحة العمل
apply_patch	رقع ملفات متعددة المقاطع	تطبيق رقعة
message	إرسال الرسائل عبر جميع القنوات	إرسال الوكيل
nodes	اكتشاف الأجهزة المقترنة واستهدافها
cron / gateway	إدارة المهام المجدولة؛ فحص Gateway أو ترقيعه أو إعادة تشغيله أو تحديثه
image / image_generate	تحليل الصور أو توليدها	توليد الصور
music_generate	توليد مسارات موسيقية	توليد الموسيقى
video_generate	توليد مقاطع الفيديو	توليد الفيديو
tts	تحويل نص إلى كلام لمرة واحدة	TTS
sessions_* / subagents / agents_list	إدارة الجلسات، والحالة، وتنسيق الوكلاء الفرعيين	الوكلاء الفرعيون
session_status	استرجاع خفيف بأسلوب /status وتجاوز نموذج الجلسة	أدوات الجلسة

لعمل الصور، استخدم image للتحليل وimage_generate للتوليد أو التحرير. إذا استهدفت openai/* أو google/* أو fal/* أو موفر صور آخر غير افتراضي، فقم بتهيئة مفتاح المصادقة/API لذلك الموفر أولًا.

لعمل الموسيقى، استخدم music_generate. إذا استهدفت google/* أو minimax/* أو موفر موسيقى آخر غير افتراضي، فقم بتهيئة مفتاح المصادقة/API لذلك الموفر أولًا.

لعمل الفيديو، استخدم video_generate. إذا استهدفت qwen/* أو موفر فيديو آخر غير افتراضي، فقم بتهيئة مفتاح المصادقة/API لذلك الموفر أولًا.

لتوليد الصوت المدفوع بسير عمل، استخدم music_generate عندما تسجله Plugin مثل ComfyUI. هذا منفصل عن tts، وهي أداة تحويل النص إلى كلام.

session_status هي أداة الحالة/الاسترجاع الخفيفة في مجموعة الجلسات. تجيب عن أسئلة بأسلوب /status حول الجلسة الحالية ويمكنها اختياريًا تعيين تجاوز للنموذج لكل جلسة؛ يؤدي model=default إلى مسح ذلك التجاوز. مثل /status، يمكنها استكمال عدادات الرموز المميزة/الذاكرة المؤقتة المتفرقة وتسمية نموذج وقت التشغيل النشط من أحدث إدخال لاستخدام النص.

gateway هي أداة وقت التشغيل المملوكة للمالك فقط لعمليات Gateway:

• config.schema.lookup لشجرة فرعية واحدة من التهيئة محددة بالمسار قبل التعديلات
• config.get للّقطة الحالية من التهيئة + التجزئة
• config.patch للتحديثات الجزئية للتهيئة مع إعادة التشغيل
• config.apply فقط لاستبدال التهيئة الكاملة
• update.run للتحديث الذاتي الصريح + إعادة التشغيل

للتغييرات الجزئية، فضّل config.schema.lookup ثم config.patch. استخدم config.apply فقط عندما تقصد استبدال التهيئة بالكامل. لمستندات التهيئة الأوسع، اقرأ التهيئة و مرجع التهيئة. ترفض الأداة أيضًا تغيير tools.exec.ask أو tools.exec.security؛ تُطبَّع الأسماء المستعارة القديمة tools.bash.* إلى مسارات exec المحمية نفسها.

# الأدوات التي توفرها Plugin

يمكن للـ plugins تسجيل أدوات إضافية. بعض الأمثلة:

• Canvas — Plugin تجريبية مدمجة للتحكم في node Canvas وتصيير A2UI
• Diffs — عارض ومصيّر الفروقات
• مهمة LLM — خطوة LLM بصيغة JSON فقط للإخراج المنظّم
• Lobster — وقت تشغيل سير عمل مضبوط النوع مع موافقات قابلة للاستئناف
• توليد الموسيقى — أداة music_generate مشتركة مع موفرين مدعومين بسير عمل
• OpenProse — تنسيق سير عمل يقدّم Markdown أولًا
• Tokenjuice — ضغط نتائج أدوات exec وbash المزعجة

لا تزال أدوات Plugin تُنشأ باستخدام api.registerTool(...) وتُصرَّح في قائمة contracts.tools في بيان Plugin. يلتقط OpenClaw واصف الأداة بعد التحقق أثناء الاكتشاف ويخزنه مؤقتًا حسب مصدر Plugin والعقد، بحيث يمكن لتخطيط الأدوات لاحقًا تخطي تحميل وقت تشغيل Plugin. لا يزال تنفيذ الأداة يحمّل Plugin المالكة ويستدعي التنفيذ المسجل الحي.

# تهيئة الأدوات

# قوائم السماح والرفض

تحكم في الأدوات التي يمكن للوكيل استدعاؤها عبر tools.allow / tools.deny في التهيئة. الرفض ينتصر دائمًا على السماح.

{
  tools: {
    allow: ["group:fs", "browser", "web_search"],
    deny: ["exec"],
  },
}

يفشل OpenClaw بإغلاق آمن عندما لا تتحول قائمة سماح صريحة إلى أي أدوات قابلة للاستدعاء. على سبيل المثال، لا يعمل tools.allow: ["query_db"] إلا إذا كانت Plugin محمّلة تسجل فعليًا query_db. إذا لم تطابق أي أداة مدمجة أو Plugin أو أداة MCP مضمّنة قائمة السماح، يتوقف التشغيل قبل استدعاء النموذج بدلًا من المتابعة كتشغيل نصي فقط قد يهلوس نتائج الأدوات.

# ملفات تعريف الأدوات

يضبط tools.profile قائمة سماح أساسية قبل تطبيق allow/deny. تجاوز لكل وكيل: agents.list[].tools.profile.

ملف التعريف	ما يتضمنه
full	جميع أدوات core وPlugin الاختيارية؛ خط أساس غير مقيّد لوصول أوسع للأوامر/التحكم
coding	group:fs, group:runtime, group:web, group:sessions, group:memory, cron, image, image_generate, music_generate, video_generate
messaging	group:messaging, sessions_list, sessions_history, sessions_send, session_status
minimal	session_status فقط

يتضمن coding أدوات ويب خفيفة (web_search وweb_fetch وx_search) ولكن ليس أداة التحكم الكاملة في المتصفح. يمكن لأتمتة المتصفح قيادة جلسات حقيقية وملفات تعريف مسجّل دخولها، لذا أضفها صراحةً باستخدام tools.alsoAllow: ["browser"] أو agents.list[].tools.alsoAllow: ["browser"] لكل وكيل.

تسمح ملفات التعريف coding وmessaging أيضًا بأدوات bundle MCP المهيأة ضمن مفتاح Plugin المسمى bundle-mcp. أضف tools.deny: ["bundle-mcp"] عندما تريد أن يحتفظ ملف التعريف بأدواته المدمجة العادية لكنه يخفي كل أدوات MCP المهيأة. لا يتضمن ملف التعريف minimal أدوات bundle MCP.

مثال (أوسع سطح أدوات افتراضيًا):

{
  tools: {
    profile: "full",
  },
}

# مجموعات الأدوات

استخدم اختصارات group:* في قوائم السماح/الرفض:

المجموعة	الأدوات
group:runtime	exec، process، code_execution (يُقبل bash كاسم بديل لـ exec)
group:fs	read، write، edit، apply_patch
group:sessions	sessions_list، sessions_history، sessions_send، sessions_spawn، sessions_yield، subagents، session_status
group:memory	memory_search، memory_get
group:web	web_search، x_search، web_fetch
group:ui	browser، canvas عند تمكين Plugin Canvas المضمّن
group:automation	heartbeat_respond، cron، gateway
group:messaging	message
group:nodes	nodes
group:agents	agents_list، update_plan
group:media	image، image_generate، music_generate، video_generate، tts
group:openclaw	كل أدوات OpenClaw المضمّنة (باستثناء أدوات Plugin)

يعيد sessions_history عرض استرجاع محدودًا ومفلترًا للسلامة. وهو يزيل وسوم التفكير، وبنية <relevant-memories> التمهيدية، وحمولات XML لاستدعاء الأدوات بنص عادي (بما في ذلك <tool_call>...</tool_call>، و<function_call>...</function_call>، و<tool_calls>...</tool_calls>، و<function_calls>...</function_calls>، وكتل استدعاء الأدوات المقتطعة)، وبنى استدعاء الأدوات التمهيدية المخفّضة، ورموز تحكّم النموذج المسرّبة بصيغتي ASCII/العرض الكامل، وXML غير السليم لاستدعاءات أدوات MiniMax من نص المساعد، ثم يطبّق التنقيح/الاقتطاع واحتمال استخدام عناصر نائبة للصفوف كبيرة الحجم بدلًا من العمل كتفريغ خام للنص الكامل.

# القيود الخاصة بالموفّر

استخدم tools.byProvider لتقييد الأدوات لموفّرين محدّدين دون تغيير الإعدادات الافتراضية العامة:

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}