Gateway

Backend della CLI

OpenClaw può eseguire CLI AI locali come fallback solo testuale quando i provider API non funzionano, sono soggetti a limiti di frequenza o si comportano temporaneamente in modo anomalo. Questo è intenzionalmente conservativo:

Gli strumenti OpenClaw non vengono iniettati direttamente, ma i backend con bundleMcp: true possono ricevere 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 possono essere inoltrate se la CLI accetta percorsi di immagini.

Questo è progettato come una rete di sicurezza invece che come percorso principale. Usalo quando vuoi risposte testuali che "funzionano sempre" senza dipendere da API esterne.

Se vuoi un runtime harness completo con controlli di sessione ACP, attività in background, associazione thread/conversazione e sessioni di coding esterne persistenti, usa invece Agenti ACP. I backend CLI non sono ACP.

Avvio rapido 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.5

Se il tuo Gateway viene eseguito sotto launchd/systemd e PATH è minimo, aggiungi solo il percorso del comando:

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

Tutto qui. 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 esplicitamente a quel backend in un riferimento di modello 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 principali falliscono:

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

Note:

Se usi agents.defaults.models (allowlist), devi includere anche lì i modelli del tuo backend CLI.
Se il provider principale fallisce (autenticazione, limiti di frequenza, 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 ID provider (ad esempio codex-cli, my-cli). L'ID provider diventa il lato sinistro del riferimento del modello:

<provider>/<model>

Configurazione di esempio

{
  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",
          // For CLIs with a dedicated prompt-file flag:
          // systemPromptFileArg: "--system-file",
          // Codex-style CLIs can point at a prompt file instead:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

Come funziona

Seleziona un backend in base al prefisso del provider (codex-cli/...).
Costruisce un prompt di sistema usando lo stesso prompt OpenClaw + contesto dell'area di lavoro.
Esegue la CLI con un ID sessione (se supportato) in modo che la cronologia rimanga coerente. Il backend claude-cli incluso mantiene attivo un processo stdio Claude per ogni sessione OpenClaw e invia i turni successivi su stdin stream-json.
Analizza l'output (JSON o testo semplice) e restituisce il testo finale.
Mantiene gli ID sessione per backend, così i follow-up riutilizzano la stessa sessione CLI.

Il backend OpenAI codex-cli incluso passa il prompt di sistema 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 Anthropic claude-cli incluso riceve lo snapshot Skills di OpenClaw in due modi: il catalogo Skills OpenClaw compatto nel prompt di sistema aggiunto, e un Plugin Claude Code temporaneo passato con --plugin-dir. Il Plugin contiene solo le Skills idonee per quell'agente/sessione, quindi il risolutore di Skill nativo di Claude Code vede lo stesso insieme filtrato che OpenClaw pubblicizzerebbe altrimenti nel prompt. Gli override env/chiavi API delle Skill vengono comunque applicati da OpenClaw all' ambiente del processo figlio per l'esecuzione.

Claude CLI ha anche una propria modalità di autorizzazione non interattiva. OpenClaw la mappa alla policy exec esistente invece di aggiungere una configurazione specifica per Claude: quando la policy exec richiesta effettiva è YOLO (tools.exec.security: "full" e tools.exec.ask: "off"), OpenClaw aggiunge --permission-mode bypassPermissions. Le impostazioni per agente agents.list[].tools.exec sovrascrivono tools.exec globale per quell'agente. Per forzare una modalità Claude diversa, imposta argomenti backend raw espliciti come --permission-mode default o --permission-mode acceptEdits sotto agents.defaults.cliBackends.claude-cli.args e resumeArgs corrispondenti.

Il backend Anthropic claude-cli incluso mappa anche i livelli /think di OpenClaw al flag nativo --effort di Claude Code per i livelli diversi da off. minimal e low vengono mappati a low, adaptive e medium vengono mappati a medium, e high, xhigh e max vengono mappati direttamente. Gli altri backend CLI richiedono che il loro Plugin proprietario dichiari un mapper argv equivalente prima che /think possa influire sulla CLI generata.

Prima che OpenClaw possa usare il backend claude-cli incluso, Claude Code stesso deve già aver effettuato l'accesso sullo stesso host:

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

Usa agents.defaults.cliBackends.claude-cli.command solo quando il binario claude non è già in PATH.

Sessioni

Se la CLI supporta le sessioni, imposta sessionArg (ad esempio --session-id) o sessionArgs (placeholder {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 alla ripresa) e opzionalmente resumeOutput (per riprese non JSON).
sessionMode:
- always: invia sempre un ID sessione (nuovo UUID se non ne è memorizzato nessuno).
- existing: invia un ID sessione solo se ne era stato memorizzato uno in precedenza.
- none: non invia mai un ID sessione.
claude-cli usa per impostazione predefinita liveSession: "claude-stdio", output: "jsonl", e input: "stdin" così i turni successivi riutilizzano il processo Claude attivo mentre è attivo. Lo stdio caldo ora è il valore predefinito, anche per configurazioni personalizzate che omettono i campi di trasporto. Se il Gateway si riavvia o il processo inattivo termina, OpenClaw riprende dall'ID sessione Claude memorizzato. Gli ID sessione memorizzati vengono verificati rispetto a una trascrizione di progetto leggibile esistente prima della ripresa, quindi le associazioni fantasma vengono cancellate con reason=transcript-missing invece di avviare silenziosamente una nuova sessione Claude CLI sotto --resume.
Le sessioni live Claude mantengono guardrail limitati per l'output JSONL. I valori predefiniti consentono fino a 8 MiB e 20.000 righe JSONL raw per turno. I turni Claude con molti strumenti possono aumentarli per backend con agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars e maxTurnLines; OpenClaw limita queste impostazioni a 64 MiB e 100.000 righe.
Le sessioni CLI memorizzate sono continuità di proprietà del provider. Il reset giornaliero implicito della sessione non le interrompe; /reset e le policy session.reset esplicite continuano a farlo.

Note sulla serializzazione:

serialize: true mantiene ordinate le esecuzioni della stessa corsia.
La maggior parte delle CLI serializza su una corsia provider.
OpenClaw abbandona il riutilizzo della sessione CLI memorizzata quando cambia l'identità di autenticazione selezionata, inclusi un ID profilo di autenticazione modificato, una chiave API statica, un token statico o un'identità account OAuth quando la CLI ne espone una. La rotazione dei token di accesso e refresh OAuth non interrompe la sessione CLI memorizzata. Se una CLI non espone un ID account OAuth stabile, OpenClaw lascia che quella CLI applichi le autorizzazioni di ripresa.

Preludio di fallback dalle sessioni claude-cli

Quando un tentativo claude-cli passa per errore a un candidato non CLI in agents.defaults.model.fallbacks, OpenClaw inizializza il tentativo successivo con un preludio di contesto raccolto dalla trascrizione JSONL locale di Claude Code in ~/.claude/projects/. Senza questo seed, il provider di fallback partirebbe a freddo perché la trascrizione della sessione di OpenClaw è vuota per le esecuzioni claude-cli.

Il preludio preferisce il riepilogo /compact più recente o il marker compact_boundary, poi aggiunge i turni post-boundary più recenti fino a un budget di caratteri. I turni pre-boundary vengono scartati perché il riepilogo li rappresenta già.
I blocchi degli strumenti vengono coalesciuti in suggerimenti compatti (tool call: name) e (tool result: …) per mantenere onesto il budget del prompt. Il riepilogo è etichettato (truncated) se eccede.
I fallback dallo stesso provider claude-cli a claude-cli si affidano al --resume di Claude e saltano il preludio.
Il seed riutilizza la convalida esistente del percorso file di sessione Claude, quindi non è possibile leggere percorsi arbitrari.

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, quei percorsi vengono passati come argomenti CLI. Se imageArg manca, OpenClaw aggiunge i percorsi dei file al prompt (iniezione del percorso), il che è sufficiente per le CLI che caricano automaticamente file locali da percorsi in testo semplice.

Input / output

output: "json" (predefinito) tenta di 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 manca o è vuoto.
output: "jsonl" analizza stream JSONL (per 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 CLI.
input: "stdin" invia il prompt tramite stdin.
Se il prompt è molto lungo e maxPromptArgChars è impostato, viene usato stdin.

Impostazioni predefinite (di proprietà del Plugin)

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}","-c","sandbox_mode=\"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 in PATH (brew install gemini-cli o npm install -g @google/gemini-cli).

Note JSON su Gemini CLI:

Il testo della risposta viene letto dal campo JSON response.
L'utilizzo ripiega su stats quando usage è assente o vuoto.
stats.cached viene normalizzato in OpenClaw cacheRead.
Se stats.input manca, OpenClaw deriva i token di input da stats.input_tokens - stats.cached.

Sovrascrivi solo se necessario (caso comune: percorso assoluto di command).

Valori predefiniti gestiti dal Plugin

I valori predefiniti del backend CLI fanno ora parte della superficie del plugin:

I plugin li registrano con api.registerCliBackend(...).
L'id del backend diventa il prefisso del provider nei riferimenti dei modelli.
La configurazione utente in agents.defaults.cliBackends.<id> continua a sovrascrivere il valore predefinito del plugin.
La pulizia della configurazione specifica del backend resta gestita dal plugin tramite l'hook opzionale normalizeConfig.

I plugin che necessitano di piccoli adattatori di compatibilità per 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 prompt di sistema e il prompt utente passati alla CLI. output riscrive i delta dell'assistente in streaming e il testo finale analizzato prima che OpenClaw gestisca i propri marcatori di controllo e la consegna al 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 del bundle

I backend CLI non ricevono direttamente chiamate agli strumenti OpenClaw, ma un backend può aderire a un overlay di configurazione MCP generato con bundleMcp: true.

Comportamento attuale in bundle:

claude-cli: file di configurazione MCP rigoroso generato
codex-cli: sovrascritture di configurazione inline per mcp_servers; il server loopback OpenClaw generato è contrassegnato con la modalità di approvazione strumenti per server di Codex, così le chiamate MCP non possono bloccarsi sui prompt di approvazione locale
google-gemini-cli: file di impostazioni di sistema Gemini generato

Quando MCP del bundle è abilitato, OpenClaw:

avvia un server HTTP MCP 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 alla sessione, all'account e al contesto del canale correnti
carica i server bundle-MCP abilitati per l'area di lavoro corrente
li unisce con qualsiasi forma di configurazione/impostazioni MCP del backend esistente
riscrive la configurazione di avvio usando la modalità di integrazione gestita dal backend dall'estensione proprietaria

Se nessun server MCP è abilitato, OpenClaw inietta comunque una configurazione rigorosa quando un backend aderisce a MCP del bundle, così le esecuzioni in background restano isolate.

I runtime MCP in bundle con ambito di sessione vengono memorizzati nella cache per il riuso all'interno di una sessione, quindi rimossi dopo mcp.sessionIdleTtlMs millisecondi di inattività (valore predefinito 10 minuti; imposta 0 per disabilitare). Le esecuzioni incorporate una tantum, come sonde di autenticazione, generazione di slug e richiamo di active-memory, richiedono la pulizia a fine esecuzione, così i figli stdio e gli stream Streamable HTTP/SSE non sopravvivono all'esecuzione.

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 aderiscono a 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 Codex CLI riprendono tramite output testuale (senza JSONL), che è meno strutturato dell'esecuzione iniziale con --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).

Backend della CLI

Avvio rapido per principianti

Usarlo come fallback

Panoramica della configurazione

Configurazione di esempio

Come funziona

Sessioni

Preludio di fallback dalle sessioni claude-cli

Immagini (pass-through)

Input / output

Impostazioni predefinite (di proprietà del Plugin)

Valori predefiniti gestiti dal Plugin

Overlay MCP del bundle

Limitazioni

Risoluzione dei problemi

Correlati

Ask OpenClaw

# Avvio rapido per principianti

# Usarlo come fallback

# Panoramica della configurazione

# Configurazione di esempio

# Come funziona

# Sessioni

# Preludio di fallback dalle sessioni claude-cli

# Immagini (pass-through)

# Input / output

# Impostazioni predefinite (di proprietà del Plugin)

# Valori predefiniti gestiti dal Plugin

# Overlay MCP del bundle

# Limitazioni

# Risoluzione dei problemi

# Correlati

Avvio rapido per principianti

Usarlo come fallback

Panoramica della configurazione

Configurazione di esempio

Come funziona

Sessioni

Preludio di fallback dalle sessioni claude-cli

Immagini (pass-through)

Input / output

Impostazioni predefinite (di proprietà del Plugin)

Valori predefiniti gestiti dal Plugin

Overlay MCP del bundle

Limitazioni

Risoluzione dei problemi

Correlati