Fundamentals
حلقهٔ عامل
حلقهٔ عامل، اجرای سریالشده و مختص هر نشست است که یک پیام را به اقدامها و یک پاسخ تبدیل میکند: دریافت، سرهمبندی زمینه، استنتاج مدل، اجرای ابزار، پخش جریانی، ماندگارسازی.
نقاط ورود
- RPC مربوط به Gateway:
agentوagent.wait. - CLI:
openclaw agent.
توالی اجرا
- RPC مربوط به
agentپارامترها را اعتبارسنجی میکند، نشست را تفکیک میکند (sessionKey/sessionId)، فرادادهٔ نشست را ماندگار میکند و بلافاصله{ runId, acceptedAt }را برمیگرداند. agentCommandنوبت را اجرا میکند: مدل و پیشفرضهای تفکر/پرحرفی/ردیابی را تفکیک میکند، اسنپشات Skills را بارگیری میکند،runEmbeddedAgentرا فراخوانی میکند و اگر حلقهٔ تعبیهشده قبلاً رویدادی منتشر نکرده باشد، یک پایان/خطای چرخهٔ حیات جایگزین منتشر میکند.runEmbeddedAgent: اجراها را از طریق صفهای مختص هر نشست و سراسری سریال میکند، مدل و پروفایل احراز هویت را تفکیک میکند، نشست OpenClaw را میسازد، مشترک رویدادهای زمان اجرا میشود، دلتاهای دستیار/ابزار را بهصورت جریانی منتشر میکند، مهلت اجرای نوبت را اعمال میکند (با انقضای آن اجرا را لغو میکند) و محمولهها را همراه با فرادادهٔ مصرف برمیگرداند. برای نوبتهای app-server مربوط به Codex، همچنین نوبت پذیرفتهشدهای را که پیش از یک رویداد پایانی دیگر پیشرفتی از app-server تولید نمیکند لغو میکند.subscribeEmbeddedAgentSessionرویدادهای زمان اجرا را به جریانagentمتصل میکند: رویدادهای ابزار بهstream: "tool"، دلتاهای دستیار بهstream: "assistant"و رویدادهای چرخهٔ حیات بهstream: "lifecycle"(phase: "start" | "end" | "error").agent.wait(waitForAgentRun) روی یکrunIdمنتظر پایان/خطای چرخهٔ حیات میماند و{ status: ok|error|timeout, startedAt, endedAt, error? }را برمیگرداند.
صفبندی و همزمانی
اجراها بهازای هر کلید نشست (مسیر نشست) و در صورت نیاز از طریق یک مسیر سراسری سریال میشوند و از رقابتهای ابزار/نشست جلوگیری میکنند. کانالهای پیامرسانی یک حالت صف (هدایت/پیگیری/تجمیع/وقفه) را انتخاب میکنند که ورودی این سامانهٔ مسیر است؛ صف فرمان را ببینید.
نوشتن رونوشت علاوه بر این با یک قفل نوشتن نشست روی فایل نشست محافظت میشود. این قفل از فرایند آگاه و مبتنی بر فایل است، بنابراین نویسندگانی را که صف درونفرایندی را دور میزنند یا از فرایند دیگری میآیند شناسایی میکند. نویسندگان بهطور پیشفرض تا 60 ثانیه منتظر میمانند (بازنویسی با متغیر محیطی OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS) و سپس نشست را مشغول گزارش میکنند.
قفلهای نوشتن نشست بهطور پیشفرض بازدرآیند نیستند. یک تابع کمکی که عمداً دریافت تودرتوی همان قفل را با حفظ یک نویسندهٔ منطقی انجام میدهد، باید با allowReentrant: true صریحاً آن را فعال کند.
آمادهسازی نشست و فضای کاری
- فضای کاری تفکیک و ایجاد میشود؛ اجراهای سندباکسشده ممکن است به ریشهٔ فضای کاری سندباکس هدایت شوند.
- Skills بارگیری میشوند (یا از یک اسنپشات دوباره استفاده میشوند) و به محیط و پرامپت تزریق میشوند.
- فایلهای راهاندازی/زمینه تفکیک و به پرامپت سامانه تزریق میشوند.
- پیش از آغاز پخش جریانی، قفل نوشتن نشست دریافت و مقصد رونوشت نشست آماده میشود. هر مسیر بازنویسی، Compaction یا کوتاهسازی بعدی رونوشت باید پیش از تغییر ردیفهای رونوشت SQLite همان قفل را دریافت کند.
سرهمبندی پرامپت
پرامپت سامانه از پرامپت پایهٔ OpenClaw، پرامپت Skills، زمینهٔ راهاندازی و بازنویسیهای مختص هر اجرا ساخته میشود. محدودیتهای مختص مدل و توکنهای ذخیرهٔ Compaction اعمال میشوند. برای آنچه مدل میبیند، پرامپت سامانه را ببینید.
هوکها
OpenClaw دو سامانهٔ هوک دارد:
- هوکهای داخلی (هوکهای Gateway): اسکریپتهای رویدادمحور برای فرمانها و رویدادهای چرخهٔ حیات.
- هوکهای Plugin: نقاط توسعه درون چرخهٔ حیات عامل/ابزار و پایپلاین Gateway.
هوکهای داخلی (هوکهای Gateway)
agent:bootstrap: هنگام ساخت فایلهای راهاندازی و پیش از نهاییشدن پرامپت سامانه اجرا میشود. از آن برای افزودن یا حذف فایلهای زمینهٔ راهاندازی استفاده کنید.- هوکهای فرمان:
/new،/reset،/stopو دیگر رویدادهای فرمان (سند هوکها را ببینید).
برای راهاندازی و نمونهها، هوکها را ببینید.
هوکهای 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 را ببینید.
مهارها میتوانند این هوکها را سازگار کنند. مهار app-server مربوط به Codex، هوکهای Plugin در OpenClaw را بهعنوان قرارداد سازگاری برای سطوح آینهشدهٔ مستندشده حفظ میکند؛ هوکهای بومی Codex سازوکاری جداگانه در سطح پایینتر Codex هستند.
پخش جریانی
- دلتاهای دستیار از زمان اجرای عامل بهشکل رویدادهای
assistantپخش میشوند. - پخش جریانی بلوکی میتواند پاسخهای جزئی را روی
text_endیاmessage_endمنتشر کند. - پخش جریانی استدلال میتواند جریانی جداگانه باشد یا پاسخهای بلوکی را مسدود کند.
- برای رفتار قطعهبندی و پاسخ بلوکی، پخش جریانی را ببینید.
اجرای ابزار
- رویدادهای آغاز/بهروزرسانی/پایان ابزار روی جریان
toolمنتشر میشوند. - نتایج ابزار پیش از ثبت/انتشار، از نظر اندازه و محمولههای تصویر پاکسازی میشوند.
- ارسالهای ابزار پیامرسانی ردیابی میشوند تا تأییدیههای تکراری دستیار سرکوب شوند.
شکلدهی پاسخ
محمولههای نهایی از متن دستیار (بهعلاوهٔ استدلال اختیاری)، خلاصههای درونخطی ابزار (در صورت پرحرفبودن و مجازبودن) و متن خطای دستیار هنگام خطای مدل سرهمبندی میشوند.
- توکن دقیق سکوت
NO_REPLYاز محمولههای خروجی حذف میشود. - موارد تکراری ابزار پیامرسانی از فهرست نهایی محموله حذف میشوند.
- اگر هیچ محمولهٔ قابلرندر باقی نماند و ابزاری خطا داده باشد، یک پاسخ جایگزین خطای ابزار منتشر میشود؛ مگر اینکه ابزار پیامرسانی از قبل پاسخی قابلمشاهده برای کاربر فرستاده باشد.
Compaction و تلاشهای مجدد
Compaction خودکار رویدادهای جریان compaction را منتشر میکند و میتواند یک تلاش مجدد را فعال کند. هنگام تلاش مجدد، بافرهای درونحافظهای و خلاصههای ابزار بازنشانی میشوند تا از خروجی تکراری جلوگیری شود. Compaction را ببینید.
جریانهای رویداد
lifecycle: توسطsubscribeEmbeddedAgentSessionمنتشر میشود (و بهعنوان جایگزین توسطagentCommand).assistant: دلتاهای پخششده از زمان اجرای عامل.tool: رویدادهای ابزار پخششده از زمان اجرای عامل.
Gateway رویدادهای چرخهٔ حیات و آغاز/پایان ابزار را در دفتر کل ممیزی محدود و صرفاً مبتنی بر فراداده نگاشت میکند. این نگاشت منشأ و کدهای نتیجه را ثبت میکند، بدون آنکه پرامپتها، پیامها، آرگومانهای ابزار، نتایج ابزار یا خطاهای خام را از مسیر رونوشت/زمان اجرا کپی کند.
مدیریت کانال گفتوگو
دلتاهای دستیار در پیامهای 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(فقط انتظار، عامل را متوقف نمیکند)
مرتبط
- ابزارها - ابزارهای عامل موجود
- هوکها - اسکریپتهای رویدادمحور که با رویدادهای چرخه عمر عامل فعال میشوند
- Compaction - نحوه خلاصهسازی گفتوگوهای طولانی
- تأییدهای اجرا - دروازههای تأیید برای فرمانهای پوسته
- تفکر - پیکربندی سطح تفکر/استدلال
