---
read_when:
    - به یک راهنمای گام‌به‌گام و دقیق درباره حلقه عامل یا رویدادهای چرخه عمر نیاز دارید
    - در حال تغییر صف‌بندی نشست، نوشتن رونوشت یا رفتار قفل نوشتن نشست هستید
summary: چرخهٔ عمر حلقهٔ عامل، جریان‌ها و معناشناسی انتظار
title: حلقهٔ عامل
x-i18n:
    generated_at: "2026-07-27T15:07:03Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 1d0102ffb6ebf572ea0201470db138775be33b0f0b655d9d08742177be5f3f31
    source_path: concepts/agent-loop.md
    workflow: 16
---

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

## نقاط ورود

- RPC مربوط به Gateway: `agent` و `agent.wait`.
- CLI: `openclaw agent`.

## توالی اجرا

1. RPC مربوط به `agent` پارامترها را اعتبارسنجی می‌کند، نشست را تفکیک می‌کند (`sessionKey`/`sessionId`)، فرادادهٔ نشست را ماندگار می‌کند و بلافاصله `{ runId, acceptedAt }` را برمی‌گرداند.
2. `agentCommand` نوبت را اجرا می‌کند: مدل و پیش‌فرض‌های تفکر/پرحرفی/ردیابی را تفکیک می‌کند، اسنپ‌شات Skills را بارگیری می‌کند، `runEmbeddedAgent` را فراخوانی می‌کند و اگر حلقهٔ تعبیه‌شده قبلاً رویدادی منتشر نکرده باشد، یک **پایان/خطای چرخهٔ حیات** جایگزین منتشر می‌کند.
3. `runEmbeddedAgent`: اجراها را از طریق صف‌های مختص هر نشست و سراسری سریال می‌کند، مدل و پروفایل احراز هویت را تفکیک می‌کند، نشست OpenClaw را می‌سازد، مشترک رویدادهای زمان اجرا می‌شود، دلتاهای دستیار/ابزار را به‌صورت جریانی منتشر می‌کند، مهلت اجرای نوبت را اعمال می‌کند (با انقضای آن اجرا را لغو می‌کند) و محموله‌ها را همراه با فرادادهٔ مصرف برمی‌گرداند. برای نوبت‌های app-server مربوط به Codex، همچنین نوبت پذیرفته‌شده‌ای را که پیش از یک رویداد پایانی دیگر پیشرفتی از app-server تولید نمی‌کند لغو می‌کند.
4. `subscribeEmbeddedAgentSession` رویدادهای زمان اجرا را به جریان `agent` متصل می‌کند: رویدادهای ابزار به `stream: "tool"`، دلتاهای دستیار به `stream: "assistant"` و رویدادهای چرخهٔ حیات به `stream: "lifecycle"` (`phase: "start" | "end" | "error"`).
5. `agent.wait` (`waitForAgentRun`) روی یک `runId` منتظر **پایان/خطای چرخهٔ حیات** می‌ماند و `{ status: ok|error|timeout, startedAt, endedAt, error? }` را برمی‌گرداند.

## صف‌بندی و هم‌زمانی

اجراها به‌ازای هر کلید نشست (مسیر نشست) و در صورت نیاز از طریق یک مسیر سراسری سریال می‌شوند و از رقابت‌های ابزار/نشست جلوگیری می‌کنند. کانال‌های پیام‌رسانی یک حالت صف (هدایت/پیگیری/تجمیع/وقفه) را انتخاب می‌کنند که ورودی این سامانهٔ مسیر است؛ [صف فرمان](/fa/concepts/queue) را ببینید.

نوشتن رونوشت علاوه بر این با یک قفل نوشتن نشست روی فایل نشست محافظت می‌شود. این قفل از فرایند آگاه و مبتنی بر فایل است، بنابراین نویسندگانی را که صف درون‌فرایندی را دور می‌زنند یا از فرایند دیگری می‌آیند شناسایی می‌کند. نویسندگان به‌طور پیش‌فرض تا 60 ثانیه منتظر می‌مانند (بازنویسی با متغیر محیطی `OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS`) و سپس نشست را مشغول گزارش می‌کنند.

