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:

这被设计为**安全网**而不是主要路径。当您想要"始终有效"的文本响应而不依赖外部 API 时使用它。

• **Tools are disabled** (no tool calls).
• 文本输入 → 文本输出（堅牢）。
• 会话対応（後続轮的一貫性）。
• **Images can be passed through** if the CLI accepts image paths.

这被设计为**安全网**而不是主要路径。当您想要"始终有效"的文本响应而不依赖外部 API 时使用它。

当您想要"始终有效"的文本响应而不依赖外部 API 时使用它。

You can use Claude Code CLI without any config (OpenClaw ships a built-in default):

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

Codex CLI also works out of the box:

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

Gateway 但 launchd/systemd 配下在 PATH 但最小的場合是、命令路径仅添加执行：

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

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

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

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: ["claude-cli/opus-4.5"],
      },
      models: {
        "anthropic/claude-opus-4-5": { alias: "Opus" },
        "claude-cli/opus-4.5": {},
      },
    },
  },
}

注意：

• If you use agents.defaults.models (allowlist), you must include claude-cli/....
• 如果主要提供商失败（认证、速率限制、超时），OpenClaw 将尝试 CLI 后端。

All CLI backends live under:

agents.defaults.cliBackends

每个条目是提供商 ID（示示例：claude-cli、my-cli）在密钥付可被。

提供商 ID 是模型参照的左側变为：

<provider>/<model>

1. Selects a backend based on the provider prefix (claude-cli/...).
2. 同自 OpenClaw 提示词 + 工作区文脈在system prompt 構築。
3. Executes the CLI with a session id (if supported) so history stays consistent.
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.

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

If your CLI accepts image paths, set imageArg:

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

OpenClaw will write base64 images to temp files. If imageArg is set, those paths are passed as CLI args. If imageArg 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 (Claude Code CLI behavior).

If imageArg 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 (Claude Code CLI behavior).

Output modes:

• output: "json" (default): parse JSON and extract text + session id.
• output: "jsonl": parse JSONL streams (Codex CLI --json) and extract the last agent message plus thread_id when present.
• output: "text"：stdout 最終応答作为扱有。

Input modes:

• input: "arg" (default) passes the prompt as the last CLI arg.
• input: "stdin" sends the prompt via stdin.
• 提示词但長可 maxPromptArgChars 但设置如果已被是 stdin 使有。

OpenClaw ships built-in defaults so you usually only need to override what's necessary.

claude-cli 的内蔵默认：

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

codex-cli 的内蔵默认：

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

必要那場合仅上写机（多可是絶対 command 路径）。

• No OpenClaw tools (CLI backends don't receive tool calls). However, the CLI itself may run its own tools.
• No streaming (CLI output is collected before returning).
• 構造化输出是 CLI 的 JSON 形式在依赖执行。
• Codex CLI sessions resume via text output (no JSONL), which is less structured than the initial --json run. OpenClaw sessions still work normally.

• CLI not found: set command to a full path.
• 模型名但違有：modelAliases 在 provider/model → CLI 模型映射。
• 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).