CLI backends

OpenClaw can run local AI CLIs as a text-only fallback when API providers are down, rate-limited, or temporarily misbehaving. This is intentionally conservative:

• OpenClaw tools are not injected directly, but backends with
  text

  Copy

  bundleMcp: true
  can receive gateway tools via a loopback MCP bridge.
• JSONL streaming for CLIs that support it.
• Sessions are supported (so follow-up turns stay coherent).
• Images can be passed through if the CLI accepts image paths.

This is designed as a safety net rather than a primary path. Use it when you want “always works” text responses without relying on external APIs.

If you want a full harness runtime with ACP session controls, background tasks, thread/conversation binding, and persistent external coding sessions, use ACP Agents instead. CLI backends are not ACP.

Beginner-friendly quick start

You can use Codex CLI without any config (the bundled OpenAI plugin registers a default backend):

bash
Copy
openclaw agent --message "hi" --model codex-cli/gpt-5.5

If your gateway runs under launchd/systemd and PATH is minimal, add just the command path:

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

That’s it. No keys, no extra auth config needed beyond the CLI itself.

If you use a bundled CLI backend as the primary message provider on a gateway host, OpenClaw now auto-loads the owning bundled plugin when your config explicitly references that backend in a model ref or under

.

Using it as a fallback

Add a CLI backend to your fallback list so it only runs when primary models fail:

json5
Copy
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["codex-cli/gpt-5.5"],
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "codex-cli/gpt-5.5": {},
      },
    },
  },
}

Notes:

• If you use
  text

  Copy

  agents.defaults.models
  (allowlist), you must include your CLI backend models there too.
• If the primary provider fails (auth, rate limits, timeouts), OpenClaw will try the CLI backend next.

Configuration overview

All CLI backends live under:

text
Copy
agents.defaults.cliBackends

Each entry is keyed by a provider id (e.g.

, ). The provider id becomes the left side of your model ref:

text
Copy
<provider>/<model>

Example configuration

