Створення backend Plugin для CLI

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

acme-cli/acme-large

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

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

Чим володіє плагін

Плагін бекенду CLI має три контракти:

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

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

Мінімальний плагін бекенду

Create package metadata

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-файли runtime. Якщо ваша вихідна точка входу — ./src/index.ts, додайте openclaw.runtimeExtensions, що вказує на відповідний зібраний JavaScript-файл. Див. Точки входу.

Declare backend ownership

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 — це список володіння runtime. Він дає OpenClaw змогу автоматично завантажувати плагін, коли конфігурація або вибір моделі згадує acme-cli/....setup.cliBackends — це поверхня налаштування, що спершу використовує дескриптор. Додайте її, коли виявлення моделей, onboarding або статус мають розпізнавати бекенд без завантаження runtime плагіна. Використовуйте 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 об’єднується з ним у runtime.

Форма конфігурації

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

Поле	Використання
`command`	Назва бінарного файлу або абсолютний шлях до команди
`args`	Базовий argv для нових запусків
`resumeArgs`	Альтернативний argv для відновлених сесій; підтримує `{sessionId}`
`output` / `resumeOutput`	Парсер: `json`, `jsonl` або `text`
`input`	Передавання промпта: `arg` або `stdin`
`modelArg`	Прапорець, що використовується перед ідентифікатором моделі
`modelAliases`	Зіставляє ідентифікатори моделей OpenClaw з нативними ідентифікаторами CLI
`sessionArg` / `sessionArgs`	Як передати ідентифікатор сесії
`sessionMode`	`always`, `existing` або `none`
`sessionIdFields`	JSON-поля, які OpenClaw читає з виводу CLI
`systemPromptArg` / `systemPromptFileArg`	Передавання системного промпта
`systemPromptWhen`	`first`, `always` або `never`
`imageArg` / `imageMode`	Підтримка шляху до зображення
`serialize`	Зберігає порядок запусків того самого бекенду
`reliability.watchdog`	Налаштування тайм-ауту без виводу

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

Розширені хуки бекенду

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

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

Залишайте ці хуки у володінні провайдера. Не додавайте специфічні для CLI гілки в core, коли хук бекенду може виразити поведінку. ctx.executionMode має значення "agent" для звичайних ходів і "side-question" для ефемерних викликів /btw. Використовуйте його, коли CLI потребує різних одноразових прапорців, як-от вимкнення нативних інструментів, збереження сесії або поведінки відновлення для BTW. Якщо бекенд зазвичай має nativeToolMode: "always-on", але його argv для побічних питань надійно вимикає ці інструменти, також задайте sideQuestionToolMode: "disabled"; інакше OpenClaw fail closed, коли BTW потребує запуску CLI без інструментів.

`ownsNativeCompaction`: відмова від compaction OpenClaw

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

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

Міст інструментів 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 міг fail closed, коли викликач потребує відсутності нативних інструментів.

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

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

{
  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.5",
        fallbacks: ["acme-cli/large"],
      },
    },
  },
}

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

Перевірка

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

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, додайте живий smoke-тест, який підтверджує ці шляхи з реальним CLI. Не покладайтеся на статичну інспекцію для поведінки prompt, зображень, MCP або відновлення сесії.

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

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

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

setup.cliBackends присутній, коли setup/виявлення моделі має бачити бекенд у холодному стані

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

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

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

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

Пов’язане

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

​Чим володіє плагін

​Мінімальний плагін бекенду

​Форма конфігурації

​Розширені хуки бекенду

​ownsNativeCompaction: відмова від compaction OpenClaw

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

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

​Перевірка

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

​Пов’язане

Чим володіє плагін

Мінімальний плагін бекенду

Форма конфігурації

Розширені хуки бекенду

`ownsNativeCompaction`: відмова від compaction OpenClaw

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

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

Перевірка

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

Пов’язане