---
read_when:
    - تحتاج إلى شرح تفصيلي دقيق لحلقة الوكيل أو أحداث دورة الحياة الخاصة بها
summary: دورة حياة حلقة الوكيل، والتدفّقات، ودلالات الانتظار
title: حلقة الوكيل
x-i18n:
    generated_at: "2026-04-12T23:27:58Z"
    model: gpt-5.4
    provider: openai
    source_hash: 3c2986708b444055340e0c91b8fce7d32225fcccf3d197b797665fd36b1991a5
    source_path: concepts/agent-loop.md
    workflow: 15
---

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

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

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

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

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

## كيف يعمل (نظرة عامة)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

- `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/architecture#provider-runtime-hooks) للاطلاع على واجهة Hook وتفاصيل التسجيل.

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

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

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

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

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

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