Fundamentals
زماناجراهای عاملها
یک زماناجرای عامل مالک یک حلقهٔ مدل آمادهشده است: پرامپت را دریافت میکند، خروجی مدل را هدایت میکند، فراخوانیهای بومی ابزار را مدیریت میکند و نوبت تکمیلشده را به OpenClaw بازمیگرداند.
زمانهای اجرا را بهراحتی میتوان با ارائهدهندگان اشتباه گرفت، زیرا هر دو در نزدیکی پیکربندی مدل ظاهر میشوند. آنها لایههای متفاوتی هستند:
| لایه | نمونهها | مفهوم |
|---|---|---|
| ارائهدهنده | anthropic, github-copilot, openai |
نحوهٔ احراز هویت OpenClaw، کشف مدلها و نامگذاری ارجاعهای مدل. |
| مدل | claude-opus-4-6, gpt-5.6-sol |
مدل انتخابشده برای نوبت عامل. |
| زماناجرای عامل | claude-cli, codex, copilot, openclaw |
حلقه یا پشتیبان سطح پایینی که نوبت آمادهشده را اجرا میکند. |
| کانال | Discord, Slack, Telegram, WhatsApp | محل ورود و خروج پیامها در OpenClaw. |
هارنس پیادهسازیای است که یک زماناجرای عامل را فراهم میکند (اصطلاح
کدنویسی). برای نمونه، هارنس همراه Codex زماناجرای codex را پیادهسازی میکند.
پیکربندی عمومی از agentRuntime.id در ورودیهای ارائهدهنده یا مدل استفاده میکند؛
کلیدهای زماناجرای کل عامل قدیمی هستند و نادیده گرفته میشوند. openclaw doctor --fix
سنجاقهای قدیمی زماناجرای کل عامل را حذف میکند و ارجاعهای قدیمی مدل زمان اجرا را،
در صورت نیاز، به ارجاعهای متعارف ارائهدهنده/مدل بههمراه سیاست زماناجرای محدود به
مدل بازنویسی میکند.
دو خانوادهٔ زمان اجرا:
- هارنسهای تعبیهشده درون حلقهٔ عامل آمادهشدهٔ OpenClaw اجرا میشوند:
زماناجرای داخلی
openclaw، بهعلاوهٔ هارنسهای Plugin ثبتشده مانندcodexوcopilot. - پشتیبانهای CLI یک فرایند محلی CLI را اجرا میکنند و در عین حال ارجاع مدل را
متعارف نگه میدارند. برای نمونه،
anthropic/claude-opus-4-8همراه باagentRuntime.id: "claude-cli"محدود به مدل، یعنی «مدل Anthropic را انتخاب کن و از طریق Claude CLI اجرا کن».claude-cliشناسهٔ هارنس تعبیهشده نیست و نباید برای انتخاب AgentHarness ارسال شود.
هارنس copilot یک هارنس Plugin خارجی، جداگانه و اختیاری برای GitHub Copilot CLI
است؛ برای تصمیم کاربرمحور میان PI، Codex و زماناجرای عامل GitHub Copilot، به
زماناجرای عامل GitHub Copilot مراجعه کنید.
سطوح Codex
چندین سطح از نام Codex استفاده میکنند:
| سطح | نام/پیکربندی OpenClaw | کاری که انجام میدهد |
|---|---|---|
| زماناجرای بومی app-server در Codex | ارجاعهای مدل openai/* |
نوبتهای عامل تعبیهشدهٔ OpenAI را از طریق Codex app-server اجرا میکند. این روش معمول راهاندازی اشتراک ChatGPT/Codex است. |
| نمایههای احراز هویت OAuth در Codex | نمایههای OAuth با openai |
احراز هویت اشتراک ChatGPT/Codex را ذخیره میکند که هارنس Codex app-server از آن استفاده میکند. |
| آداپتور ACP در Codex | runtime: "acp", agentId: "codex" |
Codex را از طریق صفحهٔ کنترل خارجی ACP/acpx اجرا میکند. فقط زمانی استفاده کنید که ACP/acpx صراحتاً درخواست شده باشد. |
| مجموعه فرمانهای بومی کنترل چت Codex | /codex ... |
رشتههای Codex app-server را از چت متصل، ازسرگرفته، هدایت، متوقف و بررسی میکند. |
| مسیر API پلتفرم OpenAI برای سطوح غیرعاملی | openai/* بههمراه احراز هویت کلید API |
APIهای مستقیم OpenAI مانند تصویر، تعبیهسازی، گفتار و بلادرنگ. |
این سطوح عمداً از یکدیگر مستقل هستند. فعالکردن Plugin codex قابلیتهای بومی
app-server را در دسترس قرار میدهد؛ openclaw doctor --fix مسئول ترمیم مسیرهای
قدیمی Codex و پاکسازی سنجاقهای منسوخ نشست است. اکنون انتخاب openai/* برای مدل
عامل یعنی «این را از طریق Codex اجرا کن»، مگر اینکه یک سطح API غیرعاملی OpenAI
در حال استفاده باشد.
راهاندازی متداول اشتراک ChatGPT/Codex از OAuth در Codex برای احراز هویت استفاده
میکند، اما ارجاع مدل را بهشکل openai/* نگه میدارد و زماناجرای codex را
انتخاب میکند:
{ agents: { defaults: { model: "openai/gpt-5.6-sol", }, },}این یعنی OpenClaw یک ارجاع مدل OpenAI را انتخاب میکند و سپس از زماناجرای Codex app-server میخواهد نوبت عامل تعبیهشده را اجرا کند. این بهمعنای «استفاده از صورتحساب API» نیست و همچنین به این معنا نیست که کانال، کاتالوگ ارائهدهندهٔ مدل یا مخزن نشست OpenClaw به Codex تبدیل میشود.
هنگامی که Plugin همراه codex فعال است، برای کنترل Codex با زبان طبیعی، بهجای
ACP از سطح فرمان بومی /codex (/codex bind، /codex threads،
/codex resume، /codex steer، /codex stop) استفاده کنید. فقط زمانی از ACP
برای Codex استفاده کنید که کاربر صراحتاً ACP/acpx را درخواست کرده یا در حال آزمایش
مسیر آداپتور ACP باشد. Claude Code، Gemini CLI، OpenCode، Cursor و هارنسهای
خارجی مشابه همچنان از ACP استفاده میکنند.
درخت تصمیم:
- اتصال/کنترل/رشته/ازسرگیری/هدایت/توقف Codex -> هنگامی که Plugin همراه
codexفعال است، سطح فرمان بومی/codex. - Codex بهعنوان زماناجرای تعبیهشده یا تجربهٔ معمول عامل Codex با پشتوانهٔ اشتراک ->
openai/<model>. - انتخاب صریح OpenClaw برای یک مدل OpenAI -> ارجاع مدل را بهشکل
openai/<model>نگه دارید و سیاست زماناجرای ارائهدهنده/مدل را رویagentRuntime.id: "openclaw"تنظیم کنید. نمایهٔ OAuth انتخابشدهٔopenaiدر داخل از طریق انتقال احراز هویت Codex متعلق به OpenClaw مسیریابی میشود. - ارجاعهای قدیمی مدل Codex در پیکربندی -> با
openclaw doctor --fixآنها را بهopenai/<model>ترمیم کنید؛ هرجا ارجاع مدل قدیمی بر آن دلالت داشته باشد، doctor با افزودنagentRuntime.id: "codex"محدود به ارائهدهنده/مدل، مسیر احراز هویت Codex را حفظ میکند. ارجاعهای قدیمی مدلcodex-cli/*نیز به همان مسیر Codex app-server باopenai/<model>ترمیم میشوند؛ OpenClaw دیگر پشتیبان همراه Codex CLI را نگه نمیدارد. - درخواست صریح ACP، acpx یا آداپتور ACP در Codex ->
runtime: "acp"وagentId: "codex". - Claude Code، Gemini CLI، OpenCode، Cursor، Droid یا هر هارنس خارجی دیگر -> ACP/acpx، نه زماناجرای بومی زیرعامل.
| منظورتان این است... | استفاده کنید از... |
|---|---|
| کنترل چت/رشتهٔ Codex app-server | /codex ... از Plugin همراه codex |
| زماناجرای عامل تعبیهشدهٔ Codex app-server | ارجاعهای مدل عامل openai/* |
| OAuth در OpenAI Codex | نمایههای OAuth با openai |
| Claude Code یا هارنس خارجی دیگر | ACP/acpx |
برای تفکیک پیشوندهای خانوادهٔ OpenAI، به OpenAI و ارائهدهندگان مدل مراجعه کنید. برای قرارداد پشتیبانی زماناجرای Codex، به زماناجرای هارنس Codex مراجعه کنید.
مالکیت زمان اجرا
زمانهای اجرای مختلف، مالک بخشهای متفاوتی از حلقه هستند:
| سطح | تعبیهشده در OpenClaw | Codex app-server |
|---|---|---|
| مالک حلقهٔ مدل | OpenClaw، از طریق اجراکنندهٔ تعبیهشدهٔ OpenClaw | Codex app-server |
| وضعیت متعارف رشته | رونوشت OpenClaw | رشتهٔ Codex، بهعلاوهٔ آینهٔ رونوشت OpenClaw |
| ابزارهای پویای OpenClaw | حلقهٔ بومی ابزار OpenClaw | از طریق آداپتور Codex پلزنی میشوند |
| ابزارهای بومی پوسته و فایل | مسیر OpenClaw | ابزارهای بومی Codex، با پلزنی از طریق هوکهای بومی در صورت پشتیبانی |
| موتور زمینه | مونتاژ بومی زمینه در OpenClaw | OpenClaw زمینهٔ مونتاژشده را به نوبت Codex میفرستد |
| Compaction | OpenClaw یا موتور زمینهٔ انتخابشده | Compaction بومی Codex، همراه با اعلانهای OpenClaw و نگهداری آینه |
| تحویل کانال | OpenClaw | OpenClaw |
قاعدهٔ طراحی: اگر OpenClaw مالک سطح باشد، میتواند رفتار عادی هوک Plugin را فراهم کند. اگر زماناجرای بومی مالک سطح باشد، OpenClaw به رویدادهای زمان اجرا یا هوکهای بومی نیاز دارد. اگر زماناجرای بومی مالک وضعیت متعارف رشته باشد، OpenClaw بهجای بازنویسی اجزای داخلی پشتیبانینشده، زمینه را آینه و نگاشت میکند.
انتخاب زمان اجرا
OpenClaw پس از حل ارائهدهنده و مدل، زماناجرای تعبیهشده را بهترتیب زیر تعیین میکند:
- سیاست زماناجرای محدود به مدل اولویت دارد. این سیاست در ورودی مدل یک
ارائهدهندهٔ پیکربندیشده، یا در
agents.defaults.models["provider/model"].agentRuntime/agents.list[].models["provider/model"].agentRuntimeقرار دارد. نویسهٔ عام ارائهدهنده مانندagents.defaults.models["vllm/*"].agentRuntimeپس از سیاست دقیق مدل اعمال میشود؛ بنابراین مدلهای ارائهدهنده که بهصورت پویا کشف شدهاند میتوانند بدون بازنویسی استثناهای دقیق هر مدل، یک زمان اجرا را بهاشتراک بگذارند. - سیاست زماناجرای محدود به ارائهدهنده:
models.providers.<provider>.agentRuntime. - حالت
auto: زمانهای اجرای Plugin ثبتشده میتوانند جفتهای ارائهدهنده/مدل پشتیبانیشده را در اختیار بگیرند. - اگر در حالت
autoهیچچیز نوبت را در اختیار نگیرد، OpenClaw بهعنوان زماناجرای سازگاری بهopenclawبازمیگردد. هنگامی که اجرا باید سختگیرانه باشد، از یک شناسهٔ صریح زمان اجرا استفاده کنید.
سنجاقهای زماناجرای کل نشست و کل عامل نادیده گرفته میشوند:
OPENCLAW_AGENT_RUNTIME، وضعیت agentHarnessId/agentRuntimeOverride نشست،
agents.defaults.agentRuntime و agents.list[].agentRuntime. برای حذف پیکربندی
منسوخ زماناجرای کل عامل و تبدیل ارجاعهای قدیمی مدل زمان اجرا در مواردی که بتوان
قصد را حفظ کرد، openclaw doctor --fix را اجرا کنید.
زمانهای اجرای صریح Plugin در سطح ارائهدهنده/مدل بهصورت بسته شکست میخورند:
agentRuntime.id: "codex" در یک ارائهدهنده یا مدل بهمعنای Codex یا یک خطای
شفاف انتخاب/زمان اجرا است و هرگز بیسروصدا به OpenClaw بازگردانده نمیشود. فقط
auto میتواند یک نوبت بدون تطابق را به OpenClaw مسیریابی کند.
نامهای مستعار پشتیبان CLI با شناسههای هارنس تعبیهشده تفاوت دارند. قالب ترجیحی Claude CLI:
{ agents: { defaults: { model: "anthropic/claude-opus-4-8", models: { "anthropic/claude-opus-4-8": { agentRuntime: { id: "claude-cli" }, }, }, }, },}ارجاعهای قدیمی مانند claude-cli/claude-opus-4-7 برای سازگاری همچنان پشتیبانی
میشوند، اما پیکربندی جدید باید ارائهدهنده/مدل را متعارف نگه دارد و پشتیبان اجرا
را در سیاست زماناجرای ارائهدهنده/مدل قرار دهد.
ارجاعهای قدیمی codex-cli/* متفاوتاند: doctor آنها را به openai/* مهاجرت
میدهد تا بهجای حفظ پشتیبان Codex CLI، از طریق هارنس Codex app-server اجرا شوند.
حالت auto عمداً برای بیشتر ارائهدهندگان محافظهکارانه است. مدلهای عامل OpenAI
استثنا هستند: هم زماناجرای تنظیمنشده و هم auto به هارنس Codex منتهی میشوند.
پیکربندی صریح زماناجرای OpenClaw همچنان یک مسیر سازگاری اختیاری برای نوبتهای
عامل openai/* است؛ وقتی این مسیر با یک نمایهٔ OAuth انتخابشدهٔ openai همراه
باشد، OpenClaw آن را در داخل از طریق انتقال احراز هویت Codex مسیریابی میکند و
در عین حال ارجاع عمومی مدل را بهشکل openai/* نگه میدارد. سنجاقهای منسوخ
نشست زماناجرای OpenAI در انتخاب زمان اجرا نادیده گرفته میشوند و میتوان آنها
را با openclaw doctor --fix پاک کرد.
اگر openclaw doctor هشدار دهد که Plugin codex فعال است، در حالی که
ارجاعهای قدیمی مدل Codex همچنان در پیکربندی باقی ماندهاند، آن را وضعیت قدیمی
مسیر در نظر بگیرید و openclaw doctor --fix را اجرا کنید تا با زماناجرای Codex
به openai/* بازنویسی شود.
زماناجرای عامل GitHub Copilot
Plugin خارجی @openclaw/copilot یک زماناجرای اختیاری copilot را ثبت میکند
که GitHub Copilot CLI (@github/copilot-sdk) پشتیبان آن است. این Plugin ارائهدهندهٔ
اشتراک استاندارد github-copilot را در اختیار میگیرد و هرگز توسط
auto انتخاب نمیشود. از طریق agentRuntime.id برای هر مدل یا هر ارائهدهنده آن را فعال کنید:
{ agents: { defaults: { model: "github-copilot/gpt-5.5", models: { "github-copilot/gpt-5.5": { agentRuntime: { id: "copilot" }, }, }, }, },}هارنس، ارائهدهنده، زماناجرا، کلید نشست CLI و پیشوند نمایهٔ احراز هویت خود را
در extensions/copilot/doctor-contract-api.ts در اختیار میگیرد؛ فایلی که openclaw doctor
آن را بهطور خودکار بارگذاری میکند. برای پیکربندی، احراز هویت، آینهسازی رونوشت، Compaction،
قرارداد اعلانی doctor و تصمیمگیری گستردهتر دربارهٔ PI در برابر Codex در برابر Copilot SDK،
به زماناجرای عامل GitHub Copilot مراجعه کنید.
قرارداد سازگاری
وقتی یک زماناجرا متعلق به OpenClaw نیست، مستندات آن باید مشخص کنند که از کدام سطوح OpenClaw پشتیبانی میکند:
| پرسش | دلیل اهمیت |
|---|---|
| مالک حلقهٔ مدل کیست؟ | مشخص میکند تلاشهای مجدد، ادامهٔ ابزار و تصمیمگیری دربارهٔ پاسخ نهایی در کجا انجام میشوند. |
| مالک تاریخچهٔ استاندارد رشته کیست؟ | مشخص میکند آیا OpenClaw میتواند تاریخچه را ویرایش کند یا فقط آن را آینهسازی میکند. |
| آیا ابزارهای پویای OpenClaw کار میکنند؟ | پیامرسانی، نشستها، Cron و ابزارهای متعلق به OpenClaw به این قابلیت وابستهاند. |
| آیا هوکهای ابزار پویا کار میکنند؟ | Pluginها انتظار دارند before_tool_call، after_tool_call و میانافزار پیرامون ابزارهای متعلق به OpenClaw وجود داشته باشند. |
| آیا هوکهای ابزار بومی کار میکنند؟ | پوسته، وصله و ابزارهای متعلق به زماناجرا برای اعمال خطمشی و مشاهده به پشتیبانی بومی از هوک نیاز دارند. |
| آیا چرخهٔ عمر موتور زمینه اجرا میشود؟ | Pluginهای حافظه و زمینه به چرخهٔ عمر سرهمبندی، دریافت، پس از نوبت و Compaction وابستهاند. |
| چه دادههای Compaction ارائه میشوند؟ | برخی Pluginها فقط به اعلانها نیاز دارند؛ برخی دیگر به فرادادهٔ نگهداشتهشده/حذفشده نیازمندند. |
| چه مواردی عمداً پشتیبانی نمیشوند؟ | کاربران نباید در مواردی که زماناجرای بومی مالک وضعیت بیشتری است، همارزی با OpenClaw را فرض کنند. |
قرارداد پشتیبانی زماناجرای Codex در زماناجرای هارنس Codex مستند شده است.
برچسبهای وضعیت
خروجی وضعیت میتواند هر دو برچسب Execution و Runtime را نمایش دهد. آنها را
بهعنوان اطلاعات تشخیصی بخوانید، نه نام ارائهدهنده:
- ارجاع مدلی مانند
openai/gpt-5.6-solهمان ارائهدهنده/مدل انتخابشده است. - شناسهٔ زماناجرایی مانند
codexحلقهای است که نوبت را اجرا میکند. - برچسب کانالی مانند Telegram یا Discord محلی است که گفتگو در آن انجام میشود.
اگر اجرایی زماناجرای غیرمنتظرهای را نشان میدهد، ابتدا خطمشی زماناجرای ارائهدهنده/مدل انتخابشده را بررسی کنید. پینهای قدیمی زماناجرای نشست دیگر مسیریابی را تعیین نمیکنند.