قفل‌های نوشتن نشست به‌طور پیش‌فرض بازدرآیند نیستند. یک تابع کمکی که عمداً دریافت تودرتوی همان قفل را با حفظ یک نویسندهٔ منطقی انجام می‌دهد، باید با `allowReentrant: true` صریحاً آن را فعال کند.

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

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

## سرهم‌بندی پرامپت

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

## هوک‌ها

OpenClaw دو سامانهٔ هوک دارد:

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

### هوک‌های داخلی (هوک‌های Gateway)

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

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

### هوک‌های Plugin

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

| هوک                                                    | زمان اجرا                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `before_model_resolve`                                  | پیش از نشست (بدون `messages`)، برای بازنویسی قطعی ارائه‌دهنده/مدل پیش از تفکیک.                                                                                                                                                                                                |
| `before_prompt_build`                                   | پس از بارگیری نشست (با `messages`)، برای تزریق `prependContext`، `systemPrompt`، `prependSystemContext` یا `appendSystemContext` پیش از ارسال. برای متن پویای مختص هر نوبت از `prependContext` و برای راهنمایی پایداری که به فضای پرامپت سامانه تعلق دارد از فیلدهای زمینهٔ سامانه استفاده کنید. |
| `before_agent_reply`                                    | پس از اقدام‌های درون‌خطی و پیش از فراخوانی LLM. به یک Plugin اجازه می‌دهد مالکیت نوبت را بر عهده بگیرد و پاسخی مصنوعی برگرداند یا آن را کاملاً بی‌صدا کند.                                                                                                                                                                |
| `agent_end`                                             | پس از تکمیل، همراه با فهرست نهایی پیام‌ها و فرادادهٔ اجرا.                                                                                                                                                                                                                             |
| `before_compaction` / `after_compaction`                | چرخه‌های Compaction را مشاهده یا حاشیه‌نویسی می‌کند.                                                                                                                                                                                                                                                      |
| `before_tool_call` / `after_tool_call`                  | پارامترها/نتایج ابزار را رهگیری می‌کند.                                                                                                                                                                                                                                                              |
| `before_install`                                        | پس از اجرای خط‌مشی نصب اپراتور، روی محتوای مرحله‌بندی‌شدهٔ نصب Skill/Plugin، هنگامی که هوک‌های 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 }` پایانی است و کنترل‌گرهای با اولویت پایین‌تر را متوقف می‌کند. `{ block: false }` هیچ عملی انجام نمی‌دهد و مسدودسازی پیشین را پاک نمی‌کند.
- `before_install`: همان معناشناسی پایانی/بدون‌عمل بالا را دارد. برای تصمیم‌های اجازه/مسدودسازی نصب تحت مالکیت اپراتور که باید مسیرهای نصب و به‌روزرسانی CLI را پوشش دهند، از `security.installPolicy` استفاده کنید، نه `before_install`.
- `message_sending`: ‏`{ cancel: true }` پایانی است و کنترل‌گرهای با اولویت پایین‌تر را متوقف می‌کند. `{ cancel: false }` هیچ عملی انجام نمی‌دهد و لغو پیشین را پاک نمی‌کند.

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

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

## پخش جریانی

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

## اجرای ابزار

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

## شکل‌دهی پاسخ

محموله‌های نهایی از متن دستیار (به‌علاوهٔ استدلال اختیاری)، خلاصه‌های درون‌خطی ابزار (در صورت پرحرف‌بودن و مجازبودن) و متن خطای دستیار هنگام خطای مدل سرهم‌بندی می‌شوند.

- توکن دقیق سکوت `NO_REPLY` از محموله‌های خروجی حذف می‌شود.
- موارد تکراری ابزار پیام‌رسانی از فهرست نهایی محموله حذف می‌شوند.
- اگر هیچ محمولهٔ قابل‌رندر باقی نماند و ابزاری خطا داده باشد، یک پاسخ جایگزین خطای ابزار منتشر می‌شود؛ مگر اینکه ابزار پیام‌رسانی از قبل پاسخی قابل‌مشاهده برای کاربر فرستاده باشد.

## Compaction و تلاش‌های مجدد

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

## جریان‌های رویداد

- `lifecycle`: توسط `subscribeEmbeddedAgentSession` منتشر می‌شود (و به‌عنوان جایگزین توسط `agentCommand`).
- `assistant`: دلتاهای پخش‌شده از زمان اجرای عامل.
- `tool`: رویدادهای ابزار پخش‌شده از زمان اجرای عامل.

Gateway رویدادهای چرخهٔ حیات و آغاز/پایان ابزار را در [دفتر کل ممیزی](/fa/cli/audit) محدود و
صرفاً مبتنی بر فراداده نگاشت می‌کند. این نگاشت منشأ و
کدهای نتیجه را ثبت می‌کند، بدون آنکه پرامپت‌ها، پیام‌ها، آرگومان‌های ابزار، نتایج ابزار
یا خطاهای خام را از مسیر رونوشت/زمان اجرا کپی کند.

## مدیریت کانال گفت‌وگو

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

## مهلت‌ها

| مهلت زمانی                                          | پیش‌فرض                                | نکات                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------ | -------------------------------------- |   |
| `agent.wait`                                     | 30s                                    | فقط برای انتظار؛ پارامتر `timeoutMs` آن را بازنویسی می‌کند. اجرای زیربنایی را متوقف نمی‌کند.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| زمان اجرای عامل (`agents.defaults.timeoutSeconds`) | 172800s (48h)                          | با تایمر لغو `runEmbeddedAgent` اعمال می‌شود. برای بودجه اجرای نامحدود، `0` را تنظیم کنید؛ ناظران زنده‌بودن جریان مدل همچنان اعمال می‌شوند.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ناظر بی‌خروجی بک‌اند CLI                   | برای هر اجرای تازه/ازسرگرفته‌شده CLI محاسبه می‌شود     | از زمان اجرای عامل جدا است و Plugin بک‌اند ثبت‌شده مالک آن است. یک وظیفه پس‌زمینه داخلی CLI، زیرفرایند والد را به‌اشتراک می‌گذارد و پس از پایان مهلت کلی عامل زنده نمی‌ماند.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| نوبت عامل ایزوله Cron                         | تحت مالکیت Cron                          | زمان‌بند هنگام آغاز اجرا تایمر خود را شروع می‌کند، اجرا را در ضرب‌الاجل پیکربندی‌شده لغو می‌کند، سپس پیش از ثبت پایان مهلت، پاک‌سازی محدودشده را اجرا می‌کند تا یک نشست فرزند منقضی نتواند مسیر اجرا را در حالت گیرکرده نگه دارد.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| مهلت بیکاری مدل                               | ابری 120s؛ خودمیزبان 300s           | اگر پیش از پایان بازه بیکاری هیچ قطعه پاسخی نرسد، OpenClaw درخواست مدل را لغو می‌کند. `models.providers.<id>.timeoutSeconds` این ناظر بیکاری را برای ارائه‌دهندگان محلی/خودمیزبان کُند افزایش می‌دهد، اما همچنان به هر `agents.defaults.timeoutSeconds` متناهیِ کوتاه‌تر یا مهلت مختص اجرا محدود می‌ماند، زیرا آن‌ها کل اجرای عامل را کنترل می‌کنند. بودجه‌های اجرای نامحدود همچنان ناظر بیکاری کلاس ارائه‌دهنده را حفظ می‌کنند. اجراهای مدل ابری که با Cron فعال می‌شوند و مهلت صریح مدل/عامل ندارند، از همین پیش‌فرض استفاده می‌کنند؛ با مهلت صریح اجرای Cron، توقف جریان مدل ابری حداکثر 60s است تا جایگزین‌های پیکربندی‌شده مدل همچنان بتوانند پیش از ضرب‌الاجل بیرونی Cron اجرا شوند. اجراهای فعال‌شده با Cron روی نقاط پایانی واقعاً محلی (baseUrl حلقه‌بازگشت/خصوصی)، امکان انصراف از مهلت بیکاری محلی را حفظ می‌کنند؛ ارائه‌دهندگان خودمیزبان روی baseUrlهای شبکه، ناظر ضمنی 300s را دریافت می‌کنند. با مهلت صریح اجرای Cron، توقف‌های محلی/خودمیزبان حداکثر به همان مهلت محدود می‌شوند. برای ارائه‌دهندگان محلی کُند، `models.providers.<id>.timeoutSeconds` را تنظیم کنید. |
| مهلت درخواست HTTP ارائه‌دهنده                    | `models.providers.<id>.timeoutSeconds` | اتصال، سرآیندها، بدنه، مهلت درخواست SDK، رسیدگی به لغو در guarded-fetch و ناظر بیکاری جریان مدل برای آن ارائه‌دهنده را پوشش می‌دهد. پیش از افزایش مهلت کل زمان اجرای عامل، از آن برای ارائه‌دهندگان محلی/خودمیزبان کُند (برای مثال Ollama) استفاده کنید؛ هنگامی که درخواست مدل باید مدت بیشتری اجرا شود، مهلت عامل/زمان اجرا را دست‌کم به همان اندازه بالا نگه دارید.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### عیب‌یابی نشست گیرکرده

با فعال بودن عیب‌یابی، یک آستانه داخلی دو‌دقیقه‌ای، نشست‌های طولانی `processing` را که هیچ پیشرفت مشاهده‌شده‌ای در پاسخ، ابزار، وضعیت، بلوک یا ACP ندارند، طبقه‌بندی می‌کند:

- اجراهای تعبیه‌شده فعال، فراخوانی‌های مدل و فراخوانی‌های ابزار به‌صورت `session.long_running` گزارش می‌شوند. فراخوانی‌های بی‌صدای مدل که مالک دارند، تا آستانه لغو در حالت `session.long_running` باقی می‌مانند تا ارائه‌دهندگان کُند یا بدون جریان بیش از حد زود متوقف‌شده علامت‌گذاری نشوند.
- کار فعال بدون پیشرفت اخیر به‌صورت `session.stalled` گزارش می‌شود. فراخوانی‌های مدل که مالک دارند، در آستانه لغو یا پس از آن به `session.stalled` تغییر می‌کنند؛ فعالیت منقضی مدل/ابزار که مالک ندارد به‌عنوان فعالیت طولانی‌مدت پنهان نمی‌شود.
- `session.stuck` برای ثبت وضعیت نشست منقضیِ بازیابی‌پذیر محفوظ است، از جمله نشست‌های صف‌شده بیکار با فعالیت منقضی مدل/ابزار که مالک ندارد.

آستانه لغو دست‌کم 5 دقیقه و 3 برابر آستانه هشدار است. ثبت وضعیت نشست منقضی، بلافاصله پس از عبور از دروازه‌های بازیابی، مسیر اجرای نشست آسیب‌دیده را آزاد می‌کند؛ اجراهای تعبیه‌شده متوقف تنها پس از آستانه لغو، لغو و تخلیه می‌شوند، بنابراین کار صف‌شده بدون قطع اجراهایی که صرفاً کُند هستند از سر گرفته می‌شود. بازیابی، نتایج ساختاریافته درخواست‌شده/تکمیل‌شده منتشر می‌کند؛ وضعیت عیب‌یابی فقط زمانی بیکار علامت‌گذاری می‌شود که همان نسل پردازش همچنان جاری باشد، و عیب‌یابی‌های تکراری `session.stuck` تا زمانی که نشست بدون تغییر بماند، با فاصله فزاینده تکرار می‌شوند.

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

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

## مرتبط

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