Tworzenie pluginów backendu CLI

CLI backend plugins pozwalają OpenClaw wywoływać lokalne AI CLI jako backend wnioskowania tekstowego. Backend pojawia się jako prefiks dostawcy w referencjach modeli:

acme-cli/acme-large

Użyj backendu CLI, gdy integracja upstream jest już udostępniona jako lokalne polecenie, gdy CLI zarządza lokalnym stanem logowania albo gdy CLI jest użytecznym rozwiązaniem awaryjnym, jeśli dostawcy API są niedostępni.

# Za co odpowiada plugin

Plugin backendu CLI ma trzy kontrakty:

Manifest to metadane wykrywania. Nie wykonuje CLI ani nie rejestruje zachowania runtime. Zachowanie runtime zaczyna się, gdy punkt wejścia pluginu wywoła api.registerCliBackend(...).

# Minimalny plugin backendu

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

# Kształt konfiguracji

CliBackendConfig opisuje, jak OpenClaw ma uruchamiać i analizować CLI:

Preferuj najmniejszą statyczną konfigurację, która pasuje do CLI. Dodawaj callbacki pluginu tylko dla zachowania, które rzeczywiście należy do backendu.

# Zaawansowane hooki backendu

CliBackendPlugin może również definiować:

Te hooki powinny pozostawać własnością dostawcy. Nie dodawaj gałęzi specyficznych dla CLI do rdzenia, gdy hook backendu może wyrazić dane zachowanie.

# Most narzędzi MCP

Backendy CLI domyślnie nie otrzymują narzędzi OpenClaw. Jeśli CLI potrafi użyć konfiguracji MCP, włącz to jawnie:

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

Obsługiwane tryby mostu to:

Włączaj most tylko wtedy, gdy CLI rzeczywiście potrafi go użyć. Jeśli CLI ma własną wbudowaną warstwę narzędzi, której nie można wyłączyć, ustaw nativeToolMode: "always-on", aby OpenClaw mógł bezpiecznie odmówić, gdy wywołujący wymaga braku narzędzi natywnych.

# Konfiguracja użytkownika

Użytkownicy mogą nadpisać dowolną wartość domyślną backendu:

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

Udokumentuj minimalne nadpisanie, którego użytkownicy prawdopodobnie będą potrzebować. Zwykle jest to tylko command, gdy plik binarny znajduje się poza PATH.

# Weryfikacja

Dla dołączonych pluginów dodaj ukierunkowany test wokół buildera i rejestracji konfiguracji, a następnie uruchom ukierunkowaną ścieżkę testową pluginu:

pnpm test extensions/acme-cli

Dla lokalnych lub zainstalowanych pluginów zweryfikuj wykrywanie i jedno rzeczywiste uruchomienie modelu:

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

Jeśli backend obsługuje obrazy lub MCP, dodaj live smoke potwierdzający te ścieżki z rzeczywistym CLI. Nie polegaj na statycznej inspekcji dla zachowania promptu, obrazu, MCP ani wznawiania sesji.

# Lista kontrolna

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json ma openclaw.extensions i zbudowane wpisy runtime dla opublikowanych pakietów OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json deklaruje cliBackends i zamierzone activation.onStartup OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s setup.cliBackends jest obecne, gdy konfiguracja/wykrywanie modeli powinny widzieć backend na zimno OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s api.registerCliBackend(...) używa tego samego identyfikatora backendu co manifest OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Nadpisania użytkownika pod agents.defaults.cliBackends.<id> nadal mają pierwszeństwo OPENCLAW_DOCS_MARKER:calloutClose: