Перейти до основного вмісту

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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 ACPruntime: "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 або інший зовнішній harnessACP/acpx
Про розділення префіксів родини OpenAI див. OpenAI і Постачальники моделей. Про контракт підтримки середовища виконання Codex див. Codex harness.

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

Різні середовища виконання володіють різними частинами циклу.
ПоверхняВбудований PI OpenClawapp-server Codex
Власник циклу моделіOpenClaw через вбудований runner PIapp-server Codex
Канонічний стан потокуТранскрипт OpenClawПотік Codex плюс дзеркало транскрипту OpenClaw
Динамічні інструменти OpenClawНативний цикл інструментів OpenClawМостяться через адаптер Codex
Нативні інструменти shell і файлівШлях PI/OpenClawНативні інструменти Codex, мостяться через нативні hooks там, де підтримується
Рушій контекстуНативне складання контексту OpenClawOpenClaw проєктує зібраний контекст у хід Codex
CompactionOpenClaw або вибраний рушій контекстуНативна compaction Codex, зі сповіщеннями OpenClaw і підтримкою дзеркала
Доставка каналомOpenClawOpenClaw
Цей розподіл власності є головним правилом дизайну:
  • Якщо 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. Наявні сесії зберігають своє записане середовище виконання, щоб транскрипт не відтворювався через дві несумісні власні системи сесій.

​
Пов’язане