Backend CLI

• Gli strumenti OpenClaw non vengono inseriti direttamente, ma un backend con bundleMcp: true può ricevere gli strumenti del Gateway tramite un bridge MCP di loopback.
• Streaming JSONL per le CLI che lo supportano.
• Le sessioni sono supportate, quindi i turni successivi rimangono coerenti.
• Le immagini vengono trasmesse se la CLI accetta percorsi di immagini.

​

Avvio rapido

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

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

​

Utilizzo come soluzione di ripiego

{
  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": {},
      },
    },
  },
}

​

Configurazione

{
  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",
          // Flag dedicato per il file del prompt:
          // systemPromptFileArg: "--system-file",
          // In alternativa, flag di sostituzione della configurazione in stile Codex:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          // Abilitare solo se questo backend può reinizializzare le sessioni invalidate dalla
          // cronologia grezza e limitata della trascrizione OpenClaw prima della Compaction.
          reseedFromRawTranscriptWhenUncompacted: true,
          serialize: true,
        },
      },
    },
  },
}

​

Funzionamento

1. Seleziona un backend in base al prefisso del provider (claude-cli/...).
2. Crea un prompt di sistema usando lo stesso prompt OpenClaw e lo stesso contesto dello spazio di lavoro.
3. Esegue la CLI con un ID sessione, se supportato, affinché la cronologia rimanga coerente. Il backend claude-cli incluso mantiene attivo un processo stdio di Claude per ogni sessione OpenClaw e invia i turni successivi tramite stdin stream-json.
4. Analizza l’output, JSON o testo normale, e restituisce il testo finale.
5. Mantiene gli ID sessione per ciascun backend affinché i turni successivi riutilizzino la stessa sessione CLI.

​

Specificità della CLI Claude

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

​

Sessioni

• Se la CLI supporta le sessioni, impostare sessionArg, ad esempio --session-id, oppure sessionArgs, con il segnaposto {sessionId}, quando l’ID deve essere inserito in più flag.
• Se la CLI usa un sottocomando di ripresa con flag diversi, impostare resumeArgs, che sostituisce args durante la ripresa, e facoltativamente resumeOutput per le riprese non JSON.
• sessionMode:
  • always: invia sempre un ID sessione, generando un nuovo UUID se non ne è memorizzato alcuno.
  • existing: invia un ID sessione solo se ne era già stato memorizzato uno.
  • none: non invia mai un ID sessione.
• claude-cli usa come valori predefiniti liveSession: "claude-stdio", output: "jsonl" e input: "stdin", quindi i turni successivi riutilizzano il processo Claude attivo finché rimane in esecuzione, anche per le configurazioni personalizzate che omettono i campi di trasporto. Se il Gateway viene riavviato o il processo inattivo termina, OpenClaw riprende dall’ID sessione Claude memorizzato. Prima della ripresa, gli ID sessione memorizzati vengono verificati rispetto a una trascrizione di progetto leggibile; una trascrizione mancante elimina l’associazione, registrando reason=transcript-missing, anziché avviare silenziosamente una nuova sessione sotto --resume.
• Le sessioni Claude attive mantengono limiti controllati per l’output JSONL: per impostazione predefinita, 8 MiB e 20,000 righe JSONL grezze per turno. È possibile aumentarli per ciascun backend con agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars e maxTurnLines; OpenClaw limita tali impostazioni rispettivamente a 64 MiB e 100,000 righe.
• Le sessioni CLI memorizzate rappresentano una continuità di proprietà del provider. La reimpostazione giornaliera implicita della sessione non le interrompe; /reset e i criteri espliciti session.reset continuano invece a farlo.
• Le nuove sessioni CLI vengono normalmente reinizializzate soltanto dal riepilogo di Compaction di OpenClaw e dalla parte successiva alla Compaction. Per recuperare sessioni brevi invalidate prima della Compaction, un backend può abilitarlo con reseedFromRawTranscriptWhenUncompacted: true. La reinizializzazione dalla trascrizione grezza rimane limitata ed è consentita solo per invalidazioni sicure, come una trascrizione CLI mancante, una coda di utilizzo degli strumenti orfana, modifiche ai criteri dei messaggi, al prompt di sistema, alla directory di lavoro o a MCP oppure un nuovo tentativo dovuto alla scadenza della sessione; le modifiche al profilo di autenticazione o all’epoca delle credenziali non reinizializzano mai la cronologia grezza della trascrizione.

