CLI-backendplugins bouwen

CLI-backendplugins stellen OpenClaw in staat een lokale AI-CLI aan te roepen als backend voor tekstinferentie. De backend verschijnt als providerprefix in modelverwijzingen:

acme-cli/acme-large

Gebruik een CLI-backend wanneer de bovenliggende integratie al beschikbaar is als een lokale opdracht, wanneer de CLI de lokale aanmeldstatus beheert, of als terugvaloptie wanneer API- providers niet beschikbaar zijn.

Wat de plugin beheert

Een CLI-backendplugin heeft drie contracten:

Het manifest is detectiemetadata: het voert de CLI niet uit en registreert geen runtimegedrag. Runtimegedrag begint wanneer de plugingang api.registerCliBackend(...) aanroept.

Minimale backendplugin

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

Configuratiestructuur

CliBackendConfig beschrijft hoe OpenClaw de CLI moet starten en parseren:

Geef de voorkeur aan de kleinste statische configuratie die bij de CLI past. Voeg plugincallbacks alleen toe voor gedrag dat daadwerkelijk bij de backend hoort.

Geavanceerde backendhooks

CliBackendPlugin kan ook het volgende definiëren:

Houd deze hooks onder beheer van de provider. Voeg geen CLI-specifieke vertakkingen toe aan de kern wanneer een backendhook het gedrag kan uitdrukken.

runtimeArtifact wordt door de plugin beheerd en kan niet door de gebruiker worden overschreven. Het wordt alleen geraadpleegd wanneer een live inferentiebeurt geverifieerde installatiebevoegdheid aanmaakt of opnieuw valideert; normale CLI-uitvoeringen vereisen dit niet. Een backend zonder deze declaratie kan geen geverifieerde CLI-installatiebevoegdheid aanmaken. Een declaratie bundled-package-tree benoemt de exacte eigenaar van package.json en vereist dat het pakketingangspunt de opdracht is. OpenClaw hasht de begrensde, volledige geïnstalleerde pakketboom, inclusief geneste afhankelijkheden, en weigert standaard bij omleidende symbolische koppelingen, starters buiten het gedeclareerde pakket, vereiste externe afhankelijkheidsdeclaraties, te grote bomen en onbekende scripts. Declareer dit alleen wanneer die boom de volledige inferentie-implementatie bevat; optionele toolintegraties maken een externe implementatiegraaf niet veilig.

Als dezelfde backend ook een zelfstandig systeemeigen uitvoerbaar bestand levert, vermeld dan de canonieke basisnamen in nativeExecutableNames. Andere systeemeigen opdrachten blijven niet-geverifieerd, zelfs wanneer een gebruiker de backendopdracht overschrijft.

ctx.executionMode is "agent" voor normale beurten en "side-question" voor tijdelijke /btw-aanroepen. Gebruik dit wanneer de CLI andere eenmalige vlaggen nodig heeft, zoals voor het uitschakelen van native tools, sessiepersistentie of hervattingsgedrag voor BTW. Als een backend normaal nativeToolMode: "always-on" heeft, maar de argv voor zijvragen deze tools betrouwbaar uitschakelt, stel dan ook sideQuestionToolMode: "disabled" in; anders weigert OpenClaw veilig wanneer BTW een CLI-uitvoering zonder tools vereist.

Stel nativeToolMode: "selectable" alleen in wanneer resolveExecutionArgs elke backend-native tool voor een afzonderlijke uitvoering kan uitschakelen. Voor deze beperkte uitvoeringen is ctx.toolAvailability.native een lege tuple en is ctx.toolAvailability.mcp de exacte, van de host geïsoleerde MCP-toelatingslijst. De hook moet conflicterende toolvlaggen vervangen en argv retourneren die beide waarden afdwingt; OpenClaw roept de hook eenmaal aan met de uiteindelijke argv voor een nieuwe of hervatte sessie en weigert veilig wanneer de backend de beperking niet kan afdwingen. MCP-namen in deze context mogen alleen automatisch worden goedgekeurd omdat de host de gegenereerde MCP-configuratie al heeft beperkt tot die servers en tools.

ownsNativeCompaction: OpenClaw-compactie uitschakelen

Als uw backend een agent uitvoert die zijn eigen transcript compacteert, stel dan ownsNativeCompaction: true in, zodat de beveiligende samenvatter van OpenClaw nooit op zijn sessies wordt uitgevoerd: de CLI-compactielevenscyclus voert geen bewerking uit en de beurt gaat verder. claude-cli declareert dit omdat Claude Code intern compacteert zonder harness-eindpunt. Sessies met een native harness, zoals Codex, blijven in plaats daarvan naar het compactie-eindpunt van hun harness worden gerouteerd.

Declareer dit alleen wanneer aan alle volgende voorwaarden is voldaan, anders kan een uitgestelde sessie die het budget overschrijdt boven het budget blijven of verouderd raken (OpenClaw herstelt deze niet langer):

• de backend compacteert of begrenst zijn eigen transcript betrouwbaar wanneer het venster bijna vol is;
• de backend bewaart een hervatbare sessie, zodat de gecompacteerde toestand tussen beurten behouden blijft (bijvoorbeeld --resume / --session-id);
• het is geen compactiesessie met een native harness: sessies met een overeenkomende agentHarnessId worden in plaats daarvan naar het harness-eindpunt gerouteerd.

MCP-toolbrug

CLI-backends ontvangen standaard geen OpenClaw-tools. Als de CLI een MCP-configuratie kan gebruiken, schakel dit dan expliciet in:

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

Ondersteunde brugmodi:

Schakel de brug alleen in wanneer de CLI deze daadwerkelijk kan gebruiken. Als de CLI een eigen ingebouwde toollaag heeft die niet kan worden uitgeschakeld, stel dan nativeToolMode: "always-on" in, zodat OpenClaw veilig kan weigeren wanneer een aanroeper vereist dat er geen native tools zijn. Als alle native tools per uitvoering kunnen worden uitgeschakeld, gebruikt u "selectable" met het hierboven beschreven resolveExecutionArgs-contract.

Gebruikersconfiguratie

Gebruikers kunnen elke standaardwaarde van een backend overschrijven:

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

Documenteer de minimale overschrijving die gebruikers waarschijnlijk nodig hebben, doorgaans alleen command wanneer het binaire bestand zich buiten PATH bevindt.

Verificatie

Voeg voor gebundelde plugins een gerichte test toe voor de builder en setupregistratie en voer vervolgens de gerichte testreeks van de Plugin uit:

pnpm test extensions/acme-cli

Controleer voor lokale of geïnstalleerde plugins de detectie en één echte modeluitvoering:

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

Als de backend afbeeldingen of MCP ondersteunt, voeg dan een live-rooktest toe die deze paden met de echte CLI bewijst. Vertrouw niet op statische inspectie voor prompt-, afbeeldings-, MCP- of sessiehervattingsgedrag.

Controlelijst

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json bevat openclaw.extensions en gebouwde runtimevermeldingen voor gepubliceerde pakketten OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json declareert cliBackends en een doelbewuste activation.onStartup OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s setup.cliBackends is aanwezig wanneer setup/modeldetectie de backend koud moet kunnen vinden OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s api.registerCliBackend(...) gebruikt dezelfde backend-id als het manifest OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Gebruikersoverschrijvingen onder agents.defaults.cliBackends.<id> blijven voorrang houden OPENCLAW_DOCS_MARKER:calloutClose: