---
read_when:
    - Ви змінюєте вбудоване середовище виконання агента або реєстр harness агента
    - Ви реєструєте harness агента з вбудованого або довіреного плагіна
    - Вам потрібно зрозуміти, як плагін Codex пов’язаний із постачальниками моделей
sidebarTitle: Agent Harness
summary: Експериментальна поверхня SDK для плагінів, які замінюють низькорівневий вбудований виконавець агента
title: Плагіни Agent Harness
x-i18n:
    generated_at: "2026-04-11T16:15:07Z"
    model: gpt-5.4
    provider: openai
    source_hash: 62b88fd24ce8b600179db27e16e8d764a2cd7a14e5c5df76374c33121aa5e365
    source_path: plugins/sdk-agent-harness.md
    workflow: 15
---

# Плагіни Agent Harness

**Agent harness** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів.

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

## Коли використовувати harness

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

Приклади:

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

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

## Чим усе ще керує ядро

До вибору harness OpenClaw уже визначив:

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

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

## Реєстрація harness

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

```typescript
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 вибирає harness після визначення постачальника/моделі:

1. `OPENCLAW_AGENT_RUNTIME=<id>` примусово вибирає зареєстрований harness з цим id.
2. `OPENCLAW_AGENT_RUNTIME=pi` примусово вибирає вбудований PI harness.
3. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані harness, чи підтримують вони визначеного постачальника/модель.
4. Якщо жоден зареєстрований harness не підходить, OpenClaw використовує PI, якщо резервний перехід на PI не вимкнено.

Помилки примусово вибраного harness плагіна відображаються як помилки виконання. У режимі `auto` OpenClaw може перейти на PI, якщо вибраний harness плагіна завершується помилкою до того, як хід породить побічні ефекти. Установіть `OPENCLAW_AGENT_HARNESS_FALLBACK=none` або `embeddedHarness.fallback: "none"`, щоб зробити такий резервний перехід жорсткою помилкою.

Вбудований плагін Codex реєструє `codex` як id свого harness. Ядро обробляє його як звичайний id harness плагіна; специфічні для Codex псевдоніми мають належати плагіну або конфігурації оператора, а не спільному селектору середовища виконання.

## Поєднання постачальника й harness

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

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

- id постачальника: `codex`
- посилання користувача на моделі: `codex/gpt-5.4`, `codex/gpt-5.2` або інша модель, повернена сервером застосунку Codex
- id harness: `codex`
- автентифікація: синтетична доступність постачальника, оскільки harness Codex керує нативним входом/сесією Codex
- запит до app-server: OpenClaw надсилає до Codex чистий id моделі й дозволяє harness взаємодіяти з нативним протоколом app-server

Плагін Codex є додатковим. Звичайні посилання `openai/gpt-*` залишаються посиланнями постачальника OpenAI й продовжують використовувати звичайний шлях постачальника OpenClaw. Вибирайте `codex/gpt-*`, коли вам потрібні автентифікація під керуванням Codex, виявлення моделей Codex, нативні потоки та виконання через app-server Codex. `/model` може перемикатися між моделями Codex, які повертає app-server Codex, без потреби в облікових даних постачальника OpenAI.

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

OpenClaw вимагає Codex app-server версії `0.118.0` або новішої. Плагін Codex перевіряє handshake ініціалізації app-server і блокує старіші сервери або сервери без версії, щоб OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано.

### Режим нативного Codex harness

Вбудований harness `codex` — це нативний режим Codex для вбудованих ходів агента OpenClaw. Спочатку ввімкніть вбудований плагін `codex` і додайте `codex` до `plugins.allow`, якщо у вашій конфігурації використовується обмежувальний allowlist. Він відрізняється від `openai-codex/*`:

- `openai-codex/*` використовує OAuth ChatGPT/Codex через звичайний шлях постачальника OpenClaw.
- `codex/*` використовує вбудований постачальник Codex і спрямовує хід через app-server Codex.

Коли цей режим працює, Codex керує нативним id потоку, поведінкою resume, компакцією та виконанням app-server. OpenClaw усе ще керує каналом чату, видимим дзеркалом транскрипту, політикою інструментів, підтвердженнями, доставленням медіа та вибором сесії. Використовуйте `embeddedHarness.runtime: "codex"` разом із `embeddedHarness.fallback: "none"`, коли потрібно довести, що використовується шлях app-server Codex і що резервний перехід на PI не приховує несправний нативний harness.

## Вимкнення резервного переходу на PI

За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, установленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані harness плагінів можуть заявляти про пару постачальник/модель. Якщо жоден не підходить або якщо автоматично вибраний harness плагіна завершується помилкою до появи результату, OpenClaw переходить на PI.

Установіть `fallback: "none"`, коли потрібно довести, що harness плагіна є єдиним середовищем виконання, яке використовується. Це вимикає автоматичний резервний перехід на PI; це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`.

Для вбудованих запусків лише з Codex:

```json
{
  "agents": {
    "defaults": {
      "model": "codex/gpt-5.4",
      "embeddedHarness": {
        "runtime": "codex",
        "fallback": "none"
      }
    }
  }
}
```

Якщо ви хочете, щоб будь-який зареєстрований harness плагіна міг заявляти про відповідні моделі, але ніколи не хочете, щоб OpenClaw непомітно переходив на PI, залиште `runtime: "auto"` і вимкніть резервний перехід:

```json
{
  "agents": {
    "defaults": {
      "embeddedHarness": {
        "runtime": "auto",
        "fallback": "none"
      }
    }
  }
}
```

Перевизначення для окремих агентів використовують ту саму форму:

```json
{
  "agents": {
    "defaults": {
      "embeddedHarness": {
        "runtime": "auto",
        "fallback": "pi"
      }
    },
    "list": [
      {
        "id": "codex-only",
        "model": "codex/gpt-5.4",
        "embeddedHarness": {
          "runtime": "codex",
          "fallback": "none"
        }
      }
    ]
  }
}
```

`OPENCLAW_AGENT_RUNTIME` усе ще перевизначає налаштоване середовище виконання. Використовуйте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути резервний перехід на PI через середовище.

```bash
OPENCLAW_AGENT_RUNTIME=codex \
OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run
```

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

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

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

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

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

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

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

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

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

Це забезпечує, що текст, зображення, відео, музика, TTS, підтвердження та результати інструментів обміну повідомленнями доставляються тим самим шляхом, що й для запусків на основі PI.

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

- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроб/результатів досі містять назви `Pi` для сумісності.
- Установлення сторонніх harness є експериментальним. Віддавайте перевагу плагінам постачальників, доки вам не знадобиться нативне середовище виконання сесій.
- Перемикання harness між ходами підтримується. Не перемикайте harness посеред ходу після того, як уже почалися нативні інструменти, підтвердження, текст асистента або надсилання повідомлень.

## Пов’язані матеріали

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