​

Preambolo di ripiego dalle sessioni claude-cli

• Il preambolo privilegia il riepilogo /compact o l’indicatore compact_boundary più recente, quindi aggiunge i turni più recenti successivi al limite fino a raggiungere un budget di caratteri. I turni precedenti al limite vengono eliminati perché il riepilogo li rappresenta già.
• I blocchi degli strumenti vengono raggruppati in indicazioni compatte (tool call: name) e (tool result: …) per rispettare il budget del prompt; un riepilogo troppo grande viene troncato ed etichettato (truncated).
• Le soluzioni di ripiego dello stesso provider da claude-cli a claude-cli si basano sul meccanismo --resume di Claude e omettono il preambolo.
• L’inizializzazione riutilizza la convalida esistente del percorso del file di sessione Claude, impedendo la lettura di percorsi arbitrari.

​

Immagini

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

​

Input e output

• output: "text", valore predefinito, considera stdout come risposta finale.
• output: "json" tenta di analizzare il JSON ed estrarre il testo insieme a un ID sessione.
• output: "jsonl" analizza un flusso JSONL ed estrae il messaggio finale dell’agente insieme agli identificatori di sessione, quando presenti.
• Per l’output JSON della CLI Gemini, OpenClaw legge il testo della risposta da response e l’utilizzo da stats quando usage è mancante o vuoto. Il valore predefinito della CLI Gemini inclusa usa stream-json; le vecchie sostituzioni --output-format json continuano a usare l’analizzatore JSON.

• input: "arg" (impostazione predefinita) passa il prompt come ultimo argomento della CLI.
• input: "stdin" invia il prompt tramite stdin.
• Se il prompt è molto lungo e maxPromptArgChars è impostato, viene invece usato stdin.

​

Impostazioni predefinite di proprietà del plugin

• I plugin le registrano con api.registerCliBackend(...).
• Il valore id del backend diventa il prefisso del provider nei riferimenti ai modelli.
• La configurazione utente in agents.defaults.cliBackends.<id> continua ad avere la precedenza sull’impostazione predefinita del plugin.
• La pulizia della configurazione specifica del backend resta di proprietà del plugin tramite l’hook facoltativo normalizeConfig.

• Il parser stream-json predefinito legge gli eventi message dell’assistente, gli eventi degli strumenti, l’utilizzo result finale e gli eventi di errore irreversibile di Gemini.
• Se gli argomenti di Gemini vengono sostituiti con --output-format json, OpenClaw normalizza nuovamente tale backend in output: "json" e legge il testo della risposta dal campo JSON response.
• L’utilizzo ripiega su stats quando usage è assente o vuoto; stats.cached viene normalizzato in cacheRead di OpenClaw e, se stats.input è assente, i token di input vengono ricavati da stats.input_tokens - stats.cached.

​

Overlay di trasformazione del testo

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

​

Proprietà della Compaction nativa

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

​

Overlay MCP inclusi

• claude-cli: file di configurazione MCP rigoroso generato.
• google-gemini-cli: file delle impostazioni di sistema di Gemini generato.

• avvia un server MCP HTTP di loopback che espone gli strumenti del Gateway al processo CLI, autenticato mediante una concessione di contesto per esecuzione (OPENCLAW_MCP_TOKEN) attiva solo per il tentativo di esecuzione corrente;
• vincola l’accesso agli strumenti alla sessione, all’account e al contesto del canale selezionati dal Gateway, anziché considerare attendibili le intestazioni del processo figlio;
• carica i server MCP inclusi abilitati per l’area di lavoro corrente e li unisce a qualsiasi configurazione o struttura di impostazioni MCP esistente del backend;
• riscrive la configurazione di avvio usando la modalità di integrazione del backend definita dal plugin proprietario.

​

Limite della cronologia di reinizializzazione

​

Limitazioni

• Nessuna chiamata diretta agli strumenti di OpenClaw: OpenClaw non inserisce chiamate agli strumenti nel protocollo del backend CLI. I backend vedono gli strumenti del Gateway solo quando scelgono di usare bundleMcp: true.
• Lo streaming dipende dal backend: alcuni backend trasmettono JSONL in streaming, altri accumulano i dati fino all’uscita.
• Gli output strutturati dipendono dal formato JSON della CLI.

​

Risoluzione dei problemi

​

Risorse correlate

• Manuale operativo del Gateway
• Modelli locali