CLI-backendplugins bouwen

CLI-backendplugins laten OpenClaw een lokale AI-CLI aanroepen als backend voor tekstinferentie. De backend verschijnt als providerprefix in modelverwijzingen:

acme-cli/acme-large

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

Wat de plugin beheert

Een CLI-backendplugin heeft drie contracten:

Het manifest bevat detectiemetadata: het voert de CLI niet uit en registreert geen runtimegedrag. Het runtimegedrag begint wanneer het pluginentrypoint 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": "Acme's lokale AI-CLI via OpenClaw uitvoeren",  "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", "--output-format", "stream-json", "--prompt", "{prompt}"],      resumeArgs: [        "chat",        "--resume",        "{sessionId}",        "--output-format",        "stream-json",        "--prompt",        "{prompt}",      ],      output: "jsonl",      resumeOutput: "jsonl",      jsonlDialect: "gemini-stream-json",      input: "arg",      modelArg: "--model",      modelAliases: {        large: "acme-large-2026",        fast: "acme-fast-2026",      },      sessionArgs: ["--session", "{sessionId}"],      sessionMode: "existing",      sessionIdFields: ["session_id", "conversation_id"],      systemPromptFileArg: "--system-file",      systemPromptWhen: "first",      imageArg: "--image",      imageMode: "repeat",      imagePathScope: "workspace",      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. Het uitgewerkte voorbeeld hierboven gebruikt bewust dezelfde opdracht-, hervattings-, JSONL-, modelalias-, sessie-, afbeeldings- en watchdogvelden als de gebundelde google-gemini-cli-adapter:

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

Geavanceerde backendhooks

CliBackendPlugin kan ook het volgende definiëren:

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

prepareExecution(ctx) ontvangt ctx.contextTokenBudget, de effectieve tokenlimiet die voor de uitvoering is geselecteerd. Backends die native Compaction beheren, kunnen dat budget koppelen aan hun CLI-specifieke startcontract.

runtimeArtifact is eigendom van de plugin. Het wordt alleen geraadpleegd wanneer een live inferentiebeurt geverifieerde setupbevoegdheid aanmaakt of opnieuw valideert; normale CLI-uitvoeringen vereisen dit niet. Een backend zonder deze declaratie kan geen geverifieerde CLI-setupbevoegdheid aanmaken. Een declaratie van bundled-package-tree benoemt de exacte eigenaar van package.json en vereist dat het pakket-entrypoint de opdracht is. OpenClaw hasht de begrensde, volledige geïnstalleerde pakketstructuur, inclusief geneste afhankelijkheden, en sluit bij fouten af voor omleidende symbolische koppelingen, startprogramma's buiten het gedeclareerde pakket, declaraties van vereiste externe afhankelijkheden, te grote structuren en onbekende scripts. Declareer dit alleen wanneer die structuur de volledige inferentie-implementatie bevat; optionele toolintegraties maken een externe implementatiegraaf niet veilig.

Als dezelfde backend ook een zelfstandig native uitvoerbaar bestand levert, vermeld dan de canonieke basisnamen ervan in nativeExecutableNames. Andere native opdrachten blijven niet-geverifieerd.

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 het uitschakelen van native tools, sessiepersistentie of hervattingsgedrag voor BTW. Als een backend normaal nativeToolMode: "always-on" heeft, maar de argv voor nevenvragen die tools betrouwbaar uitschakelt, stel dan ook sideQuestionToolMode: "disabled" in; anders sluit OpenClaw bij fouten af wanneer BTW een CLI-uitvoering zonder tools vereist.

Stel nativeToolMode: "selectable" alleen in wanneer de backend elke backend-native tool voor een afzonderlijke uitvoering kan uitschakelen. Beperkte uitvoeringen ontvangen een canoniek contract: ctx.toolAvailability.native is de exacte backend-native lijst en ctx.toolAvailability.openClaw is de exacte lijst met OpenClaw-toolnamen. De host beperkt onafhankelijk de gegenereerde MCP-configuratie en toekenning tot die OpenClaw-lijst; plugins mogen deze niet in de kern vertalen of transportvoorvoegsels toevoegen.

Declareer hoe de backend dat contract afdwingt:

• toolAvailabilityEnforcement: "execution-args" vereist resolveExecutionArgs. De hook moet conflicterende toolvlaggen vervangen, aanpassingsmogelijkheden uitschakelen die buiten de geselecteerde tools kunnen worden uitgevoerd, en afdwingende argv retourneren voor zowel nieuwe als hervatte uitvoeringen.
• toolAvailabilityEnforcement: "prepare-execution" vereist prepareExecution. De hook moet een exact beleid per uitvoering klaarzetten en toolAvailabilityEnforced: true retourneren; ontbrekende bevestiging leidt tot afsluiten bij fouten en OpenClaw ruimt de klaargezette resources vóór het starten op.

Runtimebeperkingen zoals Cron toolsAllow worden door OpenClaw genormaliseerd en per groep uitgebreid voordat dit contract wordt opgebouwd. Native tools worden uitgeschakeld en een backend zonder een volledig gedeclareerd handhavingspad faalt vóór uitvoering.

Plugins die zijn gebouwd tegen v2026.7.2-beta.1 tot en met v2026.7.2-beta.3 kunnen nog steeds de verouderde projectie van transportnamen ctx.toolAvailability.mcp lezen en mogen toolAvailabilityEnforcement weglaten wanneer een selecteerbare backend resolveExecutionArgs implementeert. OpenClaw herkent dat uitgebrachte bètapad aan de vereiste openclaw.build.openclawVersion-metadata van het pluginpakket en behoudt het gedurende de 2026.8.x-reeks. Nieuwe en bijgewerkte plugins moeten canonieke ctx.toolAvailability.openClaw-namen gebruiken en toolAvailabilityEnforcement: "execution-args" expliciet declareren; het bètacompatibiliteitspad wordt na die periode verwijderd.

ownsNativeCompaction: afzien van OpenClaw Compaction

Als je backend een agent uitvoert die zijn eigen transcript comprimeert, stel dan ownsNativeCompaction: true in, zodat de beveiligende samenvatter van OpenClaw nooit op de sessies ervan wordt uitgevoerd: de CLI-Compaction-levenscyclus doet niets en de beurt gaat verder. claude-cli declareert dit omdat Claude Code intern comprimeert zonder harness-endpoint. Native harness-sessies zoals Codex blijven in plaats daarvan naar hun harness-Compaction-endpoint routeren.

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

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

MCP-toolbridge

CLI-backends ontvangen standaard geen OpenClaw-tools. Als de CLI een MCP-configuratie kan verwerken, meld je dan expliciet aan:

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

Ondersteunde bridgemodi:

Schakel de bridge alleen in wanneer de CLI deze daadwerkelijk kan verwerken. Als de CLI een eigen ingebouwde toollaag heeft die niet kan worden uitgeschakeld, stel dan nativeToolMode: "always-on" in, zodat OpenClaw bij fouten kan afsluiten wanneer een aanroeper geen native tools vereist. Als elke native tool per uitvoering kan worden uitgeschakeld, gebruik dan "selectable" met het bovenstaande resolveExecutionArgs-contract.

De backend selecteren

Gebruikers selecteren een zelfstandige backend via het modelrefvoorvoegsel ervan. Een backend die een canonieke modelProvider declareert, kan in plaats daarvan worden geselecteerd via de agentRuntime.id van dat providermodel. De adaptermechanica blijft in de plugin:

{  agents: {    defaults: {      model: {        primary: "openai/gpt-5.6-sol",        fallbacks: ["acme-cli/large"],      },    },  },}

Plaats aanmeldgegevens in OpenClaw-authenticatieprofielen of configuratie die eigendom is van de plugin. Zorg ervoor dat de geregistreerde opdracht zich in het PATH van de Gateway-service bevindt; implementaties die een ander pad of andere argv nodig hebben, moeten de pluginregistratie wijzigen of omwikkelen.

Verificatie

Voeg voor gebundelde plugins een gerichte test toe rond de builder en setupregistratie en voer daarna de gerichte testbaan van de plugin uit:

pnpm test extensions/acme-cli

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

openclaw plugins inspect acme-cli --runtime --jsonopenclaw agent --message "antwoord exact: 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 aantoont. Vertrouw niet op statische inspectie voor prompt-, afbeeldings-, MCP- of sessiehervattingsgedrag.

Controlelijst

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json heeft openclaw.extensions en gebouwde runtime-entrypoints voor gepubliceerde pakketten OPENCLAW_DOCS_MARKER:calloutClose:

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

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s setup.cliBackends is aanwezig wanneer setup/modeldetectie de backend koud moet kunnen zien 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 Het backendmodelvoorvoegsel of de modelgebonden agentRuntime.id selecteert de registratie OPENCLAW_DOCS_MARKER:calloutClose: