CLI-backends

• OpenClaw-tools worden niet rechtstreeks geïnjecteerd, maar backends met bundleMcp: true kunnen Gateway-tools ontvangen via een loopback-MCP-brug.
• JSONL-streaming voor CLI’s die dit ondersteunen.
• Sessies worden ondersteund (zodat vervolgroundes coherent blijven).
• Afbeeldingen kunnen worden doorgegeven als de CLI afbeeldingspaden accepteert.

​

Beginnersvriendelijke snelstart

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

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

​

Gebruiken als fallback

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

• Als je agents.defaults.models (allowlist) gebruikt, moet je daar ook je CLI-backendmodellen opnemen.
• Als de primaire provider faalt (auth, rate limits, time-outs), probeert OpenClaw daarna de CLI-backend.

​

Configuratieoverzicht

agents.defaults.cliBackends

<provider>/<model>

​

Voorbeeldconfiguratie

{
  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",
          // 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",
          // Opt in only if this backend may reseed safe invalidated sessions
          // from bounded raw OpenClaw transcript history before compaction.
          reseedFromRawTranscriptWhenUncompacted: true,
          serialize: true,
        },
      },
    },
  },
}

​

Hoe het werkt

1. Selecteert een backend op basis van de providerprefix (claude-cli/...).
2. Bouwt een systeemprompt met dezelfde OpenClaw-prompt en workspace-context.
3. Voert de CLI uit met een sessie-id (indien ondersteund), zodat de geschiedenis consistent blijft. De gebundelde claude-cli-backend houdt per OpenClaw-sessie een Claude-stdio-proces actief en stuurt vervolgroundes via stream-json-stdin.
4. Parset uitvoer (JSON of platte tekst) en retourneert de uiteindelijke tekst.
5. Bewaart sessie-id’s per backend, zodat vervolgrondes dezelfde CLI-sessie hergebruiken.

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

​

Sessies

• Als de CLI sessies ondersteunt, stel dan sessionArg (bijv. --session-id) of sessionArgs (placeholder {sessionId}) in wanneer de ID in meerdere vlaggen moet worden ingevoegd.
• Als de CLI een resume-subopdracht met andere vlaggen gebruikt, stel dan resumeArgs in (vervangt args bij hervatten) en optioneel resumeOutput (voor niet-JSON-hervattingen).
• sessionMode:
  • always: stuur altijd een sessie-id (nieuwe UUID als er geen is opgeslagen).
  • existing: stuur alleen een sessie-id als er eerder een is opgeslagen.
  • none: stuur nooit een sessie-id.
• claude-cli gebruikt standaard liveSession: "claude-stdio", output: "jsonl", en input: "stdin", zodat vervolgrondes het live Claude-proces hergebruiken zolang het actief is. Warme stdio is nu de standaard, ook voor aangepaste configuraties die transportvelden weglaten. Als de Gateway opnieuw start of het idle proces afsluit, hervat OpenClaw vanaf de opgeslagen Claude-sessie-id. Opgeslagen sessie- id’s worden gecontroleerd tegen een bestaand leesbaar projecttranscript voordat wordt hervat, zodat fantoomkoppelingen worden gewist met reason=transcript-missing in plaats van stilzwijgend een nieuwe Claude CLI-sessie te starten onder --resume.
• Live Claude-sessies behouden begrensde JSONL-uitvoerbewaking. Standaarden staan tot 8 MiB en 20.000 ruwe JSONL-regels per ronde toe. Tool-intensieve Claude-rondes kunnen deze per backend verhogen met agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars en maxTurnLines; OpenClaw begrenst die instellingen op 64 MiB en 100.000 regels.
• Opgeslagen CLI-sessies zijn provider-eigendom voor continuïteit. De impliciete dagelijkse sessie- reset onderbreekt ze niet; /reset en expliciete session.reset-beleidsregels doen dat nog steeds wel.
• Nieuwe CLI-sessies worden normaal alleen opnieuw gevoed vanuit OpenClaw’s Compaction-samenvatting plus de staart na Compaction. Om korte sessies te herstellen die ongeldig worden vóór Compaction, kan een backend zich aanmelden met reseedFromRawTranscriptWhenUncompacted: true. OpenClaw houdt het opnieuw voeden uit ruwe transcripties nog steeds begrensd en beperkt het tot veilige ongeldigverklaringen, zoals ontbrekende CLI-transcripties, wijzigingen in systeemprompt/MCP of een retry na verlopen sessie; wijzigingen in authprofiel of credential-epoch voeden nooit ruwe transcriptgeschiedenis opnieuw.

• serialize: true houdt runs in dezelfde lane op volgorde.
• De meeste CLI’s serialiseren op één providerlane.
• OpenClaw laat hergebruik van opgeslagen CLI-sessies vallen wanneer de geselecteerde auth-identiteit verandert, inclusief een gewijzigde authprofiel-id, statische API-sleutel, statisch token of OAuth- accountidentiteit wanneer de CLI er een blootlegt. Rotatie van OAuth-toegangs- en refresh-tokens onderbreekt de opgeslagen CLI-sessie niet. Als een CLI geen stabiele OAuth-account-id blootlegt, laat OpenClaw die CLI de hervatpermissies afdwingen.

​

Fallback-prelude uit claude-cli-sessies

• De prelude geeft de voorkeur aan de nieuwste /compact-samenvatting of compact_boundary- marker en voegt daarna de meest recente rondes na de grens toe tot aan een teken- budget. Rondes van vóór de grens worden weggelaten omdat de samenvatting ze al vertegenwoordigt.
• Toolblokken worden samengevoegd tot compacte (tool call: name)- en (tool result: …)-hints om het promptbudget eerlijk te houden. De samenvatting wordt gelabeld als (truncated) als deze overloopt.
• Fallbacks van dezelfde provider van claude-cli naar claude-cli vertrouwen op Claude’s eigen --resume en slaan de prelude over.
• De seed hergebruikt de bestaande validatie van het Claude-sessiebestandspad, zodat willekeurige paden niet kunnen worden gelezen.

​

Afbeeldingen (doorgeven)

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

​

Invoer / uitvoer

• output: "json" (standaard) probeert JSON te parsen en tekst plus sessie-id te extraheren.
• Voor Gemini CLI-JSON-uitvoer leest OpenClaw antwoordtekst uit response en gebruik uit stats wanneer usage ontbreekt of leeg is. De gebundelde Gemini CLI-standaard gebruikt stream-json, maar oude --output-format json-overrides gebruiken nog steeds de JSON-parser.
• output: "jsonl" parset JSONL-streams en extraheert het uiteindelijke agentbericht plus sessie- identifiers wanneer aanwezig.
• output: "text" behandelt stdout als het uiteindelijke antwoord.

• input: "arg" (standaard) geeft de prompt door als het laatste CLI-argument.
• input: "stdin" verzendt de prompt via stdin.
• Als de prompt erg lang is en maxPromptArgChars is ingesteld, wordt stdin gebruikt.

​

Standaardwaarden (eigendom van de plugin)

• command: "claude"
• args: ["-p","--output-format","stream-json","--include-partial-messages","--verbose", ...]
• output: "jsonl"
• input: "stdin"
• modelArg: "--model"
• sessionMode: "always"

• command: "gemini"
• args: ["--skip-trust", "--approval-mode", "auto_edit", "--output-format", "stream-json", "--prompt", "{prompt}"]
• resumeArgs: ["--skip-trust", "--approval-mode", "auto_edit", "--resume", "{sessionId}", "--output-format", "stream-json", "--prompt", "{prompt}"]
• output: "jsonl"
• resumeOutput: "jsonl"
• jsonlDialect: "gemini-stream-json"
• imageArg: "@"
• imagePathScope: "workspace"
• modelArg: "--model"
• sessionMode: "existing"
• sessionIdFields: ["session_id", "sessionId"]

• De standaard stream-json-parser leest assistant-message-events, tool-events, definitieve result-usage en fatale Gemini-foutevents.
• Als je Gemini-argumenten overschrijft naar --output-format json, normaliseert OpenClaw die backend terug naar output: "json" en leest antwoordtekst uit het JSON-veld response.
• Usage valt terug op stats wanneer usage ontbreekt of leeg is.
• stats.cached wordt genormaliseerd naar OpenClaw cacheRead.
• Als stats.input ontbreekt, leidt OpenClaw invoertokens af uit stats.input_tokens - stats.cached.

​

Standaardwaarden in eigendom van Plugins

• Plugins registreren ze met api.registerCliBackend(...).
• De backend-id wordt het providerprefix in modelreferenties.
• Gebruikersconfiguratie in agents.defaults.cliBackends.<id> overschrijft nog steeds de Plugin-standaardwaarde.
• Backendspecifieke configuratieopschoning blijft eigendom van de Plugin via de optionele normalizeConfig-hook.

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" },
  ],
});

​

Eigendom van native Compaction

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

​

Bundle MCP-overlays

• claude-cli: gegenereerd strikt MCP-configuratiebestand
• google-gemini-cli: gegenereerd Gemini-systeeminstellingenbestand

• start een loopback-HTTP-MCP-server die gateway-tools beschikbaar maakt aan het CLI-proces
• authenticeert de bridge met een token per sessie (OPENCLAW_MCP_TOKEN)
• beperkt tooltoegang tot de huidige sessie-, account- en kanaalcontext
• laadt ingeschakelde bundle-MCP-servers voor de huidige workspace
• voegt ze samen met een bestaande backend-MCP-configuratie-/instellingenvorm
• herschrijft de startconfiguratie met de integratiemodus, eigendom van de backend, uit de beherende extensie

​

Limiet voor reseed-geschiedenis

• De limiet geldt alleen voor het prior-history-blok van de reseed-prompt. Limieten voor live-sessie-uitvoer worden afzonderlijk afgestemd onder reliability.outputLimits (zie Sessies).

​

Beperkingen

• Geen directe OpenClaw-toolaanroepen. OpenClaw injecteert geen toolaanroepen in het CLI-backendprotocol. Backends zien gateway-tools alleen wanneer ze zich aanmelden voor bundleMcp: true.
• Streaming is backendspecifiek. Sommige backends streamen JSONL; andere bufferen tot afsluiten.
• Gestructureerde uitvoer is afhankelijk van het JSON-formaat van de CLI.

​

Problemen oplossen

• CLI niet gevonden: stel command in op een volledig pad.
• Verkeerde modelnaam: gebruik modelAliases om provider/model → CLI-model te mappen.
• Geen sessiecontinuiteit: zorg dat sessionArg is ingesteld en dat sessionMode niet none is.
• Afbeeldingen genegeerd: stel imageArg in (en controleer of de CLI bestandspaden ondersteunt).

​

Gerelateerd

• Gateway-runbook
• Lokale modellen