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