CLI backends

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• OpenClaw tools are not injected directly, but backends with 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.

​

Beginner-friendly quick start

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

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

​

Using it as a fallback

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

• If you use 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

agents.defaults.cliBackends

<provider>/<model>

​

Example configuration

{
  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 (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 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.

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

​

Sessions

• If the CLI supports sessions, set sessionArg (e.g. --session-id) or sessionArgs (placeholder {sessionId}) when the ID needs to be inserted into multiple flags.
• If the CLI uses a resume subcommand with different flags, set resumeArgs (replaces args when resuming) and optionally resumeOutput (for non-JSON resumes).
• sessionMode:
  • always: always send a session id (new UUID if none stored).
  • existing: only send a session id if one was stored before.
  • none: never send a session id.
• claude-cli defaults to liveSession: "claude-stdio", output: "jsonl", and 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 reason=transcript-missing instead of silently starting a fresh Claude CLI session under --resume.
• Stored CLI sessions are provider-owned continuity. The implicit daily session reset does not cut them; /reset and explicit session.reset policies still do.

• 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

• The prelude prefers the latest /compact summary or 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 (tool call: name) and (tool result: …) hints to keep the prompt budget honest. The summary is labeled (truncated) if it overflows.
• Same-provider claude-cli to claude-cli fallbacks rely on Claude’s own --resume and skip the prelude.
• The seed reuses the existing Claude session-file path validation, so arbitrary paths cannot be read.

​

Images (pass-through)

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

​

Inputs / outputs

• output: "json" (default) tries to parse JSON and extract text + session id.
• For Gemini CLI JSON output, OpenClaw reads reply text from response and usage from stats when usage is missing or empty.
• output: "jsonl" parses JSONL streams (for example Codex CLI --json) and extracts the final agent message plus session identifiers when present.
• output: "text" treats stdout as the final response.

• input: "arg" (default) passes the prompt as the last CLI arg.
• input: "stdin" sends the prompt via stdin.
• If the prompt is very long and maxPromptArgChars is set, stdin is used.

​

Defaults (plugin-owned)

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

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

• Reply text is read from the JSON response field.
• Usage falls back to stats when usage is absent or empty.
• stats.cached is normalized into OpenClaw cacheRead.
• If stats.input is missing, OpenClaw derives input tokens from stats.input_tokens - stats.cached.

​

Plugin-owned defaults

• Plugins register them with api.registerCliBackend(...).
• The backend id becomes the provider prefix in model refs.
• User config in agents.defaults.cliBackends.<id> still overrides the plugin default.
• Backend-specific config cleanup stays plugin-owned through the optional normalizeConfig hook.

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

• claude-cli: generated strict MCP config file
• codex-cli: inline config overrides for 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
• google-gemini-cli: generated Gemini system settings file

• spawns a loopback HTTP MCP server that exposes gateway tools to the CLI process
• authenticates the bridge with a per-session token (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

​

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 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 --json run. OpenClaw sessions still work normally.

​

Troubleshooting

• CLI not found: set command to a full path.
• Wrong model name: use modelAliases to map provider/model → CLI model.
• No session continuity: ensure sessionArg is set and sessionMode is not none (Codex CLI currently cannot resume with JSON output).
• Images ignored: set imageArg (and verify CLI supports file paths).

​

Related

• Gateway runbook
• Local models