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

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

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

Обв'язка — це реалізація, що надає середовище виконання агента (термін у коді). Наприклад, вбудована обв'язка Codex реалізує середовище виконання codex. Загальнодоступна конфігурація використовує agentRuntime.id у записах провайдера або моделі; ключі середовища виконання для всього агента є застарілими та ігноруються. openclaw doctor --fix видаляє старі закріплення середовища виконання для всього агента та переписує застарілі посилання на моделі середовища виконання на канонічні посилання провайдер/модель разом із політикою середовища виконання на рівні моделі, де це потрібно.

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

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

Обв'язка copilot — це окрема, зовнішня обв'язка Plugin із явним увімкненням для GitHub Copilot CLI; див. середовище виконання агента GitHub Copilot, щоб дізнатися про користувацький вибір між PI, Codex і середовищем виконання агента GitHub Copilot.

Поверхні Codex

Назву Codex використовують кілька поверхонь:

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

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

{  agents: {    defaults: {      model: "openai/gpt-5.6-sol",    },  },}

Це означає, що OpenClaw вибирає посилання на модель OpenAI, а потім просить середовище виконання Codex app-server виконати вбудований хід агента. Це не означає «використовувати тарифікацію API» і не означає, що канал, каталог моделей провайдера або сховище сеансів OpenClaw стає частиною Codex.

Коли вбудований Plugin codex увімкнено, використовуйте нативну поверхню команд /codex (/codex bind, /codex threads, /codex resume, /codex steer, /codex stop) для керування Codex природною мовою замість ACP. Використовуйте ACP для Codex лише тоді, коли користувач явно запитує ACP/acpx або тестує шлях адаптера ACP. Claude Code, Gemini CLI, OpenCode, Cursor та подібні зовнішні обв'язки й надалі використовують ACP.

Дерево рішень:

1. Прив'язування/керування/потоки/відновлення/спрямування/зупинення Codex -> нативна поверхня команд /codex, коли вбудований Plugin codex увімкнено.
2. Codex як вбудоване середовище виконання або звичайна робота агента Codex із підтримкою передплати -> openai/<model>.
3. OpenClaw явно вибрано для моделі OpenAI -> збережіть посилання на модель як openai/<model> і встановіть політику середовища виконання провайдера/моделі на agentRuntime.id: "openclaw". Вибраний профіль OAuth openai внутрішньо маршрутизується через транспорт автентифікації Codex у OpenClaw.
4. Застарілі посилання на моделі Codex у конфігурації -> виправте за допомогою openclaw doctor --fix на openai/<model>; doctor зберігає маршрут автентифікації Codex, додаючи agentRuntime.id: "codex" на рівні провайдера/моделі там, де це передбачало старе посилання на модель. Застарілі посилання на моделі codex-cli/* виправляються на той самий маршрут Codex app-server openai/<model>; OpenClaw більше не містить вбудованого бекенду Codex CLI.
5. Явно запитано ACP, acpx або адаптер Codex ACP -> runtime: "acp" і agentId: "codex".
6. Claude Code, Gemini CLI, OpenCode, Cursor, Droid або інша зовнішня обв'язка -> ACP/acpx, а не нативне середовище виконання підагентів.

Про поділ префіксів родини OpenAI див. OpenAI і Провайдери моделей. Контракт підтримки середовища виконання Codex див. у розділі Середовище виконання обв'язки Codex.

Володіння середовищем виконання

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

Правило проєктування: якщо поверхнею володіє OpenClaw, він може забезпечувати звичайну поведінку хуків Plugin. Якщо поверхнею володіє нативне середовище виконання, 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 можуть заявляти підтримувані пари провайдер/модель.
4. Якщо жодне середовище не приймає хід у режимі auto, OpenClaw використовує openclaw як середовище виконання для сумісності. Використовуйте явний ідентифікатор середовища виконання, коли виконання має бути суворо визначеним.

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

Явно задані середовища виконання Plugin для провайдера/моделі завершуються помилкою без резервного переходу: agentRuntime.id: "codex" для провайдера або моделі означає Codex або чітку помилку вибору/середовища виконання — воно ніколи непомітно не перенаправляється назад до OpenClaw. Лише auto може спрямувати невідповідний хід до OpenClaw.

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

{  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/*, щоб вони виконувалися через обв'язку Codex app-server, а не зберігали бекенд Codex CLI.

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

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

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

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

{  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 і ширший вибір між SDK PI, Codex та Copilot див. у розділі Середовище виконання агента GitHub Copilot.

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

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

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

Мітки стану

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

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

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

Пов’язані матеріали

• Обв’язка Codex
• Середовище виконання обв’язки Codex
• Середовище виконання агента GitHub Copilot
• OpenAI
• Plugins обв’язки агента
• Цикл агента
• Моделі
• Стан