CLI-Backends (Fallback-Runtime)

OpenClaw kann lokale KI-CLIs als Nur-Text-Fallback nutzen, wenn API-Anbieter ausfallen, Rate-Limits greifen oder vorübergehend Probleme auftreten. Das ist bewusst konservativ gehalten:

  • Tools sind deaktiviert (keine Tool-Calls).
  • Text rein → Text raus (zuverlässig).
  • Sessions werden unterstützt (sodass Folgeantworten kohärent bleiben).
  • Bilder können durchgereicht werden, sofern die CLI Bildpfade akzeptiert.

Das ist als Sicherheitsnetz gedacht, nicht als primärer Pfad. Nutze es, wenn du “funktioniert immer”-Textantworten willst, ohne auf externe APIs angewiesen zu sein.

Einsteigerfreundlicher Schnellstart

Du kannst Claude Code CLI ohne jede Konfiguration verwenden (OpenClaw liefert einen eingebauten Standard):

openclaw agent --message "hi" --model claude-cli/opus-4.6

Codex CLI funktioniert ebenfalls sofort:

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

Falls dein Gateway unter launchd/systemd läuft und PATH minimal ist, füge einfach den Befehlspfad hinzu:

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

Das war’s. Keine Schlüssel, keine weitere Auth-Konfiguration nötig, abgesehen von der CLI selbst.

Als Fallback verwenden

Füge ein CLI-Backend zu deiner Fallback-Liste hinzu, damit es nur läuft, wenn primäre Modelle fehlschlagen:

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

Hinweise:

  • Wenn du agents.defaults.models (Allowlist) verwendest, musst du claude-cli/... einschließen.
  • Falls der primäre Anbieter fehlschlägt (Auth, Rate-Limits, Timeouts), versucht OpenClaw als nächstes das CLI-Backend.

Konfigurationsübersicht

Alle CLI-Backends befinden sich unter:

agents.defaults.cliBackends

Jeder Eintrag ist nach einer Provider-ID benannt (z. B. claude-cli, my-cli). Die Provider-ID wird zur linken Seite deiner Modellreferenz:

<provider>/<model>

Beispielkonfiguration

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          input: "arg",
          modelArg: "--model",
          modelAliases: {
            "claude-opus-4-6": "opus",
            "claude-opus-4-5": "opus",
            "claude-sonnet-4-5": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

So funktioniert es

  1. Wählt ein Backend basierend auf dem Provider-Präfix (claude-cli/...).
  2. Erstellt einen System-Prompt mit dem gleichen OpenClaw-Prompt + Workspace-Kontext.
  3. Führt die CLI aus mit einer Session-ID (falls unterstützt), sodass der Verlauf konsistent bleibt.
  4. Parst die Ausgabe (JSON oder Klartext) und gibt den finalen Text zurück.
  5. Speichert Session-IDs pro Backend, sodass Folgeanfragen die gleiche CLI-Session wiederverwenden.

Sessions

  • Wenn die CLI Sessions unterstützt, setze sessionArg (z. B. --session-id) oder sessionArgs (Platzhalter {sessionId}), wenn die ID in mehreren Flags eingefügt werden muss.
  • Falls die CLI ein Resume-Subcommand mit anderen Flags verwendet, setze resumeArgs (ersetzt args beim Fortsetzen) und optional resumeOutput (für Nicht-JSON-Resumes).
  • sessionMode:
    • always: immer eine Session-ID senden (neue UUID wenn keine gespeichert).
    • existing: Session-ID nur senden, wenn eine zuvor gespeichert wurde.
    • none: niemals eine Session-ID senden.

Bilder (Durchreichung)

Wenn deine CLI Bildpfade akzeptiert, setze imageArg:

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

OpenClaw schreibt Base64-Bilder in temporäre Dateien. Falls imageArg gesetzt ist, werden diese Pfade als CLI-Argumente übergeben. Ohne imageArg hängt OpenClaw die Dateipfade an den Prompt an (Pfad-Injektion), was für CLIs genügt, die lokale Dateien automatisch aus Klartextpfaden laden (Claude Code CLI-Verhalten).

Eingabe / Ausgabe

  • output: "json" (Standard) versucht JSON zu parsen und Text + Session-ID zu extrahieren.
  • output: "jsonl" parst JSONL-Streams (Codex CLI --json) und extrahiert die letzte Agent-Nachricht sowie thread_id, wenn vorhanden.
  • output: "text" behandelt stdout als finale 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 (eingebaut)

OpenClaw liefert einen Standard für claude-cli:

  • command: "claude"
  • args: ["-p", "--output-format", "json", "--permission-mode", "bypassPermissions"]
  • resumeArgs: ["-p", "--output-format", "json", "--permission-mode", "bypassPermissions", "--resume", "{sessionId}"]
  • modelArg: "--model"
  • systemPromptArg: "--append-system-prompt"
  • sessionArg: "--session-id"
  • systemPromptWhen: "first"
  • sessionMode: "always"

OpenClaw liefert auch einen Standard für codex-cli:

  • command: "codex"
  • args: ["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]
  • resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","read-only","--skip-git-repo-check"]
  • output: "jsonl"
  • resumeOutput: "text"
  • modelArg: "--model"
  • imageArg: "--image"
  • sessionMode: "existing"

Überschreibe nur bei Bedarf (häufig: absoluter command-Pfad).

Einschränkungen

  • Keine OpenClaw-Tools (das CLI-Backend erhält niemals Tool-Calls). Manche CLIs können dennoch ihr eigenes Agent-Tooling ausführen.
  • Kein Streaming (CLI-Ausgabe wird gesammelt und dann zurückgegeben).
  • Strukturierte Ausgaben hängen vom JSON-Format der CLI ab.
  • Codex CLI-Sessions werden über Text-Ausgabe fortgesetzt (kein JSONL), was weniger strukturiert ist als der initiale --json-Lauf. OpenClaw-Sessions funktionieren weiterhin normal.

Fehlerbehebung

  • CLI nicht gefunden: Setze command auf einen vollständigen Pfad.
  • Falscher Modellname: Verwende modelAliases, um provider/model → CLI-Modell abzubilden.
  • Keine Session-Kontinuität: Stelle sicher, dass sessionArg gesetzt ist und sessionMode nicht none ist (Codex CLI kann derzeit nicht mit JSON-Ausgabe fortsetzen).
  • Bilder ignoriert: Setze imageArg (und prüfe, ob die CLI Dateipfade unterstützt).
arrow_back
Zurück
Tools Invoke HTTP API
Weiter
Local Models
arrow_forward