> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Середовища виконання агентів

**Середовище виконання агента** — це компонент, який володіє одним підготовленим циклом моделі: він
отримує промпт, керує виводом моделі, обробляє нативні виклики інструментів і повертає
завершений хід до OpenClaw.

Середовища виконання легко сплутати з провайдерами, бо обидва з’являються поруч із
конфігурацією моделі. Це різні рівні:

| Рівень                      | Приклади                                     | Що це означає                                                                |
| --------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------- |
| Провайдер                   | `openai`, `anthropic`, `github-copilot`      | Як OpenClaw автентифікується, виявляє моделі та називає посилання на моделі. |
| Модель                      | `gpt-5.5`, `claude-opus-4-6`                 | Модель, вибрана для ходу агента.                                             |
| Середовище виконання агента | `openclaw`, `codex`, `copilot`, `claude-cli` | Низькорівневий цикл або бекенд, який виконує підготовлений хід.              |
| Канал                       | Telegram, Discord, Slack, WhatsApp           | Де повідомлення входять до OpenClaw і виходять із нього.                     |

У коді ви також побачите слово **harness**. Harness — це реалізація,
яка надає середовище виконання агента. Наприклад, вбудований Codex harness
реалізує середовище виконання `codex`. Публічна конфігурація використовує `agentRuntime.id` у
записах провайдера або моделі; ключі середовища виконання всього агента є застарілими та ігноруються.
`openclaw doctor --fix` видаляє старі прив’язки середовища виконання всього агента й переписує
застарілі посилання на моделі середовища виконання на канонічні посилання провайдер/модель плюс політику
середовища виконання в області моделі там, де це потрібно.

Є дві родини середовищ виконання:

* **Вбудовані harnesses** працюють усередині підготовленого циклу агента OpenClaw. Сьогодні це
  вбудоване середовище виконання `openclaw` плюс зареєстровані Plugin harnesses, як-от
  `codex` і `copilot`.
* **CLI-бекенди** запускають локальний процес CLI, зберігаючи посилання на модель
  канонічним. Наприклад, `anthropic/claude-opus-4-8` із
  політикою `agentRuntime.id: "claude-cli"` в області моделі означає «вибрати модель Anthropic,
  виконати через Claude CLI». `claude-cli` не є ідентифікатором вбудованого harness
  і не має передаватися до вибору AgentHarness.

Harness `copilot` — це окремий, явний зовнішній Plugin harness для
GitHub Copilot CLI; див. [середовище виконання агента GitHub Copilot](/uk/plugins/copilot)
для користувацького вибору між PI, Codex і середовищем виконання агента GitHub Copilot.

## Поверхні Codex

Найбільше плутанини виникає через кілька різних поверхонь, які мають назву Codex:

| Поверхня                                               | Назва/конфігурація OpenClaw               | Що вона робить                                                                                                 |
| ------------------------------------------------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Нативне середовище виконання app-server Codex          | посилання на моделі `openai/*`            | Запускає вбудовані ходи агента OpenAI через app-server Codex. Це звичайне налаштування підписки ChatGPT/Codex. |
| OAuth-профілі автентифікації Codex                     | OAuth-профілі `openai`                    | Зберігає автентифікацію підписки ChatGPT/Codex, яку споживає app-server harness Codex.                         |
| Адаптер Codex ACP                                      | `runtime: "acp"`, `agentId: "codex"`      | Запускає Codex через зовнішню площину керування ACP/acpx. Використовуйте лише коли ACP/acpx явно запитано.     |
| Нативний набір команд керування чатом Codex            | `/codex ...`                              | Прив’язує, відновлює, спрямовує, зупиняє та перевіряє потоки app-server Codex із чату.                         |
| Маршрут OpenAI Platform API для неагентських поверхонь | `openai/*` плюс автентифікація API-ключем | Використовується для прямих OpenAI API, як-от зображення, embeddings, мовлення та realtime.                    |

Ці поверхні навмисно незалежні. Увімкнення Plugin `codex` робить
нативні функції app-server доступними; `openclaw doctor --fix` володіє ремонтом
застарілих маршрутів Codex і очищенням застарілих прив’язок сесій. Вибір
`openai/*` для моделі агента тепер означає «запустити це через Codex», якщо не
використовується неагентська поверхня OpenAI API.

