Tworzenie Pluginów zaplecza CLI

Pluginy zaplecza CLI umożliwiają OpenClaw wywoływanie lokalnego CLI AI jako zaplecza wnioskowania tekstowego. Zaplecze występuje jako prefiks dostawcy w odwołaniach do modeli:

acme-cli/acme-large

Użyj zaplecza CLI, gdy integracja nadrzędna jest już udostępniona jako lokalne polecenie, gdy CLI zarządza lokalnym stanem logowania lub jako rozwiązanie awaryjne, gdy dostawcy API są niedostępni.

Za co odpowiada plugin

Plugin zaplecza CLI ma trzy kontrakty:

Manifest zawiera metadane wykrywania: nie uruchamia CLI ani nie rejestruje zachowania środowiska wykonawczego. Zachowanie wykonawcze zaczyna się, gdy punkt wejścia pluginu wywoła api.registerCliBackend(...).

Minimalny plugin zaplecza

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

Struktura konfiguracji

CliBackendConfig opisuje sposób, w jaki OpenClaw ma uruchamiać i analizować CLI:

Preferuj najmniejszą statyczną konfigurację zgodną z CLI. Dodawaj wywołania zwrotne pluginu tylko dla zachowania, które rzeczywiście należy do zaplecza.

Zaawansowane haki zaplecza

CliBackendPlugin może również definiować:

Haki te powinny pozostawać własnością dostawcy. Nie dodawaj do rdzenia gałęzi specyficznych dla CLI, gdy hak zaplecza może wyrazić dane zachowanie.

runtimeArtifact jest własnością pluginu i użytkownik nie może go nadpisać. Jest sprawdzany tylko wtedy, gdy aktywna tura wnioskowania tworzy lub ponownie weryfikuje potwierdzone uprawnienie konfiguracji; zwykłe uruchomienia CLI go nie wymagają. Zaplecze bez tej deklaracji nie może tworzyć potwierdzonego uprawnienia konfiguracji CLI. Deklaracja bundled-package-tree wskazuje dokładnego właściciela pliku package.json i wymaga, aby punktem wejścia pakietu było polecenie. OpenClaw oblicza skrót ograniczonego, kompletnego drzewa zainstalowanego pakietu, w tym zagnieżdżonych zależności, i bezpiecznie odrzuca dowiązania symboliczne przekierowujące poza drzewo, programy uruchamiające spoza zadeklarowanego pakietu, deklaracje wymaganych zależności zewnętrznych, zbyt duże drzewa oraz nieznane skrypty. Deklaruj to tylko wtedy, gdy drzewo zawiera kompletną implementację wnioskowania; opcjonalne integracje narzędzi nie zapewniają bezpieczeństwa zewnętrznemu grafowi implementacji.

Jeśli to samo zaplecze dostarcza również samodzielny natywny plik wykonywalny, wymień jego kanoniczne nazwy bazowe w nativeExecutableNames. Inne natywne polecenia pozostają niezweryfikowane, nawet gdy użytkownik nadpisze polecenie zaplecza.

ctx.executionMode ma wartość "agent" dla zwykłych tur oraz "side-question" dla tymczasowych wywołań /btw. Użyj go, gdy CLI wymaga innych jednorazowych flag, na przykład wyłączenia narzędzi natywnych, trwałości sesji lub zachowania przy wznawianiu dla BTW. Jeśli backend ma zwykle ustawienie nativeToolMode: "always-on", ale jego argumenty argv dla pytań pobocznych niezawodnie wyłączają te narzędzia, ustaw również sideQuestionToolMode: "disabled"; w przeciwnym razie OpenClaw bezpiecznie odmawia działania, gdy BTW wymaga uruchomienia CLI bez narzędzi.

Ustaw nativeToolMode: "selectable" tylko wtedy, gdy resolveExecutionArgs może wyłączyć każde narzędzie natywne backendu dla pojedynczego uruchomienia. W takich ograniczonych uruchomieniach ctx.toolAvailability.native jest pustą krotką, a ctx.toolAvailability.mcp jest dokładną, izolowaną przez host listą dozwolonych MCP. Hook musi zastąpić kolidujące flagi narzędzi i zwrócić argv wymuszające obie wartości; OpenClaw wywołuje go raz z ostatecznym argv nowej lub wznawianej sesji i bezpiecznie odmawia działania, gdy backend nie może wymusić ograniczenia. Nazwy MCP w tym kontekście można bezpiecznie zatwierdzać automatycznie wyłącznie dlatego, że host wcześniej ograniczył wygenerowaną konfigurację MCP do tych serwerów i narzędzi.

ownsNativeCompaction: rezygnacja z Compaction OpenClaw

Jeśli Twój backend uruchamia agenta, który wykonuje Compaction własnego transkryptu, ustaw ownsNativeCompaction: true, aby awaryjny mechanizm podsumowujący OpenClaw nigdy nie działał na jego sesjach — cykl życia Compaction w CLI nie wykonuje żadnej operacji, a tura jest kontynuowana. claude-cli deklaruje tę opcję, ponieważ Claude Code wykonuje Compaction wewnętrznie, bez punktu końcowego warstwy pośredniczącej. Sesje natywnej warstwy pośredniczącej, takie jak Codex, są zamiast tego nadal kierowane do punktu końcowego Compaction tej warstwy.

Deklaruj tę opcję tylko wtedy, gdy spełnione są wszystkie poniższe warunki; w przeciwnym razie odroczona sesja przekraczająca budżet może nadal go przekraczać lub stać się nieaktualna (OpenClaw już jej nie uratuje):

• backend niezawodnie wykonuje Compaction własnego transkryptu lub ogranicza jego rozmiar, gdy zbliża się on do granicy okna;
• utrwala sesję możliwą do wznowienia, dzięki czemu stan po Compaction zachowuje się między turami (na przykład --resume / --session-id);
• nie jest to sesja Compaction natywnej warstwy pośredniczącej — sesje pasujące do agentHarnessId są zamiast tego kierowane do punktu końcowego tej warstwy.

Most narzędzi MCP

Backendy CLI domyślnie nie otrzymują narzędzi OpenClaw. Jeśli CLI może używać konfiguracji MCP, włącz tę funkcję jawnie:

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

Obsługiwane tryby mostu:

Włączaj most tylko wtedy, gdy CLI rzeczywiście może go używać. 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ć działania, gdy wywołujący wymaga braku natywnych narzędzi. Jeśli może wyłączyć wszystkie narzędzia natywne dla każdego uruchomienia, użyj "selectable" wraz z opisaną powyżej umową resolveExecutionArgs.

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

Udokumentuj minimalne nadpisanie, którego użytkownicy prawdopodobnie będą potrzebować — zwykle tylko command, gdy plik wykonywalny znajduje się poza PATH.

Weryfikacja

W przypadku dołączonych Pluginów dodaj ukierunkowany test konstruktora i rejestracji konfiguracji, a następnie uruchom docelowy zestaw testów Pluginu:

pnpm test extensions/acme-cli

W przypadku lokalnych lub zainstalowanych Pluginów zweryfikuj wykrywanie i jedno rzeczywiste uruchomienie modelu:

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

Jeśli backend obsługuje obrazy lub MCP, dodaj test dymny na żywo, który potwierdza te ścieżki przy użyciu rzeczywistego CLI. Nie polegaj na statycznej inspekcji działania promptów, obrazów, MCP ani wznawiania sesji.

Lista kontrolna

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json zawiera openclaw.extensions oraz zbudowane wpisy środowiska wykonawczego dla opublikowanych pakietów OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json deklaruje cliBackends i świadomie dobrane activation.onStartup OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s setup.cliBackends jest obecne, gdy konfiguracja lub wykrywanie modeli powinny widzieć nieuruchomiony backend 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 w agents.defaults.cliBackends.<id> nadal mają pierwszeństwo OPENCLAW_DOCS_MARKER:calloutClose: