Création de Plugins backend CLI

Les plugins de backend CLI permettent à OpenClaw d’appeler une CLI d’IA locale comme backend d’inférence textuelle. Le backend apparaît comme un préfixe de fournisseur dans les références de modèle :

acme-cli/acme-large

Utilisez un backend CLI lorsque l’intégration amont est déjà exposée comme une commande locale, lorsque la CLI possède l’état de connexion local, ou lorsque la CLI constitue une solution de repli utile si les fournisseurs d’API sont indisponibles.

# Ce que possède le plugin

Un plugin de backend CLI a trois contrats :

Le manifeste est une métadonnée de découverte. Il n’exécute pas la CLI et n’enregistre pas le comportement runtime. Le comportement runtime commence lorsque le point d’entrée du plugin appelle api.registerCliBackend(...).

# Plugin de backend minimal

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

# Forme de la configuration

CliBackendConfig décrit comment OpenClaw doit lancer et analyser la CLI :

Préférez la plus petite configuration statique qui correspond à la CLI. Ajoutez des callbacks de plugin uniquement pour les comportements qui appartiennent réellement au backend.

# Hooks de backend avancés

CliBackendPlugin peut aussi définir :

Gardez ces hooks sous la responsabilité du fournisseur. N’ajoutez pas de branches propres à la CLI dans le cœur lorsqu’un hook de backend peut exprimer le comportement.

# Pont d’outils MCP

Les backends CLI ne reçoivent pas les outils OpenClaw par défaut. Si la CLI peut consommer une configuration MCP, inscrivez-la explicitement :

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

Les modes de pont pris en charge sont :

Activez le pont uniquement lorsque la CLI peut réellement le consommer. Si la CLI possède sa propre couche d’outils intégrée qui ne peut pas être désactivée, définissez nativeToolMode: "always-on" afin qu’OpenClaw puisse échouer de manière fermée lorsqu’un appelant exige l’absence d’outils natifs.

# Configuration utilisateur

Les utilisateurs peuvent remplacer toute valeur par défaut du 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"],
      },
    },
  },
}

Documentez le remplacement minimal dont les utilisateurs sont susceptibles d’avoir besoin. En général, il s’agit seulement de command lorsque le binaire se trouve hors de PATH.

# Vérification

Pour les plugins intégrés, ajoutez un test ciblé autour du générateur et de l’enregistrement de configuration, puis exécutez la voie de test ciblée du plugin :

pnpm test extensions/acme-cli

Pour les plugins locaux ou installés, vérifiez la découverte et une exécution de modèle réelle :

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

Si le backend prend en charge les images ou MCP, ajoutez un smoke test live qui prouve ces chemins avec la vraie CLI. Ne vous fiez pas à l’inspection statique pour les comportements de prompt, d’image, de MCP ou de reprise de session.

# Checklist

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json possède openclaw.extensions et des entrées runtime compilées pour les paquets publiés OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json déclare cliBackends et un activation.onStartup intentionnel OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s setup.cliBackends est présent lorsque la configuration/découverte de modèle doit voir le backend à froid OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s api.registerCliBackend(...) utilise le même id de backend que le manifeste OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Les remplacements utilisateur sous agents.defaults.cliBackends.<id> gagnent toujours OPENCLAW_DOCS_MARKER:calloutClose: