OpenClaw CLI Backends: Lokale KI als Fallback nutzen

Kennst du das? Du arbeitest konzentriert an einem Projekt, und plötzlich streikt dein KI-Provider. Die API ist überlastet oder antwortet nicht, und dein gesamter Workflow kommt zum Erliegen. Genau für solche Momente wurde OpenClaw mit seinen CLI-Backends entwickelt, um dir ein Sicherheitsnetz zu bieten.

OpenClaw ermöglicht es dir, lokale KI-CLIs als textbasiertes Fallback zu nutzen, wenn deine primären API-Dienste nicht erreichbar sind oder Ratenbegrenzungen erreichen. Dies ist bewusst konservativ gehalten:

1. OpenClaw-Tools werden nicht direkt injiziert, aber Backends mit bundleMcp: true können Gateway-Tools über eine Loopback-MCP-Brücke empfangen.
2. JSONL-Streaming wird für CLIs unterstützt, die dies ermöglichen.
3. Sessions werden unterstützt, damit Folgefragen kohärent bleiben.
4. Bilder können durchgereicht werden, sofern die CLI Bildpfade akzeptiert.

Dies ist als Sicherheitsnetz gedacht, nicht als primärer Pfad. Nutze es, wenn du “immer funktionierende” Textantworten ohne Abhängigkeit von externen APIs benötigst. Wenn du eine vollständige Runtime mit ACP-Session-Kontrolle, Hintergrundaufgaben und persistenten Coding-Sessions suchst, verwende stattdessen ACP Agents.

Schneller Einstieg für Einsteiger

Du kannst die Codex CLI ohne jegliche Konfiguration verwenden, da das gebündelte OpenAI-Plugin ein Standard-Backend registriert:

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

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

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

Das war es schon. Keine Keys oder zusätzliche Auth-Konfiguration nötig, außer der CLI selbst.

Verwendung als Fallback

Füge ein CLI-Backend zu deiner Fallback-Liste hinzu, damit es nur dann einspringt, wenn primäre Modelle ausfallen:

{
  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:

1. Wenn du agents.defaults.models (Allowlist) verwendest, musst du deine CLI-Backend-Modelle dort ebenfalls aufführen.
2. Wenn der primäre Provider ausfällt (Auth, Ratenbegrenzung, Timeouts), versucht OpenClaw als Nächstes das CLI-Backend.

Konfigurationsübersicht

Alle CLI-Backends befinden sich unter:

agents.defaults.cliBackends

Jeder Eintrag wird über eine Provider-ID (z. B. codex-cli, my-cli) identifiziert. Die Provider-ID bildet den linken Teil deiner Modell-Referenz:

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

Funktionsweise

1. Auswahl eines Backends basierend auf dem Provider-Präfix (codex-cli/...).
2. Erstellung eines System-Prompts unter Verwendung des OpenClaw-Prompts und des Workspace-Kontexts.
3. Ausführung der CLI mit einer Session-ID (falls unterstützt), damit die Historie konsistent bleibt.
4. Parsen der Ausgabe (JSON oder reiner Text) und Rückgabe des finalen Textes.
5. Persistenz der Session-IDs pro Backend, damit Folgeanfragen dieselbe CLI-Session wiederverwenden.

Sessions

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

Bilder (Durchreichen)

Wenn deine CLI Bildpfade akzeptiert, setze imageArg:

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

OpenClaw schreibt Base64-Bilder in temporäre Dateien. Wenn imageArg gesetzt ist, werden diese Pfade als CLI-Argumente übergeben. Fehlt imageArg, hängt OpenClaw die Dateipfade an den Prompt an (Pfad-Injektion), was für CLIs ausreicht, die lokale Dateien automatisch aus Pfaden laden.

Eingaben / Ausgaben

1. output: "json" (Standard) versucht, JSON zu parsen und Text sowie Session-ID zu extrahieren.
2. Für Gemini CLI JSON-Ausgabe liest OpenClaw den Antworttext aus response und die Nutzung aus stats, wenn usage fehlt oder leer ist.
3. output: "jsonl" parst JSONL-Streams (z. B. Codex CLI --json) und extrahiert die finale Agenten-Nachricht sowie Session-IDs, falls vorhanden.
4. output: "text" behandelt stdout als finale Antwort.

Eingabemodi:

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

Standardwerte (Plugin-eigen)

Das gebündelte OpenAI-Plugin registriert ebenfalls einen Standard für 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"

Das gebündelte Google-Plugin registriert 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"]

Plugin-eigene Standardwerte

CLI-Backend-Standardwerte sind nun Teil der Plugin-Oberfläche:

1. Plugins registrieren diese mit api.registerCliBackend(...).
2. Die Backend-id wird zum Provider-Präfix in Modell-Referenzen.
3. Benutzerkonfiguration in agents.defaults.cliBackends.<id> überschreibt weiterhin den Plugin-Standard.

Plugins, die kleine Kompatibilitäts-Shims für Prompts/Nachrichten benötigen, können bidirektionale Text-Transformationen deklarieren:

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

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:

1. claude-cli: generierte strikte MCP-Konfigurationsdatei.
2. codex-cli: Inline-Konfigurations-Overrides für mcp_servers.
3. google-gemini-cli: generierte Gemini-Systemeinstellungsdatei.

Einschränkungen

1. Keine direkten OpenClaw-Tool-Aufrufe. Backends sehen Gateway-Tools nur, wenn sie bundleMcp: true aktivieren.
2. Streaming ist Backend-spezifisch. Manche Backends streamen JSONL, andere puffern bis zum Beenden.
3. Strukturierte Ausgaben hängen vom JSON-Format der CLI ab.
4. Codex CLI Sessions werden über Textausgabe fortgesetzt (kein JSONL), was weniger strukturiert ist als der initiale --json-Durchlauf.

Fehlerbehebung

1. CLI nicht gefunden: Setze command auf einen vollständigen Pfad.
2. Falscher Modellname: Verwende modelAliases, um provider/model auf das CLI-Modell abzubilden.
3. Keine Session-Kontinuität: Stelle sicher, dass sessionArg gesetzt ist und sessionMode nicht none ist.
4. Bilder ignoriert: Setze imageArg und prüfe, ob die CLI Dateipfade unterstützt.

Brauchst du weitere Hilfe? Kontaktiere den AI Setup Assistant.

Nächste Schritte

• ACP Agents
• Gateway Konfiguration