Creazione di Plugin per backend CLI

I plugin di backend CLI consentono a OpenClaw di chiamare una CLI di IA locale come backend di inferenza testuale. Il backend appare come prefisso del provider nei riferimenti ai modelli:

acme-cli/acme-large

Usa un backend CLI quando l'integrazione upstream è già esposta come comando locale, quando la CLI gestisce lo stato di accesso locale oppure come soluzione di ripiego quando i provider API non sono disponibili.

Responsabilità del plugin

Un plugin di backend CLI ha tre contratti:

Il manifesto contiene metadati di rilevamento: non esegue la CLI né registra il comportamento del runtime. Il comportamento del runtime inizia quando il punto di ingresso del plugin chiama api.registerCliBackend(...).

Plugin di backend minimo

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

Struttura della configurazione

CliBackendConfig descrive come OpenClaw deve avviare e analizzare la CLI:

Preferisci la configurazione statica più piccola che corrisponde alla CLI. Aggiungi callback al plugin solo per comportamenti che appartengono realmente al backend.

Hook avanzati del backend

CliBackendPlugin può inoltre definire:

Mantieni questi hook di proprietà del provider. Non aggiungere diramazioni specifiche della CLI al core quando un hook del backend può esprimere il comportamento.

runtimeArtifact appartiene al plugin e non può essere sovrascritto dall'utente. Viene consultato solo quando un'interazione di inferenza in tempo reale crea o riconvalida un'autorità verificata per la configurazione; le normali esecuzioni della CLI non lo richiedono. Un backend privo di questa dichiarazione non può creare un'autorità verificata per la configurazione della CLI. Una dichiarazione bundled-package-tree indica l'esatto proprietario di package.json e richiede che il punto di ingresso del pacchetto sia il comando. OpenClaw calcola l'hash dell'intero albero delimitato del pacchetto installato, incluse le dipendenze annidate, e interrompe l'operazione in modo sicuro in presenza di collegamenti simbolici di reindirizzamento, launcher esterni al pacchetto dichiarato, dichiarazioni di dipendenze esterne obbligatorie, alberi troppo grandi e script sconosciuti. Dichiara questa opzione solo quando tale albero contiene l'implementazione completa dell'inferenza; le integrazioni facoltative con strumenti non rendono sicuro un grafo di implementazione esterno.

Se lo stesso backend distribuisce anche un eseguibile nativo autonomo, elenca i relativi nomi di base canonici in nativeExecutableNames. Gli altri comandi nativi restano non verificati anche quando un utente sovrascrive il comando del backend.

ctx.executionMode è "agent" per i turni normali e "side-question" per le chiamate effimere /btw. Usalo quando la CLI richiede flag monouso diversi, ad esempio per disabilitare gli strumenti nativi, la persistenza della sessione o il comportamento di ripresa per BTW. Se un backend normalmente ha nativeToolMode: "always-on" ma i relativi argv per le domande secondarie disabilitano tali strumenti in modo affidabile, imposta anche sideQuestionToolMode: "disabled"; altrimenti OpenClaw applica una chiusura sicura quando BTW richiede un'esecuzione della CLI senza strumenti.

Imposta nativeToolMode: "selectable" solo quando resolveExecutionArgs può disabilitare ogni strumento nativo del backend per una singola esecuzione. Per queste esecuzioni con restrizioni, ctx.toolAvailability.native è una tupla vuota e ctx.toolAvailability.mcp è l'esatto elenco consentito MCP isolato dall'host. L'hook deve sostituire i flag degli strumenti in conflitto e restituire argv che applichi entrambi i valori; OpenClaw lo chiama una volta con l'argv finale di una nuova esecuzione o di una ripresa e applica una chiusura sicura quando il backend non può far rispettare la restrizione. I nomi MCP in questo contesto possono essere approvati automaticamente in sicurezza solo perché l'host ha già limitato la configurazione MCP generata a tali server e strumenti.

ownsNativeCompaction: disattivare la Compaction di OpenClaw

Se il tuo backend esegue un agente che compatta la propria trascrizione, imposta ownsNativeCompaction: true affinché il riepilogatore di salvaguardia di OpenClaw non venga mai eseguito sulle sue sessioni: il ciclo di vita della Compaction della CLI non esegue alcuna operazione e il turno procede. claude-cli lo dichiara perché Claude Code esegue internamente la Compaction senza un endpoint dell'harness. Le sessioni con harness nativo, come Codex, continuano invece a essere instradate al relativo endpoint di Compaction dell'harness.

Dichiaralo solo quando sono soddisfatte tutte le condizioni seguenti, altrimenti una sessione differita che supera il limite può rimanere oltre il limite o diventare obsoleta (OpenClaw non la recupera più):

• il backend compatta o limita in modo affidabile la propria trascrizione quando si avvicina al limite della finestra;
• mantiene una sessione ripristinabile affinché lo stato compattato persista tra i turni (ad esempio --resume / --session-id);
• non è una sessione di Compaction con harness nativo: le sessioni corrispondenti a agentHarnessId vengono invece instradate all'endpoint dell'harness.

Ponte per strumenti MCP

Per impostazione predefinita, i backend CLI non ricevono gli strumenti di OpenClaw. Se la CLI può utilizzare una configurazione MCP, abilitala esplicitamente:

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

Modalità del ponte supportate:

Abilita il ponte solo quando la CLI può effettivamente utilizzarlo. Se la CLI dispone di un proprio livello di strumenti integrato che non può essere disabilitato, imposta nativeToolMode: "always-on" affinché OpenClaw possa applicare una chiusura sicura quando un chiamante richiede l'assenza di strumenti nativi. Se può disabilitare tutti gli strumenti nativi per ogni esecuzione, usa "selectable" con il contratto resolveExecutionArgs descritto sopra.

Configurazione utente

Gli utenti possono sostituire qualsiasi valore predefinito del backend:

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

Documenta la sostituzione minima di cui gli utenti avranno probabilmente bisogno, in genere solo command quando il file binario si trova al di fuori di PATH.

Verifica

Per i plugin inclusi, aggiungi un test mirato per il builder e la registrazione della configurazione, quindi esegui il percorso di test mirato del plugin:

pnpm test extensions/acme-cli

Per i plugin locali o installati, verifica il rilevamento e un'esecuzione reale del modello:

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

Se il backend supporta immagini o MCP, aggiungi uno smoke test reale che dimostri tali percorsi con la CLI effettiva. Non affidarti all'ispezione statica per il comportamento relativo a prompt, immagini, MCP o ripresa della sessione.

Elenco di controllo

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json contiene openclaw.extensions e voci di runtime compilate per i pacchetti pubblicati OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json dichiara cliBackends e un valore intenzionale per activation.onStartup OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s setup.cliBackends è presente quando la configurazione o il rilevamento dei modelli devono individuare il backend prima dell'avvio OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s api.registerCliBackend(...) usa lo stesso ID del backend del manifesto OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Le sostituzioni dell'utente in agents.defaults.cliBackends.<id> continuano ad avere la precedenza OPENCLAW_DOCS_MARKER:calloutClose: