---
read_when:
    - به یک راهنمای گام‌به‌گام دقیق از حلقهٔ عامل یا رویدادهای چرخهٔ حیات نیاز دارید
    - شما در حال تغییر صف‌بندی نشست، نوشتن رونوشت، یا رفتار قفل نوشتن نشست هستید
summary: چرخهٔ حیات حلقهٔ عامل، جریان‌ها و معناشناسی انتظار
title: حلقهٔ عامل
x-i18n:
    generated_at: "2026-05-02T20:43:18Z"
    model: gpt-5.5
    provider: openai
    source_hash: 39c49e8c5d1e380e0569e31856d855484d5a8fa33b04cf85cccde4c9ac21fbe7
    source_path: concepts/agent-loop.md
    workflow: 16
---

حلقهٔ عاملی اجرای کامل و «واقعی» یک عامل است: دریافت → مونتاژ زمینه → استنتاج مدل →
اجرای ابزار → پاسخ‌های جریانی → ماندگاری. این مسیر مرجع است که یک پیام را
به اقدام‌ها و یک پاسخ نهایی تبدیل می‌کند، در حالی که وضعیت نشست را سازگار نگه می‌دارد.

در OpenClaw، یک حلقه یک اجرای واحد و سریالی‌شده برای هر نشست است که رویدادهای چرخهٔ عمر و جریان را
هنگامی که مدل فکر می‌کند، ابزارها را فراخوانی می‌کند، و خروجی را جریان می‌دهد منتشر می‌کند. این سند توضیح می‌دهد این حلقهٔ اصیل
چگونه از ابتدا تا انتها متصل شده است.

## نقاط ورود

- RPC در Gateway: `agent` و `agent.wait`.
- CLI: فرمان `agent`.

## نحوهٔ کارکرد (سطح بالا)

1. RPC `agent` پارامترها را اعتبارسنجی می‌کند، نشست را حل می‌کند (sessionKey/sessionId)، فرادادهٔ نشست را پایدار می‌کند، و بلافاصله `{ runId, acceptedAt }` را برمی‌گرداند.
2. `agentCommand` عامل را اجرا می‌کند:
   - مدل + پیش‌فرض‌های فکر کردن/پرحرفی/ردیابی را حل می‌کند
   - نمای فوری Skills را بارگذاری می‌کند
   - `runEmbeddedPiAgent` را فراخوانی می‌کند (زمان اجرای pi-agent-core)
   - اگر حلقهٔ تعبیه‌شده چنین رویدادی منتشر نکند، **پایان/خطای چرخهٔ عمر** را منتشر می‌کند
3. `runEmbeddedPiAgent`:
   - اجراها را از طریق صف‌های هر نشست + سراسری سریالی می‌کند
   - مدل + پروفایل احراز هویت را حل می‌کند و نشست Pi را می‌سازد
   - در رویدادهای Pi مشترک می‌شود و دلتاهای دستیار/ابزار را جریان می‌دهد
   - مهلت زمانی را اعمال می‌کند -> اگر از حد بگذرد اجرا را لغو می‌کند
   - برای نوبت‌های app-server در Codex، نوبت پذیرفته‌شده‌ای را که پیش از یک رویداد پایانی دیگر پیشرفت app-server تولید نمی‌کند لغو می‌کند
   - بارهای داده + فرادادهٔ مصرف را برمی‌گرداند
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) را انتخاب کنند که این سامانهٔ مسیر را تغذیه می‌کنند.
  [صف فرمان](/fa/concepts/queue) را ببینید.
- نوشتن رونوشت نیز با یک قفل نوشتن نشست روی فایل نشست محافظت می‌شود. این قفل
  آگاه از فرایند و مبتنی بر فایل است، بنابراین نویسندگانی را که صف درون‌فرایندی را دور می‌زنند یا از
  فرایندی دیگر می‌آیند تشخیص می‌دهد. نویسندگان رونوشت نشست تا `session.writeLock.acquireTimeoutMs`
  منتظر می‌مانند پیش از آنکه نشست را مشغول گزارش کنند؛ مقدار پیش‌فرض `60000` میلی‌ثانیه است.
- قفل‌های نوشتن نشست به‌صورت پیش‌فرض بازگشت‌پذیر نیستند. اگر یک کمک‌کننده عمداً دریافت
  همان قفل را درون خود تو در تو کند و در عین حال یک نویسندهٔ منطقی را حفظ کند، باید به‌صراحت با
  `allowReentrant: true` انتخاب کند.

