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

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

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

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

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

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

• Вбудовані 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	Що вона робить
Нативне середовище виконання app-server Codex	посилання моделей openai/*	Запускає вбудовані агентські ходи OpenAI через app-server Codex. Це звичайне налаштування підписки ChatGPT/Codex.
Профілі автентифікації Codex OAuth	постачальник автентифікації openai-codex	Зберігає автентифікацію підписки 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-ключем	Використовується для прямих 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, а потім просить 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, використовуйте нативну командну поверхню /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.
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	профілі автентифікації openai-codex
Claude Code або інший зовнішній harness	ACP/acpx

Про розділення префіксів родини OpenAI див. OpenAI і Постачальники моделей. Про контракт підтримки середовища виконання Codex див. Codex harness.

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

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

Поверхня	Вбудований PI OpenClaw	app-server Codex
Власник циклу моделі	OpenClaw через вбудований runner PI	app-server Codex
Канонічний стан потоку	Транскрипт OpenClaw	Потік Codex плюс дзеркало транскрипту OpenClaw
Динамічні інструменти OpenClaw	Нативний цикл інструментів OpenClaw	Мостяться через адаптер Codex
Нативні інструменти shell і файлів	Шлях PI/OpenClaw	Нативні інструменти Codex, мостяться через нативні hooks там, де підтримується
Рушій контексту	Нативне складання контексту OpenClaw	OpenClaw проєктує зібраний контекст у хід Codex
Compaction	OpenClaw або вибраний рушій контексту	Нативна compaction Codex, зі сповіщеннями OpenClaw і підтримкою дзеркала
Доставка каналом	OpenClaw	OpenClaw

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

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

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

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

1. Записане середовище виконання сесії має перевагу. Зміни конфігурації не перемикають гарячим способом наявний транскрипт на іншу нативну систему потоків.
2. OPENCLAW_AGENT_RUNTIME=<id> примусово задає це середовище виконання для нових або скинутих сесій.
3. agents.defaults.agentRuntime.id або agents.list[].agentRuntime.id можуть встановити auto, pi, ідентифікатор зареєстрованого вбудованого harness, як-от codex, або підтримуваний псевдонім CLI-бекенда, як-от claude-cli.
4. У режимі auto зареєстровані plugin runtimes можуть заявляти підтримувані пари постачальник/модель.
5. Якщо жодне середовище виконання не заявляє хід у режимі auto, OpenClaw використовує PI як середовище виконання сумісності. Використовуйте явний ідентифікатор середовища виконання, коли запуск має бути строгим.

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

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

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

Застарілі посилання, як-от claude-cli/claude-opus-4-7, залишаються підтримуваними для сумісності, але нова конфігурація має зберігати постачальника/модель канонічними та поміщати бекенд виконання в agentRuntime.id.

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

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

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

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

Питання	Чому це важливо
Хто володіє циклом моделі?	Визначає, де відбуваються повторні спроби, продовження інструментів і рішення щодо фінальної відповіді.
Хто володіє канонічною історією потоку?	Визначає, чи може OpenClaw редагувати історію, чи лише дзеркалити її.
Чи працюють динамічні інструменти OpenClaw?	Обмін повідомленнями, сесії, cron і інструменти, якими володіє OpenClaw, залежать від цього.
Чи працюють dynamic tool hooks?	Plugins очікують before_tool_call, after_tool_call і middleware навколо інструментів, якими володіє OpenClaw.
Чи працюють native tool hooks?	Shell, patch і інструменти, якими володіє середовище виконання, потребують підтримки native hook для політик і спостереження.
Чи запускається життєвий цикл рушія контексту?	Plugins пам’яті та контексту залежать від assemble, ingest, after-turn і життєвого циклу compaction.
Які дані compaction відкрито?	Деяким plugins потрібні лише сповіщення, а іншим потрібні метадані збереженого/відкинутого.
Що навмисно не підтримується?	Користувачі не мають припускати еквівалентність PI там, де нативне середовище виконання володіє більшим станом.

Контракт підтримки середовища виконання Codex задокументовано в обв’язці Codex.

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

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

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

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

# Пов’язане

• обв’язка Codex
• OpenAI
• Plugin-и обв’язки агентів
• Цикл агента
• Моделі
• Статус