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

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

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

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

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

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

1. يتحقق RPC ‏`agent` من صحة المعلمات، ويحل الجلسة (sessionKey/sessionId)، ويحفظ بيانات تعريف الجلسة، ويعيد `{ runId, acceptedAt }` فورًا.
2. يشغّل `agentCommand` الوكيل:
   - يحل القيم الافتراضية للنموذج + thinking/verbose/trace
   - يحمّل لقطة Skills
   - يستدعي `runEmbeddedPiAgent` (بيئة تشغيل pi-agent-core)
   - يطلق **نهاية/خطأ دورة الحياة** إذا لم تطلق الحلقة المضمّنة واحدة
3. يقوم `runEmbeddedPiAgent` بما يلي:
   - يسللسل عمليات التشغيل عبر طوابير لكل جلسة + طوابير عامة
   - يحل النموذج + ملف تعريف المصادقة ويبني جلسة Pi
   - يشترك في أحداث Pi ويبث فروق المساعد/الأداة
   - يفرض مهلة -> يجهض التشغيل إذا تم تجاوزها
   - يعيد الحمولات + بيانات تعريف الاستخدام
4. يربط `subscribeEmbeddedPiSession` أحداث pi-agent-core بتدفق OpenClaw ‏`agent`:
   - أحداث الأداة => `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 (أو إعادة استخدامها من لقطة) وحقنها في البيئة والموجّه.
- يتم حل ملفات bootstrap/السياق وحقنها في تقرير system prompt.
- يتم الحصول على قفل كتابة الجلسة؛ ويُفتح `SessionManager` ويُجهّز قبل البث. وأي
  مسار لاحق لإعادة كتابة النص، أو Compaction، أو الاقتطاع يجب أن يحصل على القفل نفسه قبل فتح ملف النص أو تعديله.

## تجميع الموجّه + system prompt

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

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

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

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

### hooks داخلية (hooks Gateway)

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

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

### Plugin hooks (دورة حياة الوكيل + Gateway)

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

- **`before_model_resolve`**: يعمل قبل الجلسة (من دون `messages`) لتجاوز المزوّد/النموذج بشكل حتمي قبل حل النموذج.
- **`before_prompt_build`**: يعمل بعد تحميل الجلسة (مع `messages`) لحقن `prependContext` أو `systemPrompt` أو `prependSystemContext` أو `appendSystemContext` قبل إرسال الموجّه. استخدم `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`**: تحويل نتائج الأدوات بشكل متزامن قبل كتابتها إلى نص جلسة يملكه OpenClaw.
- **`message_received` / `message_sending` / `message_sent`**: hooks الرسائل الواردة + الصادرة.
- **`session_start` / `session_end`**: حدود دورة حياة الجلسة.
- **`gateway_start` / `gateway_stop`**: أحداث دورة حياة Gateway.

قواعد قرار hook لحواجز الإرسال/الأداة الصادرة:

- `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 }` بلا تأثير ولا تمحو إلغاءً سابقًا.

راجع [Plugin hooks](/ar/plugins/hooks) لمعرفة API الخاص بالـ hook وتفاصيل التسجيل.

قد تكيّف Harnesses هذه hooks بشكل مختلف. يحتفظ harness خادم تطبيق Codex
بـ Plugin hooks الخاصة بـ OpenClaw بوصفها عقد التوافق للأسطح المعكوسة الموثقة،
بينما تظل hooks الأصلية لـ Codex آلية Codex منخفضة المستوى منفصلة.

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

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

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

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

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

- يتم تجميع الحمولات النهائية من:
  - نص المساعد (ومع reasoning اختياري)
  - ملخصات الأدوات المضمنة (عندما يكون verbose + مسموحًا)
  - نص خطأ المساعد عندما يخطئ النموذج
- تتم تصفية الرمز الصامت الدقيق `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` بإجهاض طلب النموذج عندما لا تصل أي مقاطع استجابة قبل نافذة الخمول. عيّنه صراحةً للنماذج المحلية البطيئة أو مزوّدي reasoning/استدعاء الأدوات؛ وعيّنه إلى 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) — تهيئة مستوى التفكير/الاستدلال