## آماده‌سازی نشست + فضای کاری

- فضای کاری حل و ایجاد می‌شود؛ اجراهای سندباکس‌شده ممکن است به ریشهٔ فضای کاری سندباکس هدایت شوند.
- Skills بارگذاری می‌شود (یا از یک نمای فوری دوباره استفاده می‌شود) و به env و پرامپت تزریق می‌شود.
- فایل‌های بوت‌استرپ/زمینه حل می‌شوند و به گزارش پرامپت سامانه تزریق می‌شوند.
- یک قفل نوشتن نشست دریافت می‌شود؛ `SessionManager` پیش از جریان‌دهی باز و آماده می‌شود. هر
  مسیر بازنویسی رونوشت، Compaction، یا کوتاه‌سازی بعدی باید پیش از باز کردن یا
  تغییر فایل رونوشت همان قفل را بگیرد.

## مونتاژ پرامپت + پرامپت سامانه

- پرامپت سامانه از پرامپت پایهٔ OpenClaw، پرامپت Skills، زمینهٔ بوت‌استرپ، و بازنویسی‌های هر اجرا ساخته می‌شود.
- محدودیت‌های ویژهٔ مدل و توکن‌های ذخیرهٔ Compaction اعمال می‌شوند.
- برای آنچه مدل می‌بیند، [پرامپت سامانه](/fa/concepts/system-prompt) را ببینید.

## نقاط قلاب (جایی که می‌توانید مداخله کنید)

OpenClaw دو سامانهٔ قلاب دارد:

- **قلاب‌های داخلی** (قلاب‌های Gateway): اسکریپت‌های رویدادمحور برای فرمان‌ها و رویدادهای چرخهٔ عمر.
- **قلاب‌های Plugin**: نقاط توسعه داخل چرخهٔ عمر عامل/ابزار و خط لولهٔ Gateway.

### قلاب‌های داخلی (قلاب‌های Gateway)

- **`agent:bootstrap`**: هنگام ساخت فایل‌های بوت‌استرپ، پیش از نهایی شدن پرامپت سامانه اجرا می‌شود.
  از این برای افزودن/حذف فایل‌های زمینهٔ بوت‌استرپ استفاده کنید.
- **قلاب‌های فرمان**: `/new`، `/reset`، `/stop`، و رویدادهای فرمان دیگر (سند Hooks را ببینید).

برای راه‌اندازی و نمونه‌ها، [قلاب‌ها](/fa/automation/hooks) را ببینید.

### قلاب‌های Plugin (چرخهٔ عمر عامل + Gateway)

این‌ها داخل حلقهٔ عامل یا خط لولهٔ Gateway اجرا می‌شوند:

- **`before_model_resolve`**: پیش از نشست اجرا می‌شود (بدون `messages`) تا پیش از حل مدل، ارائه‌دهنده/مدل را به‌صورت قطعی بازنویسی کند.
- **`before_prompt_build`**: پس از بارگذاری نشست اجرا می‌شود (با `messages`) تا پیش از ارسال پرامپت، `prependContext`، `systemPrompt`، `prependSystemContext`، یا `appendSystemContext` را تزریق کند. از `prependContext` برای متن پویای هر نوبت و از فیلدهای زمینهٔ سامانه برای راهنمایی پایدار که باید در فضای پرامپت سامانه قرار گیرد استفاده کنید.
- **`before_agent_start`**: قلاب سازگاری قدیمی که ممکن است در هر یک از دو فاز اجرا شود؛ قلاب‌های صریح بالا را ترجیح دهید.
- **`before_agent_reply`**: پس از اقدام‌های درون‌خطی و پیش از فراخوانی LLM اجرا می‌شود و به یک Plugin اجازه می‌دهد نوبت را تصاحب کند و یک پاسخ مصنوعی برگرداند یا نوبت را کاملاً ساکت کند.
- **`agent_end`**: فهرست پیام نهایی و فرادادهٔ اجرا را پس از تکمیل بررسی می‌کند.
- **`before_compaction` / `after_compaction`**: چرخه‌های Compaction را مشاهده یا حاشیه‌نویسی می‌کند.
- **`before_tool_call` / `after_tool_call`**: پارامترها/نتایج ابزار را رهگیری می‌کند.
- **`before_install`**: یافته‌های اسکن داخلی را بررسی می‌کند و به‌صورت اختیاری نصب‌های Skills یا Plugin را مسدود می‌کند.
- **`tool_result_persist`**: نتایج ابزار را پیش از نوشته شدن در رونوشت نشست متعلق به OpenClaw، به‌صورت همگام تبدیل می‌کند.
- **`message_received` / `message_sending` / `message_sent`**: قلاب‌های پیام ورودی + خروجی.
- **`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 }` بدون اثر است و لغو قبلی را پاک نمی‌کند.

