CLI-Backends

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• OpenClaw-Tools werden nicht direkt injiziert, aber Backends mit bundleMcp: true können Gateway-Tools über eine local loopback-MCP-Bridge empfangen.
• JSONL-Streaming für CLIs, die es unterstützen.
• Sitzungen werden unterstützt (damit Folgeturns kohärent bleiben).
• Bilder können durchgereicht werden, wenn die CLI Bildpfade akzeptiert.

​

Einsteigerfreundlicher Schnellstart

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

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

​

Verwendung als Ausweichlösung

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

• Wenn Sie agents.defaults.models (Zulassungsliste) verwenden, müssen Sie dort auch Ihre CLI-Backend-Modelle einschließen.
• Wenn der primäre Provider fehlschlägt (Authentifizierung, Ratenbegrenzungen, Zeitüberschreitungen), versucht OpenClaw als Nächstes das CLI-Backend.

​

Konfigurationsübersicht

agents.defaults.cliBackends

<provider>/<model>

​

Beispielkonfiguration

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

​

Funktionsweise

1. Wählt ein Backend aus basierend auf dem Provider-Präfix (codex-cli/...).
2. Erstellt einen System-Prompt mit demselben OpenClaw-Prompt und Workspace-Kontext.
3. Führt die CLI aus mit einer Sitzungs-ID (falls unterstützt), damit der Verlauf konsistent bleibt. Das gebündelte claude-cli-Backend hält pro OpenClaw-Sitzung einen Claude-stdio-Prozess aktiv und sendet Folgeturns über stream-json-stdin.
4. Parst die Ausgabe (JSON oder Klartext) und gibt den finalen Text zurück.
5. Persistiert Sitzungs-IDs pro Backend, damit Folgeturns dieselbe CLI-Sitzung wiederverwenden.

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

​

Sitzungen

• Wenn die CLI Sitzungen unterstützt, setzen Sie sessionArg (z. B. --session-id) oder sessionArgs (Platzhalter {sessionId}), wenn die ID in mehrere Flags eingefügt werden muss.
• Wenn die CLI einen resume-Unterbefehl mit anderen Flags verwendet, setzen Sie resumeArgs (ersetzt args beim Fortsetzen) und optional resumeOutput (für Nicht-JSON-Fortsetzungen).
• sessionMode:
  • always: immer eine Sitzungs-ID senden (neue UUID, wenn keine gespeichert ist).
  • existing: nur eine Sitzungs-ID senden, wenn zuvor eine gespeichert wurde.
  • none: nie eine Sitzungs-ID senden.
• claude-cli ist standardmäßig auf liveSession: "claude-stdio", output: "jsonl", und input: "stdin" gesetzt, sodass Folgeturns den laufenden Claude-Prozess wiederverwenden, solange er aktiv ist. Warmes stdio ist jetzt der Standard, auch für benutzerdefinierte Konfigurationen, die Transportfelder auslassen. Wenn das Gateway neu startet oder der untätige Prozess beendet wird, setzt OpenClaw anhand der gespeicherten Claude-Sitzungs-ID fort. Gespeicherte Sitzungs- IDs werden vor dem Fortsetzen gegen ein vorhandenes lesbares Projekttranskript geprüft, sodass Phantom-Bindungen mit reason=transcript-missing bereinigt werden, statt stillschweigend eine neue Claude CLI-Sitzung unter --resume zu starten.
• Claude-Live-Sitzungen behalten begrenzte JSONL-Ausgabeschutzmechanismen. Standardwerte erlauben bis zu 8 MiB und 20.000 rohe JSONL-Zeilen pro Turn. Tool-lastige Claude-Turns können sie pro Backend mit agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars und maxTurnLines erhöhen; OpenClaw begrenzt diese Einstellungen auf 64 MiB und 100.000 Zeilen.
• Gespeicherte CLI-Sitzungen sind Provider-eigene Kontinuität. Der implizite tägliche Sitzungs- Reset unterbricht sie nicht; /reset und explizite session.reset-Richtlinien tun dies weiterhin.
• Neue CLI-Sitzungen werden normalerweise nur aus OpenClaws Compaction-Zusammenfassung plus dem Nach-Compaction-Endstück neu befüllt. Um kurze Sitzungen wiederherzustellen, die vor der Compaction ungültig werden, kann ein Backend sich mit reseedFromRawTranscriptWhenUncompacted: true dafür anmelden. OpenClaw hält das rohe Transkript-Neubefüllen weiterhin begrenzt und beschränkt es auf sichere Ungültigkeiten wie fehlende CLI-Transkripte, System-Prompt-/MCP-Änderungen oder eine Sitzung-abgelaufen-Wiederholung; Änderungen an Authentifizierungsprofil oder Anmeldedaten-Epoche befüllen den rohen Transkriptverlauf nie neu.

• serialize: true hält Läufe derselben Lane in Reihenfolge.
• Die meisten CLIs serialisieren auf einer Provider-Lane.
• OpenClaw verwirft die Wiederverwendung gespeicherter CLI-Sitzungen, wenn sich die ausgewählte Authentifizierungsidentität ändert, einschließlich geänderter Authentifizierungsprofil-ID, statischem API-Schlüssel, statischem Token oder OAuth- Kontoidentität, wenn die CLI eine offenlegt. OAuth-Zugriffs- und Aktualisierungstoken- Rotation unterbricht die gespeicherte CLI-Sitzung nicht. Wenn eine CLI keine stabile OAuth-Konto-ID offenlegt, lässt OpenClaw diese CLI die Fortsetzungsberechtigungen erzwingen.

