OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Plugin SDK reference

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

Обв’язка агента — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не провайдер моделі, не канал і не реєстр інструментів. Для користувацької ментальної моделі див. Середовища виконання агентів.

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

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

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

Приклади:

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

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

Чим досі володіє 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
  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.

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
{  "models": {    "providers": {      "openai": {        "agentRuntime": {          "id": "codex"        }      }    }  },  "agents": {    "defaults": {      "model": "openai/gpt-5.5"    }  }}

Якщо вам потрібен CLI backend для однієї канонічної моделі, помістіть runtime у цей запис моделі:

json
{  "agents": {    "defaults": {      "model": "anthropic/claude-opus-4-8",      "models": {        "anthropic/claude-opus-4-8": {          "agentRuntime": {            "id": "claude-cli"          }        }      }    }  }}

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

json
{  "agents": {    "list": [      {        "id": "codex-only",        "model": "openai/gpt-5.5",        "models": {          "openai/gpt-5.5": {            "agentRuntime": { "id": "codex" }          }        }      }    ]  }}

Такі застарілі приклади runtime для всього агента ігноруються:

json
{  "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, текст асистента або надсилання повідомлень.

Пов’язане

Was this useful?
On this page

On this page