برای API قلاب و جزئیات ثبت، [قلاب‌های Plugin](/fa/plugins/hooks) را ببینید.

هارنس‌ها ممکن است این قلاب‌ها را متفاوت سازگار کنند. هارنس app-server در Codex
قلاب‌های Plugin در OpenClaw را به‌عنوان قرارداد سازگاری برای سطوح آینه‌شدهٔ مستندشده نگه می‌دارد،
در حالی که قلاب‌های بومی Codex یک سازوکار جداگانهٔ سطح پایین‌تر در Codex باقی می‌مانند.

## جریان‌دهی + پاسخ‌های جزئی

- دلتاهای دستیار از pi-agent-core جریان داده می‌شوند و به‌عنوان رویدادهای `assistant` منتشر می‌شوند.
- جریان‌دهی بلوکی می‌تواند پاسخ‌های جزئی را یا روی `text_end` یا `message_end` منتشر کند.
- جریان‌دهی استدلال می‌تواند به‌عنوان یک جریان جداگانه یا به‌عنوان پاسخ‌های بلوکی منتشر شود.
- برای رفتار بخش‌بندی و پاسخ بلوکی، [جریان‌دهی](/fa/concepts/streaming) را ببینید.

## اجرای ابزار + ابزارهای پیام‌رسانی

- رویدادهای شروع/به‌روزرسانی/پایان ابزار روی جریان `tool` منتشر می‌شوند.
- نتایج ابزار پیش از ثبت/انتشار، از نظر اندازه و بارهای دادهٔ تصویر پاک‌سازی می‌شوند.
- ارسال‌های ابزار پیام‌رسانی ردیابی می‌شوند تا تأییدهای تکراری دستیار سرکوب شوند.

## شکل‌دهی پاسخ + سرکوب

- بارهای دادهٔ نهایی از این موارد مونتاژ می‌شوند:
  - متن دستیار (و استدلال اختیاری)
  - خلاصه‌های ابزار درون‌خطی (وقتی verbose + مجاز باشد)
  - متن خطای دستیار وقتی مدل خطا می‌دهد
- توکن سکوت دقیق `NO_REPLY` / `no_reply` از بارهای دادهٔ خروجی
  فیلتر می‌شود.
- تکرارهای ابزار پیام‌رسانی از فهرست بار دادهٔ نهایی حذف می‌شوند.
- اگر هیچ بار دادهٔ قابل نمایشی باقی نماند و ابزاری خطا داده باشد، یک پاسخ جایگزین خطای ابزار منتشر می‌شود
  (مگر اینکه یک ابزار پیام‌رسانی قبلاً پاسخی قابل مشاهده برای کاربر ارسال کرده باشد).

## Compaction + تلاش‌های دوباره

- Compaction خودکار رویدادهای جریان `compaction` را منتشر می‌کند و می‌تواند یک تلاش دوباره را آغاز کند.
- در تلاش دوباره، بافرهای درون‌حافظه و خلاصه‌های ابزار بازنشانی می‌شوند تا از خروجی تکراری جلوگیری شود.
- برای خط لولهٔ Compaction، [Compaction](/fa/concepts/compaction) را ببینید.

## جریان‌های رویداد (امروز)

- `lifecycle`: توسط `subscribeEmbeddedPiSession` منتشر می‌شود (و به‌عنوان مسیر جایگزین توسط `agentCommand`)
- `assistant`: دلتاهای جریانی از pi-agent-core
- `tool`: رویدادهای جریانی ابزار از pi-agent-core

## مدیریت کانال چت

- دلتاهای دستیار در پیام‌های `delta` چت بافر می‌شوند.
- یک `final` چت روی **پایان/خطای چرخهٔ عمر** منتشر می‌شود.

