> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugins обвязки агента

**Обвязка агента** — это низкоуровневый исполнитель для одного подготовленного
хода агента OpenClaw. Это не провайдер модели, не канал и не реестр инструментов.
Ментальную модель для пользователей см. в [средах выполнения агентов](/ru/concepts/agent-runtimes).

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

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

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

Примеры:

* нативный сервер coding-agent, который владеет тредами и Compaction
* локальный CLI или daemon, который должен стримить нативные события планирования, рассуждений и инструментов
* среда выполнения модели, которой нужен собственный resume id в дополнение к
  транскрипту сеанса OpenClaw

**Не** регистрируйте обвязку только для добавления нового API LLM. Для обычных HTTP- или
WebSocket API моделей создайте [provider plugin](/ru/plugins/sdk-provider-plugins).

## Чем по-прежнему владеет ядро

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

* провайдера и модель
* состояние runtime-аутентификации
* уровень thinking и бюджет контекста
* файл транскрипта/сеанса OpenClaw
* рабочую область, sandbox и политику инструментов
* callback-и ответа канала и callback-и стриминга
* политику fallback модели и live-переключения модели

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

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

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

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

## Регистрация обвязки

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

```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}}
import type { AgentHarness } from "openclaw/plugin-sdk/agent-harness";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

const myHarness: AgentHarness = {
  id: "my-harness",
  label: "My native agent harness",

  supports(ctx) {
    return ctx.provider === "my-provider"
      ? { supported: true, priority: 100 }
      : { supported: false };
  },

  async runAttempt(params) {
    // Start or resume your native thread.
    // Use params.prompt, params.tools, params.images, params.onPartialReply,
    // params.onAgentEvent, and the other prepared attempt fields.
    return await runMyNativeTurn(params);
  },
};

export default definePluginEntry({
  id: "my-native-agent",
  name: "My Native Agent",
  description: "Runs selected models through a native agent daemon.",
  register(api) {
    api.registerAgentHarness(myHarness);
  },
});
```

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

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

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

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

Пины среды выполнения на уровне всего сеанса и всего агента игнорируются выбором. Это
включает устаревшие значения сеанса `agentHarnessId`, `agents.defaults.agentRuntime`,
`agents.list[].agentRuntime` и `OPENCLAW_AGENT_RUNTIME`. `/status` показывает
эффективную среду выполнения, выбранную из маршрута провайдера/модели.
Если выбранная обвязка неожиданна, включите debug-логирование `agents/harness` и
проверьте структурированную запись Gateway `agent harness selected`. Она включает
id выбранной обвязки, причину выбора, политику runtime/fallback и, в режиме
`auto`, результат поддержки каждого кандидата Plugin.

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

## Сочетание провайдера и обвязки

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

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

* предпочтительные пользовательские ref-ы моделей: `openai/gpt-5.5`
* совместимые ref-ы: устаревшие ref-ы `codex/gpt-*` остаются принимаемыми, но новые
  конфиги не должны использовать их как обычные ref-ы провайдера/модели
* id обвязки: `codex`
* auth: синтетическая доступность провайдера, потому что обвязка Codex владеет
  нативным логином/сеансом Codex
* запрос app-server: OpenClaw отправляет в Codex bare model id и позволяет
  обвязке общаться с нативным протоколом app-server

Plugin Codex является добавочным. Обычные ref-ы агентов `openai/gpt-*` на официальном
провайдере OpenAI по умолчанию выбирают обвязку Codex. Более старые ref-ы `codex/gpt-*`
по-прежнему выбирают провайдера и обвязку Codex для совместимости.

Настройку оператора, примеры префиксов моделей и конфиги только для Codex см. в
[Codex Harness](/ru/plugins/codex-harness).

OpenClaw требует Codex app-server `0.125.0` или новее. Plugin Codex проверяет
handshake инициализации app-server и блокирует более старые или неверсированные серверы, чтобы
OpenClaw запускался только на поверхности протокола, с которой был протестирован. Нижняя
граница `0.125.0` включает поддержку payload нативного MCP hook, появившуюся в
Codex `0.124.0`, при этом закрепляя OpenClaw на более новой протестированной стабильной линии.

### Middleware результатов инструментов

Встроенные plugins и явно включенные установленные plugins с подходящими контрактами manifest
могут подключать runtime-neutral middleware результатов инструментов через
`api.registerAgentToolResultMiddleware(...)`, когда их manifest объявляет
целевые id сред выполнения в `contracts.agentToolResultMiddleware`. Эта доверенная
граница предназначена для async-преобразований результатов инструментов, которые должны выполняться до того, как OpenClaw или Codex
передаст вывод инструмента обратно в модель.

