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

Среда выполнения агента — это низкоуровневый исполнитель одного подготовленного хода агента OpenClaw. Это не провайдер модели, не канал и не реестр инструментов. Описание пользовательской модели см. в разделе Среды выполнения агентов.

Используйте эту поверхность только для встроенных или доверенных нативных плагинов. Контракт пока экспериментальный, поскольку типы параметров намеренно отражают текущую встроенную среду выполнения.

Когда использовать среду выполнения

Регистрируйте среду выполнения агента, когда семейство моделей имеет собственную нативную среду выполнения сеансов, а обычный транспорт провайдера OpenClaw является неподходящей абстракцией:

• нативный сервер агента программирования, который управляет потоками и Compaction
• локальный CLI или демон, который должен передавать в потоковом режиме нативные события планирования, рассуждений и инструментов
• среда выполнения модели, которой помимо расшифровки сеанса OpenClaw требуется собственный идентификатор возобновления

Не регистрируйте среду выполнения только ради добавления нового API LLM. Для обычных API моделей на базе HTTP или WebSocket создайте плагин провайдера.

За что по-прежнему отвечает ядро

До выбора среды выполнения OpenClaw уже определяет:

• провайдера и модель
• состояние аутентификации среды выполнения, если среда выполнения не объявляет, что сама выполняет начальную настройку аутентификации
• уровень рассуждений и бюджет контекста
• файл расшифровки/сеанса OpenClaw
• рабочую область, песочницу и политику инструментов
• обратные вызовы ответов канала и потоковой передачи
• политику резервного выбора модели и переключения модели во время выполнения

Среда выполнения исполняет подготовленную попытку; она не выбирает провайдеров, не заменяет доставку через канал и не переключает модели неявно.

Начальная настройка аутентификации, выполняемая средой выполнения

По умолчанию ядро определяет учетные данные провайдера до вызова среды выполнения. Доверенная среда выполнения, способная аутентифицироваться через собственную нативную среду, может задать authBootstrap: "harness" в своей статической регистрации AgentHarness. Тогда ядро пропускает общую начальную настройку учетных данных провайдера и ошибку отсутствия учетных данных для каждой попытки, принятой этой средой выполнения.

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

Проверенные артефакты среды выполнения для настройки

Локальная среда выполнения, способная обеспечивать инференс при первоначальной настройке, должна засвидетельствовать реализацию, завершившую проверку. Если params.captureRuntimeArtifact имеет значение true, верните непрозрачный result.runtimeArtifact со стабильным идентификатором и отпечатком содержимого. Зарегистрируйте соответствующую возможность runtimeArtifact.validate(...), которая повторно проверяет эту привязку, не загружая другую среду выполнения и не сканируя несвязанные плагины.

Проверенные продолжения OpenClaw также передают params.expectedRuntimeArtifact. Среда выполнения должна сравнить его с точным нативным процессом, который она получила, и завершиться с ошибкой до запуска или возобновления нативного потока, если они различаются. Обычные ходы агента не содержат оба поля, поэтому хеширование содержимого не попадает в обычный горячий путь запроса. Для участия удаленным средам выполнения и средам выполнения WebSocket требуется контракт аттестации сервера; одной строки версии недостаточно для идентификации артефакта.

Подготовленная попытка также содержит params.runtimePlan — принадлежащий OpenClaw набор политик для решений среды выполнения, которые должны оставаться общими для OpenClaw и нативных сред выполнения:

• runtimePlan.tools.normalize(...) и runtimePlan.tools.logDiagnostics(...) для политики схемы инструментов с учетом провайдера
• runtimePlan.transcript.resolvePolicy(...) для очистки расшифровки и политики исправления вызовов инструментов
• runtimePlan.delivery.isSilentPayload(...) для общего NO_REPLY и подавления доставки медиафайлов
• runtimePlan.outcome.classifyRunResult(...) для классификации резервного выбора модели
• runtimePlan.observability для определенных метаданных провайдера, модели и среды выполнения

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

Контракт транспорта запросов

supports(ctx) получает определенный транспорт модели в ctx.modelProvider. Выбранный маршрут описывается двумя принадлежащими провайдеру фактами, не содержащими секретов:

• runtimePolicy.compatibleIds перечисляет идентификаторы сред выполнения, которые провайдер объявляет совместимыми с этим конкретным маршрутом. Отсутствие политики означает, что провайдер не объявил совместимость на уровне маршрута; это не разрешает предполагать поддержку.
• requestTransportOverrides: "none" означает, что не требуется воспроизводить переопределение запроса, заданное для провайдера или модели. "present" означает наличие заданных заголовков, транспорта аутентификации, прокси, TLS, поведения локальной службы или частной сети либо параметров запроса. Этот факт не раскрывает их значения.

Верните { supported: false, reason }, если среда выполнения не может воспроизвести подготовленный транспорт. Не определяйте поддержку путем чтения необработанной конфигурации после выбора. Если подготовка аутентификации создает несколько маршрутов повторной попытки, одна среда выполнения должна поддерживать их все до диспетчеризации. При неявном выборе используется OpenClaw, если ни один плагин не может обслужить весь набор; явный или сохраненный выбор плагина приводит к отказу по принципу запрета по умолчанию.

Регистрация среды выполнения

