Перейти до основного вмісту

​
Плагіни Agent Harness

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

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

Реєструйте agent harness, коли сімейство моделей має власний нативний рантайм сесій і звичайний транспорт постачальника OpenClaw є хибною абстракцією. Приклади:
  • нативний сервер coding-agent, який керує потоками й компакцією
  • локальний CLI або демон, який має транслювати нативні події плану/міркування/інструментів
  • рантайм моделі, якому потрібен власний resume id на додачу до транскрипту сесії OpenClaw
Не реєструйте harness лише для того, щоб додати новий LLM API. Для звичайних HTTP або WebSocket API моделей створіть плагін постачальника.

​
Чим і далі керує ядро

Перш ніж буде вибрано harness, OpenClaw уже визначив:
  • постачальника й модель
  • стан автентифікації рантайму
  • рівень міркування й бюджет контексту
  • транскрипт OpenClaw/файл сесії
  • робочий простір, sandbox і політику інструментів
  • колбеки відповіді каналу та колбеки потокової передачі
  • політику резервного переходу між моделями й перемикання на живу модель
Такий поділ є навмисним. Harness виконує підготовлену спробу; він не вибирає постачальників, не замінює доставку через канали й не перемикає моделі непомітно.

​
Зареєструвати harness

Імпорт: openclaw/plugin-sdk/agent-harness 
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 примусово вибирає вбудований harness PI.
  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. Для сумісності codex-app-server і app-server також указують на цей самий harness, коли ви вручну встановлюєте OPENCLAW_AGENT_RUNTIME.

​
Поєднання постачальника й 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. OpenClaw вимагає Codex app-server версії 0.118.0 або новішої. Плагін Codex перевіряє initialize-handshake app-server і блокує старіші сервери або сервери без версії, щоб OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано.

​
Вимкнення резервного переходу до 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: 
{
  "agents": {
    "defaults": {
      "model": "codex/gpt-5.4",
      "embeddedHarness": {
        "runtime": "codex",
        "fallback": "none"
      }
    }
  }
}
Якщо ви хочете, щоб будь-який зареєстрований harness плагіна міг заявити підтримку відповідних моделей, але ніколи не хочете, щоб OpenClaw непомітно повертався до PI, залиште runtime: "auto" і вимкніть резервний перехід: 
{
  "agents": {
    "defaults": {
      "embeddedHarness": {
        "runtime": "auto",
        "fallback": "none"
      }
    }
  }
}
Перевизначення на рівні окремого агента використовують ту саму форму: 
{
  "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 через середовище. 
OPENCLAW_AGENT_RUNTIME=codex \
OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run
Якщо резервний перехід вимкнено, сесія завершується помилкою на ранньому етапі, коли запитаний harness не зареєстровано, не підтримує визначеного постачальника/модель або зазнає збою до створення побічних ефектів ходу. Це зроблено навмисно для середовищ лише з Codex і для live-тестів, які мають довести, що фактично використовується шлях app-server Codex. Цей параметр керує лише вбудованим agent harness. Він не вимикає маршрутизацію моделей, специфічну для постачальника, для зображень, відео, музики, TTS, PDF або інших типів.

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

Harness може зберігати нативний id сесії, id потоку або daemon-side токен відновлення. Явно пов’язуйте таку прив’язку із сесією OpenClaw і продовжуйте віддзеркалювати видимий користувачу вивід помічника/інструментів у транскрипт OpenClaw. Транскрипт OpenClaw залишається шаром сумісності для:
  • історії сесії, видимої в каналі
  • пошуку та індексації транскрипту
  • повернення до вбудованого harness PI на наступному ході
  • узагальненої поведінки /new, /reset і видалення сесії
Якщо ваш harness зберігає sidecar-прив’язку, реалізуйте reset(...), щоб OpenClaw міг очистити її, коли відповідну сесію OpenClaw буде скинуто.

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

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

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

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

​
Пов’язане