Zum Hauptinhalt springen

​
CLI-Backends (Fallback-Laufzeit)

OpenClaw kann lokale KI-CLIs als reinen Text-Fallback ausführen, wenn API-Anbieter ausfallen, ratenbegrenzt sind oder sich vorübergehend fehlerhaft verhalten. Das ist bewusst konservativ ausgelegt:
  • OpenClaw-Tools werden nicht direkt eingebunden, aber Backends mit bundleMcp: true können Gateway-Tools über eine Loopback-MCP-Bridge erhalten.
  • JSONL-Streaming für CLIs, die es unterstützen.
  • Sitzungen werden unterstützt (damit zusammenhängende Folge-Turns kohärent bleiben).
  • Bilder können durchgereicht werden, wenn die CLI Bildpfade akzeptiert.
Dies ist als Sicherheitsnetz und nicht als primärer Pfad gedacht. Verwenden Sie es, wenn Sie zuverlässige Textantworten möchten, ohne von externen APIs abhängig zu sein. Wenn Sie eine vollständige Harness-Laufzeit mit ACP-Sitzungssteuerung, Hintergrundaufgaben, Thread-/Unterhaltungs-Bindung und persistenten externen Coding-Sitzungen möchten, verwenden Sie stattdessen ACP Agents. CLI-Backends sind kein ACP.

​
Schnellstart für Einsteiger

Sie können Codex CLI ohne Konfiguration verwenden (das gebündelte OpenAI-Plugin registriert ein Standard-Backend): 
openclaw agent --message "hi" --model codex-cli/gpt-5.4
Wenn Ihr Gateway unter launchd/systemd läuft und PATH minimal ist, fügen Sie nur den Befehlspfad hinzu: 
{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
      },
    },
  },
}
Das ist alles. Keine Schlüssel, keine zusätzliche Authentifizierungskonfiguration außer der CLI selbst erforderlich. Wenn Sie ein gebündeltes CLI-Backend als primären Nachrichtenanbieter auf einem Gateway-Host verwenden, lädt OpenClaw jetzt automatisch das zugehörige gebündelte Plugin, wenn Ihre Konfiguration dieses Backend explizit in einer Modellreferenz oder unter agents.defaults.cliBackends referenziert.

​
Verwendung als Fallback

Fügen Sie Ihrer Fallback-Liste ein CLI-Backend hinzu, damit es nur ausgeführt wird, wenn primäre Modelle fehlschlagen: 
{
  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": {},
      },
    },
  },
}
Hinweise:
  • Wenn Sie agents.defaults.models (Allowlist) verwenden, müssen Sie dort auch Ihre CLI-Backend-Modelle einschließen.
  • Wenn der primäre Anbieter fehlschlägt (Authentifizierung, Ratenbegrenzungen, Timeouts), versucht OpenClaw als Nächstes das CLI-Backend.

​
Konfigurationsübersicht

Alle CLI-Backends befinden sich unter: 
agents.defaults.cliBackends
Jeder Eintrag wird durch eine Anbieter-ID identifiziert (z. B. codex-cli, my-cli). Die Anbieter-ID wird zur linken Seite Ihrer Modellreferenz: 
<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",
          // CLIs im Codex-Stil können stattdessen auf eine Prompt-Datei verweisen:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

​
So funktioniert es

  1. Wählt ein Backend aus basierend auf dem Anbieterprä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.
  4. Parst die Ausgabe (JSON oder Klartext) und gibt den endgültigen Text zurück.
  5. Speichert Sitzungs-IDs pro Backend, damit Folgeanfragen dieselbe CLI-Sitzung wiederverwenden.
Das gebündelte Anthropic-claude-cli-Backend wird wieder unterstützt. Mitarbeitende von Anthropic haben uns mitgeteilt, dass die Nutzung von Claude CLI im OpenClaw-Stil wieder erlaubt ist, daher behandelt OpenClaw die Nutzung von claude -p für diese Integration als zulässig, sofern Anthropic keine neue Richtlinie veröffentlicht.
Das gebündelte OpenAI-codex-cli-Backend übergibt den System-Prompt von OpenClaw über Codex’ model_instructions_file-Konfigurationsüberschreibung (-c model_instructions_file="..."). Codex bietet kein Flag im Claude-Stil wie --append-system-prompt, daher schreibt OpenClaw den zusammengesetzten Prompt für jede neue Codex-CLI-Sitzung in eine temporäre Datei.

​
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-Subcommand mit anderen Flags verwendet, setzen Sie resumeArgs (ersetzt args beim Fortsetzen) und optional resumeOutput (für nicht-JSON-Resumes).
  • sessionMode:
    • always: sendet immer eine Sitzungs-ID (neue UUID, falls keine gespeichert ist).
    • existing: sendet nur dann eine Sitzungs-ID, wenn bereits eine gespeichert wurde.
    • none: sendet niemals eine Sitzungs-ID.
