Створення плагінів бекенду CLI

Плагіни серверної частини CLI дають змогу OpenClaw викликати локальний CLI ШІ як серверну частину текстового інференсу. Серверна частина відображається як префікс провайдера в посиланнях на моделі:

acme-cli/acme-large

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

Якщо зовнішній сервіс надає звичайний HTTP API моделей, натомість створіть плагін провайдера. Якщо зовнішнє середовище виконання керує повними сеансами агента, подіями інструментів, Compaction або станом фонових завдань, використовуйте обв’язку агента.

За що відповідає плагін

Плагін серверної частини CLI має три контракти:

Контракт	Файл	Призначення
Точка входу пакета	`package.json`	Спрямовує OpenClaw до модуля середовища виконання плагіна
Визначення належності	`openclaw.plugin.json`	Оголошує ідентифікатор серверної частини до завантаження середовища виконання
Реєстрація виконання	`index.ts`	Викликає `api.registerCliBackend(...)` зі стандартними параметрами команди

Маніфест — це метадані виявлення: він не виконує CLI та не реєструє поведінку середовища виконання. Поведінка середовища виконання починається, коли точка входу плагіна викликає api.registerCliBackend(...).

Мінімальний плагін серверної частини

Створіть метадані пакета

package.json

{
  "name": "@acme/openclaw-acme-cli",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2",
      "minGatewayVersion": "2026.3.24-beta.2"
    },
    "build": {
      "openclawVersion": "2026.3.24-beta.2",
      "pluginSdkVersion": "2026.3.24-beta.2"
    }
  },
  "dependencies": {
    "openclaw": "^2026.3.24"
  },
  "devDependencies": {
    "typescript": "^5.9.0"
  }
}

Опубліковані пакети мають містити зібрані JavaScript-файли середовища виконання. Якщо ваша вихідна точка входу — ./src/index.ts, додайте openclaw.runtimeExtensions, що вказує на відповідний зібраний JavaScript-файл. Див. Точки входу.

Оголосіть належність серверної частини

openclaw.plugin.json

