--- read_when: - Ви обираєте між PI, Codex, ACP або іншим нативним середовищем виконання агента - Вам незрозумілі мітки постачальника/моделі/середовища виконання у статусі або конфігурації - Ви документуєте паритет підтримки для нативної обв’язки summary: Як OpenClaw розділяє постачальників моделей, моделі, канали та середовища виконання агентів title: Середовища виконання агентів x-i18n: generated_at: "2026-05-11T20:31:09Z" 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` видаляє старі прив’язки середовища виконання на рівні всього агента й переписує застарілі посилання на моделі середовища виконання на канонічні посилання провайдера/моделі плюс політику середовища виконання на рівні моделі там, де це потрібно. Є дві родини середовищ виконання: - **Вбудовані harnesses** працюють усередині підготовленого агентного циклу OpenClaw. Нині це вбудоване середовище виконання `pi` плюс зареєстровані plugin harnesses, як-от `codex`. - **CLI-бекенди** запускають локальний процес CLI, зберігаючи канонічне посилання на модель. Наприклад, `anthropic/claude-opus-4-7` із `agentRuntime.id: "claude-cli"` на рівні моделі означає «вибрати модель Anthropic, виконати через Claude CLI». `claude-cli` не є ідентифікатором вбудованого harness і не має передаватися до вибору AgentHarness. ## Поверхні Codex Найбільше плутанини виникає через кілька різних поверхонь, які використовують назву Codex: | Поверхня | Назва/конфігурація OpenClaw | Що вона робить | | ------------------------------------------------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------- | | Нативне середовище виконання Codex app-server | `openai/*` посилання на моделі | Запускає вбудовані агентні ходи OpenAI через Codex app-server. Це звичайне налаштування підписки ChatGPT/Codex. | | Профілі автентифікації Codex OAuth | `openai-codex` провайдер автентифікації | Зберігає автентифікацію підписки ChatGPT/Codex, яку споживає harness Codex app-server. | | Адаптер Codex ACP | `runtime: "acp"`, `agentId: "codex"` | Запускає Codex через зовнішню площину керування ACP/acpx. Використовуйте лише тоді, коли явно запитано ACP/acpx. | | Нативний набір команд керування чатом Codex | `/codex ...` | Прив’язує, відновлює, спрямовує, зупиняє й перевіряє потоки Codex app-server із чату. | | Маршрут OpenAI Platform API для неагентних поверхонь | `openai/*` плюс автентифікація API-ключем | Використовується для прямих API OpenAI, як-от зображення, embeddings, мовлення й realtime. | Ці поверхні навмисно незалежні. Увімкнення plugin `codex` робить нативні функції app-server доступними; `openclaw doctor --fix` відповідає за виправлення застарілого маршруту `openai-codex/*` і очищення застарілих прив’язок сесій. Вибір `openai/*` як моделі агента тепер означає «запустити це через Codex», якщо не використовується неагентна поверхня OpenAI API. Типове налаштування підписки ChatGPT/Codex використовує Codex OAuth для автентифікації, але зберігає посилання на модель як `openai/*` і вибирає середовище виконання `codex`: ```json5 { agents: { defaults: { model: "openai/gpt-5.5", }, }, } ``` Це означає, що OpenClaw вибирає посилання на модель OpenAI, а потім просить середовище виконання Codex app-server запустити вбудований агентний хід. Це не означає «використовувати білінг 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 і подібні зовнішні harnesses усе ще використовують ACP. Це дерево рішень для агентів: 1. Якщо користувач просить **Codex bind/control/thread/resume/steer/stop**, використовуйте нативну командну поверхню `/codex`, коли вбудований plugin `codex` увімкнено. 2. Якщо користувач просить **Codex як вбудоване середовище виконання** або хоче звичайний агентний досвід Codex на основі підписки, використовуйте `openai/`. 3. Якщо користувач явно вибирає **PI для моделі OpenAI**, збережіть посилання на модель як `openai/` і встановіть політику середовища виконання провайдера/моделі як `agentRuntime.id: "pi"`. Вибраний профіль автентифікації `openai-codex` маршрутизується всередині через застарілий транспорт Codex-auth PI. 4. Якщо застаріла конфігурація все ще містить **`openai-codex/*` посилання на моделі**, виправте її на `openai/` за допомогою `openclaw doctor --fix`; doctor зберігає маршрут автентифікації Codex, додаючи `agentRuntime.id: "codex"` на рівні провайдера/моделі там, де старе посилання на модель це передбачало. 5. Якщо користувач явно каже **ACP**, **acpx** або **адаптер Codex ACP**, використовуйте ACP з `runtime: "acp"` і `agentId: "codex"`. 6. Якщо запит стосується **Claude Code, Gemini CLI, OpenCode, Cursor, Droid або іншого зовнішнього harness**, використовуйте ACP/acpx, а не нативне середовище виконання sub-agent. | Ви маєте на увазі... | Використовуйте... | | --------------------------------------- | -------------------------------------------- | | Керування чатом/потоком Codex app-server | `/codex ...` із вбудованого plugin `codex` | | Вбудоване агентне середовище виконання Codex app-server | `openai/*` посилання на моделі агента | | OpenAI Codex OAuth | `openai-codex` профілі автентифікації | | Claude Code або інший зовнішній harness | ACP/acpx | Про розділення префіксів родини OpenAI див. [OpenAI](/uk/providers/openai) і [Провайдери моделей](/uk/concepts/model-providers). Контракт підтримки середовища виконання Codex див. у [Середовище виконання Codex harness](/uk/plugins/codex-harness-runtime#v1-support-contract). ## Відповідальність середовища виконання Різні середовища виконання відповідають за різні частини циклу. | Поверхня | Вбудований OpenClaw PI | Codex app-server | | --------------------------- | --------------------------------------- | --------------------------------------------------------------------------- | | Власник циклу моделі | OpenClaw через вбудований runner PI | Codex app-server | | Канонічний стан потоку | Транскрипт OpenClaw | Потік Codex плюс дзеркало транскрипту OpenClaw | | Динамічні інструменти OpenClaw | Нативний цикл інструментів OpenClaw | Передаються через адаптер Codex | | Нативні інструменти shell і файлів | Шлях PI/OpenClaw | Нативні інструменти Codex, передані через нативні hooks там, де підтримується | | Двигун контексту | Нативне складання контексту OpenClaw | OpenClaw projects зібраний контекст у хід Codex | | Compaction | OpenClaw або вибраний двигун контексту | Нативне compaction Codex з повідомленнями OpenClaw і підтримкою дзеркала | | Доставка каналом | OpenClaw | OpenClaw | Це розділення відповідальності є головним правилом дизайну: - Якщо OpenClaw володіє поверхнею, OpenClaw може надавати звичайну поведінку plugin hooks. - Якщо нативне середовище виконання володіє поверхнею, OpenClaw потрібні події середовища виконання або нативні hooks. - Якщо нативне середовище виконання володіє канонічним станом потоку, OpenClaw має дзеркалити й проєктувати контекст, а не переписувати непідтримувані внутрішні дані. ## Вибір середовища виконання OpenClaw вибирає вбудоване середовище виконання після визначення провайдера й моделі: 1. Політика середовища виконання на рівні моделі має пріоритет. Вона може міститися в налаштованому записі моделі провайдера або в `agents.defaults.models["provider/model"].agentRuntime` / `agents.list[].models["provider/model"].agentRuntime`. 2. Далі застосовується політика середовища виконання на рівні провайдера в `models.providers..agentRuntime`. 3. У режимі `auto` зареєстровані середовища виконання plugin можуть заявляти про підтримувані пари провайдер/модель. 4. Якщо жодне середовище виконання не заявляє хід у режимі `auto`, OpenClaw використовує PI як середовище виконання сумісності. Використовуйте явний ідентифікатор середовища виконання, коли запуск має бути суворим. Прив’язки середовища виконання на рівні всієї сесії та всього агента ігноруються. Це включає `OPENCLAW_AGENT_RUNTIME`, стан сесії `agentHarnessId`/`agentRuntimeOverride`, `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. Запустіть `openclaw doctor --fix`, щоб видалити застарілу конфігурацію середовища виконання на рівні всього агента й перетворити застарілі посилання на моделі середовища виконання там, де OpenClaw може зберегти намір. Явні середовища виконання 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-auth, зберігаючи публічне посилання на модель як `openai/*`. Застарілі прив’язки сесій OpenAI PI ігноруються під час вибору середовища виконання й можуть бути очищені за допомогою `openclaw doctor --fix`. Якщо `openclaw doctor` попереджає, що plugin `codex` увімкнено, тоді як `openai-codex/*` залишається в конфігурації, розглядайте це як застарілий стан маршруту. Запустіть `openclaw doctor --fix`, щоб переписати його на `openai/*` із середовищем виконання Codex. ## Контракт сумісності Коли середовище виконання не є PI, воно має документувати, які поверхні OpenClaw підтримує. Використовуйте цю форму для документації середовища виконання: | Запитання | Чому це важливо | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | Хто володіє циклом моделі? | Визначає, де відбуваються повторні спроби, продовження інструментів і ухвалення рішення щодо фінальної відповіді. | | Хто володіє канонічною історією треду? | Визначає, чи може OpenClaw редагувати історію, чи лише віддзеркалювати її. | | Чи працюють динамічні інструменти OpenClaw? | На це покладаються обмін повідомленнями, сесії, cron та інструменти, якими володіє OpenClaw. | | Чи працюють хуки динамічних інструментів? | Plugins очікують `before_tool_call`, `after_tool_call` і middleware навколо інструментів, якими володіє OpenClaw. | | Чи працюють хуки нативних інструментів? | Shell, patch та інструменти, якими володіє середовище виконання, потребують підтримки нативних хуків для політик і спостереження. | | Чи виконується життєвий цикл контекстного рушія? | Плагіни пам’яті та контексту залежать від життєвого циклу assemble, ingest, after-turn і compaction. | | Які дані compaction розкриваються? | Деяким Plugins потрібні лише сповіщення, тоді як іншим потрібні метадані збереженого/відкинутого. | | Що навмисно не підтримується? | Користувачі не повинні припускати еквівалентність PI там, де нативне середовище виконання володіє більшим обсягом стану. | Контракт підтримки середовища виконання Codex задокументовано в [середовище виконання Codex harness](/uk/plugins/codex-harness-runtime#v1-support-contract). ## Мітки стану Вивід стану може показувати обидві мітки: `Execution` і `Runtime`. Сприймайте їх як діагностику, а не як назви провайдерів. - Посилання на модель, як-от `openai/gpt-5.5`, повідомляє вибраного провайдера/модель. - Ідентифікатор середовища виконання, як-от `codex`, повідомляє, який цикл виконує turn. - Мітка каналу, як-от Telegram або Discord, повідомляє, де відбувається розмова. Якщо запуск усе ще показує неочікуване середовище виконання, спершу перевірте політику середовища виконання для вибраного провайдера/моделі. Застарілі прив’язки середовища виконання сесії більше не визначають маршрутизацію. ## Пов’язане - [Codex harness](/uk/plugins/codex-harness) - [Середовище виконання Codex harness](/uk/plugins/codex-harness-runtime) - [OpenAI](/uk/providers/openai) - [Plugins агентного harness](/uk/plugins/sdk-agent-harness) - [Цикл агента](/uk/concepts/agent-loop) - [Моделі](/uk/concepts/models) - [Стан](/uk/cli/status)