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

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

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

Когда использовать обвязку

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

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

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

Что по-прежнему контролирует ядро

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

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

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

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

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

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

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

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

Проверенные продолжения Crestodian также передают 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(...) для промежуточного ПО, предназначенного только для app-server 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. Нативные конфигурации app-server должны использовать openai/gpt-*; ходы агента OpenAI выбирают средство запуска Codex только тогда, когда эффективный маршрут объявляет совместимость с Codex. Устаревшие ссылки на модели Codex следует исправлять с помощью openclaw doctor --fix, а устаревшие ссылки на модели codex/* остаются псевдонимами совместимости для нативного средства запуска.

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

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

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

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

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

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

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

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

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

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

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

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

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

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