---
read_when:
    - تحتاج إلى شرح دقيق لحلقة الوكيل أو أحداث دورة الحياة
    - أنت تغيّر اصطفاف الجلسات، أو عمليات كتابة النصوص، أو سلوك قفل كتابة الجلسة
summary: دورة حياة حلقة الوكيل، والتدفقات، ودلالات الانتظار
title: حلقة الوكيل
x-i18n:
    generated_at: "2026-04-23T07:23:49Z"
    model: gpt-5.4
    provider: openai
    source_hash: 439b68446cc75db3ded7a7d20df8e074734e6759ecf989a41299d1b84f1ce79c
    source_path: concepts/agent-loop.md
    workflow: 15
---

# حلقة الوكيل (OpenClaw)

الحلقة الوكيلة هي التشغيل “الحقيقي” الكامل لوكيل: الاستقبال → تجميع السياق → استدلال النموذج →
تنفيذ الأدوات → بث الردود → الاستمرارية. وهي المسار المرجعي الذي يحوّل الرسالة
إلى إجراءات ورد نهائي، مع الحفاظ على اتساق حالة الجلسة.

في OpenClaw، تكون الحلقة تشغيلًا واحدًا متسلسلًا لكل جلسة يصدر أحداث دورة حياة وأحداث تدفق
بينما يفكر النموذج، ويستدعي الأدوات، ويبث المخرجات. يشرح هذا المستند كيف يتم توصيل هذه الحلقة
الحقيقية من البداية إلى النهاية.

## نقاط الدخول

- Gateway RPC: ‏`agent` و`agent.wait`.
- CLI: أمر `agent`.

## كيف يعمل (نظرة عامة عالية المستوى)

1. يتحقق `agent` RPC من المعاملات، ويحل الجلسة (`sessionKey/sessionId`)، ويحفظ بيانات تعريف الجلسة، ثم يعيد `{ runId, acceptedAt }` فورًا.
2. يشغّل `agentCommand` الوكيل:
   - يحل إعدادات النموذج + التفكير/الإسهاب/التتبع الافتراضية
   - يحمّل لقطة Skills
   - يستدعي `runEmbeddedPiAgent` ‏(وقت تشغيل pi-agent-core)
   - يصدر **نهاية/خطأ دورة الحياة** إذا لم تصدر الحلقة المضمنة أحدهما
3. يقوم `runEmbeddedPiAgent` بما يلي:
   - يسلسل عمليات التشغيل عبر طوابير لكل جلسة + طوابير عامة
   - يحل النموذج + ملف تعريف المصادقة ويبني جلسة Pi
   - يشترك في أحداث Pi ويبث فروق المساعد/الأداة
   - يفرض مهلة -> ويوقف التشغيل إذا تم تجاوزها
   - يعيد الحمولات + بيانات الاستخدام الوصفية
4. يصل `subscribeEmbeddedPiSession` أحداث pi-agent-core إلى تدفق `agent` في OpenClaw:
   - أحداث الأداة => `stream: "tool"`
   - فروق المساعد => `stream: "assistant"`
   - أحداث دورة الحياة => `stream: "lifecycle"` ‏(`phase: "start" | "end" | "error"`)
5. يستخدم `agent.wait` الدالة `waitForAgentRun`:
   - ينتظر **نهاية/خطأ دورة الحياة** لـ `runId`
   - يعيد `{ status: ok|error|timeout, startedAt, endedAt, error? }`

## الاصطفاف + التزامن

- تُسلسل عمليات التشغيل لكل مفتاح جلسة (مسار الجلسة) واختياريًا عبر مسار عام.
- يمنع هذا تعارضات الأدوات/الجلسات ويحافظ على اتساق سجل الجلسة.
- يمكن لقنوات المراسلة اختيار أوضاع الطابور (collect/steer/followup) التي تغذي نظام المسارات هذا.
  راجع [طابور الأوامر](/ar/concepts/queue).
- تُحمى أيضًا عمليات كتابة النصوص بقفل كتابة جلسة على ملف الجلسة. القفل
  واعٍ بالعمليات ومعتمد على الملفات، لذلك يلتقط الكتّاب الذين يتجاوزون الطابور داخل العملية أو يأتون من
  عملية أخرى.
- أقفال كتابة الجلسات غير قابلة لإعادة الدخول افتراضيًا. إذا كان هناك مساعد يعشش عن قصد عملية الحصول على
  القفل نفسه مع الحفاظ على كاتب منطقي واحد، فيجب عليه التفعيل الصريح لذلك باستخدام
  `allowReentrant: true`.

## إعداد الجلسة + مساحة العمل

