Среды выполнения агентов

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

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

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

Есть два семейства сред выполнения:

• Встроенные harness работают внутри подготовленного агентного цикла OpenClaw. Сейчас это встроенная среда выполнения openclaw плюс зарегистрированные plugin harness, такие как 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 для пользовательского выбора между PI, Codex и средой выполнения агента GitHub Copilot.

Поверхности Codex

Большая часть путаницы возникает из-за нескольких разных поверхностей с именем Codex:

Эти поверхности намеренно независимы. Включение plugin codex делает нативные функции app-server доступными; openclaw doctor --fix отвечает за исправление устаревших устаревших маршрутов Codex и очистку устаревших привязок сессий. Выбор openai/* для агентной модели теперь означает «запустить это через Codex», если не используется неагентная поверхность OpenAI API.

Обычная настройка подписки ChatGPT/Codex использует OAuth Codex для аутентификации, но сохраняет ссылку на модель как 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 и похожие внешние harness по-прежнему используют 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, исправьте ее на openai/<model> с помощью openclaw doctor --fix; doctor сохраняет маршрут аутентификации Codex, добавляя agentRuntime.id: "codex" на уровне поставщика/модели там, где старая ссылка на модель это подразумевала. Устаревшие ссылки на модели codex-cli/* исправляются в тот же маршрут app-server Codex openai/<model>; OpenClaw больше не сохраняет встроенный CLI-бэкенд Codex.
5. Если пользователь явно говорит ACP, acpx или адаптер Codex ACP, используйте ACP с runtime: "acp" и agentId: "codex".
6. Если запрос относится к Claude Code, Gemini CLI, OpenCode, Cursor, Droid или другому внешнему harness, используйте ACP/acpx, а не нативную среду выполнения sub-agent.

О разделении префиксов семейства OpenAI см. OpenAI и поставщики моделей. Контракт поддержки среды выполнения Codex см. в разделе Среда выполнения обвязки Codex.

Владение средой выполнения

Разные среды выполнения владеют разными частями цикла.

Это разделение владения является главным правилом проектирования:

• Если OpenClaw владеет поверхностью, OpenClaw может предоставлять обычное поведение хуков плагинов.
• Если нативная среда выполнения владеет поверхностью, 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 зарегистрированные среды выполнения плагинов могут заявлять поддерживаемые пары поставщик/модель.
4. Если в режиме auto ни одна среда выполнения не заявляет ход, OpenClaw использует openclaw как среду выполнения совместимости. Используйте явный идентификатор среды выполнения, когда запуск должен быть строгим.

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

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

Псевдонимы backend 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, остаются поддерживаемыми для совместимости, но новая конфигурация должна сохранять канонические поставщика/модель и помещать backend выполнения в политику среды выполнения поставщика/модели.

Устаревшие ссылки codex-cli/* отличаются: doctor мигрирует их в openai/*, чтобы они выполнялись через обвязку сервера приложения Codex, а не сохраняли backend 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.5, указывает выбранного провайдера/модель.
• Идентификатор среды выполнения, например codex, указывает, какой цикл выполняет ход.
• Метка канала, например Telegram или Discord, указывает, где происходит разговор.

Если запуск по-прежнему показывает неожиданную среду выполнения, сначала проверьте политику среды выполнения выбранного провайдера/модели. Устаревшие привязки среды выполнения сеанса больше не определяют маршрутизацию.

Связанные материалы

• Среда Codex
• Среда выполнения среды Codex
• Среда выполнения агента GitHub Copilot
• OpenAI
• Plugin сред агента
• Цикл агента
• Модели
• Статус