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-5همراه با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 را از طریق app-server متعلق به Codex اجرا میکند. این تنظیم معمول اشتراک ChatGPT/Codex است. |
| پروفایلهای احراز هویت OAuth متعلق به Codex | پروفایلهای OAuth متعلق به openai |
احراز هویت اشتراک ChatGPT/Codex را ذخیره میکند که هارنس app-server متعلق به Codex مصرف میکند. |
| آداپتور ACP متعلق به Codex | runtime: "acp"، agentId: "codex" |
Codex را از طریق صفحهٔ کنترل خارجی ACP/acpx اجرا میکند. فقط زمانی استفاده کنید که ACP/acpx صریحاً درخواست شده باشد. |
| مجموعهفرمان بومی کنترل چت Codex | /codex ... |
رشتههای app-server متعلق به Codex را از چت متصل، ازسرگرفته، هدایت، متوقف و بررسی میکند. |
| مسیر 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 را انتخاب میکند، سپس از زمان اجرای app-server متعلق به Codex میخواهد نوبت عامل تعبیهشده را اجرا کند. این بهمعنای «استفاده از صورتحساب API» نیست و به این معنا نیز نیست که کانال، کاتالوگ ارائهدهندهٔ مدل یا ذخیرهگاه نشست OpenClaw به Codex تبدیل میشود.
وقتی Plugin همراه codex فعال است، برای کنترل Codex با زبان طبیعی بهجای ACP
از سطح فرمان بومی /codex (/codex bind، /codex threads، /codex resume، /codex steer،
/codex stop) استفاده کنید. فقط زمانی برای Codex از ACP استفاده کنید که کاربر صریحاً
ACP/acpx را درخواست کرده یا در حال آزمایش مسیر آداپتور ACP باشد. Claude Code، Gemini CLI،
OpenCode، Cursor و هارنسهای خارجی مشابه همچنان از ACP استفاده میکنند.
درخت تصمیم:
- اتصال/کنترل/رشته/ازسرگیری/هدایت/توقف Codex -> سطح فرمان بومی
/codexهنگامی که Plugin همراهcodexفعال است. - Codex بهعنوان زمان اجرای تعبیهشده یا تجربهٔ عادی عامل Codex با پشتوانهٔ اشتراک ->
openai/<model>. - OpenClaw که صریحاً برای یک مدل OpenAI انتخاب شده است -> ارجاع مدل را بهصورت
openai/<model>نگه دارید و خطمشی زمان اجرای ارائهدهنده/مدل را رویagentRuntime.id: "openclaw"تنظیم کنید. پروفایل OAuth انتخابشدهٔopenaiدر داخل از طریق انتقال احراز هویت Codex متعلق به OpenClaw مسیریابی میشود. - ارجاعهای قدیمی مدل Codex در پیکربندی -> با
openclaw doctor --fixآنها را بهopenai/<model>ترمیم کنید؛ doctor مسیر احراز هویت Codex را با افزودنagentRuntime.id: "codex"محدود به ارائهدهنده/مدل، در جایی که ارجاع مدل قدیمی بر آن دلالت داشت، حفظ میکند. ارجاعهای مدل قدیمیcodex-cli/*به همان مسیر app-server متعلق به Codex درopenai/<model>ترمیم میشوند؛ OpenClaw دیگر بکاند CLI همراه Codex را نگه نمیدارد. - ACP، acpx یا آداپتور ACP متعلق به Codex که صریحاً درخواست شده است ->
runtime: "acp"وagentId: "codex". - Claude Code، Gemini CLI، OpenCode، Cursor، Droid یا هارنس خارجی دیگر -> ACP/acpx، نه زمان اجرای بومی زیرعامل.
| منظورتان این است... | استفاده کنید از... |
|---|---|
| کنترل چت/رشتهٔ app-server متعلق به Codex | /codex ... از Plugin همراه codex |
| زمان اجرای عامل تعبیهشدهٔ app-server متعلق به Codex | ارجاعهای مدل عامل openai/* |
| OAuth متعلق به OpenAI Codex | پروفایلهای OAuth متعلق به openai |
| Claude Code یا هارنس خارجی دیگر | ACP/acpx |
برای تفکیک پیشوند خانوادهٔ OpenAI، OpenAI و ارائهدهندگان مدل را ببینید. برای قرارداد پشتیبانی زمان اجرای Codex، زمان اجرای هارنس Codex را ببینید.
مالکیت زمان اجرا
زمانهای اجرای مختلف، بخشهای متفاوتی از حلقه را در اختیار دارند:
| سطح | تعبیهشده در OpenClaw | app-server متعلق به Codex |
|---|---|---|
| مالک حلقهٔ مدل | OpenClaw، از طریق اجراکنندهٔ تعبیهشدهٔ OpenClaw | app-server متعلق به Codex |
| وضعیت متعارف رشته | رونوشت 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.entries.*.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.entries.*.agentRuntime. برای حذف پیکربندی کهنهٔ زمان اجرای کل عامل و تبدیل
ارجاعهای قدیمی مدل زمان اجرا در مواردی که میتوان مقصود را حفظ کرد،
openclaw doctor --fix را اجرا کنید.
زمانهای اجرای صریح Plugin برای ارائهدهنده/مدل در صورت خطا بسته میمانند: وجود
agentRuntime.id: "codex" در یک ارائهدهنده یا مدل یعنی Codex، یا یک خطای روشن انتخاب/زمان اجرا؛
هرگز بیسروصدا به OpenClaw بازگردانده نمیشود. فقط auto میتواند یک
نوبت تطبیقنیافته را به OpenClaw مسیریابی کند.
نامهای مستعار بکاند CLI با شناسههای هارنس تعبیهشده متفاوتاند. شکل ترجیحی Claude CLI:
{ agents: { defaults: { model: "anthropic/claude-opus-5", models: { "anthropic/claude-opus-5": { agentRuntime: { id: "claude-cli" }, }, }, }, },}ارجاعهای قدیمی مانند claude-cli/claude-opus-4-7 برای
سازگاری همچنان پشتیبانی میشوند، اما پیکربندی جدید باید ارائهدهنده/مدل را متعارف نگه دارد و
بکاند اجرا را در خطمشی زمان اجرای ارائهدهنده/مدل قرار دهد.
ارجاعهای قدیمی codex-cli/* متفاوتاند: doctor آنها را به openai/* مهاجرت میدهد تا
بهجای حفظ بکاند CLI متعلق به Codex، از طریق هارنس app-server متعلق به Codex اجرا شوند.
حالت 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 را ثبت میکند
که از CLI GitHub Copilot (@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 و تصمیم گستردهتر SDK میان PI، Codex و Copilot، به زماناجرای عامل 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 محل انجام مکالمه است.
اگر یک اجرا زماناجرای غیرمنتظرهای را نشان میدهد، ابتدا خطمشی زماناجرای ارائهدهنده/مدل انتخابشده را بررسی کنید. پینهای قدیمی زماناجرای نشست دیگر مسیریابی را تعیین نمیکنند.
