Creazione di Plugin backend per CLI

I plugin backend CLI consentono a OpenClaw di chiamare una CLI AI locale come backend di inferenza testuale. Il backend appare come prefisso provider nei riferimenti modello:

acme-cli/acme-large

Usa un backend CLI quando l’integrazione upstream è già esposta come comando locale, quando la CLI gestisce lo stato di login locale, oppure quando la CLI è un fallback utile se i provider API non sono disponibili.

Se il servizio upstream espone una normale API modello HTTP, scrivi invece un plugin provider. Se il runtime upstream gestisce sessioni agente complete, eventi tool, compaction o stato di task in background, usa un agent harness.

Cosa gestisce il plugin

Un plugin backend CLI ha tre contratti:

Contratto	File	Scopo
Entry del package	`package.json`	Punta OpenClaw al modulo runtime del plugin
Proprietà manifest	`openclaw.plugin.json`	Dichiara l’id backend prima del caricamento del runtime
Registrazione runtime	`index.ts`	Chiama `api.registerCliBackend(...)` con i default comando

Il manifest è metadato di discovery. Non esegue la CLI e non registra comportamenti runtime. Il comportamento runtime inizia quando l’entry del plugin chiama api.registerCliBackend(...).

Plugin backend minimale

Crea i metadati del package

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 package pubblicati devono includere file runtime JavaScript compilati. Se la tua entry sorgente è ./src/index.ts, aggiungi openclaw.runtimeExtensions che punta al peer JavaScript compilato. Vedi Entry point.

Dichiara la proprietà 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 proprietà 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 setup descriptor-first. Aggiungila quando discovery dei modelli, onboarding o stato devono riconoscere il backend senza caricare il runtime del plugin. Usa requiresRuntime: false solo quando quei descrittori statici sono sufficienti per il setup.

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 backend deve corrispondere alla voce cliBackends del manifest. La config registrata è solo il default; la configurazione utente sotto agents.defaults.cliBackends.acme-cli viene unita sopra di essa a runtime.

Forma della configurazione

CliBackendConfig descrive come OpenClaw deve avviare e analizzare la CLI:

Campo	Uso
`command`	Nome binario o percorso comando assoluto
`args`	Argv base per esecuzioni nuove
`resumeArgs`	Argv alternativo per sessioni riprese; supporta `{sessionId}`
`output` / `resumeOutput`	Parser: `json`, `jsonl` o `text`
`input`	Trasporto prompt: `arg` o `stdin`
`modelArg`	Flag usato prima dell’id modello
`modelAliases`	Mappa gli id modello OpenClaw agli id nativi della CLI
`sessionArg` / `sessionArgs`	Come passare un id sessione
`sessionMode`	`always`, `existing` o `none`
`sessionIdFields`	Campi JSON che OpenClaw legge dall’output della CLI
`systemPromptArg` / `systemPromptFileArg`	Trasporto del prompt di sistema
`systemPromptWhen`	`first`, `always` o `never`
`imageArg` / `imageMode`	Supporto percorso immagine
`serialize`	Mantiene ordinate le esecuzioni dello stesso backend
`reliability.watchdog`	Regolazione timeout senza output

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

Hook backend avanzati

CliBackendPlugin può anche definire:

Hook	Uso
`normalizeConfig(config, context)`	Riscrive la configurazione utente legacy dopo il merge
`resolveExecutionArgs(ctx)`	Aggiunge flag con ambito richiesta come il thinking effort
`prepareExecution(ctx)`	Crea bridge temporanei di auth o configurazione prima dell’avvio
`transformSystemPrompt(ctx)`	Applica una trasformazione finale del prompt di sistema specifica della CLI
`textTransforms`	Sostituzioni bidirezionali prompt/output
`defaultAuthProfileId`	Preferisce un profilo auth OpenClaw specifico
`authEpochMode`	Decide come le modifiche auth invalidano le sessioni CLI archiviate
`nativeToolMode`	Dichiara se la CLI ha strumenti nativi sempre attivi
`bundleMcp` / `bundleMcpMode`	Abilita il bridge tool MCP loopback di OpenClaw

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

Bridge tool MCP

I backend CLI non ricevono i tool OpenClaw per impostazione predefinita. Se la CLI può consumare una configurazione MCP, abilitala esplicitamente:

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

Le modalità bridge supportate sono:

Modalità	Uso
`claude-config-file`	CLI che accettano un file di configurazione MCP
`codex-config-overrides`	CLI che accettano override di configurazione su argv
`gemini-system-settings`	CLI che leggono impostazioni MCP dalla propria directory impostazioni di sistema

Abilita il bridge solo quando la CLI può effettivamente consumarlo. Se la CLI ha un proprio layer tool integrato che non può essere disabilitato, imposta nativeToolMode: "always-on" così OpenClaw può fallire chiuso quando un chiamante richiede nessun tool nativo.

Configurazione utente

Gli utenti possono sovrascrivere qualsiasi default 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.5",
        fallbacks: ["acme-cli/large"],
      },
    },
  },
}

Documenta l’override minimo di cui gli utenti avranno probabilmente bisogno. Di solito è solo command quando il binario è fuori da PATH.

Verifica

Per i plugin bundled, aggiungi un test mirato intorno al builder e alla registrazione setup, quindi esegui la lane di test mirata del plugin:

pnpm test extensions/acme-cli

Per plugin locali o installati, verifica discovery 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 live che provi quei percorsi con la CLI reale. Non affidarti all’ispezione statica per prompt, immagine, MCP o comportamento di ripresa sessione.

Checklist

package.json ha openclaw.extensions e entry runtime compilate per i package pubblicati

openclaw.plugin.json dichiara cliBackends e activation.onStartup intenzionale

setup.cliBackends è presente quando setup/discovery dei modelli deve vedere il backend a freddo

api.registerCliBackend(...) usa lo stesso id backend del manifest

Gli override utente sotto agents.defaults.cliBackends.<id> continuano a prevalere

Le impostazioni sessione, prompt di sistema, immagine e parser output corrispondono al contratto reale della CLI

Test mirati e almeno uno smoke CLI live provano il percorso backend

Correlati

Backend CLI - configurazione utente e comportamento runtime
Creare plugin - basi di package e manifest
Panoramica del Plugin SDK - riferimento API di registrazione
Manifest del plugin - cliBackends e descrittori setup
Agent harness - runtime agente esterni completi

Documentation Index

​Cosa gestisce il plugin

​Plugin backend minimale

​Forma della configurazione

​Hook backend avanzati

​Bridge tool MCP

​Configurazione utente

​Verifica

​Checklist

​Correlati

Cosa gestisce il plugin

Plugin backend minimale

Forma della configurazione

Hook backend avanzati

Bridge tool MCP

Configurazione utente

Verifica

Checklist

Correlati