Configure OpenClaw CLI Backends for Reliable Fallback AI

We’ve all been there—you’re in the middle of a deep work session and suddenly your AI provider starts throwing 503 errors or you hit a surprise rate limit. It’s a total flow-breaker. That is why having a local fallback is a smart move for any setup.

OpenClaw can run local AI CLIs as a text-only fallback when your main API providers are down or acting up. This is a conservative safety net: tools are disabled and it focuses on reliable text-in/text-out communication. It still supports sessions so your follow-up questions stay coherent, and it can even handle images if your CLI supports them.

Beginner-friendly quick start

You can use the Claude Code CLI right away without touching any config files. The bundled Anthropic plugin already has a default backend ready for you:

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

Codex CLI also works out of the box through the bundled OpenAI plugin:

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

If your gateway runs under launchd or systemd where the PATH might be limited, you just need to add the specific command path to your config:

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

That is the whole process. You don’t need extra keys or auth config beyond what the CLI itself requires. If you reference a backend in your model settings, OpenClaw automatically loads the right plugin for you.

Using it as a fallback

The best way to use this is by adding a CLI backend to your fallback list. This way, it only kicks in if your primary models fail:

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

Keep these points in mind:

• If you use an allowlist in agents.defaults.models, you have to include the claude-cli/... entries.
• When the primary provider hits a rate limit, timeout, or auth error, OpenClaw tries the CLI backend next.

Configuration overview

All your CLI backend settings live in this location:

agents.defaults.cliBackends

You key each entry by a provider id like claude-cli or my-cli. This ID becomes the left side of your model reference:

<provider>/<model>

Example configuration

Here is how a more detailed setup looks:

{
  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-sonnet-4-6": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

How it works

The system follows a specific logic to get your response:

1. It selects a backend based on the provider prefix.
2. It builds a system prompt using your OpenClaw prompt and workspace context.
3. It executes the CLI with a session ID to keep history consistent.
4. It parses the output (JSON or plain text) to return the final text.
5. It persists session IDs per backend so follow-ups reuse the same session.

Sessions

If your CLI supports sessions, you can set sessionArg or use sessionArgs with the {sessionId} placeholder. This is useful when the ID needs to go into multiple flags.

If the CLI uses a specific subcommand to resume, use resumeArgs to replace the standard arguments. You can also use resumeOutput if the resume command returns a different format.

The sessionMode options are:

• always: Always sends a session ID (generates a new UUID if needed).
• existing: Only sends a session ID if one was already stored.
• none: Never sends a session ID.

Images (pass-through)

When your CLI can handle image paths, you should set the imageArg:

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

OpenClaw writes base64 images to temporary files. If imageArg is set, those file paths are passed as arguments. If it is missing, OpenClaw appends the paths to the prompt, which works for CLIs like Claude Code that auto-load local files from paths.

Inputs / outputs

The output setting determines how the response is read:

• json: This is the default. It parses JSON to find text and session IDs.
• jsonl: This parses JSONL streams (like Codex CLI) and takes the last message.
• text: This treats the entire stdout as the response.

For input modes:

• arg: The default mode that passes the prompt as the last CLI argument.
• stdin: Sends the prompt via standard input.
• If a prompt is too long and maxPromptArgChars is set, the system switches to stdin automatically.

Defaults (plugin-owned)

The Anthropic plugin comes with these defaults for 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", and sessionMode: "always".

The OpenAI plugin provides these for 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", and sessionMode: "existing".

The Google plugin includes these for google-gemini-cli:

• command: "gemini"
• args: ["--prompt", "--output-format", "json"]
• resumeArgs: ["--resume", "{sessionId}", "--prompt", "--output-format", "json"]
• modelArg: "--model", sessionMode: "existing", and sessionIdFields: ["session_id", "sessionId"].

Plugin-owned defaults

CLI backend defaults are handled directly by the plugins now. Plugins register them using api.registerCliBackend(...), and the backend ID becomes your provider prefix. Your local config in agents.defaults.cliBackends.<id> will still override these plugin defaults. Any specific config cleanup is handled through the normalizeConfig hook.

Limitations

There are a few things to keep in mind when using CLI backends:

• No OpenClaw tools: The backend won’t receive tool calls, though the CLI might run its own internal tools.
• No streaming: The system collects the full CLI output before returning it.
• Structured outputs: These are entirely dependent on the CLI’s specific JSON format.
• Codex CLI sessions: These resume via text output rather than JSONL, though OpenClaw sessions still function.

Troubleshooting

If things aren’t working as expected, check these common fixes:

• CLI not found: Try setting the command to an absolute full path.
• Wrong model name: Use modelAliases to map your model names to what the CLI expects.
• No session continuity: Check that sessionArg is set and sessionMode isn’t set to none.
• Images ignored: Verify the CLI supports file paths and that imageArg is configured.

Next Steps

• Configure your first agent
• Learn about model aliases

AI Setup Assistant