Fundamentals
محیطهای اجرای عامل
یک زمان اجرای عامل مؤلفهای است که مالک یک حلقه مدل آماده است: پرامپت را دریافت میکند، خروجی مدل را پیش میبرد، فراخوانیهای ابزار بومی را مدیریت میکند و نوبت تکمیلشده را به OpenClaw برمیگرداند.
زمانهای اجرا بهراحتی با ارائهدهندهها اشتباه گرفته میشوند، چون هر دو نزدیک پیکربندی مدل ظاهر میشوند. اینها لایههای متفاوتی هستند:
| لایه | نمونهها | معنی آن |
|---|---|---|
| ارائهدهنده | openai, anthropic, github-copilot |
اینکه OpenClaw چگونه احراز هویت میکند، مدلها را کشف میکند و ارجاعهای مدل را نامگذاری میکند. |
| مدل | gpt-5.5, claude-opus-4-6 |
مدلی که برای نوبت عامل انتخاب شده است. |
| زمان اجرای عامل | openclaw, codex, copilot, claude-cli |
حلقه یا پشتیبان سطح پایینی که نوبت آمادهشده را اجرا میکند. |
| کانال | Telegram, Discord, Slack, 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 | کاری که انجام میدهد |
|---|---|---|
| زمان اجرای بومی اپسرور Codex | ارجاعهای مدل openai/* |
نوبتهای عامل جاسازیشده OpenAI را از طریق اپسرور Codex اجرا میکند. این راهاندازی معمول اشتراک ChatGPT/Codex است. |
| پروفایلهای احراز هویت OAuth در Codex | پروفایلهای OAuth مربوط به openai |
احراز هویت اشتراک ChatGPT/Codex را ذخیره میکند که هارنس اپسرور Codex مصرف میکند. |
| آداپتور ACP در Codex | runtime: "acp", agentId: "codex" |
Codex را از طریق صفحه کنترل خارجی ACP/acpx اجرا میکند. فقط زمانی استفاده کنید که ACP/acpx صراحتا درخواست شده باشد. |
| مجموعه فرمان کنترل گفتوگوی بومی Codex | /codex ... |
نخهای اپسرور Codex را از گفتوگو متصل، ازسرگیری، هدایت، متوقف و بررسی میکند. |
| مسیر OpenAI Platform API برای سطوح غیرعاملی | openai/* بههمراه احراز هویت کلید API |
برای APIهای مستقیم OpenAI مانند تصویر، embedding، گفتار و realtime استفاده میشود. |
این سطوح عمدا مستقل هستند. فعال کردن Plugin codex قابلیتهای بومی اپسرور را در دسترس قرار میدهد؛ openclaw doctor --fix مالک تعمیر مسیر میراثی میراثی Codex و پاکسازی پینهای نشست کهنه است. انتخاب openai/* برای مدل عامل اکنون یعنی «این را از طریق Codex اجرا کن»، مگر اینکه یک سطح OpenAI API غیرعاملی در حال استفاده باشد.
راهاندازی رایج اشتراک ChatGPT/Codex از OAuth در Codex برای احراز هویت استفاده میکند، اما ارجاع مدل را بهصورت openai/* نگه میدارد و زمان اجرای codex را انتخاب میکند:
{ agents: { defaults: { model: "openai/gpt-5.5", }, },}این یعنی OpenClaw یک ارجاع مدل OpenAI را انتخاب میکند، سپس از زمان اجرای اپسرور Codex میخواهد نوبت عامل جاسازیشده را اجرا کند. این به معنی «استفاده از صورتحساب API» نیست، و به این معنی نیست که کانال، کاتالوگ ارائهدهنده مدل یا ذخیره نشست OpenClaw به Codex تبدیل میشود.
وقتی Plugin همراهسازیشده codex فعال است، کنترل Codex با زبان طبیعی باید از سطح فرمان بومی /codex (/codex bind, /codex threads, /codex resume, /codex steer, /codex stop) بهجای ACP استفاده کند. 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 مسیر احراز هویت Codex را با افزودنagentRuntime.id: "codex"محدود به ارائهدهنده/مدل در جاهایی که ارجاع مدل قدیمی آن را القا میکرد حفظ میکند. ارجاعهای مدل میراثیcodex-cli/*به همان مسیر اپسرور Codex باopenai/<model>تعمیر میشوند؛ OpenClaw دیگر یک پشتیبان Codex CLI همراهسازیشده نگه نمیدارد. - اگر کاربر صراحتا ACP، acpx یا آداپتور ACP در Codex را بگوید، از ACP با
runtime: "acp"وagentId: "codex"استفاده کنید. - اگر درخواست برای Claude Code، Gemini CLI، OpenCode، Cursor، Droid یا هارنس خارجی دیگری است، از ACP/acpx استفاده کنید، نه زمان اجرای زیرعامل بومی.
| منظورتان این است... | استفاده کنید از... |
|---|---|
| کنترل گفتوگو/نخ اپسرور Codex | /codex ... از Plugin همراهسازیشده codex |
| زمان اجرای عامل جاسازیشده اپسرور Codex | ارجاعهای مدل عامل openai/* |
| OAuth در OpenAI Codex | پروفایلهای OAuth مربوط به openai |
| Claude Code یا هارنس خارجی دیگر | ACP/acpx |
برای جداسازی پیشوند خانواده OpenAI، OpenAI و ارائهدهندگان مدل را ببینید. برای قرارداد پشتیبانی زمان اجرای Codex، زمان اجرای هارنس Codex را ببینید.
مالکیت زمان اجرا
زمانهای اجرای مختلف مقدارهای متفاوتی از حلقه را مالک هستند.
| سطح | جاسازیشده OpenClaw | اپسرور Codex |
|---|---|---|
| مالک حلقه مدل | OpenClaw از طریق اجراکننده جاسازیشده OpenClaw | اپسرور Codex |
| وضعیت نخ استاندارد | رونوشت OpenClaw | نخ Codex، بههمراه آینه رونوشت OpenClaw |
| ابزارهای پویای OpenClaw | حلقه ابزار بومی OpenClaw | از طریق آداپتور Codex پل زده میشود |
| ابزارهای پوسته و فایل بومی | مسیر OpenClaw | ابزارهای بومی Codex، در صورت پشتیبانی از طریق قلابهای بومی پل زده میشود |
| موتور زمینه | سرهمسازی زمینه بومی OpenClaw | OpenClaw زمینه پروژهها را داخل نوبت Codex سرهم میکند |
| Compaction | OpenClaw یا موتور زمینه انتخابشده | Compaction بومی Codex، با اعلانهای OpenClaw و نگهداری آینه |
| تحویل کانال | OpenClaw | OpenClaw |
این تقسیم مالکیت قانون اصلی طراحی است:
- اگر OpenClaw مالک سطح باشد، OpenClaw میتواند رفتار عادی قلاب Plugin را فراهم کند.
- اگر زمان اجرای بومی مالک سطح باشد، OpenClaw به رویدادهای زمان اجرا یا قلابهای بومی نیاز دارد.
- اگر زمان اجرای بومی مالک وضعیت استاندارد نخ باشد، OpenClaw باید زمینه را آینه و تصویر کند، نه اینکه داخلیهای پشتیبانینشده را بازنویسی کند.
انتخاب زمان اجرا
OpenClaw پس از حل ارائهدهنده و مدل، یک زمان اجرای جاسازیشده را انتخاب میکند:
- سیاست زمان اجرای محدود به مدل اولویت دارد. این میتواند در یک ورودی مدل ارائهدهنده پیکربندیشده یا در
agents.defaults.models["provider/model"].agentRuntime/agents.list[].models["provider/model"].agentRuntimeباشد. یک wildcard ارائهدهنده مانند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 میتواند نیت را حفظ کند، openclaw doctor --fix را اجرا کنید.
زمانهای اجرای Plugin صریح ارائهدهنده/مدل بسته شکست میخورند. برای مثال، agentRuntime.id: "codex" روی یک ارائهدهنده یا مدل یعنی Codex یا یک خطای روشن انتخاب/زمان اجرا؛ هرگز بیصدا دوباره به 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 اجرا شوند.
حالت 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 را دارند. |
| آیا قلابهای ابزار بومی کار میکنند؟ | ابزارهای پوسته، patch، و ابزارهای متعلق به زمان اجرا برای سیاست و مشاهده به پشتیبانی قلاب بومی نیاز دارند. |
| آیا چرخه عمر موتور زمینه اجرا میشود؟ | Pluginهای حافظه و زمینه به چرخه عمر assemble، ingest، after-turn، و Compaction وابستهاند. |
| چه دادههای Compaction نمایان میشود؟ | برخی Pluginها فقط به اعلانها نیاز دارند، در حالی که برخی دیگر به فراداده نگهداشتهشده/حذفشده نیاز دارند. |
| چه چیزی عمداً پشتیبانی نمیشود؟ | کاربران نباید در جاهایی که زمان اجرای بومی مالک وضعیت بیشتری است، همارزی با OpenClaw را فرض کنند. |
قرارداد پشتیبانی زمان اجرای Codex در زمان اجرای هارنس Codex مستند شده است.
برچسبهای وضعیت
خروجی وضعیت ممکن است هر دو برچسب Execution و Runtime را نشان دهد. آنها را بهعنوان
تشخیص بخوانید، نه نام ارائهدهنده.
- یک ارجاع مدل مانند
openai/gpt-5.5ارائهدهنده/مدل انتخابشده را به شما نشان میدهد. - یک شناسه زمان اجرا مانند
codexبه شما نشان میدهد کدام حلقه در حال اجرای نوبت است. - یک برچسب کانال مانند Telegram یا Discord به شما نشان میدهد گفتگو کجا در حال انجام است.
اگر یک اجرا همچنان زمان اجرای غیرمنتظرهای را نشان میدهد، ابتدا سیاست زمان اجرای ارائهدهنده/مدل انتخابشده را بررسی کنید. پینهای زمان اجرای نشست قدیمی دیگر مسیریابی را تعیین نمیکنند.