Типове налаштування підписки ChatGPT/Codex використовує Codex OAuth для автентифікації, але зберігає
посилання на модель як `openai/*` і вибирає середовище виконання `codex`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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. Використовуйте 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/<model>`.
3. Якщо користувач явно вибирає **OpenClaw для моделі OpenAI**, збережіть посилання на модель
   як `openai/<model>` і встановіть політику середовища виконання провайдера/моделі на
   `agentRuntime.id: "openclaw"`. Вибраний OAuth-профіль `openai` маршрутизується
   внутрішньо через транспорт автентифікації Codex OpenClaw.
4. Якщо застаріла конфігурація досі містить **застарілі посилання на моделі Codex**, відремонтуйте її до
   `openai/<model>` за допомогою `openclaw doctor --fix`; doctor зберігає маршрут автентифікації Codex,
   додаючи `agentRuntime.id: "codex"` в області провайдера/моделі там, де старе
   посилання на модель це передбачало.
   Застарілі **посилання на моделі `codex-cli/*`** ремонтуються до того самого маршруту app-server Codex
   `openai/<model>`; OpenClaw більше не зберігає вбудований бекенд Codex CLI.
5. Якщо користувач явно каже **ACP**, **acpx** або **адаптер Codex ACP**, використовуйте
   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/*`      |
| OpenAI Codex OAuth                                     | OAuth-профілі `openai`                     |
| 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                        | app-server Codex                                                             |
| ------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------- |
| Власник циклу моделі                  | OpenClaw через вбудований runner OpenClaw | app-server Codex                                                             |
| Канонічний стан потоку                | Транскрипт OpenClaw                       | Потік Codex плюс дзеркало транскрипту OpenClaw                               |
| Динамічні інструменти OpenClaw        | Нативний цикл інструментів OpenClaw       | З’єднані через адаптер Codex                                                 |
| Нативні shell- та файлові інструменти | Шлях OpenClaw                             | Нативні інструменти Codex, з’єднані через нативні хуки там, де підтримується |
| Рушій контексту                       | Нативне складання контексту OpenClaw      | OpenClaw проєктує зібраний контекст у хід Codex                              |
| Compaction                            | OpenClaw або вибраний рушій контексту     | Нативне стискання Codex із сповіщеннями OpenClaw і підтримкою дзеркала       |
| Доставка каналом                      | OpenClaw                                  | OpenClaw                                                                     |

Цей поділ володіння є головним правилом дизайну:

* Якщо OpenClaw володіє поверхнею, OpenClaw може надавати звичайну поведінку Plugin hooks.
* Якщо нативне середовище виконання володіє поверхнею, OpenClaw потрібні події середовища виконання або нативні хуки.
* Якщо нативне середовище виконання володіє канонічним станом потоку, OpenClaw має дзеркалити і проєктувати контекст, а не переписувати непідтримувані внутрішні частини.

## Вибір середовища виконання

OpenClaw вибирає вбудоване середовище виконання після визначення провайдера й моделі:

1. Політика середовища виконання в області моделі має пріоритет. Вона може жити в налаштованому записі моделі
   провайдера або в `agents.defaults.models["provider/model"].agentRuntime` /
   `agents.list[].models["provider/model"].agentRuntime`. Маска провайдера,
   як-от `agents.defaults.models["vllm/*"].agentRuntime`, застосовується після точної
   політики моделі, тож динамічно виявлені моделі провайдера можуть спільно використовувати одне
   середовище виконання, не перевизначаючи точних винятків для окремих моделей.
2. Далі йде політика середовища виконання в області провайдера в
   `models.providers.<provider>.agentRuntime`.
3. У режимі `auto` зареєстровані Plugin runtimes можуть заявляти підтримувані пари провайдер/модель.
4. Якщо жодне середовище виконання не заявляє хід у режимі `auto`, OpenClaw використовує `openclaw` як
   сумісне середовище виконання. Використовуйте явний ідентифікатор середовища виконання, коли запуск має бути
   строгим.

Прив’язки середовища виконання всієї сесії та всього агента ігноруються. Це включає
`OPENCLAW_AGENT_RUNTIME`, стан сесії `agentHarnessId`/`agentRuntimeOverride`,
`agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. Запустіть
`openclaw doctor --fix`, щоб видалити застарілу конфігурацію середовища виконання всього агента й перетворити
застарілі посилання на моделі середовища виконання там, де OpenClaw може зберегти намір.

Явні Plugin runtimes провайдера/моделі закриваються з помилкою. Наприклад,
`agentRuntime.id: "codex"` на провайдері або моделі означає Codex або чітку
помилку вибору/середовища виконання; це ніколи не маршрутизується тихо назад до OpenClaw.

Аліаси CLI-бекендів відрізняються від ідентифікаторів вбудованих harness. Бажана
форма Claude CLI така:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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/*`, щоб
вони запускалися через app-server harness Codex замість збереження бекенда Codex CLI.

Режим `auto` навмисно консервативний для більшості провайдерів. Моделі агентів OpenAI
є винятком: невстановлене середовище виконання й `auto` обидва визначаються як Codex
harness. Явна конфігурація середовища виконання OpenClaw залишається сумісним маршрутом за вибором для
ходів агента `openai/*`; у парі з вибраним OAuth-профілем `openai`
OpenClaw маршрутизує цей шлях внутрішньо через транспорт автентифікації Codex, зберігаючи
публічне посилання на модель як `openai/*`. Застарілі прив’язки сесії середовища виконання OpenAI
ігноруються вибором середовища виконання й можуть бути очищені за допомогою `openclaw doctor --fix`.

Якщо `openclaw doctor` попереджає, що плагін `codex` увімкнено, тоді як
застарілі посилання на моделі Codex лишаються в конфігурації, вважайте це застарілим станом маршруту. Запустіть
`openclaw doctor --fix`, щоб переписати його на `openai/*` із середовищем виконання Codex.

## Середовище виконання агента GitHub Copilot

Зовнішній плагін `@openclaw/copilot` реєструє opt-in середовище виконання `copilot`,
підтримане GitHub Copilot CLI (`@github/copilot-sdk`). Він заявляє
канонічного провайдера підписки `github-copilot` і **ніколи** не вибирається через
`auto`. Увімкніть його для окремої моделі або провайдера через `agentRuntime.id`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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 vs Codex vs
Copilot SDK див. [Середовище виконання агента GitHub Copilot](/uk/plugins/copilot).

## Контракт сумісності

Коли середовище виконання не є OpenClaw, воно має документувати, які поверхні OpenClaw підтримує.
Використовуйте таку форму для документації середовища виконання:

| Питання                                       | Чому це важливо                                                                                                                   |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Хто володіє циклом моделі?                    | Визначає, де відбуваються повторні спроби, продовження інструментів і рішення щодо фінальної відповіді.                           |
| Хто володіє канонічною історією треду?        | Визначає, чи OpenClaw може редагувати історію, чи лише дзеркалити її.                                                             |
| Чи працюють динамічні інструменти OpenClaw?   | Обмін повідомленнями, сесії, Cron та інструменти, якими володіє OpenClaw, залежать від цього.                                     |
| Чи працюють динамічні хуки інструментів?      | Плагіни очікують `before_tool_call`, `after_tool_call` і middleware навколо інструментів, якими володіє OpenClaw.                 |
| Чи працюють нативні хуки інструментів?        | Shell, patch та інструментам, якими володіє середовище виконання, потрібна підтримка нативних хуків для політики й спостереження. |
| Чи виконується життєвий цикл рушія контексту? | Плагіни пам'яті та контексту залежать від життєвого циклу assemble, ingest, after-turn і Compaction.                              |
| Які дані Compaction відкриваються?            | Деяким плагінам потрібні лише сповіщення, тоді як іншим потрібні метадані про збережене й відкинуте.                              |
| Що навмисно не підтримується?                 | Користувачі не повинні припускати еквівалентність OpenClaw там, де нативне середовище виконання володіє більшим обсягом стану.    |

Контракт підтримки середовища виконання Codex задокументовано в
[Середовище виконання обв'язки Codex](/uk/plugins/codex-harness-runtime#v1-support-contract).

## Мітки статусу

Вивід статусу може показувати одночасно мітки `Execution` і `Runtime`. Читайте їх як
діагностику, а не як назви провайдерів.

* Посилання на модель, як-от `openai/gpt-5.5`, вказує вибраного провайдера/модель.
* Ідентифікатор середовища виконання, як-от `codex`, вказує, який цикл виконує хід.
* Мітка каналу, як-от Telegram або Discord, вказує, де відбувається розмова.

Якщо запуск досі показує неочікуване середовище виконання, спершу перевірте політику середовища виконання
вибраного провайдера/моделі. Застарілі прив'язки середовища виконання сесії більше не визначають маршрутизацію.

## Пов'язане

* [Обв'язка Codex](/uk/plugins/codex-harness)
* [Середовище виконання обв'язки Codex](/uk/plugins/codex-harness-runtime)
* [Середовище виконання агента GitHub Copilot](/uk/plugins/copilot)
* [OpenAI](/uk/providers/openai)
* [Плагіни обв'язки агента](/uk/plugins/sdk-agent-harness)
* [Цикл агента](/uk/concepts/agent-loop)
* [Моделі](/uk/concepts/models)
* [Статус](/uk/cli/status)