> ## 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.

# Плагіни середовища агентів

**Обв’язка агента** — це низькорівневий виконавець для одного підготовленого
ходу агента OpenClaw. Це не провайдер моделі, не канал і не реєстр інструментів.
Для користувацької ментальної моделі див. [Середовища виконання агентів](/uk/concepts/agent-runtimes).

Використовуйте цю поверхню лише для вбудованих або довірених нативних plugins. Контракт
досі експериментальний, тому що типи параметрів навмисно віддзеркалюють поточний
вбудований runner.

## Коли використовувати обв’язку

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

Приклади:

* нативний сервер coding-agent, який володіє потоками та Compaction
* локальний CLI або демон, який має транслювати нативні події плану/міркування/інструментів
* середовище виконання моделі, якому потрібен власний resume id на додачу до
  стенограми сеансу OpenClaw

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

## Чим досі володіє core

Перш ніж вибрати обв’язку, OpenClaw уже визначив:

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

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

Підготовлена спроба також містить `params.runtimePlan`, пакет політик, яким
володіє OpenClaw, для рішень середовища виконання, що мають залишатися спільними
для 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 не
відтворює той самий хід через інше середовище виконання, тому що це може змінити
семантику автентифікації/середовища виконання або дублювати побічні ефекти.

Закріплення середовища виконання для всього сеансу й усього агента ігноруються під час вибору. Це
включає застарілі значення сеансу `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 обв’язки. Core трактує це
як звичайний id обв’язки Plugin; специфічні для Codex псевдоніми мають бути в plugin
або операторській конфігурації, а не у спільному селекторі середовища виконання.

## Поєднання провайдера й обв’язки

Більшість обв’язок також мають реєструвати провайдера. Провайдер робить model refs,
стан автентифікації, метадані моделі та вибір `/model` видимими для решти
OpenClaw. Потім обв’язка заявляє цей провайдер у `supports(...)`.

Вбудований plugin Codex дотримується цього шаблону:

* бажані користувацькі model refs: `openai/gpt-5.5`
* refs сумісності: застарілі refs `codex/gpt-*` залишаються прийнятими, але нові
  конфігурації не повинні використовувати їх як звичайні refs провайдера/моделі
* id обв’язки: `codex`
* автентифікація: синтетична доступність провайдера, тому що обв’язка Codex володіє
  нативним login/session Codex
* запит app-server: OpenClaw надсилає Codex чистий id моделі й дозволяє
  обв’язці говорити з нативним протоколом app-server

Plugin Codex є адитивним. Звичайні refs агентів `openai/gpt-*` на офіційному
провайдері OpenAI за замовчуванням вибирають обв’язку Codex. Старі refs `codex/gpt-*`
досі вибирають провайдер і обв’язку Codex для сумісності.

Для налаштування оператором, прикладів префіксів моделей і конфігурацій лише для Codex див.
[Codex Harness](/uk/plugins/codex-harness).

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

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

Вбудовані plugins і явно ввімкнені встановлені plugins з відповідними контрактами manifest
можуть під’єднувати runtime-neutral middleware результатів інструментів через
`api.registerAgentToolResultMiddleware(...)`, коли їхній manifest оголошує
цільові runtime ids у `contracts.agentToolResultMiddleware`. Ця довірена
межа призначена для асинхронних перетворень результатів інструментів, які мають виконуватися до того,
як OpenClaw або Codex передасть вивід інструмента назад у модель.

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

### Класифікація термінального результату

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

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

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

### Користувацьке введення та поверхні інструментів

Нативні обв’язки, які expose runtime-level запит користувацького введення, мають використовувати
helper-и user-input з `openclaw/plugin-sdk/agent-harness-runtime`, щоб форматувати
prompt, доставляти його через blocking reply path OpenClaw і нормалізувати
відповіді вибору/free-form назад у нативну форму відповіді середовища виконання. Helper
зберігає узгоджене представлення channel/TUI, тоді як кожна обв’язка зберігає
власний парсинг протоколу та життєвий цикл pending-request.

Нативні обв’язки, яким потрібна компактна маршрутизація інструментів у стилі PI, мають використовувати
`createAgentHarnessToolSurfaceRuntime(...)` з
`openclaw/plugin-sdk/agent-harness-tool-runtime`. Він володіє
вибором контролю tool-search/code-mode, lean defaults локальної моделі,
runtime-compatible schema filtering, виконанням hidden catalog, гідратацією директорій
і очищенням catalog. Обв’язки досі володіють своїм SDK-specific перетворенням
інструментів і нативним callback виконання.

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

Вбудована обв’язка `codex` є нативним режимом Codex для вбудованих ходів агента
OpenClaw. Спершу ввімкніть вбудований plugin `codex` і додайте `codex` до
`plugins.allow`, якщо ваша конфігурація використовує обмежувальний allowlist. Нативні конфігурації app-server
мають використовувати `openai/gpt-*`; ходи агентів OpenAI за замовчуванням вибирають обв’язку Codex.
Маршрути застарілих refs моделей Codex слід виправляти за допомогою
`openclaw doctor --fix`, а застарілі refs моделей `codex/*` залишаються compatibility
aliases для нативної обв’язки.

Коли цей режим працює, Codex володіє нативним thread id, поведінкою resume,
Compaction і виконанням app-server. OpenClaw досі володіє chat-каналом,
видимим дзеркалом стенограми, політикою інструментів, approvals, доставкою медіа та вибором
сеансу. Використовуйте provider/model `agentRuntime.id: "codex"`, коли потрібно довести,
що лише шлях Codex app-server може заявити запуск. Явні середовища виконання Plugin
fail closed; збої вибору Codex app-server і збої середовища виконання не
повторюються через інше середовище виконання.

## Строгість середовища виконання

За замовчуванням OpenClaw використовує політику середовища виконання provider/model `auto`: зареєстровані
обв’язки Plugin можуть заявити пару provider/model, а вбудоване середовище виконання
обробляє хід, коли збігів немає. Refs агентів OpenAI на офіційному провайдері OpenAI за замовчуванням використовують Codex.
Використовуйте явне середовище виконання Plugin для provider/model, як-от
`agentRuntime.id: "codex"`, коли відсутній вибір обв’язки має завершуватися з помилкою замість
маршрутизації через вбудоване середовище виконання. Збої вибраної обв’язки Plugin завжди
завершуються жорсткою помилкою. Це не блокує явний provider/model `agentRuntime.id: "openclaw"`.

Для embedded runs лише з 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"
      }
    }
  }
}
```

За явного середовища виконання Plugin сесія завершується помилкою на ранньому етапі, якщо запитаний
harness не зареєстрований, не підтримує визначеного провайдера/модель або
завершується помилкою до створення побічних ефектів ходу. Це навмисно для розгортань лише з Codex
і для live-тестів, які мають довести, що шлях app-server Codex
справді використовується.

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

## Нативні сесії та дзеркало транскрипту

Harness може зберігати нативний ідентифікатор сесії, ідентифікатор потоку або токен відновлення на боці демона.
Тримайте цю прив’язку явно пов’язаною із сесією OpenClaw і продовжуйте
дзеркалити видимий для користувача вивід асистента/інструментів у транскрипт OpenClaw.

Транскрипт OpenClaw залишається шаром сумісності для:

* видимої в каналі історії сесії
* пошуку та індексації транскриптів
* перемикання назад на вбудований harness OpenClaw на пізнішому ході
* загальної поведінки `/new`, `/reset` і видалення сесії

Якщо ваш harness зберігає допоміжну прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг
очистити її, коли скидається сесія OpenClaw, якій вона належить.

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

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

Це зберігає текстові, зображувальні, відео-, музичні, TTS, approval та messaging-tool виводи
на тому самому шляху доставки, що й запуски на базі OpenClaw.

## Поточні обмеження

* Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроби/результату все ще
  мають застарілі назви для сумісності.
* Встановлення сторонніх harness є експериментальним. Віддавайте перевагу provider plugins,
  доки вам не знадобиться нативне середовище виконання сесії.
* Перемикання harness підтримується між ходами. Не перемикайте harness у
  середині ходу після того, як почалися нативні інструменти, approvals, текст асистента або надсилання повідомлень.

## Пов’язане

* [Огляд SDK](/uk/plugins/sdk-overview)
* [Допоміжні засоби середовища виконання](/uk/plugins/sdk-runtime)
* [Provider Plugins](/uk/plugins/sdk-provider-plugins)
* [Codex Harness](/uk/plugins/codex-harness)
* [Провайдери моделей](/uk/concepts/model-providers)