Hinweise zur Serialisierung:
  • serialize: true hält Ausführungen auf derselben Lane geordnet.
  • Die meisten CLIs serialisieren auf einer Anbieter-Lane.
  • OpenClaw verwirft die Wiederverwendung gespeicherter CLI-Sitzungen, wenn sich der Authentifizierungsstatus des Backends ändert, einschließlich erneutem Login, Token-Rotation oder geänderten Anmeldedaten eines Authentifizierungsprofils.

​
Bilder (Durchreichung)

Wenn Ihre CLI Bildpfade akzeptiert, setzen Sie imageArg: 
imageArg: "--image",
imageMode: "repeat"
OpenClaw schreibt Base64-Bilder in temporäre Dateien. Wenn imageArg gesetzt ist, werden diese Pfade als CLI-Argumente übergeben. Wenn imageArg fehlt, hängt OpenClaw die Dateipfade an den Prompt an (Path Injection), was für CLIs ausreicht, die lokale Dateien automatisch aus einfachen Pfaden laden.

​
Eingaben / Ausgaben

  • output: "json" (Standard) versucht, JSON zu parsen und Text + Sitzungs-ID zu extrahieren.
  • Für die JSON-Ausgabe von Gemini CLI 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 endgültige Agentennachricht sowie Sitzungs- kennungen, sofern vorhanden.
  • output: "text" behandelt stdout als die endgültige Antwort.
Eingabemodi:
  • 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.

​
Standards (plugin-eigen)

Das gebündelte OpenAI-Plugin registriert auch einen Standard für 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"
Das gebündelte Google-Plugin registriert auch einen Standard für 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"]
Voraussetzung: Die lokale Gemini CLI muss installiert und als gemini auf PATH verfügbar sein (brew install gemini-cli oder npm install -g @google/gemini-cli). Hinweise zu Gemini-CLI-JSON:
  • Antworttext wird aus dem JSON-Feld response gelesen.
  • Nutzung greift 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.
Überschreiben Sie dies nur bei Bedarf (häufig: absoluter command-Pfad).

​
Plugin-eigene Standards

Standardwerte für CLI-Backends sind jetzt Teil der Plugin-Oberfläche:
  • Plugins registrieren sie mit api.registerCliBackend(...).
  • Die Backend-id wird zum Anbieterpräfix in Modellreferenzen.
  • Benutzerkonfiguration in agents.defaults.cliBackends.<id> überschreibt weiterhin den Plugin-Standard.
  • Backend-spezifische Konfigurationsbereinigung bleibt über den optionalen Hook normalizeConfig plugin-eigen.

​
Bundle-MCP-Overlays

CLI-Backends erhalten keine direkten OpenClaw-Tool-Aufrufe, aber ein Backend kann sich mit bundleMcp: true für ein generiertes MCP-Konfigurations-Overlay entscheiden. Aktuelles gebündeltes Verhalten:
  • claude-cli: generierte strikte MCP-Konfigurationsdatei
  • codex-cli: Inline-Konfigurationsüberschreibungen für mcp_servers
  • google-gemini-cli: generierte Gemini-Systemeinstellungsdatei
Wenn Bundle MCP aktiviert ist, führt OpenClaw Folgendes aus:
  • startet einen Loopback-HTTP-MCP-Server, der Gateway-Tools für den CLI-Prozess bereitstellt
  • authentifiziert die Bridge mit einem sitzungsbezogenen Token (OPENCLAW_MCP_TOKEN)
  • begrenzt den Tool-Zugriff auf die aktuelle Sitzung, das aktuelle Konto und den Kanal-Kontext
  • lädt aktivierte Bundle-MCP-Server für den aktuellen Workspace
  • führt sie mit einer vorhandenen MCP-Konfigurations-/Einstellungsstruktur des Backends zusammen
  • schreibt die Startkonfiguration unter Verwendung des backend-eigenen Integrationsmodus aus der zugehörigen Erweiterung um
Wenn keine MCP-Server aktiviert sind, injiziert OpenClaw dennoch eine strikte Konfiguration, wenn ein Backend sich für Bundle MCP entscheidet, damit Hintergrundausführungen isoliert bleiben.

​
Einschränkungen

  • Keine direkten OpenClaw-Tool-Aufrufe. OpenClaw bindet Tool-Aufrufe nicht direkt in das CLI-Backend-Protokoll ein. Backends sehen Gateway-Tools nur dann, wenn sie sich für bundleMcp: true entscheiden.
  • Streaming ist backend-spezifisch. Manche 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 der anfängliche --json-Lauf. OpenClaw-Sitzungen funktionieren dennoch 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 fortsetzen).
  • Bilder werden ignoriert: Setzen Sie imageArg (und prüfen Sie, ob die CLI Dateipfade unterstützt).