Импорт: openclaw/plugin-sdk/agent-harness

  const myHarness: AgentHarness = {  id: "my-harness",  label: "Моя нативная среда выполнения агента",   supports(ctx) {    const routeSupportsHarness =      ctx.modelProvider?.runtimePolicy?.compatibleIds.includes("my-harness") === true;    const canReproduceRequest = ctx.modelProvider?.requestTransportOverrides !== "present";    return ctx.provider === "my-provider" && routeSupportsHarness && canReproduceRequest      ? { supported: true, priority: 100 }      : { supported: false, reason: "эффективный маршрут несовместим со средой выполнения" };  },   async runAttempt(params) {    // Запустите или возобновите нативный поток.    // Используйте params.prompt, params.tools, params.images, params.onPartialReply,    // params.onAgentEvent и другие поля подготовленной попытки.    return await runMyNativeTurn(params);  },}; export default definePluginEntry({  id: "my-native-agent",  name: "Мой нативный агент",  description: "Запускает выбранные модели через нативный демон агента.",  register(api) {    api.registerAgentHarness(myHarness);  },});

authBootstrap намеренно отсутствует в этом общем примере. Добавляйте authBootstrap: "harness", только если среда выполнения соответствует приведенному выше контракту.

Делегированное выполнение

Владелец среды выполнения может задать в delegatedExecutionPluginIds идентификаторы доверенных плагинов, которым требуется выполнять существующий сеанс с зафиксированной моделью, например голосовой транспорт, продолжающий разговор на базе Codex. Это статическое согласие владельца, а не список разрешений ядра. Ограничивайте его необходимым минимумом.

Делегаты получают только допуск к работе и встроенное выполнение. OpenClaw требует точный сохраненный ключ сеанса, путь к хранилищу и идентификатор сеанса; modelSelectionLocked: true; а также совпадающие значения agentHarnessId и agentHarnessRuntimeOverride. После этого выполнение ограничивается областью владельца среды выполнения. Создание, изменение, сброс, удаление и архивирование сеансов, а также изменение Gateway остаются доступными только владельцу.

Политика выбора

OpenClaw выбирает среду выполнения после определения провайдера и модели:

1. Приоритет имеет политика среды выполнения на уровне модели.
2. Затем применяется политика среды выполнения на уровне провайдера.
3. auto запрашивает у зарегистрированных сред выполнения, поддерживают ли они определенный эффективный маршрут. Одни лишь префиксы провайдера или модели никогда не выбирают среду выполнения.
4. Если ни одна зарегистрированная среда выполнения не подходит, OpenClaw использует встроенную среду выполнения.

Сбои сред выполнения плагинов отображаются как сбои выполнения. В режиме auto резервный переход на встроенную среду применяется, только если ни одна зарегистрированная среда выполнения плагина не поддерживает определенные провайдер и модель. После того как среда выполнения плагина приняла выполнение, OpenClaw не повторяет тот же ход через другую среду, поскольку это может изменить семантику аутентификации или среды выполнения либо продублировать побочные эффекты.

Настроенная политика среды выполнения остается авторитетным источником сведений о требуемой среде. Сохраненный сеанс agentHarnessId сохраняет владение своей нативной расшифровкой, пока подготовка маршрута и аутентификации еще не завершена. Ни одно из этих условий не делает несовместимый маршрут совместимым: после появления подготовленных фактов выбранная или закрепленная среда выполнения должна их поддерживать, иначе выполнение завершается отказом по принципу запрета по умолчанию. /status показывает эффективную среду выполнения, выбранную на основе политики, сохраненного владения и поддержки маршрута. Подготовленный статус задается явно: отсутствующий runtimePolicy остается необъявленным, а не выводится из случайно присутствующих полей транспорта. Если при аутентификации, принадлежащей среде выполнения, остаются неопределенными несколько физических маршрутов, подготовленный факт поддержки представляет собой пересечение идентификаторов совместимых сред выполнения и сообщает о переопределениях запросов, если они есть хотя бы у одного кандидата. Поэтому один кандидат с необъявленной поддержкой делает набор нативной совместимости пустым; preparedAuth.source: "harness" является владельцем аутентификации, а не разрешением выводить поддержку маршрута.

Если выбор среды выполнения кажется неожиданным, включите отладочное журналирование agents/harness и проверьте структурированную запись Gateway agent harness selected: она содержит идентификатор выбранной среды выполнения, причину выбора, политику среды выполнения и резервного перехода, а в режиме auto — результат проверки поддержки каждого кандидата-плагина.

Встроенный плагин Codex регистрирует codex как идентификатор своей среды выполнения. Ядро считает его обычным идентификатором среды выполнения плагина; псевдонимы, относящиеся к Codex, должны находиться в плагине или конфигурации оператора, а не в общем селекторе среды выполнения.

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

Большинству сред выполнения также следует регистрировать провайдера. Провайдер делает ссылки на модели, состояние аутентификации, метаданные модели и выбор /model видимыми остальным компонентам OpenClaw. Затем среда выполнения принимает этого провайдера в supports(...).

Встроенный плагин Codex следует этому шаблону:

• предпочтительные пользовательские ссылки на модели: openai/gpt-5.6-sol
• ссылки совместимости: устаревшие ссылки codex/gpt-* по-прежнему принимаются, но в новых конфигурациях их не следует использовать как обычные ссылки на провайдера или модель
• идентификатор среды выполнения: codex
• аутентификация: синтетическая доступность провайдера, поскольку среда выполнения Codex управляет нативным входом и сеансом Codex
• запрос к серверу приложения: OpenClaw отправляет Codex простой идентификатор модели и позволяет среде выполнения взаимодействовать с нативным протоколом сервера приложения

Плагин Codex является дополнением. Если политика среды выполнения не задана или имеет значение auto, OpenAI может выбрать Codex, только когда принадлежащий провайдеру контракт маршрута объявляет совместимым codex: точный официальный маршрут HTTPS для Platform Responses или ChatGPT Responses без заданного переопределения запроса. Один лишь префикс openai/* никогда не выбирает Codex. Пользовательские конечные точки, адаптеры Completions и заданное поведение запросов остаются в OpenClaw. Официальные конечные точки с незашифрованным HTTP отклоняются. Более старые ссылки codex/gpt-* по-прежнему принимаются как входные данные совместимости. См. Неявная среда выполнения агента OpenAI.

Инструкции по настройке оператором, примеры префиксов моделей и конфигурации только для Codex см. в разделе Среда выполнения Codex.

Плагин Codex обеспечивает соблюдение минимальной версии сервера приложения, указанной в разделе Среда выполнения Codex. Он проверяет начальное рукопожатие и блокирует старые серверы или серверы без версии, поэтому OpenClaw работает только с той поверхностью протокола, которую он протестировал.

Промежуточное ПО для результатов инструментов

Встроенные плагины и явно включенные установленные плагины с соответствующими контрактами манифеста могут подключать нейтральное к среде выполнения промежуточное ПО для результатов инструментов через api.registerAgentToolResultMiddleware(...), если их манифест объявляет целевые идентификаторы сред выполнения в contracts.agentToolResultMiddleware. Эта доверенная точка расширения предназначена для асинхронных преобразований результатов инструментов, которые должны выполняться до того, как OpenClaw или Codex передаст вывод инструмента обратно модели.

Устаревшие встроенные плагины по-прежнему могут использовать api.registerCodexAppServerExtensionFactory(...) для промежуточного ПО, предназначенного только для сервера приложений Codex, но новые преобразования результатов должны использовать API, не зависящий от среды выполнения. Хук api.registerEmbeddedExtensionFactory(...), предназначенный только для встроенного исполнителя, удалён; преобразования результатов инструментов во встроенной среде должны использовать промежуточное ПО, не зависящее от среды выполнения.

Классификация результата завершения

Нативные среды выполнения, самостоятельно управляющие проекцией протокола, могут использовать classifyAgentHarnessTerminalOutcome(...) из openclaw/plugin-sdk/agent-harness-runtime, если завершённый ход не создал видимого текста ассистента. Вспомогательная функция возвращает empty, reasoning-only или planning-only, чтобы политика резервного поведения OpenClaw могла решить, следует ли повторить попытку с другой моделью. Для planning-only требуется явное поле planText среды выполнения; OpenClaw не выводит его значение из текста ассистента. Вспомогательная функция намеренно не классифицирует ошибки промпта, выполняющиеся ходы и намеренные ответы без вывода, такие как NO_REPLY.

Побочные эффекты завершения работы агента

Нативные среды выполнения должны вызывать runAgentEndSideEffects(...) из openclaw/plugin-sdk/agent-harness-runtime после окончательного завершения попытки. Эта функция запускает переносимый хук agent_end и сбор исследовательских данных OpenClaw, не задерживая интерактивные ответы. Используйте awaitAgentEndSideEffects(...) для локальных неинтерактивных запусков, в которых попытка не должна завершаться до окончания этих побочных эффектов. Обе вспомогательные функции принимают ту же полезную нагрузку { event, ctx }, что и runAgentHarnessAgentEndHook(...); их сбои не изменяют результат завершённой попытки.

Пользовательский ввод и интерфейсы инструментов

Нативные среды выполнения, предоставляющие запрос пользовательского ввода на уровне среды выполнения, должны использовать вспомогательные функции пользовательского ввода из openclaw/plugin-sdk/agent-harness-runtime, чтобы форматировать запрос, доставлять его через блокирующий путь ответов OpenClaw и нормализовать ответы с выбором или в свободной форме обратно в нативную структуру ответа среды выполнения. Эта вспомогательная функция обеспечивает единообразное представление в каналах и TUI, тогда как каждая среда выполнения сохраняет собственные механизмы разбора протокола и управления жизненным циклом ожидающего запроса.

Нативные среды выполнения, которым нужна компактная маршрутизация инструментов в стиле PI, должны использовать createAgentHarnessToolSurfaceRuntime(...) из openclaw/plugin-sdk/agent-harness-tool-runtime. Эта функция управляет выбором элементов управления поиском инструментов и режимом кода, упрощёнными настройками по умолчанию для локальных моделей, фильтрацией схем, совместимой со средой выполнения, скрытым выполнением каталога, заполнением каталогов и очисткой каталога. Среды выполнения по-прежнему отвечают за преобразование инструментов, специфичное для их SDK, и нативный обратный вызов выполнения.

Режим нативной среды выполнения Codex

Встроенная среда выполнения codex — это нативный режим Codex для встроенных ходов агента OpenClaw. Сначала включите встроенный плагин codex, а если в конфигурации используется ограничивающий список разрешённых элементов, добавьте codex в plugins.allow. В конфигурациях нативного сервера приложений следует использовать openai/gpt-*; ходы агента OpenAI выбирают среду выполнения Codex, только если действующий маршрут объявляет совместимость с Codex. Устаревшие ссылки на модели Codex следует исправить с помощью openclaw doctor --fix, а устаревшие ссылки на модели codex/* остаются псевдонимами совместимости для нативной среды выполнения.

При работе в этом режиме Codex управляет нативным идентификатором потока, возобновлением, Compaction и выполнением сервера приложений. OpenClaw по-прежнему управляет каналом чата, видимым зеркалом расшифровки, политикой инструментов, подтверждениями, доставкой медиафайлов и выбором сеанса. Используйте поставщика/модель agentRuntime.id: "codex", когда необходимо доказать, что выполнение может быть закреплено исключительно за путём сервера приложений Codex. Явно заданные среды выполнения плагинов при сбоях завершают работу без резервного перехода; сбои выбора сервера приложений Codex и среды выполнения не приводят к повторной попытке через другую среду выполнения.

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

По умолчанию OpenClaw использует политику среды выполнения поставщика/модели auto: зарегистрированные среды выполнения плагинов могут обрабатывать совместимые действующие маршруты, а встроенная среда выполнения обрабатывает ход, если соответствий нет. Один лишь префикс поставщика/модели никогда не выбирает среду выполнения. Используйте явно заданную среду выполнения плагина поставщика/модели, например agentRuntime.id: "codex", если отсутствие выбранной среды выполнения должно приводить к сбою, а не к маршрутизации через встроенную среду выполнения. Явный выбор не делает несовместимый маршрут совместимым. Сбои выбранных сред выполнения плагинов всегда приводят к безусловному сбою. Это не блокирует явно заданный agentRuntime.id: "openclaw" поставщика/модели.

Для встроенных запусков только с Codex:

{  "models": {    "providers": {      "openai": {        "agentRuntime": {          "id": "codex"        }      }    }  },  "agents": {    "defaults": {      "model": "openai/gpt-5.6-sol"    }  }}

Если требуется серверная часть CLI для одной канонической модели, укажите среду выполнения в записи этой модели:

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

Переопределения для отдельных агентов используют ту же структуру на уровне модели:

{  "agents": {    "list": [      {        "id": "codex-only",        "model": "openai/gpt-5.6-sol",        "models": {          "openai/gpt-5.6-sol": {            "agentRuntime": { "id": "codex" }          }        }      }    ]  }}

Устаревшие примеры среды выполнения на уровне всего агента, подобные этому, игнорируются:

{  "agents": {    "defaults": {      "agentRuntime": {        "id": "codex"      }    }  }}

При явно заданной среде выполнения плагина сеанс завершается с ошибкой на раннем этапе, если запрошенная среда выполнения не зарегистрирована, не поддерживает разрешённую пару поставщик/модель или завершается сбоем до возникновения побочных эффектов хода. Это сделано намеренно для развёртываний только с Codex и для динамических тестов, которые должны подтвердить, что путь сервера приложений Codex действительно используется.

Этот параметр управляет только встроенной средой выполнения агента. Он не отключает маршрутизацию изображений, видео, музыки, TTS, PDF или других моделей, специфичных для поставщиков.

Нативные сеансы и зеркало расшифровки

Среда выполнения может хранить нативный идентификатор сеанса, идентификатор потока или токен возобновления на стороне фонового процесса. Явно сохраняйте связь этих данных с сеансом OpenClaw и продолжайте зеркалировать видимый пользователю вывод ассистента и инструментов в расшифровку OpenClaw.

Расшифровка OpenClaw остаётся слоем совместимости для:

• видимой в канале истории сеанса
• поиска и индексирования расшифровок
• возврата к встроенной среде выполнения OpenClaw в последующем ходе
• стандартного поведения /new, /reset и удаления сеанса

Если среда выполнения хранит привязку во вспомогательном файле, реализуйте reset(...), чтобы OpenClaw мог удалить её при сбросе соответствующего сеанса OpenClaw.

Результаты инструментов и медиафайлов

Ядро формирует список инструментов OpenClaw и передаёт его в подготовленную попытку. Когда среда выполнения выполняет динамический вызов инструмента, возвращайте результат инструмента через структуру результата среды выполнения, а не отправляйте медиафайлы в канал самостоятельно.

Так текст, изображения, видео, музыка, TTS, подтверждения и результаты инструментов обмена сообщениями проходят по тому же пути доставки, что и запуски на базе OpenClaw.

Итоговые результаты инструментов

AgentHarnessAttemptParams.observeToolTerminal — это управляемый хостом накопитель итоговых результатов. Среда выполнения, выполняющая динамические инструменты OpenClaw или нативные инструменты, должна вызывать его, когда каждый инструмент достигает одного итогового результата, до окончательного формирования результата попытки. Средам выполнения, которые не выполняют инструменты, вызывать его не требуется.

Передавайте факты с границы выполнения:

• Передавайте идентификатор вызова протокола, если он существует, каноническое имя инструмента и аргументы, которые фактически поступили в инструмент после подготовки или перезаписи хуками.
• Устанавливайте executionStarted: false, если проверка, подтверждение или другой защитный механизм остановил вызов до начала работы реализации инструмента. Если диспетчеризация уже могла произойти, из соображений осторожности указывайте true.
• Указывайте outcome: "success" или outcome: "failure". Включайте доступные из среды выполнения структурированные поля сбоя вместо определения сбоя по отображаемому тексту.
• Используйте nativeMutation только для нативных инструментов, которые не используют определение инструмента OpenClaw. Указывайте в нём данные об изменениях и повторном воспроизведении, относящиеся к протоколу; не копируйте классификатор изменений OpenClaw в среду выполнения.

Обратный вызов возвращает каноническое решение для этого вызова. Передавайте его lastToolError в AgentHarnessAttemptResult и используйте содержащиеся в нём сведения о выполнении, аргументах и побочных эффектах в проекции среды выполнения вместо формирования параллельного состояния. Хост сохраняет неразрешённый сбой с изменением состояния при выполнении других, не связанных с ним успешных инструментов и сбрасывает его только после успешного выполнения соответствующего действия.

Обратный вызов остаётся необязательным для совместимости исходного кода со старыми экспериментальными средами выполнения. Необязательность не означает, что среда выполнения, выполняющая инструменты, может его игнорировать: без отчётов об итоговых результатах OpenClaw не может сохранить достоверные сведения о сбое инструмента, изменяющего состояние, при последующих вызовах инструментов, включая тихое завершение Heartbeat.

Текущие ограничения

• Публичный путь импорта является универсальным, но некоторые псевдонимы типов попыток и результатов всё ещё используют устаревшие имена для обеспечения совместимости.
• Установка сторонних сред выполнения является экспериментальной. Отдавайте предпочтение плагинам поставщиков, пока не потребуется среда выполнения с нативными сеансами.
• Переключение сред выполнения поддерживается между ходами. Не переключайте среды выполнения посреди хода после начала работы нативных инструментов, подтверждений, вывода текста ассистента или отправки сообщений.

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

• Обзор SDK
• Вспомогательные функции среды выполнения
• Плагины поставщиков
• Среда выполнения Codex
• Поставщики моделей