​

Backends CLI (runtime de repli)

• Les outils sont désactivés (aucun appel d’outil).
• Texte entrant → texte sortant (fiable).
• Les sessions sont prises en charge (les tours de suivi restent cohérents).
• Les images peuvent être transmises si la CLI accepte des chemins d’image.

​

Demarrage rapide pour debutants

openclaw agent --message "hi" --model claude-cli/opus-4.6

openclaw agent --message "hi" --model codex-cli/gpt-5.3-codex

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

​

L’utiliser comme repli

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

• Si vous utilisez agents.defaults.models (allowlist), vous devez inclure claude-cli/....
• Si le fournisseur principal échoue (authentification, limites de débit, délais), OpenClaw essaiera ensuite le backend CLI.

​

Vue d’ensemble de la configuration

agents.defaults.cliBackends

<provider>/<model>

​

Exemple de configuration

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          input: "arg",
          modelArg: "--model",
          modelAliases: {
            "claude-opus-4-6": "opus",
            "claude-opus-4-5": "opus",
            "claude-sonnet-4-5": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

​

Fonctionnement

1. Sélectionne un backend en fonction du préfixe de fournisseur (claude-cli/...).
2. Construit un prompt système en utilisant le même prompt OpenClaw + le contexte de l’espace de travail.
3. Exécute la CLI avec un identifiant de session (si pris en charge) afin que l’historique reste cohérent.
4. Analyse la sortie (JSON ou texte brut) et renvoie le texte final.
5. Conserve les identifiants de session par backend, afin que les suivis réutilisent la même session CLI.

​

Sessions

• Si la CLI prend en charge les sessions, définissez sessionArg (par ex. --session-id) ou sessionArgs (placeholder {sessionId}) lorsque l’identifiant doit être inséré dans plusieurs options.
• Si la CLI utilise une sous‑commande de reprise avec des options différentes, 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 (nouvel UUID s’il n’en existe pas).
  • existing : n’envoyer un identifiant de session que s’il a été stocké auparavant.
  • none : ne jamais envoyer d’identifiant de session.

​

Images (pass‑through)

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

​

Entrées / sorties

• output: "json" (par défaut) tente d’analyser le JSON et d’extraire le texte + l’identifiant de session.
• output: "jsonl" analyse des flux JSONL (Codex CLI --json) et extrait le dernier message de l’agent ainsi que thread_id lorsqu’il est présent.
• output: "text" traite stdout comme la réponse finale.

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

​

Par défaut (intégré)

• command: "claude"
• args: ["-p", "--output-format", "json", "--dangerously-skip-permissions"]
• resumeArgs: ["-p", "--output-format", "json", "--dangerously-skip-permissions", "--resume", "{sessionId}"]
• modelArg: "--model"
• systemPromptArg: "--append-system-prompt"
• sessionArg: "--session-id"
• systemPromptWhen: "first"
• sessionMode: "always"

• command: "codex"
• args: ["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]
• resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","read-only","--skip-git-repo-check"]
• output: "jsonl"
• resumeOutput: "text"
• modelArg: "--model"
• imageArg: "--image"
• sessionMode: "existing"

​

Limitations

• Aucun outil OpenClaw (le backend CLI ne reçoit jamais d’appels d’outils). Certaines CLI peuvent néanmoins exécuter leurs propres outils d’agent.
• Pas de streaming (la sortie de la CLI est collectée puis renvoyée).
• Les sorties structurées dépendent du format JSON de la CLI.
• Les sessions Codex CLI reprennent via une sortie texte (pas de JSONL), ce qui est moins structuré que l’exécution initiale --json. Les sessions OpenClaw fonctionnent néanmoins normalement.

​

Problemes courants

• CLI introuvable : définissez command vers un chemin complet.
• Nom de modèle incorrect : utilisez modelAliases pour mapper provider/model → modèle CLI.
• Pas de continuité de session : assurez‑vous que sessionArg est défini et que sessionMode n’est pas none (Codex CLI ne peut actuellement pas reprendre avec une sortie JSON).
• Images ignorées : définissez imageArg (et vérifiez que la CLI prend en charge les chemins de fichiers).