​

CLI-Backends (Fallback-Runtime)

• Werkzeuge sind deaktiviert (keine Tool-Aufrufe).
• Text rein → Text raus (zuverlässig).
• Sitzungen werden unterstützt (damit Folgeeingaben kohärent bleiben).
• Bilder können durchgereicht werden, wenn die CLI Bildpfade akzeptiert.

​

Einsteigerfreundlicher Schnellstart

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

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

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

​

Verwendung als Fallback

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

• Wenn Sie agents.defaults.models (Allowlist) verwenden, müssen Sie claude-cli/... einschließen.
• Wenn der primäre Anbieter fehlschlägt (Auth, Rate-Limits, Timeouts), versucht OpenClaw als Nächstes den CLI-Backend.

​

Konfigurationsübersicht

agents.defaults.cliBackends

<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,
        },
      },
    },
  },
}

​

Wie es funktioniert

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

​

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 unterschiedlichen Flags verwendet, setzen Sie resumeArgs (ersetzt args beim Fortsetzen) und optional resumeOutput (für Nicht-JSON-Resumes).
• sessionMode:
  • always: immer eine Sitzungs-ID senden (neue UUID, falls keine gespeichert ist).
  • existing: nur eine Sitzungs-ID senden, wenn zuvor eine gespeichert war.
  • none: niemals eine Sitzungs-ID senden.

​

Bilder (Durchreichen)

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

​

Eingaben / Ausgaben

• output: "json" (Standard) versucht, JSON zu parsen und Text + Sitzungs-ID zu extrahieren.
• output: "jsonl" parst JSONL-Streams (Codex CLI --json) und extrahiert die letzte Agent-Nachricht sowie thread_id, 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 (integriert)

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

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

​

Einschränkungen

• Keine OpenClaw-Werkzeuge (der CLI-Backend erhält niemals Tool-Aufrufe). Einige CLIs können dennoch ihre eigenen Agent-Werkzeuge ausführen.
• Kein Streaming (CLI-Ausgabe wird gesammelt und dann zurückgegeben).
• 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 initiale --json-Lauf. 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 Sitzungs-Kontinuitä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 verifizieren Sie, dass die CLI Dateipfade unterstützt).