Устаревшие встроенные plugins по-прежнему могут использовать
`api.registerCodexAppServerExtensionFactory(...)` для middleware только Codex app-server,
но новые преобразования результатов должны использовать runtime-neutral API.
Hook `api.registerEmbeddedExtensionFactory(...)`, работавший только для embedded-runner, был удален;
встроенные преобразования результатов инструментов должны использовать runtime-neutral middleware.

### Классификация терминального исхода

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

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

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

### Пользовательский ввод и поверхности инструментов

Нативные обвязки, которые предоставляют runtime-level запрос пользовательского ввода, должны использовать
helper-ы пользовательского ввода из `openclaw/plugin-sdk/agent-harness-runtime`, чтобы форматировать
prompt, доставлять его через блокирующий путь ответа OpenClaw и нормализовать
ответы choice/free-form обратно в нативную форму ответа среды выполнения. Helper
сохраняет единообразное представление канала/TUI, пока каждая обвязка сохраняет
собственный парсинг протокола и жизненный цикл pending-request.

Нативные обвязки, которым нужна похожая на PI компактная маршрутизация инструментов, должны использовать
`createAgentHarnessToolSurfaceRuntime(...)` из
`openclaw/plugin-sdk/agent-harness-tool-runtime`. Он владеет
выбором управления tool-search/code-mode, lean defaults локальной модели,
фильтрацией схем, совместимой с runtime, выполнением скрытого catalog, directory
hydration и очисткой catalog. Обвязки по-прежнему владеют своей SDK-specific конвертацией инструментов
и native execution callback.

### Режим нативной обвязки Codex

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

Когда этот режим работает, Codex владеет нативным thread id, поведением resume,
Compaction и выполнением app-server. OpenClaw по-прежнему владеет каналом чата,
видимым зеркалом транскрипта, политикой инструментов, approvals, доставкой медиа и выбором
сеанса. Используйте provider/model `agentRuntime.id: "codex"`, когда нужно доказать,
что только путь Codex app-server может заявить запуск. Явные runtime-ы Plugin
fail closed; сбои выбора Codex app-server и сбои runtime не
повторяются через другую среду выполнения.

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

По умолчанию OpenClaw использует runtime policy провайдера/модели `auto`: зарегистрированные
обвязки Plugin могут заявить пару провайдер/модель, а встроенная среда выполнения
обрабатывает ход, когда совпадений нет. Ref-ы агентов OpenAI на официальном провайдере OpenAI по умолчанию используют Codex.
Используйте явную среду выполнения Plugin для провайдера/модели, например
`agentRuntime.id: "codex"`, когда отсутствие выбора обвязки должно приводить к сбою, а не
к маршрутизации через встроенную среду выполнения. Сбои выбранной обвязки Plugin всегда
завершаются жесткой ошибкой. Это не блокирует явный provider/model `agentRuntime.id: "openclaw"`.

Для embedded-запусков только Codex:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "models": {
    "providers": {
      "openai": {
        "agentRuntime": {
          "id": "codex"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "openai/gpt-5.5"
    }
  }
}
```

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-8",
      "models": {
        "anthropic/claude-opus-4-8": {
          "agentRuntime": {
            "id": "claude-cli"
          }
        }
      }
    }
  }
}
```

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "agents": {
    "list": [
      {
        "id": "codex-only",
        "model": "openai/gpt-5.5",
        "models": {
          "openai/gpt-5.5": {
            "agentRuntime": { "id": "codex" }
          }
        }
      }
    ]
  }
}
```

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "agents": {
    "defaults": {
      "agentRuntime": {
        "id": "codex"
      }
    }
  }
}
```

При явном runtime Plugin сеанс завершается с ошибкой на раннем этапе, если запрошенная
обвязка не зарегистрирована, не поддерживает разрешенного провайдера/модель или
завершается с ошибкой до создания побочных эффектов хода. Это сделано намеренно для развертываний только с Codex
и для live-тестов, которые должны доказать, что путь app-server Codex
действительно используется.

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

## Нативные сеансы и зеркало транскрипта

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

Транскрипт OpenClaw остается слоем совместимости для:

* истории сеанса, видимой в канале
* поиска и индексирования транскриптов
* переключения обратно на встроенную обвязку OpenClaw на последующем ходе
* общего поведения `/new`, `/reset` и удаления сеансов

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

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

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

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

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

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

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

* [Обзор SDK](/ru/plugins/sdk-overview)
* [Вспомогательные средства runtime](/ru/plugins/sdk-runtime)
* [Provider Plugins](/ru/plugins/sdk-provider-plugins)
* [Обвязка Codex](/ru/plugins/codex-harness)
* [Провайдеры моделей](/ru/concepts/model-providers)