Backends CLI

• Les outils OpenClaw ne sont pas injectés directement, mais un backend doté de bundleMcp: true peut recevoir les outils du Gateway par l’intermédiaire d’un pont MCP en boucle locale.
• Diffusion JSONL pour les CLI qui la prennent en charge.
• Les sessions sont prises en charge, afin que les échanges suivants restent cohérents.
• Les images sont transmises si la CLI accepte les chemins d’images.

​

Démarrage rapide

openclaw agent --agent main --message "hi" --model claude-cli/claude-sonnet-4-6

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
      },
    },
  },
}

​

Utilisation comme solution de secours

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["claude-cli/claude-sonnet-4-6"],
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "claude-cli/claude-sonnet-4-6": {},
      },
    },
  },
}

​

Configuration

{
  agents: {
    defaults: {
      cliBackends: {
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          input: "arg",
          modelArg: "--model",
          modelAliases: {
            "claude-opus-4-6": "opus",
            "claude-sonnet-4-6": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          // Indicateur dédié au fichier d’invite :
          // systemPromptFileArg: "--system-file",
          // Ou indicateur de remplacement de configuration de style Codex :
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          // Activez cette option uniquement si ce backend peut réinitialiser les sessions invalidées à partir
          // de l’historique brut et limité de la transcription OpenClaw avant la Compaction.
          reseedFromRawTranscriptWhenUncompacted: true,
          serialize: true,
        },
      },
    },
  },
}

​

Fonctionnement

1. Sélectionne un backend selon le préfixe du fournisseur (claude-cli/...).
2. Construit une invite système à l’aide de la même invite OpenClaw et du même contexte d’espace de travail.
3. Exécute la CLI avec un identifiant de session (si cette fonctionnalité est prise en charge) afin que l’historique reste cohérent. Le backend claude-cli intégré maintient un processus stdio Claude actif pour chaque session OpenClaw et envoie les échanges suivants via l’entrée standard stream-json.
4. Analyse la sortie (JSON ou texte brut) et renvoie le texte final.
5. Conserve les identifiants de session pour chaque backend afin que les échanges suivants réutilisent la même session CLI.

​

Particularités de la CLI Claude

claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

​

Sessions

• Si la CLI prend en charge les sessions, définissez sessionArg (par exemple --session-id), ou sessionArgs (espace réservé {sessionId}) lorsque l’identifiant doit être inséré dans plusieurs indicateurs.
• Si la CLI utilise une sous-commande de reprise avec des indicateurs différents, définissez resumeArgs (remplace args lors de la reprise) et, éventuellement, resumeOutput pour les reprises non JSON.
• sessionMode :
  • always : toujours envoyer un identifiant de session (un nouvel UUID si aucun n’est enregistré).
  • existing : envoyer un identifiant de session uniquement si un identifiant a déjà été enregistré.
  • none : ne jamais envoyer d’identifiant de session.
• claude-cli utilise par défaut liveSession: "claude-stdio", output: "jsonl" et input: "stdin", afin que les échanges suivants réutilisent le processus Claude actif tant qu’il est disponible, y compris avec les configurations personnalisées qui omettent les champs de transport. Si le Gateway redémarre ou si le processus inactif se termine, OpenClaw reprend à partir de l’identifiant de session Claude enregistré. Avant la reprise, les identifiants de session enregistrés sont vérifiés par rapport à une transcription de projet lisible ; si la transcription est absente, la liaison est supprimée (avec une journalisation sous reason=transcript-missing) au lieu de démarrer silencieusement une nouvelle session sous --resume.
• Les sessions Claude actives conservent des limites de sécurité pour la sortie JSONL : 8 Mio et 20,000 lignes JSONL brutes par échange par défaut. Augmentez-les pour chaque backend avec agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars et maxTurnLines ; OpenClaw plafonne ces paramètres à 64 Mio et 100,000 lignes.
• Les sessions CLI enregistrées assurent une continuité appartenant au fournisseur. La réinitialisation quotidienne implicite de la session ne les interrompt pas ; les politiques /reset et session.reset explicites continuent de le faire.
• Les nouvelles sessions CLI ne sont normalement réinitialisées qu’à partir du résumé de Compaction d’OpenClaw et de la partie qui suit la Compaction. Pour récupérer de courtes sessions invalidées avant la Compaction, un backend peut activer reseedFromRawTranscriptWhenUncompacted: true. La réinitialisation à partir de la transcription brute reste limitée en taille et aux invalidations sûres, telles qu’une transcription CLI manquante, une fin d’utilisation d’outil orpheline, des changements de politique de messages, d’invite système, de répertoire de travail ou de MCP, ou une nouvelle tentative après expiration de la session ; les changements de profil d’authentification ou d’époque des identifiants ne réinitialisent jamais l’historique de transcription brute.