{
  "id": "acme-cli",
  "name": "Acme CLI",
  "description": "Run Acme's local AI CLI through OpenClaw",
  "cliBackends": ["acme-cli"],
  "setup": {
    "cliBackends": ["acme-cli"],
    "requiresRuntime": false
  },
  "activation": {
    "onStartup": false
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

cliBackends — це список належності середовища виконання; він дає змогу OpenClaw автоматично завантажувати плагін, коли конфігурація або вибір моделі містить acme-cli/....setup.cliBackends — це поверхня налаштування, що насамперед використовує дескриптори. Додайте її, коли виявлення моделей, початкове налаштування або стан мають розпізнавати серверну частину без завантаження середовища виконання плагіна. Використовуйте requiresRuntime: false, лише коли цих статичних дескрипторів достатньо для налаштування.

Зареєструйте серверну частину

index.ts

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import {
  CLI_FRESH_WATCHDOG_DEFAULTS,
  CLI_RESUME_WATCHDOG_DEFAULTS,
  type CliBackendPlugin,
} from "openclaw/plugin-sdk/cli-backend";

function buildAcmeCliBackend(): CliBackendPlugin {
  return {
    id: "acme-cli",
    liveTest: {
      defaultModelRef: "acme-cli/acme-large",
      defaultImageProbe: false,
      defaultMcpProbe: false,
      docker: {
        npmPackage: "@acme/acme-cli",
        binaryName: "acme",
      },
    },
    config: {
      command: "acme",
      args: ["chat", "--json"],
      output: "json",
      input: "stdin",
      modelArg: "--model",
      sessionArg: "--session",
      sessionMode: "existing",
      sessionIdFields: ["session_id", "conversation_id"],
      systemPromptFileArg: "--system-file",
      systemPromptWhen: "first",
      imageArg: "--image",
      imageMode: "repeat",
      reliability: {
        watchdog: {
          fresh: { ...CLI_FRESH_WATCHDOG_DEFAULTS },
          resume: { ...CLI_RESUME_WATCHDOG_DEFAULTS },
        },
      },
      serialize: true,
    },
  };
}

export default definePluginEntry({
  id: "acme-cli",
  name: "Acme CLI",
  description: "Run Acme's local AI CLI through OpenClaw",
  register(api) {
    api.registerCliBackend(buildAcmeCliBackend());
  },
});

Ідентифікатор серверної частини має відповідати запису cliBackends у маніфесті. Зареєстрований config — лише значення за замовчуванням; користувацька конфігурація в agents.defaults.cliBackends.acme-cli об’єднується з ним під час виконання.

Структура конфігурації

CliBackendConfig описує, як OpenClaw має запускати й аналізувати CLI:

Поле	Використання
`command`	Назва виконуваного файла або абсолютний шлях до команди
`args`	Базовий масив argv для нових запусків
`resumeArgs`	Альтернативний масив argv для відновлених сеансів; підтримує `{sessionId}`
`output` / `resumeOutput`	Аналізатор: `json`, `jsonl` або `text`
`jsonlDialect`	Діалект подій JSONL: `claude-stream-json` або `gemini-stream-json`
`liveSession`	Режим довготривалого процесу CLI (`claude-stdio`)
`input`	Передавання запиту: `arg` або `stdin`
`maxPromptArgChars`	Максимальна довжина запиту для режиму `arg` перед переходом на stdin
`env` / `clearEnv`	Додаткові змінні середовища для додавання або назви змінних, які слід вилучити перед запуском
`modelArg`	Прапорець, що використовується перед ідентифікатором моделі
`modelAliases`	Зіставлення ідентифікаторів моделей OpenClaw із нативними ідентифікаторами CLI
`sessionArg` / `sessionArgs`	Спосіб передавання ідентифікатора сеансу
`sessionMode`	`always`, `existing` або `none`
`sessionIdFields`	Поля JSON, які OpenClaw зчитує з виводу CLI
`systemPromptArg` / `systemPromptFileArg`	Передавання системного запиту
`systemPromptFileConfigArg` / `systemPromptFileConfigKey`	Передавання перевизначення конфігурації для файла системного запиту (наприклад, `-c`)
`systemPromptMode`	`append` або `replace`
`systemPromptWhen`	`first`, `always` або `never`
`imageArg` / `imageMode`	Прапорець шляху до зображення та спосіб передавання кількох зображень (`repeat` або `list`)
`imagePathScope`	Місце розташування підготовлених файлів зображень перед передаванням: `temp` або `workspace`
`serialize`	Зберігає впорядкованість запусків тієї самої серверної частини
`reseedFromRawTranscriptWhenUncompacted`	Увімкнення обмеженого повторного заповнення з необробленої стенограми перед Compaction для безпечного скидання сеансів
`reliability.outputLimits`	Максимальна кількість символів/рядків необробленого JSONL, що зберігаються для одного активного ходу CLI (для серверних частин з активним сеансом)
`reliability.watchdog`	Налаштування часу очікування за відсутності виводу окремо для нових і відновлених запусків

Віддавайте перевагу найменшій статичній конфігурації, що відповідає CLI. Додавайте зворотні виклики плагіна лише для поведінки, яка справді належить серверній частині.

Розширені перехоплювачі серверної частини

CliBackendPlugin також може визначати:

Перехоплювач	Використання
`normalizeConfig(config, context)`	Перетворення застарілої користувацької конфігурації після об’єднання
`resolveExecutionArgs(ctx)`	Додавання прапорців для окремого запиту, як-от глибина міркувань або ізоляція додаткових запитань
`prepareExecution(ctx)`	Створення тимчасових мостів автентифікації або конфігурації перед запуском
`transformSystemPrompt(ctx)`	Застосування остаточного перетворення системного запиту для конкретного CLI
`textTransforms`	Двонапрямні заміни у запитах і виводі
`defaultAuthProfileId`	Надання переваги певному профілю автентифікації OpenClaw
`authEpochMode`	Визначення того, як зміни автентифікації скасовують збережені сеанси CLI
`nativeToolMode`	Оголошення того, чи нативні інструменти відсутні, завжди ввімкнені або можуть вибиратися хостом
`sideQuestionToolMode`	Оголошення вимкнених нативних інструментів для додаткових запитань `/btw`
`bundleMcp` / `bundleMcpMode`	Увімкнення мосту інструментів MCP через local loopback в OpenClaw
`ownsNativeCompaction`	Серверна частина сама керує Compaction — OpenClaw відкладає її
`runtimeArtifact`	Прив’язування засобу запуску скрипту до повного дерева його пакетного комплекту

Залишайте ці перехоплювачі у власності провайдера. Не додавайте до ядра гілки, специфічні для CLI, коли перехоплювач серверної частини може виразити таку поведінку. runtimeArtifact належить плагіну й не може бути перевизначений користувачем. Він використовується лише коли активний хід інференсу створює або повторно перевіряє підтверджене право на налаштування; звичайні запуски CLI його не потребують. Серверна частина без цього оголошення не може створювати підтверджене право на налаштування CLI. Оголошення bundled-package-tree визначає точного власника package.json і вимагає, щоб точкою входу пакета була команда. OpenClaw хешує обмежене повне дерево встановленого пакета, включно з вкладеними залежностями, і припиняє роботу в разі перенаправлювальних символічних посилань, засобів запуску поза оголошеним пакетом, оголошень обов’язкових зовнішніх залежностей, завеликих дерев і невідомих скриптів. Оголошуйте це лише тоді, коли це дерево містить повну реалізацію інференсу; необов’язкові інтеграції інструментів не роблять зовнішній граф реалізації безпечним. Якщо та сама серверна частина також постачає самодостатній нативний виконуваний файл, перелічіть його канонічні базові назви в nativeExecutableNames. Інші нативні команди залишаються непідтвердженими, навіть коли користувач перевизначає команду серверної частини. ctx.executionMode має значення "agent" для звичайних ходів і "side-question" для ефемерних викликів /btw. Використовуйте його, коли CLI потребує інших одноразових прапорців, наприклад для вимкнення вбудованих інструментів, збереження сеансу або поведінки відновлення для BTW. Якщо бекенд зазвичай має nativeToolMode: "always-on", але його argv для побічного запитання надійно вимикає ці інструменти, також установіть sideQuestionToolMode: "disabled"; інакше OpenClaw безпечно завершує роботу з відмовою, коли BTW потребує запуску CLI без інструментів. Установлюйте nativeToolMode: "selectable" лише тоді, коли resolveExecutionArgs може вимкнути кожен вбудований інструмент бекенду для окремого запуску. Для таких обмежених запусків ctx.toolAvailability.native є порожнім кортежем, а ctx.toolAvailability.mcp — точним ізольованим на рівні хоста списком дозволених MCP. Хук має замінити конфліктні прапорці інструментів і повернути argv, який забезпечує обидва значення; OpenClaw викликає його один раз з остаточним argv нового запуску або відновлення та безпечно завершує роботу з відмовою, коли бекенд не може забезпечити це обмеження. Імена MCP у цьому контексті можна безпечно автоматично схвалювати лише тому, що хост уже обмежив згенеровану конфігурацію MCP цими серверами та інструментами.

`ownsNativeCompaction`: відмова від Compaction у OpenClaw

Якщо ваш бекенд запускає агента, який ущільнює власну історію взаємодії, установіть ownsNativeCompaction: true, щоб запобіжний засіб підсумовування OpenClaw ніколи не запускався для його сеансів — життєвий цикл Compaction у CLI повертає відсутність дії, і хід продовжується. claude-cli оголошує це, оскільки Claude Code виконує Compaction внутрішньо без кінцевої точки середовища виконання. Натомість сеанси з нативним середовищем виконання, як-от Codex, і далі спрямовуються до кінцевої точки Compaction свого середовища виконання. Оголошуйте це лише тоді, коли виконуються всі наведені нижче умови, інакше відкладений сеанс із перевищеним бюджетом може залишитися понад бюджет або застаріти (OpenClaw більше не відновлюватиме його):

бекенд надійно ущільнює або обмежує власну історію взаємодії в міру наближення до межі свого вікна;
він зберігає сеанс, який можна відновити, щоб ущільнений стан зберігався між ходами (наприклад, --resume / --session-id);
це не сеанс Compaction із нативним середовищем виконання — сеанси з відповідним agentHarnessId натомість спрямовуються до кінцевої точки середовища виконання.

Міст інструментів MCP

Бекенди CLI типово не отримують інструменти OpenClaw. Якщо CLI може використовувати конфігурацію MCP, явно ввімкніть цю можливість:

return {
  id: "acme-cli",
  bundleMcp: true,
  bundleMcpMode: "codex-config-overrides",
  config: {
    command: "acme",
    args: ["chat", "--json"],
    output: "json",
  },
};

Підтримувані режими мосту:

Режим	Використання
`claude-config-file`	CLI, які приймають файл конфігурації MCP
`codex-config-overrides`	CLI, які приймають перевизначення конфігурації через argv
`gemini-system-settings`	CLI, які читають налаштування MCP зі свого каталогу системних налаштувань

Вмикайте міст лише тоді, коли CLI справді може його використовувати. Якщо CLI має власний вбудований рівень інструментів, який неможливо вимкнути, установіть nativeToolMode: "always-on", щоб OpenClaw міг безпечно завершити роботу з відмовою, коли викликач вимагає відсутності вбудованих інструментів. Якщо він може вимкнути всі вбудовані інструменти для кожного окремого запуску, використовуйте "selectable" із контрактом resolveExecutionArgs, наведеним вище.

Конфігурація користувача

Користувачі можуть перевизначити будь-яке типове значення бекенду:

{
  agents: {
    defaults: {
      cliBackends: {
        "acme-cli": {
          command: "/opt/acme/bin/acme",
          args: ["chat", "--json", "--profile", "work"],
          modelAliases: {
            large: "acme-large-2026",
          },
        },
      },
      model: {
        primary: "openai/gpt-5.6-sol",
        fallbacks: ["acme-cli/large"],
      },
    },
  },
}

Документуйте мінімальне перевизначення, яке, ймовірно, знадобиться користувачам — зазвичай лише command, коли виконуваний файл розташований поза PATH.

Перевірка

Для вбудованих плагінів додайте цільовий тест для побудовника та реєстрації налаштування, а потім запустіть цільовий набір тестів плагіна:

pnpm test extensions/acme-cli

Для локальних або встановлених плагінів перевірте виявлення та один реальний запуск моделі:

openclaw plugins inspect acme-cli --runtime --json
openclaw agent --message "reply exactly: backend ok" --model acme-cli/acme-large

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

Контрольний список

package.json містить openclaw.extensions і зібрані точки входу середовища виконання для опублікованих пакетів

openclaw.plugin.json оголошує cliBackends і навмисне налаштований activation.onStartup

setup.cliBackends наявний, коли налаштування або виявлення моделей має бачити бекенд до його запуску

api.registerCliBackend(...) використовує той самий ідентифікатор бекенду, що й маніфест

Користувацькі перевизначення в agents.defaults.cliBackends.<id> і надалі мають пріоритет

Налаштування сеансу, системного запиту, зображень і аналізатора виводу відповідають фактичному контракту CLI

Цільові тести та принаймні одна перевірка працездатності реального CLI підтверджують шлях бекенду

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

Бекенди CLI — конфігурація користувача та поведінка середовища виконання
Створення плагінів — основи пакетів і маніфестів
Огляд SDK плагінів — довідник API реєстрації
Маніфест плагіна — cliBackends і дескриптори налаштування
Середовище виконання агента — повноцінні зовнішні середовища виконання агентів

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Створення плагінів бекенду CLI

За що відповідає плагін

Мінімальний плагін серверної частини

Структура конфігурації

Розширені перехоплювачі серверної частини

`ownsNativeCompaction`: відмова від Compaction у OpenClaw

Міст інструментів MCP

Конфігурація користувача

Перевірка

Контрольний список

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

​За що відповідає плагін

​Мінімальний плагін серверної частини

​Структура конфігурації

​Розширені перехоплювачі серверної частини

​ownsNativeCompaction: відмова від Compaction у OpenClaw

​Міст інструментів MCP

​Конфігурація користувача

​Перевірка

​Контрольний список

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

За що відповідає плагін

Мінімальний плагін серверної частини

Структура конфігурації

Розширені перехоплювачі серверної частини

`ownsNativeCompaction`: відмова від Compaction у OpenClaw

Міст інструментів MCP

Конфігурація користувача

Перевірка

Контрольний список

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