Vai al contenuto principale

​
Backend CLI (runtime di fallback)

OpenClaw può eseguire CLI AI locali come fallback solo testo quando i provider API non sono disponibili, soggetti a rate limit o temporaneamente malfunzionanti. Questo comportamento è intenzionalmente conservativo:
  • Gli strumenti OpenClaw non vengono iniettati direttamente, ma i backend con bundleMcp: true possono ricevere gli strumenti del gateway tramite un bridge MCP loopback.
  • Streaming JSONL per le CLI che lo supportano.
  • Le sessioni sono supportate (quindi i turni successivi restano coerenti).
  • Le immagini possono essere passate se la CLI accetta percorsi di immagini.
Questo è progettato come rete di sicurezza piuttosto che come percorso principale. Usalo quando vuoi risposte testuali “sempre funzionanti” senza dipendere da API esterne. Se vuoi un runtime harness completo con controlli di sessione ACP, attività in background, binding thread/conversazione e sessioni di coding esterne persistenti, usa ACP Agents invece. I backend CLI non sono ACP.

​
Guida rapida per principianti

Puoi usare Codex CLI senza alcuna configurazione (il plugin OpenAI incluso registra un backend predefinito): 
openclaw agent --message "hi" --model codex-cli/gpt-5.4
Se il tuo gateway viene eseguito sotto launchd/systemd e PATH è minimale, aggiungi solo il percorso del comando: 
{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
      },
    },
  },
}
È tutto. Nessuna chiave, nessuna configurazione di autenticazione aggiuntiva necessaria oltre alla CLI stessa. Se usi un backend CLI incluso come provider di messaggi principale su un host gateway, OpenClaw ora carica automaticamente il plugin incluso proprietario quando la tua configurazione fa riferimento esplicito a quel backend in un model ref o sotto agents.defaults.cliBackends.

​
Usarlo come fallback

Aggiungi un backend CLI al tuo elenco di fallback in modo che venga eseguito solo quando i modelli primari falliscono: 
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["codex-cli/gpt-5.4"],
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "codex-cli/gpt-5.4": {},
      },
    },
  },
}
Note:
  • Se usi agents.defaults.models (allowlist), devi includere anche lì i modelli del tuo backend CLI.
  • Se il provider primario fallisce (autenticazione, rate limit, timeout), OpenClaw proverà poi il backend CLI.

​
Panoramica della configurazione

Tutti i backend CLI si trovano sotto: 
agents.defaults.cliBackends
Ogni voce è indicizzata da un provider id (ad esempio codex-cli, my-cli). Il provider id diventa la parte sinistra del tuo model ref: 
<provider>/<model>

​
Esempio di configurazione

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "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",
          // Le CLI in stile Codex possono invece puntare a un file di prompt:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

​
Come funziona

  1. Seleziona un backend in base al prefisso del provider (codex-cli/...).
  2. Costruisce un system prompt usando lo stesso prompt OpenClaw + contesto workspace.
  3. Esegue la CLI con un id di sessione (se supportato) in modo che la cronologia resti coerente.
  4. Analizza l’output (JSON o testo semplice) e restituisce il testo finale.
  5. Mantiene gli id di sessione per backend, così i turni successivi riutilizzano la stessa sessione CLI.
Il backend incluso Anthropic claude-cli è di nuovo supportato. Lo staff Anthropic ci ha detto che l’uso di Claude CLI in stile OpenClaw è di nuovo consentito, quindi OpenClaw tratta l’uso di claude -p come autorizzato per questa integrazione, a meno che Anthropic non pubblichi una nuova policy.
Il backend incluso OpenAI codex-cli passa il system prompt di OpenClaw tramite l’override di configurazione model_instructions_file di Codex (-c model_instructions_file="..."). Codex non espone un flag in stile Claude --append-system-prompt, quindi OpenClaw scrive il prompt assemblato in un file temporaneo per ogni nuova sessione Codex CLI. Il backend incluso Anthropic claude-cli riceve lo snapshot delle Skills di OpenClaw in due modi: il catalogo compatto delle Skills OpenClaw nel system prompt aggiunto e un plugin Claude Code temporaneo passato con --plugin-dir. Il plugin contiene solo le Skills idonee per quell’agente/sessione, quindi il resolver nativo delle skill di Claude Code vede lo stesso insieme filtrato che OpenClaw altrimenti pubblicizzerebbe nel prompt. Gli override Skill env/API key vengono comunque applicati da OpenClaw all’ambiente del processo figlio per l’esecuzione.

​
Sessioni

  • Se la CLI supporta le sessioni, imposta sessionArg (ad esempio --session-id) o sessionArgs (segnaposto {sessionId}) quando l’ID deve essere inserito in più flag.
  • Se la CLI usa un sottocomando di ripresa con flag diversi, imposta resumeArgs (sostituisce args durante la ripresa) e opzionalmente resumeOutput (per riprese non JSON).
  • sessionMode:
    • always: invia sempre un id di sessione (nuovo UUID se non ne è memorizzato nessuno).
    • existing: invia un id di sessione solo se ne è stato memorizzato uno in precedenza.
    • none: non inviare mai un id di sessione.
Note sulla serializzazione:
  • serialize: true mantiene ordinate le esecuzioni sulla stessa corsia.
  • La maggior parte delle CLI serializza su una corsia di provider.
  • OpenClaw interrompe il riutilizzo della sessione CLI memorizzata quando cambia lo stato di autenticazione del backend, inclusi nuovo login, rotazione del token o credenziale del profilo di autenticazione modificata.

​
Immagini (pass-through)

Se la tua CLI accetta percorsi di immagini, imposta imageArg: 
imageArg: "--image",
imageMode: "repeat"
OpenClaw scriverà le immagini base64 in file temporanei. Se imageArg è impostato, tali percorsi vengono passati come argomenti della CLI. Se imageArg manca, OpenClaw aggiunge i percorsi dei file al prompt (path injection), il che è sufficiente per le CLI che caricano automaticamente i file locali a partire da semplici percorsi.

​
Input / output

  • output: "json" (predefinito) prova ad analizzare JSON ed estrarre testo + id sessione.
  • Per l’output JSON di Gemini CLI, OpenClaw legge il testo della risposta da response e l’utilizzo da stats quando usage è assente o vuoto.
  • output: "jsonl" analizza stream JSONL (ad esempio Codex CLI --json) ed estrae il messaggio finale dell’agente più gli identificatori di sessione quando presenti.
  • output: "text" tratta stdout come risposta finale.
Modalità di input:
  • input: "arg" (predefinito) passa il prompt come ultimo argomento della CLI.
  • input: "stdin" invia il prompt tramite stdin.
  • Se il prompt è molto lungo e maxPromptArgChars è impostato, viene usato stdin.

​
Predefiniti (plugin-owned)

Il plugin OpenAI incluso registra anche un valore predefinito per codex-cli:
  • command: "codex"
  • args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
  • resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
  • output: "jsonl"
  • resumeOutput: "text"
  • modelArg: "--model"
  • imageArg: "--image"
  • sessionMode: "existing"
Il plugin Google incluso registra anche un valore predefinito per google-gemini-cli:
  • command: "gemini"
  • args: ["--output-format", "json", "--prompt", "{prompt}"]
  • resumeArgs: ["--resume", "{sessionId}", "--output-format", "json", "--prompt", "{prompt}"]
  • imageArg: "@"
  • imagePathScope: "workspace"
  • modelArg: "--model"
  • sessionMode: "existing"
  • sessionIdFields: ["session_id", "sessionId"]
Prerequisito: la Gemini CLI locale deve essere installata e disponibile come gemini nel PATH (brew install gemini-cli oppure npm install -g @google/gemini-cli). Note sul JSON di Gemini CLI:
  • Il testo della risposta viene letto dal campo JSON response.
  • L’utilizzo usa stats come fallback quando usage è assente o vuoto.
  • stats.cached viene normalizzato in OpenClaw cacheRead.
  • Se stats.input manca, OpenClaw ricava i token di input da stats.input_tokens - stats.cached.
