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

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

acme-cli/acme-large

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

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

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

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

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

{  "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"  }}

{  "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  }}

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());  },});

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

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

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

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

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

Залишайте ці перехоплювачі у власності провайдера. Не додавайте до ядра гілки, специфічні для 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",  },};

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

Вмикайте міст лише тоді, коли 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 --jsonopenclaw agent --message "reply exactly: backend ok" --model acme-cli/acme-large

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

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

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

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

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

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

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