​

Ausweich-Präludium aus claude-cli-Sitzungen

• Das Präludium bevorzugt die neueste /compact-Zusammenfassung oder den compact_boundary- Marker und hängt dann die neuesten Nach-Grenze-Turns bis zu einem Zeichen- Budget an. Vor-Grenze-Turns werden verworfen, weil die Zusammenfassung sie bereits repräsentiert.
• Tool-Blöcke werden zu kompakten Hinweisen (tool call: name) und (tool result: …) zusammengeführt, um das Prompt-Budget ehrlich zu halten. Die Zusammenfassung wird mit (truncated) gekennzeichnet, wenn sie überläuft.
• claude-cli-zu-claude-cli-Ausweichpfade desselben Providers verlassen sich auf Claudes eigenes --resume und überspringen das Präludium.
• Die Befüllung verwendet die vorhandene Claude-Sitzungsdateipfad-Validierung wieder, sodass keine beliebigen Pfade gelesen werden können.

​

Bilder (Durchreichen)

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

​

Eingaben / Ausgaben

• output: "json" (Standard) versucht, JSON zu parsen und Text + Sitzungs-ID zu extrahieren.
• Für Gemini CLI-JSON-Ausgabe liest OpenClaw Antworttext aus response und Nutzung aus stats, wenn usage fehlt oder leer ist.
• output: "jsonl" parst JSONL-Streams (zum Beispiel Codex CLI --json) und extrahiert die finale Agentennachricht plus Sitzungs- Kennungen, sofern vorhanden.
• output: "text" behandelt stdout als finale Antwort.

• input: "arg" (Standard) übergibt den Prompt als letztes CLI-Argument.
• input: "stdin" sendet den Prompt über stdin.
• Wenn der Prompt sehr lang ist und maxPromptArgChars gesetzt ist, wird stdin verwendet.

​

Standardwerte (Plugin-eigen)

• 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"

• 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"]

• Antworttext wird aus dem JSON-Feld response gelesen.
• Die Nutzung fällt auf stats zurück, wenn usage fehlt oder leer ist.
• stats.cached wird in OpenClaw cacheRead normalisiert.
• Wenn stats.input fehlt, leitet OpenClaw Eingabe-Token aus stats.input_tokens - stats.cached ab.

​

Plugin-eigene Standardeinstellungen

• Plugins registrieren sie mit api.registerCliBackend(...).
• Die Backend-id wird zum Provider-Präfix in Modellreferenzen.
• Benutzerkonfiguration in agents.defaults.cliBackends.<id> überschreibt weiterhin den Plugin-Standard.
• Backend-spezifische Konfigurationsbereinigung bleibt über den optionalen normalizeConfig-Hook Plugin-eigen.

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

​

Bundle-MCP-Overlays

• claude-cli: generierte strikte MCP-Konfigurationsdatei
• codex-cli: Inline-Konfigurationsüberschreibungen für mcp_servers; der generierte OpenClaw-Loopback-Server wird mit dem Tool-Genehmigungsmodus pro Server von Codex markiert, sodass MCP-Aufrufe nicht durch lokale Genehmigungsaufforderungen blockiert werden können
• google-gemini-cli: generierte Gemini-Systemeinstellungsdatei

• startet einen Loopback-HTTP-MCP-Server, der Gateway-Tools für den CLI-Prozess bereitstellt
• authentifiziert die Bridge mit einem Token pro Sitzung (OPENCLAW_MCP_TOKEN)
• beschränkt den Tool-Zugriff auf die aktuelle Sitzung, das Konto und den Kanalkontext
• lädt aktivierte Bundle-MCP-Server für den aktuellen Workspace
• führt sie mit jeder bestehenden Backend-MCP-Konfigurations-/Einstellungsstruktur zusammen
• schreibt die Startkonfiguration mit dem Backend-eigenen Integrationsmodus der besitzenden Erweiterung um

​

Einschränkungen

• Keine direkten OpenClaw-Tool-Aufrufe. OpenClaw injiziert keine Tool-Aufrufe in das CLI-Backend-Protokoll. Backends sehen Gateway-Tools nur, wenn sie bundleMcp: true aktivieren.
• Streaming ist Backend-spezifisch. Einige Backends streamen JSONL; andere puffern bis zum Beenden.
• Strukturierte Ausgaben hängen vom JSON-Format der CLI ab.
• Codex CLI-Sitzungen werden über Textausgabe fortgesetzt (kein JSONL), was weniger strukturiert ist als die anfängliche --json-Ausführung. OpenClaw-Sitzungen funktionieren weiterhin normal.

​

Fehlerbehebung

• CLI nicht gefunden: Setzen Sie command auf einen vollständigen Pfad.
• Falscher Modellname: Verwenden Sie modelAliases, um provider/model → CLI-Modell zuzuordnen.
• Keine Sitzungskontinuität: Stellen Sie sicher, dass sessionArg gesetzt ist und sessionMode nicht none ist (Codex CLI kann derzeit nicht mit JSON-Ausgabe fortgesetzt werden).
• Bilder ignoriert: Setzen Sie imageArg (und prüfen Sie, ob die CLI Dateipfade unterstützt).

​

Verwandt

• Gateway-Runbook
• Lokale Modelle