- يتم حل مساحة العمل وإنشاؤها؛ وقد تعيد العمليات المعزولة توجيهها إلى جذر مساحة عمل معزول.
- يتم تحميل Skills ‏(أو إعادة استخدامها من لقطة) وحقنها في env وprompt.
- يتم حل ملفات التمهيد/السياق وحقنها في تقرير system prompt.
- يتم الحصول على قفل كتابة جلسة؛ ثم يُفتح `SessionManager` ويُجهز قبل البث. وأي
  مسار لاحق لإعادة كتابة النص، أو Compaction، أو الاقتطاع يجب أن يأخذ القفل نفسه قبل فتح
  ملف النص أو تعديله.

## تجميع Prompt وsystem prompt

- يُبنى system prompt من الـ prompt الأساسي لـ OpenClaw، وprompt الخاص بـ Skills، وسياق التمهيد، وتجاوزات كل تشغيل.
- تُفرض حدود خاصة بالنموذج ورموز احتياط Compaction.
- راجع [system prompt](/ar/concepts/system-prompt) لمعرفة ما يراه النموذج.

## نقاط Hooks ‏(حيث يمكنك الاعتراض)

يحتوي OpenClaw على نظامي Hooks:

- **Hooks داخلية** (Hooks الخاصة بـ Gateway): نصوص برمجية قائمة على الأحداث للأوامر وأحداث دورة الحياة.
- **Hooks خاصة بـ Plugin**: نقاط امتداد داخل دورة حياة الوكيل/الأداة ومسار Gateway.

### Hooks داخلية (Hooks الخاصة بـ Gateway)

- **`agent:bootstrap`**: تعمل أثناء بناء ملفات التمهيد قبل إنهاء system prompt.
  استخدمها لإضافة/إزالة ملفات سياق التمهيد.
- **Hooks الأوامر**: `/new` و`/reset` و`/stop` وأحداث أوامر أخرى (راجع مستند Hooks).

راجع [Hooks](/ar/automation/hooks) للإعداد والأمثلة.

### Hooks الخاصة بـ Plugin ‏(دورة حياة الوكيل + Gateway)

تعمل هذه داخل حلقة الوكيل أو مسار Gateway:

- **`before_model_resolve`**: تعمل قبل الجلسة (من دون `messages`) لتجاوز المزوّد/النموذج بشكل حتمي قبل حل النموذج.
- **`before_prompt_build`**: تعمل بعد تحميل الجلسة (مع `messages`) لحقن `prependContext` أو `systemPrompt` أو `prependSystemContext` أو `appendSystemContext` قبل إرسال prompt. استخدم `prependContext` للنص الديناميكي لكل دور، واستخدم حقول system-context للإرشاد الثابت الذي يجب أن يكون في مساحة system prompt.
- **`before_agent_start`**: Hook قديمة للتوافق وقد تعمل في أي من المرحلتين؛ فضّل Hooks الصريحة أعلاه.
- **`before_agent_reply`**: تعمل بعد الإجراءات المضمنة وقبل استدعاء LLM، مما يسمح لـ Plugin بالمطالبة بالدور وإرجاع رد اصطناعي أو إسكات الدور بالكامل.
- **`agent_end`**: افحص قائمة الرسائل النهائية وبيانات التشغيل الوصفية بعد الاكتمال.
- **`before_compaction` / `after_compaction`**: راقب دورات Compaction أو أضف تعليقات عليها.
- **`before_tool_call` / `after_tool_call`**: اعترض معاملات/نتائج الأداة.
- **`before_install`**: افحص نتائج الفحص المضمنة وامنع اختياريًا تثبيت Skill أو Plugin.
- **`tool_result_persist`**: حوّل نتائج الأدوات بشكل متزامن قبل كتابتها إلى نص الجلسة.
- **`message_received` / `message_sending` / `message_sent`**: Hooks الرسائل الواردة + الصادرة.
- **`session_start` / `session_end`**: حدود دورة حياة الجلسة.
- **`gateway_start` / `gateway_stop`**: أحداث دورة حياة Gateway.

قواعد قرار Hooks الخاصة بحراس الأدوات/الخروج:

- `before_tool_call`: القيمة `{ block: true }` نهائية وتوقف المعالجات ذات الأولوية الأقل.
- `before_tool_call`: القيمة `{ block: false }` بلا تأثير ولا تزيل حظرًا سابقًا.
- `before_install`: القيمة `{ block: true }` نهائية وتوقف المعالجات ذات الأولوية الأقل.
- `before_install`: القيمة `{ block: false }` بلا تأثير ولا تزيل حظرًا سابقًا.
- `message_sending`: القيمة `{ cancel: true }` نهائية وتوقف المعالجات ذات الأولوية الأقل.
- `message_sending`: القيمة `{ cancel: false }` بلا تأثير ولا تزيل إلغاءً سابقًا.

