OpenClaw CLI backends

When an API provider is down, rate-limited or misbehaving, OpenClaw can run a local AI CLI as a text-only fallback. The docs are deliberate about the shape: tools are not injected directly, though a backend can receive Gateway tools through a loopback MCP bridge, streaming is JSONL where the CLI supports it, sessions are supported so follow-ups stay coherent, and images pass through when the CLI accepts paths. It is a safety net, not a primary path, and not ACP. Here is the quick start, the fallback wiring, the mechanics of a turn, the Claude CLI specifics, sessions, the MCP bridge, compaction, and the limits.

Quick start and fallback

• The bundled Anthropic plugin registers a Claude CLI backend that works with no config beyond having Claude Code installed and logged in; a one-message agent run with a Claude CLI model reference proves it, and the Gateway service must have the CLI on its path, with a backend plugin for a nonstandard executable.
• To use it only when primary models fail, add a Claude CLI model to the fallback list; configured fallbacks stay eligible when the primary fails on auth, rate limits or timeouts even when they are not in the model allow policy, which only matters for direct selection.
• To route a canonical Anthropic model through the CLI, set the agent runtime id on that model; credentials stay in auth profiles or the plugin’s config, and command, arguments, environment, parsing, sessions, images and watchdog mechanics are plugin code.
• A turn selects the backend by provider prefix, builds the system prompt from the same OpenClaw prompt and workspace context, executes the CLI with a session id where supported, parses JSON or text, and persists session ids per backend so follow-ups reuse the session.

Use it as a safety net for "always works" text responses, not a primary path.

Claude CLI specifics

The bundled backend talks to the installed Claude Code executable over its structured stdio protocol, keeps one warm subprocess across compatible turns, starting a new one when the model, system prompt or tool policy changes, and resumes from stored session ids after a restart; Claude Code owns its login and subscription, and OpenClaw never reads, persists, refreshes or forwards native tokens. Prompt-build hook context reaches Claude as a native hook attachment, saved session notes are replayed within a bounded weighted budget, the native skill resolver is used through a temporary plugin directory when a skill has a materialised path, and Claude Code’s Git instructions are disabled so workspace edits do not invalidate its cached history. Claude Code launches in its default permission mode while OpenClaw’s permission responses and pre-tool hook keep native tools under host control, projecting native tool names and file arguments into their OpenClaw equivalents before exec policy and approval; when the exec ask setting prompts, native tool requests are relayed to the session’s channel with allow once, allow always for the same warm session, and deny, where a timeout, an unreachable route or a closed turn all deny, and allow always never applies to Bash. Thinking levels map to Claude Code’s effort flag and, for fixed-budget models, a max-thinking-tokens value, and native login or a pasted subscription token both work.

Native Bash, sessions, the bridge

• With the on-miss ask setting, native Bash commands are checked against the agent’s exec allowlist using OpenClaw’s own shell evaluator: a call runs without a prompt only when every segment resolves to an allowlisted binary and can be fully bound, pipelines, substitutions, subshells and redirections are denied before any prompt, and this is argument-level policy on the command Claude Code will run, not sandboxed execution, since Claude Code owns the working directory, path, environment and sandboxing.
• Stored CLI sessions are provider-owned continuity verified against a readable transcript before resume; fresh sessions can recover OpenClaw history from the session database when the account boundary matches the selected credential, and a private account fingerprint with contiguous transcript coverage decides eligibility, so switching accounts makes mixed history ineligible and a changed auth identity drops session reuse. A failed Claude CLI attempt can fail over to a non-CLI model seeded with a prelude harvested from Claude Code’s local transcript, its latest compaction summary plus recent turns.
• A backend that opts into the bundle-MCP overlay gets a loopback HTTP MCP server exposing Gateway tools to the CLI process under a per-run token, bound to the Gateway-selected session, account and channel; allow and deny policies constrain native MCP servers too, restricted runs such as cron jobs disable Claude’s native tools and customisations entirely and expose only the allowed OpenClaw tools, and session-scoped bridge runtimes are reaped after ten minutes idle.

OpenClaw and Claude Code is the same pairing seen from the other side, and OpenClaw model failover the mechanism that decides when the fallback runs.

Timeouts, compaction, limits

Two independent limits: the agent turn budget, forty-eight hours by default and zero for unlimited, and the CLI no-output watchdog owned by the backend, active even when the turn budget is unlimited; background work started inside a CLI dies with the subprocess when the turn ends, so durable long work belongs to a detached sub-agent. The Claude CLI backend declares that it owns native compaction, so OpenClaw defers to Claude Code and forwards the context budget through Claude Code’s auto-compact window while an explicit compact command resumes the bound session and sends the native one; the Gemini CLI backend owns its compaction too, with no manual command. Anthropic owns the Claude backend and Google the Gemini one, whose prerequisites are the CLI on the path and a Google AI Studio key profile; there is no bundled Codex CLI backend, since Codex runs through the app-server harness. The limits: no tool calls injected into the CLI protocol without the bridge, streaming that varies by backend, and structured outputs that depend on the CLI’s own JSON. OpenClaw exec approvals covers the allowlist native Bash is checked against, and OpenClaw and Gemini the provider behind the second bundled backend.

On Diali

On Diali there is no host CLI to fall back to: the model route is the API key in the vault or the managed credits, and failover happens between providers rather than to a local binary. Hosted OpenClaw on Diali is the assistant and OpenClaw models and providers covers the providers that route can use.

• A fallback, not a primary path.
• Warm subprocess, native login, tools only through the bridge.
• Native Bash is allowlisted, never sandboxed, by OpenClaw.