محیط‌های اجرای عامل‌ها

یک زمان اجرای عامل مؤلفه‌ای است که مالک یک حلقهٔ مدل آماده است: پرامپت را دریافت می‌کند، خروجی مدل را پیش می‌برد، فراخوانی‌های ابزار بومی را مدیریت می‌کند، و نوبت کامل‌شده را به OpenClaw بازمی‌گرداند.

زمان‌های اجرا به‌راحتی با ارائه‌دهنده‌ها اشتباه گرفته می‌شوند، چون هر دو نزدیک پیکربندی مدل دیده می‌شوند. آن‌ها لایه‌های متفاوتی هستند:

لایه	نمونه‌ها	معنای آن
ارائه‌دهنده	openai, anthropic, openai-codex	اینکه OpenClaw چگونه احراز هویت می‌کند، مدل‌ها را کشف می‌کند، و نام ارجاع‌های مدل را تعیین می‌کند.
مدل	gpt-5.5, claude-opus-4-6	مدلی که برای نوبت عامل انتخاب شده است.
زمان اجرای عامل	pi, codex, claude-cli	حلقه یا بک‌اند سطح پایینی که نوبت آماده‌شده را اجرا می‌کند.
کانال	Telegram, Discord, Slack, WhatsApp	جایی که پیام‌ها وارد OpenClaw می‌شوند و از آن خارج می‌شوند.

در کد همچنین واژهٔ هارنس را خواهید دید. هارنس پیاده‌سازی‌ای است که یک زمان اجرای عامل را فراهم می‌کند. برای نمونه، هارنس Codex همراه‌شده، زمان اجرای codex را پیاده‌سازی می‌کند. پیکربندی عمومی از agentRuntime.id استفاده می‌کند؛ openclaw doctor --fix کلیدهای قدیمی سیاست زمان اجرا را به همین شکل بازنویسی می‌کند.

دو خانوادهٔ زمان اجرا وجود دارد:

• هارنس‌های جاسازی‌شده داخل حلقهٔ عامل آمادهٔ OpenClaw اجرا می‌شوند. امروز این شامل زمان اجرای داخلی pi به‌علاوهٔ هارنس‌های Plugin ثبت‌شده مانند codex است.
• بک‌اندهای CLI یک فرایند CLI محلی را اجرا می‌کنند، در حالی که ارجاع مدل را canonical نگه می‌دارند. برای مثال، anthropic/claude-opus-4-7 همراه با agentRuntime.id: "claude-cli" یعنی «مدل Anthropic را انتخاب کن، از طریق Claude CLI اجرا کن.» claude-cli شناسهٔ هارنس جاسازی‌شده نیست و نباید به انتخاب AgentHarness پاس داده شود.

# سطوح Codex

بیشتر سردرگمی از چند سطح متفاوت می‌آید که نام Codex را به اشتراک می‌گذارند:

