---
read_when:
    - شما در حال انتخاب بین PI، Codex، ACP یا محیط اجرای عامل بومی دیگری هستید
    - برچسب‌های ارائه‌دهنده/مدل/زمان اجرا در وضعیت یا پیکربندی شما را سردرگم کرده‌اند
    - شما در حال مستندسازی هم‌ارزی پشتیبانی برای یک هارنس بومی هستید
summary: OpenClaw چگونه ارائه‌دهندگان مدل، مدل‌ها، کانال‌ها و محیط‌های اجرای عامل را تفکیک می‌کند
title: محیط‌های اجرای عامل
x-i18n:
    generated_at: "2026-05-10T19:35:02Z"
    model: gpt-5.5
    provider: openai
    source_hash: dc5493bbcfb9fd60d4060455215780ca752040cc09b1b5a4d05bd84a59ce5a1e
    source_path: concepts/agent-runtimes.md
    workflow: 16
---

یک **اجرای عامل** مؤلفه‌ای است که مالک یک حلقهٔ مدل آماده است: پرامپت را
دریافت می‌کند، خروجی مدل را هدایت می‌کند، فراخوانی‌های ابزار بومی را مدیریت می‌کند، و نوبت
تکمیل‌شده را به 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` را انتخاب می‌کند:

```json5
{
  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 استفاده می‌کنند.

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

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>` تعمیر کنید؛ doctor با افزودن
   `agentRuntime.id: "codex"` محدود به ارائه‌دهنده/مدل در جایی که ارجاع مدل
   قدیمی آن را ضمنی کرده بود، مسیر احراز هویت Codex را حفظ می‌کند.
5. اگر کاربر صریحاً **ACP**، **acpx**، یا **آداپتر ACP در Codex** را می‌گوید، از
   ACP با `runtime: "acp"` و `agentId: "codex"` استفاده کنید.
6. اگر درخواست برای **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](/fa/providers/openai) و
[ارائه‌دهندگان مدل](/fa/concepts/model-providers) را ببینید. برای قرارداد پشتیبانی اجرای
Codex، [اجرای harness در Codex](/fa/plugins/codex-harness-runtime#v1-support-contract) را ببینید.

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

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

| سطح                     | 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 پس از حل ارائه‌دهنده و مدل یک اجرای توکار انتخاب می‌کند:

1. سیاست اجرای محدود به مدل اولویت دارد. این می‌تواند در یک ورودی مدل
   ارائه‌دهندهٔ پیکربندی‌شده یا در `agents.defaults.models["provider/model"].agentRuntime` /
   `agents.list[].models["provider/model"].agentRuntime` قرار داشته باشد.
2. سیاست اجرای محدود به ارائه‌دهنده بعد از آن در
   `models.providers.<provider>.agentRuntime` می‌آید.
3. در حالت `auto`، اجراهای Plugin ثبت‌شده می‌توانند زوج‌های ارائه‌دهنده/مدل
   پشتیبانی‌شده را ادعا کنند.
4. اگر هیچ اجرایی در حالت `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 این است:

```json5
{
  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](/fa/plugins/codex-harness-runtime#v1-support-contract) مستند شده است.

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

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

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

اگر یک اجرا همچنان زمان اجرای غیرمنتظره‌ای را نشان می‌دهد، ابتدا سیاست زمان اجرای ارائه‌دهنده/مدل
انتخاب‌شده را بررسی کنید. پین‌های زمان اجرای نشست قدیمی دیگر مسیریابی را تعیین نمی‌کنند.

## مرتبط

- [هارنس Codex](/fa/plugins/codex-harness)
- [زمان اجرای هارنس Codex](/fa/plugins/codex-harness-runtime)
- [OpenAI](/fa/providers/openai)
- [Pluginهای هارنس عامل](/fa/plugins/sdk-agent-harness)
- [حلقه عامل](/fa/concepts/agent-loop)
- [مدل‌ها](/fa/concepts/models)
- [وضعیت](/fa/cli/status)