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.

Se il servizio upstream espone una normale API HTTP per modelli, crea invece un plugin provider. Se il runtime upstream gestisce sessioni complete dell’agente, eventi degli strumenti, Compaction o lo stato delle attività in background, usa un harness per agenti.

Responsabilità del plugin

Un plugin di backend CLI ha tre contratti:

Contratto	File	Scopo
Punto di ingresso del pacchetto	`package.json`	Indica a OpenClaw il modulo runtime del plugin
Titolarità nel manifesto	`openclaw.plugin.json`	Dichiara l’ID del backend prima del caricamento del runtime
Registrazione nel runtime	`index.ts`	Chiama `api.registerCliBackend(...)` con i valori predefiniti del comando

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

Crea i metadati del pacchetto

package.json

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

I pacchetti pubblicati devono includere file runtime JavaScript compilati. Se il punto di ingresso del codice sorgente è ./src/index.ts, aggiungi openclaw.runtimeExtensions che faccia riferimento al corrispondente file JavaScript compilato. Consulta Punti di ingresso.

Dichiara la titolarità del backend

openclaw.plugin.json

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

cliBackends è l’elenco di titolarità del runtime; consente a OpenClaw di caricare automaticamente il plugin quando la configurazione o la selezione del modello menziona acme-cli/....setup.cliBackends è la superficie di configurazione basata prima di tutto sui descrittori. Aggiungila quando il rilevamento dei modelli, la procedura iniziale o lo stato devono riconoscere il backend senza caricare il runtime del plugin. Usa requiresRuntime: false solo quando questi descrittori statici sono sufficienti per la configurazione.

Registra il backend

index.ts

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

L’ID del backend deve corrispondere alla voce cliBackends del manifesto. La config registrata è solo quella predefinita; la configurazione utente in agents.defaults.cliBackends.acme-cli viene unita a essa durante l’esecuzione e ha la precedenza.

Struttura della configurazione

CliBackendConfig descrive come OpenClaw deve avviare e analizzare la CLI:

Campo	Uso
`command`	Nome del binario o percorso assoluto del comando
`args`	Argomenti argv di base per nuove esecuzioni
`resumeArgs`	Argomenti argv alternativi per sessioni riprese; supporta `{sessionId}`
`output` / `resumeOutput`	Analizzatore: `json`, `jsonl` o `text`
`jsonlDialect`	Dialetto degli eventi JSONL: `claude-stream-json` o `gemini-stream-json`
`liveSession`	Modalità di processo CLI di lunga durata (`claude-stdio`)
`input`	Trasporto del prompt: `arg` o `stdin`
`maxPromptArgChars`	Lunghezza massima del prompt per la modalità `arg` prima di ricorrere a stdin
`env` / `clearEnv`	Variabili d’ambiente aggiuntive da inserire o nomi da rimuovere prima dell’avvio
`modelArg`	Flag usato prima dell’ID del modello
`modelAliases`	Associa gli ID modello di OpenClaw agli ID nativi della CLI
`sessionArg` / `sessionArgs`	Modalità di passaggio dell’ID di sessione
`sessionMode`	`always`, `existing` o `none`
`sessionIdFields`	Campi JSON che OpenClaw legge dall’output della CLI
`systemPromptArg` / `systemPromptFileArg`	Trasporto del prompt di sistema
`systemPromptFileConfigArg` / `systemPromptFileConfigKey`	Trasporto dell’override di configurazione per un file del prompt di sistema, ad esempio `-c`
`systemPromptMode`	`append` o `replace`
`systemPromptWhen`	`first`, `always` o `never`
`imageArg` / `imageMode`	Flag del percorso immagine e modalità di passaggio di più immagini (`repeat` o `list`)
`imagePathScope`	Posizione dei file immagine preparati prima del passaggio: `temp` o `workspace`
`serialize`	Mantiene ordinate le esecuzioni dello stesso backend
`reseedFromRawTranscriptWhenUncompacted`	Abilita il reinserimento limitato della trascrizione grezza prima della Compaction per reimpostazioni sicure delle sessioni
`reliability.outputLimits`	Numero massimo di caratteri/righe JSONL grezzi conservati per una singola interazione CLI in tempo reale (backend con sessione attiva)
`reliability.watchdog`	Regolazione del timeout in assenza di output, separata per esecuzioni nuove e riprese

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:

Hook	Uso
`normalizeConfig(config, context)`	Riscrive la configurazione utente precedente dopo l’unione
`resolveExecutionArgs(ctx)`	Aggiunge flag specifici della richiesta, come l’intensità di ragionamento o l’isolamento delle domande secondarie
`prepareExecution(ctx)`	Crea ponti temporanei di autenticazione o configurazione prima dell’avvio
`transformSystemPrompt(ctx)`	Applica una trasformazione finale del prompt di sistema specifica della CLI
`textTransforms`	Sostituzioni bidirezionali di prompt/output
`defaultAuthProfileId`	Preferisce un profilo di autenticazione OpenClaw specifico
`authEpochMode`	Decide in che modo le modifiche all’autenticazione invalidano le sessioni CLI memorizzate
`nativeToolMode`	Dichiara se gli strumenti nativi sono assenti, sempre attivi o selezionabili dall’host
`sideQuestionToolMode`	Dichiara gli strumenti nativi disabilitati per le domande secondarie `/btw`
`bundleMcp` / `bundleMcpMode`	Abilita il ponte agli strumenti MCP tramite local loopback di OpenClaw
`ownsNativeCompaction`	Il backend gestisce la propria Compaction; OpenClaw la demanda
`runtimeArtifact`	Vincola un launcher di script al relativo albero completo del pacchetto incluso

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:

Modalità	Utilizzo
`claude-config-file`	CLI che accettano un file di configurazione MCP
`codex-config-overrides`	CLI che accettano sostituzioni della configurazione negli argv
`gemini-system-settings`	CLI che leggono le impostazioni MCP dalla directory di sistema delle impostazioni

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 --json
openclaw 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

package.json contiene openclaw.extensions e voci di runtime compilate per i pacchetti pubblicati

openclaw.plugin.json dichiara cliBackends e un valore intenzionale per activation.onStartup

setup.cliBackends è presente quando la configurazione o il rilevamento dei modelli devono individuare il backend prima dell’avvio

api.registerCliBackend(...) usa lo stesso ID del backend del manifesto

Le sostituzioni dell’utente in agents.defaults.cliBackends.<id> continuano ad avere la precedenza

Le impostazioni della sessione, del prompt di sistema, delle immagini e del parser dell’output corrispondono al contratto reale della CLI

I test mirati e almeno uno smoke test reale della CLI dimostrano il funzionamento del percorso del backend

Contenuti correlati

Backend CLI - configurazione utente e comportamento in fase di esecuzione
Creazione di plugin - nozioni di base su pacchetti e manifesti
Panoramica dell’SDK dei plugin - riferimento dell’API di registrazione
Manifesto del plugin - cliBackends e descrittori di configurazione
Harness dell’agente - runtime completi per agenti esterni

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Creazione di Plugin per backend CLI

Responsabilità del plugin

Plugin di backend minimo

Struttura della configurazione

Hook avanzati del backend

`ownsNativeCompaction`: disattivare la Compaction di OpenClaw

Ponte per strumenti MCP

Configurazione utente

Verifica

Elenco di controllo

Contenuti correlati

​Responsabilità del plugin

​Plugin di backend minimo

​Struttura della configurazione

​Hook avanzati del backend

​ownsNativeCompaction: disattivare la Compaction di OpenClaw

​Ponte per strumenti MCP

​Configurazione utente

​Verifica

​Elenco di controllo

​Contenuti correlati

Responsabilità del plugin

Plugin di backend minimo

Struttura della configurazione

Hook avanzati del backend

`ownsNativeCompaction`: disattivare la Compaction di OpenClaw

Ponte per strumenti MCP

Configurazione utente

Verifica

Elenco di controllo

Contenuti correlati