Fundamentals
پرامپت سیستم
OpenClaw برای هر اجرای عامل یک پرامپت سیستمی سفارشی میسازد. پرامپت متعلق به OpenClaw است و از پرامپت پیشفرض زمان اجرا استفاده نمیکند.
این پرامپت توسط OpenClaw مونتاژ و به هر اجرای عامل تزریق میشود.
مونتاژ پرامپت سه لایه دارد:
buildAgentSystemPromptپرامپت را از ورودیهای صریح رندر میکند. باید یک رندرکنندهٔ خالص بماند و پیکربندی سراسری را مستقیماً نخواند.resolveAgentSystemPromptConfigکنترلهای پرامپت متکی به پیکربندی را برای یک عامل مشخص حل میکند؛ مانند نمایش مالک، راهنماییهای TTS، نامهای مستعار مدل، حالت ارجاع به حافظه، و حالت واگذاری به عامل فرعی.- آداپترهای زمان اجرا (تعبیهشده، CLI، پیشنمایشهای فرمان/صدور، Compaction) واقعیتهای زنده مانند ابزارها، وضعیت سندباکس، قابلیتهای کانال، فایلهای زمینه، و مشارکتهای پرامپتی ارائهدهنده را گردآوری میکنند، سپس facade پیکربندیشدهٔ پرامپت را فراخوانی میکنند.
این کار سطحهای پرامپت صادرشده/اشکالزدایی را با اجراهای زنده همراستا نگه میدارد بدون اینکه هر جزئیات مختص زمان اجرا به یک سازندهٔ یکپارچهٔ عظیم تبدیل شود.
Pluginهای ارائهدهنده میتوانند بدون جایگزینکردن کل پرامپت متعلق به OpenClaw، راهنمایی پرامپتی آگاه از کش ارائه کنند. زمان اجرای ارائهدهنده میتواند:
- مجموعهٔ کوچکی از بخشهای هستهٔ نامگذاریشده را جایگزین کند (
interaction_style,tool_call_style,execution_bias) - یک پیشوند پایدار بالای مرز کش پرامپت تزریق کند
- یک پسوند پویا پایین مرز کش پرامپت تزریق کند
از مشارکتهای متعلق به ارائهدهنده برای تنظیمات مختص خانوادهٔ مدل استفاده کنید.
جهش قدیمی پرامپت before_prompt_build را برای سازگاری یا تغییرات واقعاً سراسری
پرامپت نگه دارید، نه رفتار عادی ارائهدهنده.
لایهٔ خانوادهٔ OpenAI GPT-5 قاعدهٔ اجرای هسته را کوچک نگه میدارد و راهنمایی مختص مدل را برای چسبیدن به پرسونا، خروجی موجز، انضباط ابزار، جستوجوی موازی، پوشش خروجیهای تحویلی، راستیآزمایی، زمینهٔ مفقود، و پاکیزگی ابزار ترمینال اضافه میکند.
ساختار
پرامپت عمداً فشرده است و از بخشهای ثابت استفاده میکند:
- ابزارها: یادآور منبع حقیقت ابزارهای ساختاریافته بههمراه راهنمایی استفاده از ابزار در زمان اجرا.
- سوگیری اجرا: راهنمایی فشرده برای پیگیری تا پایان: روی درخواستهای قابل اقدام در همان نوبت عمل کن، تا انجامشدن یا مسدودشدن ادامه بده، از نتایج ضعیف ابزار بازیابی کن، وضعیت تغییرپذیر را زنده بررسی کن، و پیش از نهاییکردن راستیآزمایی کن.
- ایمنی: یادآور کوتاه حفاظتی برای پرهیز از رفتار قدرتطلبانه یا دورزدن نظارت.
- Skills (وقتی در دسترس باشد): به مدل میگوید چگونه دستورالعملهای skill را در صورت نیاز بارگذاری کند.
- کنترل OpenClaw: به مدل میگوید برای کارهای پیکربندی/راهاندازی مجدد، ابزار
gatewayرا ترجیح دهد و از اختراع فرمانهای CLI خودداری کند. - بهروزرسانی خودکار OpenClaw: چگونگی بررسی امن پیکربندی با
config.schema.lookup، وصلهکردن پیکربندی باconfig.patch، جایگزینی کامل پیکربندی باconfig.apply، و اجرایupdate.runفقط با درخواست صریح کاربر. ابزار عاملمحورgatewayهمچنین از بازنویسیtools.exec.ask/tools.exec.securityخودداری میکند، از جمله نامهای مستعار قدیمیtools.bash.*که به آن مسیرهای exec محافظتشده نرمال میشوند. - فضای کاری: دایرکتوری کاری (
agents.defaults.workspace). - مستندات: مسیر محلی مستندات/منبع OpenClaw و اینکه چه زمانی باید آنها را خواند.
- فایلهای فضای کاری (تزریقشده): نشان میدهد فایلهای راهانداز در پایین گنجانده شدهاند.
- سندباکس (وقتی فعال باشد): زمان اجرای سندباکسشده، مسیرهای سندباکس، و اینکه آیا exec ارتقایافته در دسترس است را نشان میدهد.
- تاریخ و زمان فعلی: فقط منطقهٔ زمانی (پایدار برای کش؛ ساعت زنده از
session_statusمیآید). - دستورالعملهای خروجی دستیار: نحو فشردهٔ پیوست، یادداشت صوتی، و برچسب پاسخ.
- Heartbeatها: پرامپت Heartbeat و رفتار تأیید، وقتی Heartbeatها برای عامل پیشفرض فعالاند.
- زمان اجرا: میزبان، سیستمعامل، Node، مدل، ریشهٔ مخزن (وقتی تشخیص داده شود)، سطح تفکر (یک خط).
- استدلال: سطح دید فعلی + راهنمای کلید /reasoning.
OpenClaw محتوای پایدار بزرگ، از جمله زمینهٔ پروژه، را بالای مرز داخلی کش پرامپت نگه میدارد. بخشهای ناپایدار کانال/نشست مانند راهنمایی تعبیهٔ Control UI، پیامرسانی، صدا، زمینهٔ گفتوگوی گروهی، واکنشها، Heartbeatها، و زمان اجرا پایین آن مرز افزوده میشوند تا backendهای محلی دارای کش پیشوند بتوانند پیشوند پایدار فضای کاری را در نوبتهای کانال بازاستفاده کنند. توضیحات ابزار نیز به همین ترتیب باید از قراردادن نامهای فعلی کانال خودداری کنند وقتی schema پذیرفتهشده از قبل آن جزئیات زمان اجرا را حمل میکند.
بخش ابزارها همچنین شامل راهنمایی زمان اجرا برای کارهای طولانیمدت است:
- برای پیگیری آینده (
check back later، یادآورها، کار تکرارشونده) از Cron استفاده کن نه حلقههای sleep درexec، ترفندهای تأخیرyieldMs، یا polling تکراریprocess - از
exec/processفقط برای فرمانهایی استفاده کن که اکنون شروع میشوند و در پسزمینه به اجرا ادامه میدهند - وقتی بیدارسازی تکمیل خودکار فعال است، فرمان را یکبار شروع کن و به مسیر بیدارسازی مبتنی بر push تکیه کن وقتی خروجی منتشر میکند یا شکست میخورد
- وقتی لازم است یک فرمان در حال اجرا را بررسی کنی، برای لاگها، وضعیت، ورودی، یا مداخله
از
processاستفاده کن - اگر کار بزرگتر است،
sessions_spawnرا ترجیح بده؛ تکمیل عامل فرعی مبتنی بر push است و خودکار به درخواستکننده اعلام میشود - فقط برای انتظار تکمیل،
subagents list/sessions_listرا در حلقه poll نکن
agents.defaults.subagents.delegationMode میتواند این راهنمایی را تقویت کند.
حالت پیشفرض suggest تلنگر پایه را نگه میدارد. prefer یک بخش اختصاصی
واگذاری به عامل فرعی اضافه میکند که به عامل اصلی میگوید مانند هماهنگکنندهای
پاسخگو عمل کند و هر چیزی فراتر از پاسخ مستقیم را از طریق sessions_spawn پیش ببرد.
این فقط پرامپتی است؛ سیاست ابزار همچنان کنترل میکند که آیا sessions_spawn
در دسترس است یا نه.
وقتی ابزار آزمایشی update_plan فعال باشد، ابزارها همچنین به مدل میگوید فقط برای
کارهای چندمرحلهای غیرساده از آن استفاده کند، دقیقاً یک مرحلهٔ in_progress نگه دارد،
و پس از هر بهروزرسانی کل برنامه را تکرار نکند.
حفاظهای ایمنی در پرامپت سیستمی توصیهای هستند. آنها رفتار مدل را هدایت میکنند اما سیاست را اجرا نمیکنند. برای اجرای سختگیرانه از سیاست ابزار، تأییدهای exec، سندباکس، و allowlistهای کانال استفاده کنید؛ اپراتورها میتوانند اینها را عمداً غیرفعال کنند.
در کانالهایی با کارتها/دکمههای تأیید بومی، پرامپت زمان اجرا اکنون به عامل میگوید
ابتدا به همان UI تأیید بومی تکیه کند. فقط وقتی نتیجهٔ ابزار میگوید تأییدهای چت
در دسترس نیستند یا تأیید دستی تنها مسیر است، باید فرمان دستی /approve را شامل کند.
حالتهای پرامپت
OpenClaw میتواند برای عاملهای فرعی پرامپتهای سیستمی کوچکتری رندر کند. زمان اجرا برای
هر اجرا یک promptMode تنظیم میکند (نه یک پیکربندی کاربرمحور):
full(پیشفرض): همهٔ بخشهای بالا را شامل میشود.minimal: برای عاملهای فرعی استفاده میشود؛ یادآوری حافظه، بهروزرسانی خودکار OpenClaw، نامهای مستعار مدل، هویت کاربر، دستورالعملهای خروجی دستیار، پیامرسانی، پاسخهای خاموش، و Heartbeatها را حذف میکند. ابزارها، ایمنی، Skills وقتی ارائه شده باشد، فضای کاری، سندباکس، تاریخ و زمان فعلی (وقتی شناخته باشد)، زمان اجرا، و زمینهٔ تزریقشده در دسترس میمانند.none: فقط خط هویت پایه را برمیگرداند.
وقتی promptMode=minimal باشد، پرامپتهای تزریقشدهٔ اضافی بهجای زمینهٔ گفتوگوی گروهی
با برچسب زمینهٔ عامل فرعی مشخص میشوند.
برای اجراهای پاسخ خودکار کانال، OpenClaw بخش عمومی پاسخهای خاموش را حذف میکند
وقتی زمینهٔ مستقیم، گروهی، یا فقط ابزار پیام مالک قرارداد پاسخ قابل مشاهده باشد.
فقط حالت قدیمی گروه/کانال خودکار باید NO_REPLY را نشان دهد؛ چتهای مستقیم و
پاسخهای فقط ابزار پیام راهنمایی توکن خاموش دریافت نمیکنند.
اسنپشاتهای پرامپت
OpenClaw اسنپشاتهای پرامپت ثبتشده را برای مسیر موفق زمان اجرای Codex زیر
test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/ نگه میدارد. آنها
پارامترهای منتخب thread/turn سرور برنامه بههمراه یک پشتهٔ بازسازیشدهٔ لایههای
پرامپت متصل به مدل را برای نوبتهای مستقیم Telegram، گروه Discord، و Heartbeat رندر میکنند.
آن پشته شامل fixture پرامپت مدل Codex gpt-5.5 پینشده است که از شکل کاتالوگ/کش مدل Codex
تولید شده، متن توسعهدهندهٔ مجوز مسیر موفق Codex، دستورالعملهای توسعهدهندهٔ OpenClaw،
دستورالعملهای حالت همکاری محدود به نوبت وقتی OpenClaw آنها را ارائه میکند، ورودی نوبت کاربر،
و ارجاعها به مشخصات پویای ابزار.
fixture پرامپت مدل Codex پینشده را با
pnpm prompt:snapshots:sync-codex-model تازهسازی کنید. بهصورت پیشفرض، اسکریپت ابتدا
کش زمان اجرای Codex را در $CODEX_HOME/models_cache.json جستوجو میکند، سپس
~/.codex/models_cache.json، و فقط بعد از آن به قرارداد checkout نگهدارندهٔ Codex
در ~/code/codex/codex-rs/models-manager/models.json برمیگردد. اگر هیچکدام از این
منابع وجود نداشته باشد، فرمان بدون تغییر fixture ثبتشده خارج میشود. برای تازهسازی
از یک فایل مشخص models_cache.json یا models.json، --catalog <path> را پاس بدهید.
این اسنپشاتها همچنان ثبت خام byte-for-byte درخواست OpenAI نیستند. Codex میتواند
زمینهٔ فضای کاری متعلق به زمان اجرا مانند AGENTS.md، زمینهٔ محیط،
حافظهها، دستورالعملهای برنامه/Plugin، و دستورالعملهای داخلی حالت همکاری
Default را پس از ارسال پارامترهای thread و turn توسط OpenClaw، داخل زمان اجرای Codex اضافه کند.
آنها را با pnpm prompt:snapshots:gen دوباره تولید کنید و drift را با
pnpm prompt:snapshots:check راستیآزمایی کنید. CI بررسی drift را در shard مرزی
اضافی اجرا میکند تا تغییرات پرامپت و بهروزرسانیهای اسنپشات به همان PR متصل بمانند.
تزریق راهانداز فضای کاری
فایلهای راهانداز از فضای کاری فعال resolve میشوند، سپس به سطح پرامپتی هدایت میشوند که با طول عمرشان مطابق است:
AGENTS.mdSOUL.mdTOOLS.mdIDENTITY.mdUSER.mdHEARTBEAT.mdBOOTSTRAP.md(فقط در فضاهای کاری کاملاً جدید)MEMORY.mdوقتی وجود داشته باشد
در harness بومی Codex، OpenClaw از تکرار فایلهای پایدار فضای کاری در هر نوبت کاربر
خودداری میکند. Codex از طریق کشف اسناد پروژهٔ خودش AGENTS.md را بارگذاری میکند.
SOUL.md، IDENTITY.md، TOOLS.md، و USER.md بهعنوان دستورالعملهای توسعهدهندهٔ
Codex ارسال میشوند. فهرست فشردهٔ Skills در OpenClaw نیز بهعنوان دستورالعملهای
توسعهدهندهٔ همکاری محدود به نوبت ارسال میشود. محتوای HEARTBEAT.md تزریق نمیشود؛
نوبتهای Heartbeat یک یادداشت حالت همکاری دریافت میکنند که وقتی فایل وجود دارد و
خالی نیست، به آن اشاره میکند. محتوای MEMORY.md از فضای کاری عامل پیکربندیشده
در هر نوبت بومی Codex چسبانده نمیشود؛ وقتی ابزارهای حافظه برای آن فضای کاری
در دسترس باشند، نوبتهای Codex در دستورالعملهای توسعهدهندهٔ همکاری محدود به نوبت
یک یادداشت کوچک حافظهٔ فضای کاری دریافت میکنند و وقتی حافظهٔ پایدار مرتبط است
باید از memory_search یا memory_get استفاده کنند. اگر ابزارها غیرفعال باشند،
جستوجوی حافظه در دسترس نباشد، یا فضای کاری فعال با فضای کاری حافظهٔ عامل متفاوت باشد،
MEMORY.md به مسیر عادی زمینهٔ محدود نوبت برمیگردد. محتوای فعال BOOTSTRAP.md
فعلاً نقش عادی زمینهٔ نوبت را حفظ میکند.
در harnessهای غیر Codex، فایلهای راهانداز همچنان طبق gateهای موجودشان در
پرامپت OpenClaw ترکیب میشوند. HEARTBEAT.md در اجراهای عادی حذف میشود وقتی
Heartbeatها برای عامل پیشفرض غیرفعال باشند یا
agents.defaults.heartbeat.includeSystemPromptSection برابر false باشد. فایلهای
تزریقشده را موجز نگه دارید، بهویژه MEMORY.md غیر Codex. هدف MEMORY.md این است
که یک خلاصهٔ بلندمدت گزینششده بماند؛ یادداشتهای روزانهٔ تفصیلی باید در memory/*.md
قرار بگیرند، جایی که memory_search و memory_get میتوانند آنها را در صورت نیاز
بازیابی کنند. فایلهای بزرگ MEMORY.md غیر Codex مصرف پرامپت را افزایش میدهند و
ممکن است بهدلیل محدودیتهای فایل راهانداز در پایین، فقط بخشی از آنها تزریق شود.
فایلهای بزرگ با یک نشانگر کوتاه میشوند. حداکثر اندازه برای هر فایل با
agents.defaults.bootstrapMaxChars کنترل میشود (پیشفرض: 20000). مجموع محتوای bootstrap
تزریقشده در همه فایلها با agents.defaults.bootstrapTotalMaxChars
محدود میشود (پیشفرض: 60000). فایلهای گمشده یک نشانگر کوتاهِ فایلِ گمشده تزریق میکنند. وقتی کوتاهسازی
رخ میدهد، OpenClaw میتواند یک اعلان هشدار موجز در پرامپت سیستم تزریق کند؛ این را با
agents.defaults.bootstrapPromptTruncationWarning کنترل کنید (off، once، always؛
پیشفرض: always). شمارشهای خام/تزریقشده تفصیلی در عیبیابیهایی مانند
/context، /status، doctor، و گزارشها باقی میمانند.
برای فایلهای حافظه، کوتاهسازی بهمعنای از دست رفتن داده نیست: فایل روی دیسک دستنخورده باقی میماند.
در Codex بومی، MEMORY.md در صورت در دسترس بودن، از طریق ابزارهای حافظه و بر حسب نیاز خوانده میشود،
با fallback محدود پرامپت وقتی ابزارها نمیتوانند اجرا شوند. در
چارچوبهای اجرای دیگر، مدل فقط نسخه تزریقشده کوتاهشده را میبیند تا زمانی که حافظه را مستقیماً بخواند یا
جستوجو کند. اگر MEMORY.md در آنجا بارها کوتاه میشود، آن را به یک خلاصه بادوام کوتاهتر
تقطیر کنید و تاریخچه تفصیلی را به memory/*.md منتقل کنید،
یا آگاهانه محدودیتهای bootstrap را افزایش دهید.
نشستهای زیرعامل فقط AGENTS.md و TOOLS.md را تزریق میکنند (فایلهای bootstrap دیگر
برای کوچک نگه داشتن زمینه زیرعامل فیلتر میشوند).
hookهای داخلی میتوانند این مرحله را از طریق agent:bootstrap رهگیری کنند تا
فایلهای bootstrap تزریقشده را تغییر دهند یا جایگزین کنند (برای مثال جایگزین کردن SOUL.md با یک شخصیت جایگزین).
اگر میخواهید عامل کمتر عمومی به نظر برسد، با راهنمای شخصیت SOUL.md شروع کنید.
برای بررسی اینکه هر فایل تزریقشده چهقدر سهم دارد (خام در برابر تزریقشده، کوتاهسازی، بههمراه سربار طرحواره ابزار)، از /context list یا /context detail استفاده کنید. زمینه را ببینید.
مدیریت زمان
وقتی منطقه زمانی کاربر شناخته شده باشد، پرامپت سیستم یک بخش اختصاصی تاریخ و زمان فعلی دارد. برای پایدار نگه داشتن کش پرامپت، اکنون فقط شامل منطقه زمانی است (بدون ساعت پویا یا قالب زمان).
وقتی عامل به زمان فعلی نیاز دارد از session_status استفاده کنید؛ کارت وضعیت
یک خط timestamp دارد. همین ابزار میتواند بهصورت اختیاری یک override مدل در سطح نشست
تنظیم کند (model=default آن را پاک میکند).
پیکربندی با:
agents.defaults.userTimezoneagents.defaults.timeFormat(auto|12|24)
برای جزئیات کامل رفتار، تاریخ و زمان را ببینید.
Skills
وقتی Skills واجد شرایط وجود داشته باشند، OpenClaw یک فهرست skills در دسترس فشرده
(formatSkillsForPrompt) تزریق میکند که شامل مسیر فایل و نشانگر
<version> مشتقشده از محتوا برای هر skill است. پرامپت به مدل دستور میدهد از read
برای بارگذاری SKILL.md در مکان فهرستشده (workspace، مدیریتشده، یا bundled) استفاده کند،
و وقتی <version> آن با نوبت قبلی متفاوت است، skill را دوباره بخواند. اگر هیچ
skills واجد شرایطی وجود نداشته باشد، بخش Skills حذف میشود.
نوبتهای Codex بومی این فهرست را بهجای ورودی کاربر در هر نوبت، بهعنوان دستورالعملهای توسعهدهنده همکاری محدود به نوبت دریافت میکنند، بهجز نوبتهای سبک cron که پرامپت زمانبندیشده دقیق را حفظ میکنند. چارچوبهای اجرای دیگر بخش معمول پرامپت را نگه میدارند.
مکان میتواند به یک skill تودرتو اشاره کند، مانند
skills/personal/foo/SKILL.md. تودرتویی فقط سازمانی است؛ پرامپت همچنان
از نام مسطح skill از frontmatter SKILL.md استفاده میکند.
واجد شرایط بودن شامل gateهای فراداده skill، بررسیهای محیط/پیکربندی runtime،
و allowlist مؤثر skill عامل هنگام پیکربندی agents.defaults.skills یا
agents.list[].skills است.
skills همراه Plugin فقط وقتی واجد شرایط هستند که plugin مالک آنها فعال باشد. این به tool plugins اجازه میدهد راهنماهای عملیاتی عمیقتری ارائه کنند، بدون اینکه همه آن راهنمایی مستقیماً در هر توضیح ابزار جاسازی شود.
<available_skills> <skill> <name>...</name> <description>...</description> <location>...</location> <version>sha256:...</version> </skill></available_skills>این کار پرامپت پایه را کوچک نگه میدارد و همچنان استفاده هدفمند از skill را ممکن میکند.
بودجه فهرست skills متعلق به زیرسیستم skills است:
- پیشفرض سراسری:
skills.limits.maxSkillsPromptChars - override برای هر عامل:
agents.list[].skillsLimits.maxSkillsPromptChars
گزیدههای runtime محدودشده عمومی از سطح متفاوتی استفاده میکنند:
agents.defaults.contextLimits.*agents.list[].contextLimits.*
این جداسازی، اندازهگذاری skills را از اندازهگذاری خواندن/تزریق runtime مانند
memory_get، نتایج ابزار زنده، و تازهسازیهای AGENTS.md پس از Compaction جدا نگه میدارد.
مستندات
پرامپت سیستم شامل یک بخش مستندات است. وقتی مستندات محلی در دسترس باشند، به
دایرکتوری مستندات محلی OpenClaw اشاره میکند (docs/ در یک checkout گیت یا مستندات package npm
همراه). اگر مستندات محلی در دسترس نباشند، به
https://docs.openclaw.ai fallback میکند.
همین بخش همچنین مکان source OpenClaw را شامل میشود. checkoutهای گیت، ریشه source محلی را در دسترس میگذارند
تا عامل بتواند کد را مستقیماً بررسی کند. نصبهای package شامل URL source در GitHub هستند
و به عامل میگویند هر زمان مستندات ناقص یا stale هستند، source را آنجا مرور کند.
پرامپت همچنین mirror عمومی مستندات، Discord جامعه، و ClawHub
(https://clawhub.ai) را برای کشف skills یادآوری میکند. این بخش مستندات را
مرجع خودشناسی OpenClaw پیش از آن میداند که مدل بفهمد OpenClaw چگونه کار میکند،
از جمله حافظه/یادداشتهای روزانه، نشستها، ابزارها، Gateway، پیکربندی، دستورها، یا زمینه پروژه.
پرامپت به مدل میگوید ابتدا از مستندات محلی (یا mirror مستندات وقتی مستندات محلی
در دسترس نیستند) استفاده کند، و AGENTS.md، زمینه پروژه، یادداشتهای workspace/profile/memory
و memory_search را بهعنوان زمینه دستورالعمل یا حافظه کاربر تلقی کند، نه دانش طراحی
یا پیادهسازی OpenClaw. اگر مستندات ساکت یا stale باشند، مدل باید این را بگوید
و source را بررسی کند. پرامپت همچنین به مدل میگوید هر وقت ممکن است خودش openclaw status را اجرا کند
و فقط وقتی دسترسی ندارد از کاربر بپرسد.
بهطور خاص برای پیکربندی، عاملها را ابتدا به action ابزار gateway
یعنی config.schema.lookup برای مستندات و محدودیتهای دقیق در سطح field، سپس به
docs/gateway/configuration.md و docs/gateway/configuration-reference.md
برای راهنمایی گستردهتر ارجاع میدهد.