## مهلت‌های زمانی

- پیش‌فرض `agent.wait`: 30 ثانیه (فقط انتظار). پارامتر `timeoutMs` بازنویسی می‌کند.
- زمان اجرای عامل: پیش‌فرض `agents.defaults.timeoutSeconds` برابر 172800 ثانیه (48 ساعت) است؛ در تایمر لغو `runEmbeddedPiAgent` اعمال می‌شود.
- زمان اجرای Cron: `timeoutSeconds` نوبت عاملِ ایزوله متعلق به cron است. زمان‌بند این تایمر را هنگام آغاز اجرا شروع می‌کند، اجرای زیرین را در ضرب‌الاجل پیکربندی‌شده لغو می‌کند، سپس پیش از ثبت مهلت زمانی، پاک‌سازی محدود را اجرا می‌کند تا یک نشست فرزند کهنه نتواند مسیر را گیر بیندازد.
- عیب‌یابی زنده بودن نشست: با فعال بودن عیب‌یابی، `diagnostics.stuckSessionWarnMs` نشست‌های طولانی `processing` را که هیچ پیشرفت مشاهده‌شده‌ای در پاسخ، ابزار، وضعیت، بلوک، یا ACP ندارند طبقه‌بندی می‌کند. اجراهای تعبیه‌شدهٔ فعال، فراخوانی‌های مدل، و فراخوانی‌های ابزار به‌عنوان `session.long_running` گزارش می‌شوند؛ کار فعال بدون پیشرفت اخیر به‌عنوان `session.stalled` گزارش می‌شود؛ `session.stuck` برای دفترداری نشست کهنه بدون کار فعال محفوظ است، و فقط همان مسیر مسیر نشست تحت تأثیر را آزاد می‌کند تا کار شروع صف‌شده تخلیه شود. عیب‌یابی‌های تکراری `session.stuck` تا وقتی نشست بدون تغییر بماند عقب‌نشینی می‌کنند.
- مهلت زمانی بیکاری مدل: OpenClaw یک درخواست مدل را وقتی پیش از پنجرهٔ بیکاری هیچ قطعهٔ پاسخی نرسد لغو می‌کند. `models.providers.<id>.timeoutSeconds` این نگهبان بیکاری را برای ارائه‌دهنده‌های محلی/خودمیزبان کند گسترش می‌دهد؛ در غیر این صورت OpenClaw هنگام پیکربندی از `agents.defaults.timeoutSeconds` استفاده می‌کند، که به‌صورت پیش‌فرض در 120 ثانیه محدود شده است. اجراهای آغازشده توسط Cron که مهلت زمانی صریح مدل یا عامل ندارند نگهبان بیکاری را غیرفعال می‌کنند و به مهلت زمانی بیرونی cron تکیه می‌کنند.
- مهلت زمانی درخواست HTTP ارائه‌دهنده: `models.providers.<id>.timeoutSeconds` روی دریافت‌های HTTP مدل آن ارائه‌دهنده اعمال می‌شود، از جمله اتصال، سرآیندها، بدنه، مهلت زمانی درخواست SDK، مدیریت لغو guarded-fetch کلی، و نگهبان بیکاری جریان مدل. برای ارائه‌دهنده‌های محلی/خودمیزبان کند مانند Ollama پیش از افزایش مهلت زمانی کل اجرای عامل از این استفاده کنید.

## جاهایی که کار می‌تواند زود پایان یابد

- مهلت زمانی عامل (لغو)
- AbortSignal (لغو)
- قطع اتصال Gateway یا مهلت زمانی RPC
- مهلت زمانی `agent.wait` (فقط انتظار، عامل را متوقف نمی‌کند)

## مرتبط

- [ابزارها](/fa/tools) — ابزارهای عامل موجود
- [قلاب‌ها](/fa/automation/hooks) — اسکریپت‌های رویدادمحور که با رویدادهای چرخهٔ عمر عامل فعال می‌شوند
- [Compaction](/fa/concepts/compaction) — نحوهٔ خلاصه‌سازی گفت‌وگوهای طولانی
- [تأییدیه‌های Exec](/fa/tools/exec-approvals) — دروازه‌های تأیید برای فرمان‌های شل
- [فکر کردن](/fa/tools/thinking) — پیکربندی سطح فکر کردن/استدلال