راجع [Hooks الخاصة بـ Plugin](/ar/plugins/architecture#provider-runtime-hooks) للحصول على API الخاصة بـ Hooks وتفاصيل التسجيل.

## البث + الردود الجزئية

- تُبث فروق المساعد من pi-agent-core وتُصدر كأحداث `assistant`.
- يمكن أن يصدر بث الكتل ردودًا جزئية إما عند `text_end` أو `message_end`.
- يمكن إصدار بث الاستدلال كتدفق منفصل أو كاستجابات كتل.
- راجع [البث](/ar/concepts/streaming) لمعرفة سلوك التقطيع وردود الكتل.

## تنفيذ الأدوات + أدوات المراسلة

- تُصدر أحداث بدء/تحديث/نهاية الأداة على تدفق `tool`.
- تُنقّى نتائج الأدوات من حيث الحجم وحمولات الصور قبل التسجيل/الإصدار.
- يتم تتبع عمليات إرسال أدوات المراسلة لمنع تأكيدات المساعد المكررة.

## تشكيل الرد + منعه

- تُجمع الحمولات النهائية من:
  - نص المساعد (واختياريًا الاستدلال)
  - ملخصات الأدوات المضمنة (عند تفعيل الإسهاب + السماح)
  - نص خطأ المساعد عند حدوث خطأ في النموذج
- تتم تصفية الرمز الصامت المطابق تمامًا `NO_REPLY` / `no_reply` من
  الحمولات الصادرة.
- تتم إزالة التكرارات الناتجة عن أدوات المراسلة من قائمة الحمولات النهائية.
- إذا لم تبق أي حمولات قابلة للعرض وحدث خطأ في أداة، فسيتم إصدار
  رد احتياطي لخطأ الأداة (ما لم تكن أداة مراسلة قد أرسلت بالفعل ردًا مرئيًا للمستخدم).

## Compaction + إعادة المحاولات

- تصدر Compaction التلقائية أحداث تدفق `compaction` ويمكن أن تؤدي إلى إعادة محاولة.
- عند إعادة المحاولة، تتم إعادة تعيين المخازن المؤقتة داخل الذاكرة وملخصات الأدوات لتجنب تكرار المخرجات.
- راجع [Compaction](/ar/concepts/compaction) لمعرفة مسار Compaction.

## تدفقات الأحداث (حاليًا)

- `lifecycle`: يصدرها `subscribeEmbeddedPiSession` ‏(وكاحتياط بواسطة `agentCommand`)
- `assistant`: فروق متدفقة من pi-agent-core
- `tool`: أحداث أدوات متدفقة من pi-agent-core

## معالجة قناة الدردشة

- تُخزن فروق المساعد في رسائل `delta` للدردشة.
- يتم إصدار `final` للدردشة عند **نهاية/خطأ دورة الحياة**.

## المهل

- القيمة الافتراضية لـ `agent.wait`: ‏30 ثانية (للانتظار فقط). تتجاوزها المعلمة `timeoutMs`.
- وقت تشغيل الوكيل: القيمة الافتراضية لـ `agents.defaults.timeoutSeconds` هي 172800 ثانية (48 ساعة)؛ ويتم فرضها في مؤقت الإيقاف داخل `runEmbeddedPiAgent`.
- مهلة خمول LLM: تقوم `agents.defaults.llm.idleTimeoutSeconds` بإيقاف طلب النموذج عندما لا تصل أي مقاطع استجابة قبل نافذة الخمول. اضبطها صراحةً للنماذج المحلية البطيئة أو لمزوّدي الاستدلال/استدعاء الأدوات؛ واضبطها على 0 لتعطيلها. إذا لم تكن مضبوطة، يستخدم OpenClaw القيمة `agents.defaults.timeoutSeconds` عند تكوينها، وإلا 120 ثانية. التشغيلات المُشغّلة عبر Cron والتي ليس لها مهلة صريحة لـ LLM أو الوكيل تعطل مراقب الخمول وتعتمد على المهلة الخارجية الخاصة بـ Cron.

## الأماكن التي يمكن أن ينتهي فيها التشغيل مبكرًا

- مهلة الوكيل (إيقاف)
- `AbortSignal` ‏(إلغاء)
- قطع Gateway أو مهلة RPC
- مهلة `agent.wait` ‏(للانتظار فقط، ولا توقف الوكيل)

## ذو صلة

- [الأدوات](/ar/tools) — أدوات الوكيل المتاحة
- [Hooks](/ar/automation/hooks) — نصوص برمجية قائمة على الأحداث تُشغَّل بواسطة أحداث دورة حياة الوكيل
- [Compaction](/ar/concepts/compaction) — كيف يتم تلخيص المحادثات الطويلة
- [موافقات Exec](/ar/tools/exec-approvals) — بوابات الموافقة لأوامر shell
- [Thinking](/ar/tools/thinking) — إعداد مستوى التفكير/الاستدلال
