Создание плагинов бэкенда 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": "Запускайте локальный CLI ИИ Acme через 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: "Запускайте локальный CLI ИИ Acme через OpenClaw",  register(api) {    api.registerCliBackend(buildAcmeCliBackend());  },});

Структура конфигурации

CliBackendConfig описывает, как OpenClaw должен запускать CLI и разбирать его вывод:

Предпочитайте минимальную статическую конфигурацию, соответствующую CLI. Добавляйте обратные вызовы плагина только для поведения, которое действительно относится к серверной части.

Расширенные хуки серверной части

CliBackendPlugin также может определять:

Эти хуки должны оставаться в ведении провайдера. Не добавляйте специфичные для CLI ветви в ядро, если поведение можно выразить через хук серверной части.

prepareExecution(ctx) получает ctx.contextTokenBudget — эффективный лимит токенов, выбранный для запуска. Серверные части, самостоятельно выполняющие нативную Compaction, могут преобразовать этот бюджет в свой контракт запуска CLI.

runtimeArtifact принадлежит плагину и не может быть переопределён пользователем. Он проверяется только тогда, когда рабочий цикл инференса создаёт или повторно проверяет подтверждённые полномочия настройки; обычные запуски CLI не требуют его. Бэкенд без этого объявления не может создавать подтверждённые полномочия настройки CLI. Объявление bundled-package-tree указывает точного владельца package.json и требует, чтобы точкой входа пакета была команда. OpenClaw хеширует ограниченное полное дерево установленного пакета, включая вложенные зависимости, и блокирует выполнение при перенаправляющих символических ссылках, запускателях за пределами объявленного пакета, объявлениях обязательных внешних зависимостей, слишком больших деревьях и неизвестных скриптах. Объявляйте это только тогда, когда дерево содержит полную реализацию инференса; необязательные интеграции инструментов не делают внешний граф реализации безопасным.

Если тот же бэкенд также поставляет самодостаточный нативный исполняемый файл, перечислите его канонические базовые имена в nativeExecutableNames. Другие нативные команды остаются неподтверждёнными, даже когда пользователь переопределяет команду бэкенда.

ctx.executionMode имеет значение "agent" для обычных циклов и "side-question" для эфемерных вызовов /btw. Используйте его, когда CLI требуются другие одноразовые флаги, например для отключения нативных инструментов, сохранения сеанса или возобновления работы для BTW. Если у бэкенда обычно есть nativeToolMode: "always-on", но его аргументы командной строки для побочного вопроса надёжно отключают эти инструменты, также задайте sideQuestionToolMode: "disabled"; иначе OpenClaw блокирует выполнение, когда для BTW требуется запуск CLI без инструментов.

Задавайте nativeToolMode: "selectable" только тогда, когда resolveExecutionArgs может отключить все нативные инструменты бэкенда для отдельного запуска. Для таких ограниченных запусков ctx.toolAvailability.native является пустым кортежем, а ctx.toolAvailability.mcp — точным списком разрешённых MCP с изоляцией на стороне хоста. Хук должен заменять конфликтующие флаги инструментов и возвращать аргументы командной строки, обеспечивающие оба значения; OpenClaw вызывает его один раз с окончательными аргументами нового или возобновляемого запуска и блокирует выполнение, если бэкенд не может обеспечить соблюдение ограничения. Имена MCP в этом контексте можно безопасно подтверждать автоматически только потому, что хост уже ограничил создаваемую конфигурацию MCP этими серверами и инструментами.

ownsNativeCompaction: отказ от Compaction OpenClaw

Если ваш бэкенд запускает агента, который выполняет Compaction собственной расшифровки, задайте ownsNativeCompaction: true, чтобы защитный суммаризатор OpenClaw никогда не запускался для его сеансов: жизненный цикл Compaction CLI ничего не делает, и цикл продолжается. claude-cli объявляет это, поскольку Claude Code выполняет Compaction внутренне, без конечной точки среды выполнения. Сеансы нативной среды выполнения, такие как Codex, вместо этого продолжают направляться к конечной точке Compaction своей среды выполнения.

Объявляйте это, только если выполняются все следующие условия, иначе отложенный сеанс с превышенным бюджетом может остаться за пределами бюджета или устареть (OpenClaw больше не восстанавливает его):

• бэкенд надёжно выполняет Compaction или ограничивает собственную расшифровку по мере приближения к пределу контекстного окна;
• он сохраняет возобновляемый сеанс, чтобы состояние после Compaction сохранялось между циклами (например, --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 мог блокировать выполнение, когда вызывающей стороне требуется отсутствие нативных инструментов. Если CLI может отключить все нативные инструменты для отдельного запуска, используйте "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 или возобновления сеанса.

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

Связанные материалы

• Бэкенды CLI — пользовательская конфигурация и поведение среды выполнения
• Создание плагинов — основы пакетов и манифестов
• Обзор SDK плагинов — справочник по API регистрации
• Манифест плагина — cliBackends и дескрипторы настройки
• Среда выполнения агента — полноценные внешние среды выполнения агентов