Esegui override solo se necessario (caso comune: percorso command assoluto).

​
Predefiniti di proprietà del plugin

I valori predefiniti del backend CLI ora fanno parte della superficie del plugin:
  • I plugin li registrano con api.registerCliBackend(...).
  • L’id del backend diventa il prefisso provider nei model ref.
  • La configurazione utente in agents.defaults.cliBackends.<id> continua a sovrascrivere il valore predefinito del plugin.
  • La pulizia della configurazione specifica del backend resta di proprietà del plugin tramite l’hook facoltativo normalizeConfig.
I plugin che hanno bisogno di piccoli shim di compatibilità prompt/messaggi possono dichiarare trasformazioni di testo bidirezionali senza sostituire un provider o un backend CLI: 
api.registerTextTransforms({
  input: [
    { from: /red basket/g, to: "blue basket" },
    { from: /paper ticket/g, to: "digital ticket" },
    { from: /left shelf/g, to: "right shelf" },
  ],
  output: [
    { from: /blue basket/g, to: "red basket" },
    { from: /digital ticket/g, to: "paper ticket" },
    { from: /right shelf/g, to: "left shelf" },
  ],
});
input riscrive il system prompt e il prompt utente passati alla CLI. output riscrive i delta in streaming dell’assistente e il testo finale analizzato prima che OpenClaw gestisca i propri marcatori di controllo e la consegna sul canale. Per le CLI che emettono JSONL compatibile con Claude Code stream-json, imposta jsonlDialect: "claude-stream-json" nella configurazione di quel backend.

​
Overlay MCP inclusi

I backend CLI non ricevono direttamente chiamate agli strumenti OpenClaw, ma un backend può scegliere di usare un overlay di configurazione MCP generato con bundleMcp: true. Comportamento incluso attuale:
  • claude-cli: file di configurazione MCP strict generato
  • codex-cli: override di configurazione inline per mcp_servers
  • google-gemini-cli: file di impostazioni di sistema Gemini generato
Quando bundle MCP è abilitato, OpenClaw:
  • avvia un server MCP HTTP loopback che espone gli strumenti del gateway al processo CLI
  • autentica il bridge con un token per sessione (OPENCLAW_MCP_TOKEN)
  • limita l’accesso agli strumenti al contesto corrente di sessione, account e canale
  • carica i server bundle-MCP abilitati per il workspace corrente
  • li unisce con qualsiasi configurazione/impostazione MCP esistente del backend
  • riscrive la configurazione di avvio usando la modalità di integrazione di proprietà del backend dall’estensione proprietaria
Se nessun server MCP è abilitato, OpenClaw inietta comunque una configurazione strict quando un backend sceglie bundle MCP, così le esecuzioni in background restano isolate.

​
Limitazioni

  • Nessuna chiamata diretta agli strumenti OpenClaw. OpenClaw non inietta chiamate agli strumenti nel protocollo del backend CLI. I backend vedono gli strumenti del gateway solo quando scelgono bundleMcp: true.
  • Lo streaming è specifico del backend. Alcuni backend trasmettono JSONL in streaming; altri accumulano fino all’uscita.
  • Gli output strutturati dipendono dal formato JSON della CLI.
  • Le sessioni di Codex CLI vengono riprese tramite output testuale (nessun JSONL), che è meno strutturato rispetto all’esecuzione iniziale --json. Le sessioni OpenClaw continuano comunque a funzionare normalmente.

​
Risoluzione dei problemi

  • CLI non trovata: imposta command su un percorso completo.
  • Nome modello errato: usa modelAliases per mappare provider/model → modello CLI.
  • Nessuna continuità di sessione: assicurati che sessionArg sia impostato e che sessionMode non sia none (Codex CLI attualmente non può riprendere con output JSON).
  • Immagini ignorate: imposta imageArg (e verifica che la CLI supporti i percorsi dei file).