​

Préambule de secours issu des sessions claude-cli

• Le préambule privilégie le résumé /compact ou le marqueur compact_boundary le plus récent, puis ajoute les échanges les plus récents suivant cette limite, jusqu’à atteindre un budget de caractères. Les échanges antérieurs à cette limite sont supprimés, car le résumé les représente déjà.
• Les blocs d’outils sont regroupés sous forme d’indications (tool call: name) et (tool result: …) compactes afin de préserver l’exactitude du budget de l’invite ; un résumé trop volumineux est tronqué et marqué (truncated).
• Les basculements du même fournisseur de claude-cli vers claude-cli s’appuient sur le mécanisme --resume propre à Claude et ignorent le préambule.
• L’initialisation réutilise la validation existante du chemin du fichier de session Claude, ce qui empêche la lecture de chemins arbitraires.

​

Images

imageArg: "--image",
imageMode: "repeat"

​

Entrées et sorties

• output: "text" (par défaut) traite la sortie standard comme réponse finale.
• output: "json" tente d’analyser le JSON et d’en extraire le texte ainsi qu’un identifiant de session.
• output: "jsonl" analyse un flux JSONL et en extrait le message final de l’agent ainsi que les identifiants de session lorsqu’ils sont présents.
• Pour la sortie JSON de la CLI Gemini, OpenClaw lit le texte de la réponse depuis response et les données d’utilisation depuis stats lorsque usage est absent ou vide. La configuration intégrée par défaut de la CLI Gemini utilise stream-json ; les anciens remplacements --output-format json continuent d’utiliser l’analyseur JSON.

• input: "arg" (par défaut) transmet le prompt comme dernier argument de la CLI.
• input: "stdin" envoie le prompt via l’entrée standard.
• Si le prompt est très long et que maxPromptArgChars est défini, l’entrée standard est utilisée à la place.

​

Valeurs par défaut détenues par les plugins

• Les plugins les enregistrent avec api.registerCliBackend(...).
• Le id du backend devient le préfixe du fournisseur dans les références de modèles.
• La configuration utilisateur dans agents.defaults.cliBackends.<id> remplace toujours la valeur par défaut du plugin.
• Le nettoyage de la configuration propre au backend reste sous la responsabilité du plugin grâce au hook facultatif normalizeConfig.

• L’analyseur stream-json par défaut lit les événements message de l’assistant, les événements d’outils, l’utilisation result finale et les événements d’erreur fatale de Gemini.
• Si vous remplacez les arguments de Gemini par --output-format json, OpenClaw normalise à nouveau ce backend vers output: "json" et lit le texte de la réponse dans le champ JSON response.
• L’utilisation se rabat sur stats lorsque usage est absent ou vide ; stats.cached est normalisé en cacheRead d’OpenClaw et, si stats.input est manquant, les jetons d’entrée sont dérivés de stats.input_tokens - stats.cached.

​

Surcouches de transformation de texte

api.registerTextTransforms({
  input: [{ from: /red basket/g, to: "blue basket" }],
  output: [{ from: /blue basket/g, to: "red basket" }],
});

​

Responsabilité de la compaction native

api.registerCliBackend({ id: "my-cli", ownsNativeCompaction: true /* ... */ });

​

Surcouches MCP du bundle

• claude-cli : fichier de configuration MCP strict généré.
• google-gemini-cli : fichier de paramètres système Gemini généré.

• lance un serveur MCP HTTP en boucle locale qui expose les outils du Gateway au processus CLI, authentifié par une autorisation de contexte propre à l’exécution (OPENCLAW_MCP_TOKEN), active uniquement pour la tentative d’exécution en cours ;
• lie l’accès aux outils au contexte de session, de compte et de canal sélectionné par le Gateway au lieu de faire confiance aux en-têtes du processus enfant ;
• charge les serveurs MCP du bundle activés pour l’espace de travail actuel et les fusionne avec toute structure de configuration ou de paramètres MCP existante du backend ;
• réécrit la configuration de lancement à l’aide du mode d’intégration détenu par le backend dans le plugin responsable.

​

Limite de l’historique de réamorçage

​

Limites

• Aucun appel direct aux outils OpenClaw : OpenClaw n’injecte pas d’appels d’outils dans le protocole du backend CLI. Les backends ne voient les outils du Gateway que lorsqu’ils choisissent d’utiliser bundleMcp: true.
• La diffusion en continu dépend du backend : certains backends diffusent du JSONL, tandis que d’autres mettent les données en mémoire tampon jusqu’à la fin du processus.
• Les sorties structurées dépendent du propre format JSON de la CLI.

​

Dépannage

​

Voir aussi

• Guide d’exploitation du Gateway
• Modèles locaux