json5
Copy
{
  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",
          // For CLIs with a dedicated prompt-file flag:
          // systemPromptFileArg: "--system-file",
          // Codex-style CLIs can point at a prompt file instead:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

How it works

1. Selects a backend based on the provider prefix (
   text

   Copy

   codex-cli/...
   ).
2. Builds a system prompt using the same OpenClaw prompt + workspace context.
3. Executes the CLI with a session id (if supported) so history stays consistent. The bundled
   text

   Copy

   claude-cli
   backend keeps a Claude stdio process alive per OpenClaw session and sends follow-up turns over stream-json stdin.
4. Parses output (JSON or plain text) and returns the final text.
5. Persists session ids per backend, so follow-ups reuse the same CLI session.

The bundled OpenAI

backend passes OpenClaw's system prompt through Codex's config override (). Codex does not expose a Claude-style flag, so OpenClaw writes the assembled prompt to a temporary file for each fresh Codex CLI session.

The bundled Anthropic

backend receives the OpenClaw skills snapshot two ways: the compact OpenClaw skills catalog in the appended system prompt, and a temporary Claude Code plugin passed with . The plugin contains only the eligible skills for that agent/session, so Claude Code's native skill resolver sees the same filtered set that OpenClaw would otherwise advertise in the prompt. Skill env/API key overrides are still applied by OpenClaw to the child process environment for the run.

Claude CLI also has its own noninteractive permission mode. OpenClaw maps that to the existing exec policy instead of adding Claude-specific config: when the effective requested exec policy is YOLO (

and ), OpenClaw adds . Per-agent settings override global for that agent. To force a different Claude mode, set explicit raw backend args such as or under and matching .

Before OpenClaw can use the bundled

backend, Claude Code itself must already be logged in on the same host:

bash
Copy
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

Use

only when the binary is not already on .

Sessions

• If the CLI supports sessions, set
  text

  Copy

  sessionArg
  (e.g.
  text

  Copy

  --session-id
  ) or
  text

  Copy

  sessionArgs
  (placeholder
  text

  Copy

  {sessionId}
  ) when the ID needs to be inserted into multiple flags.
• If the CLI uses a resume subcommand with different flags, set
  text

  Copy

  resumeArgs
  (replaces
  text

  Copy

  args
  when resuming) and optionally
  text

  Copy

  resumeOutput
  (for non-JSON resumes).
• text

  Copy

  sessionMode
  :
  • text

    Copy

    always
    : always send a session id (new UUID if none stored).
  • text

    Copy

    existing
    : only send a session id if one was stored before.
  • text

    Copy

    none
    : never send a session id.
• text

  Copy

  claude-cli
  defaults to
  text

  Copy

  liveSession: "claude-stdio"
  ,
  text

  Copy

  output: "jsonl"
  , and
  text

  Copy

  input: "stdin"
  so follow-up turns reuse the live Claude process while it is active. Warm stdio is the default now, including for custom configs that omit transport fields. If the Gateway restarts or the idle process exits, OpenClaw resumes from the stored Claude session id. Stored session ids are verified against an existing readable project transcript before resume, so phantom bindings are cleared with
  text

  Copy

  reason=transcript-missing
  instead of silently starting a fresh Claude CLI session under
  text

  Copy

  --resume
  .
• Stored CLI sessions are provider-owned continuity. The implicit daily session reset does not cut them;
  text

  Copy

  /reset
  and explicit
  text

  Copy

  session.reset
  policies still do.

Serialization notes:

• text

  Copy

  serialize: true
  keeps same-lane runs ordered.
• Most CLIs serialize on one provider lane.
• OpenClaw drops stored CLI session reuse when the selected auth identity changes, including a changed auth profile id, static API key, static token, or OAuth account identity when the CLI exposes one. OAuth access and refresh token rotation does not cut the stored CLI session. If a CLI does not expose a stable OAuth account id, OpenClaw lets that CLI enforce resume permissions.

Fallback prelude from claude-cli sessions

When a

attempt fails over to a non-CLI candidate in

text

Copy

agents.defaults.model.fallbacks

, OpenClaw seeds the next attempt with a context prelude harvested from Claude Code's local JSONL transcript at . Without this seed, the fallback provider would start cold because OpenClaw's own session transcript is empty for runs.

• The prelude prefers the latest
  text

  Copy

  /compact
  summary or
  text

  Copy

  compact_boundary
  marker, then appends the most recent post-boundary turns up to a char budget. Pre-boundary turns are dropped because the summary already represents them.
• Tool blocks are coalesced to compact
  text

  Copy

  (tool call: name)
  and
  text

  Copy

  (tool result: …)
  hints to keep the prompt budget honest. The summary is labeled
  text

  Copy

  (truncated)
  if it overflows.
• Same-provider
  text

  Copy

  claude-cli
  to
  text

  Copy

  claude-cli
  fallbacks rely on Claude's own
  text

  Copy

  --resume
  and skip the prelude.
• The seed reuses the existing Claude session-file path validation, so arbitrary paths cannot be read.

Images (pass-through)

If your CLI accepts image paths, set

:

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

OpenClaw will write base64 images to temp files. If

is set, those paths are passed as CLI args. If is missing, OpenClaw appends the file paths to the prompt (path injection), which is enough for CLIs that auto- load local files from plain paths.

Inputs / outputs

• text

  Copy

  output: "json"
  (default) tries to parse JSON and extract text + session id.
• For Gemini CLI JSON output, OpenClaw reads reply text from
  text

  Copy

  response
  and usage from
  text

  Copy

  stats
  when
  text

  Copy

  usage
  is missing or empty.
• text

  Copy

  output: "jsonl"
  parses JSONL streams (for example Codex CLI
  text

  Copy

  --json
  ) and extracts the final agent message plus session identifiers when present.
• text

  Copy

  output: "text"
  treats stdout as the final response.

Input modes:

• text

  Copy

  input: "arg"
  (default) passes the prompt as the last CLI arg.
• text

  Copy

  input: "stdin"
  sends the prompt via stdin.
• If the prompt is very long and
  text

  Copy

  maxPromptArgChars
  is set, stdin is used.

Defaults (plugin-owned)

The bundled OpenAI plugin also registers a default for

:

• text

  Copy

  command: "codex"
• text

  Copy

  args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
• text

  Copy

  resumeArgs: ["exec","resume","{sessionId}","-c","sandbox_mode=\"workspace-write\"","--skip-git-repo-check"]
• text

  Copy

  output: "jsonl"
• text

  Copy

  resumeOutput: "text"
• text

  Copy

  modelArg: "--model"
• text

  Copy

  imageArg: "--image"
• text

  Copy

  sessionMode: "existing"

The bundled Google plugin also registers a default for

:

• text

  Copy

  command: "gemini"
• text

  Copy

  args: ["--output-format", "json", "--prompt", "{prompt}"]
• text

  Copy

  resumeArgs: ["--resume", "{sessionId}", "--output-format", "json", "--prompt", "{prompt}"]
• text

  Copy

  imageArg: "@"
• text

  Copy

  imagePathScope: "workspace"
• text

  Copy

  modelArg: "--model"
• text

  Copy

  sessionMode: "existing"
• text

  Copy

  sessionIdFields: ["session_id", "sessionId"]

Prerequisite: the local Gemini CLI must be installed and available as

on ( or ).

Gemini CLI JSON notes:

• Reply text is read from the JSON
  text

  Copy

  response
  field.
• Usage falls back to
  text

  Copy

  stats
  when
  text

  Copy

  usage
  is absent or empty.
• text

  Copy

  stats.cached
  is normalized into OpenClaw
  text

  Copy

  cacheRead
  .
• If
  text

  Copy

  stats.input
  is missing, OpenClaw derives input tokens from
  text

  Copy

  stats.input_tokens - stats.cached
  .

Override only if needed (common: absolute

path).

Plugin-owned defaults

CLI backend defaults are now part of the plugin surface:

• Plugins register them with
  text

  Copy

  api.registerCliBackend(...)
  .
• The backend
  text

  Copy

  id
  becomes the provider prefix in model refs.
• User config in
  text

  Copy

  agents.defaults.cliBackends.<id>
  still overrides the plugin default.
• Backend-specific config cleanup stays plugin-owned through the optional
  text

  Copy

  normalizeConfig
  hook.

Plugins that need tiny prompt/message compatibility shims can declare bidirectional text transforms without replacing a provider or CLI backend:

typescript
Copy
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" },
  ],
});