سطح	نام/پیکربندی در OpenClaw	کاری که انجام می‌دهد
زمان اجرای بومی سرور برنامهٔ Codex	ارجاع‌های مدل openai/*	نوبت‌های عامل جاسازی‌شدهٔ OpenAI را از طریق سرور برنامهٔ Codex اجرا می‌کند. این چیدمان معمول اشتراک ChatGPT/Codex است.
پروفایل‌های احراز هویت OAuth مربوط به Codex	ارائه‌دهندهٔ احراز هویت openai-codex	احراز هویت اشتراک ChatGPT/Codex را ذخیره می‌کند که هارنس سرور برنامهٔ Codex مصرف می‌کند.
آداپتور ACP مربوط به Codex	runtime: "acp", agentId: "codex"	Codex را از طریق صفحهٔ کنترل خارجی ACP/acpx اجرا می‌کند. فقط وقتی استفاده کنید که ACP/acpx صراحتا درخواست شده باشد.
مجموعه فرمان‌های کنترل چت بومی Codex	/codex ...	رشته‌های سرور برنامهٔ Codex را از چت متصل، ازسرگرفته، هدایت، متوقف، و بررسی می‌کند.
مسیر API پلتفرم OpenAI برای سطوح غیرعاملی	openai/* به‌علاوهٔ احراز هویت کلید API	برای APIهای مستقیم OpenAI مانند تصویر، embedding، گفتار، و realtime استفاده می‌شود.

این سطوح عمدا مستقل هستند. فعال کردن Plugin codex قابلیت‌های بومی سرور برنامه را در دسترس می‌گذارد؛ openclaw doctor --fix مالک تعمیر مسیر قدیمی openai-codex/* و پاک‌سازی پین‌های جلسهٔ کهنه است. انتخاب openai/* برای مدل عامل اکنون یعنی «این را از طریق Codex اجرا کن»، مگر اینکه یک سطح API غیرعاملی OpenAI در حال استفاده باشد.

چیدمان رایج اشتراک ChatGPT/Codex از OAuth مربوط به Codex برای احراز هویت استفاده می‌کند، اما ارجاع مدل را به‌صورت openai/* نگه می‌دارد و زمان اجرای codex را انتخاب می‌کند:

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
    },
  },
}

این یعنی OpenClaw یک ارجاع مدل OpenAI را انتخاب می‌کند، سپس از زمان اجرای سرور برنامهٔ 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 استفاده می‌کنند.

این درخت تصمیم روبه‌روی عامل است:

1. اگر کاربر اتصال/کنترل/رشته/ازسرگیری/هدایت/توقف Codex را بخواهد، وقتی Plugin همراه‌شدهٔ codex فعال است از سطح فرمان بومی /codex استفاده کنید.
2. اگر کاربر Codex را به‌عنوان زمان اجرای جاسازی‌شده بخواهد یا تجربهٔ معمول عامل Codex متکی بر اشتراک را بخواهد، از openai/<model> استفاده کنید.
3. اگر کاربر صراحتا PI را برای یک مدل OpenAI انتخاب کند، ارجاع مدل را به شکل openai/<model> نگه دارید و agentRuntime.id: "pi" را تنظیم کنید. یک پروفایل احراز هویت انتخاب‌شدهٔ openai-codex به‌صورت داخلی از طریق انتقال قدیمی احراز هویت Codex مربوط به PI مسیریابی می‌شود.
4. اگر پیکربندی قدیمی هنوز شامل ارجاع‌های مدل openai-codex/* است، آن را با openclaw doctor --fix به openai/<model> تعمیر کنید.
5. اگر کاربر صراحتا ACP، acpx، یا آداپتور ACP مربوط به Codex را بگوید، از ACP با runtime: "acp" و agentId: "codex" استفاده کنید.
6. اگر درخواست برای Claude Code، Gemini CLI، OpenCode، Cursor، Droid، یا هارنس خارجی دیگری است، از ACP/acpx استفاده کنید، نه زمان اجرای بومی زیرفرمان عامل.

منظورتان این است...	از این استفاده کنید...
کنترل چت/رشتهٔ سرور برنامهٔ Codex	/codex ... از Plugin همراه‌شدهٔ codex
زمان اجرای عامل جاسازی‌شدهٔ سرور برنامهٔ Codex	ارجاع‌های مدل عامل openai/*
OAuth مربوط به OpenAI Codex	پروفایل‌های احراز هویت openai-codex
Claude Code یا هارنس خارجی دیگر	ACP/acpx

برای جداسازی پیشوند خانوادهٔ OpenAI، OpenAI و ارائه‌دهنده‌های مدل را ببینید. برای قرارداد پشتیبانی زمان اجرای Codex، هارنس Codex را ببینید.

# مالکیت زمان اجرا

زمان‌های اجرای مختلف، مقدار متفاوتی از حلقه را در مالکیت دارند.

سطح	PI جاسازی‌شدهٔ OpenClaw	سرور برنامهٔ Codex
مالک حلقهٔ مدل	OpenClaw از طریق اجراکنندهٔ جاسازی‌شدهٔ PI	سرور برنامهٔ Codex
وضعیت canonical رشته	رونوشت OpenClaw	رشتهٔ Codex، به‌علاوهٔ آینهٔ رونوشت OpenClaw
ابزارهای پویا OpenClaw	حلقهٔ ابزار بومی OpenClaw	از طریق آداپتور Codex پل زده می‌شود
ابزارهای بومی پوسته و فایل	مسیر PI/OpenClaw	ابزارهای بومی Codex، از طریق hookهای بومی در جاهایی که پشتیبانی می‌شود پل زده می‌شود
موتور زمینه	مونتاژ زمینهٔ بومی OpenClaw	OpenClaw زمینهٔ مونتاژشدهٔ پروژه‌ها را به نوبت Codex می‌فرستد
Compaction	OpenClaw یا موتور زمینهٔ انتخاب‌شده	Compaction بومی Codex، همراه با اعلان‌های OpenClaw و نگهداری آینه
تحویل کانالی	OpenClaw	OpenClaw

این جداسازی مالکیت، قاعدهٔ اصلی طراحی است:

• اگر OpenClaw مالک سطح باشد، OpenClaw می‌تواند رفتار معمول hook مربوط به Plugin را فراهم کند.
• اگر زمان اجرای بومی مالک سطح باشد، OpenClaw به رویدادهای زمان اجرا یا hookهای بومی نیاز دارد.
• اگر زمان اجرای بومی مالک وضعیت canonical رشته باشد، OpenClaw باید زمینه را آینه و تصویر کند، نه اینکه بخش‌های داخلی پشتیبانی‌نشده را بازنویسی کند.

# انتخاب زمان اجرا

OpenClaw پس از حل ارائه‌دهنده و مدل، یک زمان اجرای جاسازی‌شده را انتخاب می‌کند:

1. زمان اجرای ثبت‌شدهٔ یک جلسه برنده است. تغییرات پیکربندی یک رونوشت موجود را به‌صورت فوری به سیستم رشتهٔ بومی دیگری جابه‌جا نمی‌کند.
2. OPENCLAW_AGENT_RUNTIME=<id> آن زمان اجرا را برای جلسه‌های جدید یا بازنشانی‌شده اجباری می‌کند.
3. agents.defaults.agentRuntime.id یا agents.list[].agentRuntime.id می‌تواند auto، pi، یک شناسهٔ هارنس جاسازی‌شدهٔ ثبت‌شده مانند codex، یا یک نام مستعار بک‌اند CLI پشتیبانی‌شده مانند claude-cli را تنظیم کند.
4. در حالت auto، زمان‌های اجرای Plugin ثبت‌شده می‌توانند جفت‌های ارائه‌دهنده/مدل پشتیبانی‌شده را claim کنند.
5. اگر هیچ زمان اجرایی در حالت auto یک نوبت را claim نکند، OpenClaw از PI به‌عنوان زمان اجرای سازگاری استفاده می‌کند. وقتی اجرا باید سخت‌گیرانه باشد از شناسهٔ زمان اجرای صریح استفاده کنید.

زمان‌های اجرای Plugin صریح به‌صورت بسته شکست می‌خورند. برای مثال، agentRuntime.id: "codex" یعنی Codex یا یک خطای روشن انتخاب/زمان اجرا؛ هرگز بی‌سروصدا دوباره به PI مسیریابی نمی‌شود.

نام‌های مستعار بک‌اند CLI با شناسه‌های هارنس جاسازی‌شده فرق دارند. شکل ترجیحی Claude CLI این است:

{
  agents: {
    defaults: {
      model: "anthropic/claude-opus-4-7",
      agentRuntime: { id: "claude-cli" },
    },
  },
}

ارجاع‌های قدیمی مانند claude-cli/claude-opus-4-7 برای سازگاری همچنان پشتیبانی می‌شوند، اما پیکربندی جدید باید ارائه‌دهنده/مدل را canonical نگه دارد و بک‌اند اجرا را در agentRuntime.id قرار دهد.

حالت auto برای بیشتر ارائه‌دهنده‌ها عمدا محافظه‌کار است. مدل‌های عامل OpenAI استثنا هستند: زمان اجرای تنظیم‌نشده و auto هر دو به هارنس Codex حل می‌شوند. پیکربندی صریح زمان اجرای PI برای نوبت‌های عامل openai/* همچنان یک مسیر سازگاری opt-in است؛ وقتی با یک پروفایل احراز هویت انتخاب‌شدهٔ openai-codex جفت شود، OpenClaw در داخل PI را از طریق انتقال قدیمی احراز هویت Codex مسیریابی می‌کند، در حالی که ارجاع مدل عمومی را به‌صورت openai/* نگه می‌دارد. پین‌های جلسهٔ OpenAI PI کهنه بدون پیکربندی صریح دوباره به Codex تعمیر می‌شوند.

اگر openclaw doctor هشدار دهد که Plugin codex فعال است در حالی که openai-codex/* همچنان در پیکربندی باقی مانده، آن را وضعیت مسیر قدیمی تلقی کنید. openclaw doctor --fix را اجرا کنید تا آن را با زمان اجرای Codex به openai/* بازنویسی کند.

# قرارداد سازگاری

وقتی یک زمان اجرا PI نیست، باید مستند کند که از کدام سطوح OpenClaw پشتیبانی می‌کند. برای مستندات زمان اجرا از این شکل استفاده کنید:

پرسش	چرا مهم است
مالک حلقهٔ مدل کیست؟	تعیین می‌کند retryها، ادامهٔ ابزار، و تصمیم‌های پاسخ نهایی کجا انجام می‌شوند.
مالک تاریخچهٔ canonical رشته کیست؟	تعیین می‌کند آیا OpenClaw می‌تواند تاریخچه را ویرایش کند یا فقط آن را آینه کند.
آیا ابزارهای پویا OpenClaw کار می‌کنند؟	پیام‌رسانی، جلسه‌ها، cron، و ابزارهای تحت مالکیت OpenClaw به این متکی هستند.
آیا hookهای ابزار پویا کار می‌کنند؟	Pluginها انتظار before_tool_call، after_tool_call، و middleware پیرامون ابزارهای تحت مالکیت OpenClaw را دارند.
آیا hookهای ابزار بومی کار می‌کنند؟	پوسته، patch، و ابزارهای تحت مالکیت زمان اجرا برای سیاست و مشاهده به پشتیبانی hook بومی نیاز دارند.
آیا چرخهٔ عمر موتور زمینه اجرا می‌شود؟	Pluginهای حافظه و زمینه به چرخهٔ عمر assemble، ingest، after-turn، و compaction وابسته‌اند.
چه دادهٔ compaction افشا می‌شود؟	برخی Pluginها فقط به اعلان‌ها نیاز دارند، در حالی که برخی دیگر به metadata مربوط به نگه‌داشته‌شده/حذف‌شده نیاز دارند.
چه چیزی عمدا پشتیبانی نمی‌شود؟	کاربران نباید در جایی که زمان اجرای بومی وضعیت بیشتری را مالک است، معادل بودن با PI را فرض کنند.

قرارداد پشتیبانی زمان اجرای Codex در هارنس Codex مستند شده است.

# برچسب‌های وضعیت

خروجی وضعیت ممکن است هر دو برچسب Execution و Runtime را نشان دهد. آن‌ها را به‌عنوان عیب‌یابی بخوانید، نه به‌عنوان نام ارائه‌دهنده.

• یک ارجاع مدل مانند openai/gpt-5.5 ارائه‌دهنده/مدل انتخاب‌شده را به شما می‌گوید.
• یک شناسه زمان اجرا مانند codex به شما می‌گوید کدام حلقه در حال اجرای نوبت است.
• یک برچسب کانال مانند Telegram یا Discord به شما می‌گوید گفتگو کجا در جریان است.

اگر یک نشست پس از تغییر پیکربندی زمان اجرا همچنان PI را نشان می‌دهد، یک نشست جدید با /new شروع کنید یا نشست فعلی را با /reset پاک کنید. نشست‌های موجود زمان اجرای ثبت‌شده خود را نگه می‌دارند تا یک رونوشت از طریق دو سامانه نشست بومی ناسازگار بازپخش نشود.

# مرتبط

• هارنس Codex
• OpenAI
• Pluginهای هارنس عامل
• حلقه عامل
• مدل‌ها
• وضعیت