أدوات الجلسة

يمنح OpenClaw الوكلاء أدوات للعمل عبر الجلسات وفحص الحالة وتنسيق الوكلاء الفرعيين.

الأدوات المتاحة

تظل هذه الأدوات خاضعة لملف تعريف الأدوات النشط ولسياسة السماح/المنع. يتضمن tools.profile: "coding" المجموعة الكاملة لتنسيق الجلسات، بما فيها sessions_spawn وsessions_yield وsubagents. يتضمن tools.profile: "messaging" أدوات المراسلة عبر الجلسات (sessions_list وsessions_history وsessions_send وsession_status) لكنه لا يتضمن إنشاء الوكلاء الفرعيين. للاحتفاظ بملف تعريف للمراسلة مع السماح بالتفويض الأصلي، أضف:

{  tools: {    profile: "messaging",    alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"],  },}

يمكن لسياسات المجموعة والموفّر ووضع الحماية والسياسات الخاصة بكل وكيل أن تزيل تلك الأدوات بعد مرحلة ملف التعريف. استخدم /tools من الجلسة المتأثرة لفحص قائمة الأدوات الفعلية.

سرد الجلسات وقراءتها

يعيد sessions_list الجلسات مع مفتاحها وagentId ونوعها وقناتها ونموذجها وأعداد الرموز وطوابعها الزمنية. يمكنك التصفية حسب kinds (مصفوفة؛ القيم المقبولة: main وgroup وcron وhook وnode وother) أو label المطابق تمامًا أو agentId المطابق تمامًا أو نص search أو الحداثة (activeMinutes). تُعاد الجلسات النشطة افتراضيًا؛ مرّر archived: true لفحص الجلسات المؤرشفة بدلًا منها. تتضمن الصفوف حالة pinned وarchived. عيّن includeDerivedTitles أو includeLastMessage أو messageLimit (بحد أقصى 20) عند الحاجة إلى فرز على نمط صندوق البريد: عنوان مشتق ضمن نطاق الرؤية، أو مقتطف معاينة لآخر رسالة، أو رسائل حديثة محدودة في كل صف. لا تُنشأ العناوين والمعاينات المشتقة إلا للجلسات التي يستطيع المستدعي رؤيتها بالفعل بموجب سياسة رؤية أدوات الجلسة المضبوطة، ولذلك تظل الجلسات غير المرتبطة مخفية. عندما تكون الرؤية مقيّدة، يعيد sessions_list بيانات وصفية اختيارية في visibility توضّح الوضع الفعلي وتحذيرًا من أن النتائج قد تكون محدودة النطاق.

يجلب sessions_history نص المحادثة لجلسة محددة. تُستبعد نتائج الأدوات افتراضيًا؛ مرّر includeTools: true لرؤيتها. استخدم limit للحصول على أحدث ذيل محدود. مرّر offset: 0 عند الحاجة إلى بيانات وصفية للتقسيم إلى صفحات، ثم مرّر قيم nextOffset المعادة للتنقل إلى الخلف عبر نوافذ نصوص OpenClaw الأقدم من دون قراءة ملفات النصوص الخام. لا تدمج صفحات الإزاحة الصريحة عمليات الاستيراد الاحتياطية الخارجية من CLI؛ استخدم عرض أحدث ذيل الافتراضي (من دون offset) عند الحاجة إلى سجل العرض المدمج هذا.

العرض المعاد محدود ومصفّى لأغراض السلامة عمدًا:

• يُطبّع نص المساعد قبل الاسترجاع:
  • تُزال وسوم التفكير
  • تُزال كتل البنية المساعدة <relevant-memories> / <relevant_memories>
  • تُزال كتل حمولات XML لاستدعاءات الأدوات ذات النص العادي، مثل <tool_call>...</tool_call> و<function_call>...</function_call> و<tool_calls>...</tool_calls> و<function_calls>...</function_calls>، بما في ذلك الحمولات المبتورة التي لا تُغلق بصورة سليمة
  • تُزال البنية المساعدة لاستدعاءات الأدوات/نتائجها المخفّضة، مثل [Tool Call: ...] و[Tool Result ...] و[Historical context ...]
  • تُزال رموز التحكم المتسربة من النموذج، مثل <|assistant|>، ورموز ASCII الأخرى من نوع <|...|>، وصيغ <｜...｜> كاملة العرض
  • تُزال صيغة XML المشوهة لاستدعاءات أدوات MiniMax، مثل <invoke ...> / </minimax:tool_call>
• تُنقّح النصوص الشبيهة ببيانات الاعتماد/الرموز قبل إعادتها
• تُقتطع كتل النص الطويلة
• يمكن للسجلات الكبيرة جدًا إسقاط الصفوف الأقدم أو استبدال صف مفرط الحجم بـ [sessions_history omitted: message too large]
• تبلّغ الأداة عن أعلام الملخص، مثل truncated وdroppedMessages وcontentTruncated وcontentRedacted وbytes، وعن البيانات الوصفية للتقسيم إلى صفحات

تقبل كلتا الأداتين إما مفتاح جلسة (مثل "main") أو معرّف جلسة من استدعاء سرد سابق.

إذا كنت بحاجة إلى النص الخام الدقيق، فافحص صفوف نصوص SQLite ضمن النطاق بدلًا من التعامل مع sessions_history على أنه تفريغ غير مصفّى.

إرسال الرسائل عبر الجلسات

يوصل sessions_send رسالة إلى جلسة أخرى وينتظر الاستجابة اختياريًا:

• إرسال دون انتظار: عيّن timeoutSeconds: 0 لإضافة الرسالة إلى قائمة الانتظار والعودة فورًا.
• انتظار الرد: عيّن مهلة زمنية واحصل على الاستجابة ضمن السياق.

جلسات الدردشة محددة النطاق بسلسلة محادثات، مثل المفاتيح المنتهية بـ :thread:<id>، ليست أهدافًا صالحة لـ sessions_send. استخدم مفتاح جلسة القناة الأم للتنسيق بين الوكلاء حتى لا تظهر الرسائل الموجّهة عبر الأدوات داخل سلسلة محادثات نشطة موجهة للبشر.

تُعلّم الرسائل وردود المتابعة بين الوكلاء A2A على أنها بيانات بين الجلسات في مطالبة المستقبِل ([Inter-session message ... isUser=false]) وفي مصدر النص. ينبغي للوكيل المستقبِل التعامل معها على أنها بيانات موجّهة عبر الأدوات، لا تعليمات صاغها المستخدم النهائي مباشرةً.

بعد استجابة الهدف، يمكن لـ OpenClaw تشغيل حلقة رد متبادل يتبادل فيها الوكلاء الرسائل (حتى session.agentToAgent.maxPingPongTurns، النطاق 0-20، الافتراضي 5). يمكن للوكيل الهدف الرد بـ REPLY_SKIP للتوقف مبكرًا.

مرّر watch: true لتسجيل المرسِل أيضًا بصفته مراقبًا لتغييرات حالة الهدف: عندما يرسل طرف آخر لاحقًا رسالة بشرية مباشرة إلى الهدف أو يغيّر هدفه، يتلقى المرسِل إشعارًا من النظام يشير إلى session_status changesSince. يحدث التسجيل بعد الإرسال الناجح، ويستهدف الجلسة التي تلقت الرسالة فعليًا، ويبدأ من إصدار حالتها الحالي، ولذلك لا تنتج الإشعارات إلا عن التغييرات اللاحقة. تبلغ النتيجة عن watched: true عند نجاح التسجيل. راجع الوعي بحالة الجلسة.

مساعدات الحالة والتنسيق

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

عند توفر البيانات الوصفية للمسار، يتضمن session_status أيضًا كتلة JSON مرئية في Route context وحقول details منظّمة مطابقة. تزيل هذه الحقول الالتباس بين مفتاح الجلسة والمسار الذي يعالج التشغيل المباشر حاليًا:

• origin هو المكان الذي أُنشئت فيه الجلسة، أو الموفّر المستنتج من بادئة مفتاح جلسة قابلة للتسليم عندما تفتقر الحالة الأقدم إلى بيانات وصفية مخزنة عن الأصل.
• active هو مسار التشغيل المباشر الحالي. ولا يُبلّغ عنه إلا للجلسة المباشرة أو الحالية التي تجري معالجتها الآن.
• deliveryContext هو مسار التسليم الدائم المخزن في الجلسة، والذي يستطيع OpenClaw إعادة استخدامه للتسليم اللاحق حتى عندما تختلف الواجهة النشطة.

تغييرات حالة الجلسة

يحتفظ OpenClaw بسجل إشارات دائم لتغييرات حالة الجلسة الجوهرية (الرسائل البشرية المباشرة إلى الجلسات المراقبة، ونتائج عمليات التشغيل الفرعية، وتغييرات الهدف، وCompaction). تعرض صفوف sessions_list وsession_status قيمة stateVersion للجلسة، ويقبل session_status القيمة changesSince: <version> لإعادة الأحداث المعرّفة نوعيًا بعد ذلك الإصدار، مع إشارة historyGap دقيقة عندما يسبق الإصدار المطلوب السجل المحتفظ به. يتلقى المراقبون — الآباء المنشئون تلقائيًا، وsessions_send watch: true صراحةً — إشعارًا واحدًا مدمجًا بتقادم الحالة عندما يغيّر طرف آخر جلسة مراقبة.

راجع الوعي بحالة الجلسة للاطلاع على النموذج الكامل: أنواع الأحداث، وتسجيل المراقبين، وبروتوكول الإشعار المضاد للإزعاج، وتدفق المطابقة، والقيود الحالية.

ينهي sessions_yield الدور الحالي عمدًا حتى تكون الرسالة التالية هي حدث المتابعة الذي تنتظره. استخدمه بعد إنشاء الوكلاء الفرعيين عندما تريد وصول نتائج الإكمال بوصفها الرسالة التالية بدلًا من إنشاء حلقات استطلاع.

يمثل subagents مساعد الرؤية لوكلاء OpenClaw الفرعيين الذين سبق إنشاؤهم. وهو يدعم action: "list" لفحص عمليات التشغيل النشطة/الحديثة.

إنشاء الوكلاء الفرعيين

ينشئ sessions_spawn جلسة معزولة لمهمة تعمل في الخلفية افتراضيًا. وهو دائمًا غير حاجب؛ إذ يعود فورًا مع runId وchildSessionKey. تتلقى عمليات تشغيل الوكلاء الفرعيين الأصلية المهمة المفوّضة في أول رسالة [Subagent Task] مرئية ضمن الجلسة الفرعية، بينما تحمل مطالبة النظام قواعد بيئة تشغيل الوكيل الفرعي وسياق التوجيه فقط.

الخيارات الأساسية:

• runtime: "subagent" (الافتراضي) أو "acp" لوكلاء بيئات الاختبار الخارجية.
• تجاوزات model وthinking للجلسة الفرعية.
• thread: true لربط الإنشاء بسلسلة محادثات دردشة (Discord وSlack وغيرهما).
• sandbox: "require" لفرض وضع الحماية على الجلسة الفرعية.
• context: "fork" للوكلاء الفرعيين الأصليين عندما يحتاج الوكيل الفرعي إلى نص المستدعي الحالي؛ احذفه أو استخدم context: "isolated" للحصول على وكيل فرعي نظيف. لا تكون context: "fork" صالحة إلا مع runtime: "subagent". تستخدم الوكلاء الفرعية الأصلية المرتبطة بسلسلة محادثات context: "fork" افتراضيًا ما لم ينص threadBindings.defaultSpawnContext على خلاف ذلك.

لا تحصل الوكلاء الفرعية الطرفية الافتراضية على أدوات الجلسة. عند maxSpawnDepth >= 2، تتلقى الوكلاء الفرعية المنسقة من العمق 1 أيضًا sessions_spawn وsubagents وsessions_list وsessions_history حتى تتمكن من إدارة وكلائها الفرعية. ولا تزال عمليات التشغيل الطرفية لا تحصل على أدوات التنسيق التكراري.

بعد الإكمال، تنشر خطوة إعلان النتيجة في قناة المستدعي. يحافظ تسليم الإكمال على توجيه سلسلة المحادثات/الموضوع المرتبط عند توفره، وإذا كان أصل الإكمال لا يحدد سوى قناة، فلا يزال بإمكان OpenClaw إعادة استخدام المسار المخزن لجلسة المستدعي (lastChannel / lastTo) للتسليم المباشر.

للسلوك الخاص بـ ACP، راجع وكلاء ACP.

الرؤية

تُقيّد أدوات الجلسة بنطاق يحد مما يستطيع الوكيل رؤيته:

القيمة الافتراضية هي tree. تُقيّد الجلسات الخاضعة لوضع الحماية إلى tree بغض النظر عن التكوين.

قراءات إضافية

• إدارة الجلسات: التوجيه ودورة الحياة والصيانة
• الوكلاء الفرعيون: دورة حياة الجلسات الفرعية وتسليمها
• وكلاء ACP: إنشاء مثيلات عبر إطار تشغيل خارجي
• الوكلاء المتعددون: بنية الوكلاء المتعددين
• تهيئة Gateway: خيارات ضبط أداة الجلسة

ذات صلة

• إدارة الجلسات
• تشذيب الجلسات