rewrites the system prompt and user prompt passed to the CLI. rewrites streamed assistant deltas and parsed final text before OpenClaw handles its own control markers and channel delivery.

For CLIs that emit Claude Code stream-json compatible JSONL, set

on that backend's config.

Bundle MCP overlays

CLI backends do not receive OpenClaw tool calls directly, but a backend can opt into a generated MCP config overlay with

.

Current bundled behavior:

• text

  Copy

  claude-cli
  : generated strict MCP config file
• text

  Copy

  codex-cli
  : inline config overrides for
  text

  Copy

  mcp_servers
  ; the generated OpenClaw loopback server is marked with Codex's per-server tool approval mode so MCP calls cannot stall on local approval prompts
• text

  Copy

  google-gemini-cli
  : generated Gemini system settings file

When bundle MCP is enabled, OpenClaw:

• spawns a loopback HTTP MCP server that exposes gateway tools to the CLI process
• authenticates the bridge with a per-session token (
  text

  Copy

  OPENCLAW_MCP_TOKEN
  )
• scopes tool access to the current session, account, and channel context
• loads enabled bundle-MCP servers for the current workspace
• merges them with any existing backend MCP config/settings shape
• rewrites the launch config using the backend-owned integration mode from the owning extension

If no MCP servers are enabled, OpenClaw still injects a strict config when a backend opts into bundle MCP so background runs stay isolated.

Session-scoped bundled MCP runtimes are cached for reuse within a session, then reaped after

milliseconds of idle time (default 10 minutes; set to disable). One-shot embedded runs such as auth probes, slug generation, and active-memory recall request cleanup at run end so stdio children and Streamable HTTP/SSE streams do not outlive the run.

Limitations

• No direct OpenClaw tool calls. OpenClaw does not inject tool calls into the CLI backend protocol. Backends only see gateway tools when they opt into
  text

  Copy

  bundleMcp: true
  .
• Streaming is backend-specific. Some backends stream JSONL; others buffer until exit.
• Structured outputs depend on the CLI’s JSON format.
• Codex CLI sessions resume via text output (no JSONL), which is less structured than the initial
  text

  Copy

  --json
  run. OpenClaw sessions still work normally.

Troubleshooting

• CLI not found: set
  text

  Copy

  command
  to a full path.
• Wrong model name: use
  text

  Copy

  modelAliases
  to map
  text

  Copy

  provider/model
  → CLI model.
• No session continuity: ensure
  text

  Copy

  sessionArg
  is set and
  text

  Copy

  sessionMode
  is not
  text

  Copy

  none
  (Codex CLI currently cannot resume with JSON output).
• Images ignored: set
  text

  Copy

  imageArg
  (and verify CLI supports file paths).

Related

• Gateway runbook
• Local models