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

Середовище виконання агента — це компонент, який володіє одним підготовленим циклом моделі: він отримує промпт, керує виводом моделі, обробляє нативні виклики інструментів і повертає завершений хід в 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:

{
  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/<model>.
3. Якщо користувач явно вибирає PI для моделі OpenAI, збережіть посилання на модель як openai/<model> і встановіть політику середовища виконання провайдера/моделі як agentRuntime.id: "pi". Вибраний профіль автентифікації openai-codex маршрутизується всередині через застарілий транспорт Codex-auth PI.
4. Якщо застаріла конфігурація все ще містить openai-codex/* посилання на моделі, виправте її на openai/<model> за допомогою 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 і Провайдери моделей. Контракт підтримки середовища виконання Codex див. у Середовище виконання Codex harness.

​

Відповідальність середовища виконання

Різні середовища виконання відповідають за різні частини циклу.

Поверхня	Вбудований 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.<provider>.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 така:

{
  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.

​

Мітки стану

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

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

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

​

Пов’язане

• Codex harness
• Середовище виконання Codex harness
• OpenAI
• Plugins агентного harness
• Цикл агента
• Моделі
• Стан