CLI バックエンド

API プロバイダーが落ちた/レート制限された/一時的に不安定なとき、OpenClaw はローカル AI CLIをテキスト専用フォールバックとして実行できます。

これは意図的に保守的です：

• ツールは無効（ツール呼び出しなし）。
• テキスト入力 → テキスト出力（堅牢）。
• セッション対応（後続ターンの一貫性）。
• 画像のパススルー（CLI が画像パスを受け取れる場合）。

これはセーフティネットであり、主経路ではありません。

外部 API に依存せずに「とにかく動く」テキスト応答が欲しい場合に使います。

Claude Code CLI は設定ゼロで使えます（OpenClaw が内蔵デフォルトを持ちます）：

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

Codex CLI もそのまま動くことがあります：

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

これで完了。CLI 自体以外に追加の認証設定やキーは不要です。

CLI バックエンドをフォールバックリストに追加し、プライマリが失敗したときだけ実行させます：

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

Notes:

• agents.defaults.models（ホワイトリスト）を使っている場合、claude-cli/... を含める必要があります。
• プライマリが失敗（認証、レート制限、タイムアウト）すると、OpenClaw は次に CLI バックエンドを試します。

CLI バックエンドは次に置きます：

agents.defaults.cliBackends

各エントリはプロバイダー ID（例：claude-cli、my-cli）でキー付けされます。

プロバイダー ID はモデル参照の左側になります：

<provider>/<model>

1. プロバイダー接頭辞（claude-cli/...）でバックエンドを選択。
2. 同じ OpenClaw プロンプト + ワークスペース文脈でsystem prompt を構築。
3. （対応していれば）セッション ID 付きでCLI を実行し、履歴の一貫性を保つ。
4. （JSON またはテキスト）を解析して最終テキストを返す。
5. バックエンドごとにセッション ID を保存し、後続ターンで同じ CLI セッションを再利用。

• CLI がセッション対応なら、sessionArg（例：--session-id）を設定するか、ID を複数フラグに分割する必要がある場合は sessionArgs（{{sessionId}}）を設定します。
• CLI が別のresume サブコマンドを使う場合、resumeArgs（resume 時に args の代わりに使用）と、必要なら resumeOutput（JSON 以外の resume 出力）を設定します。

sessionMode：

• always：常にセッション ID を送る（保存がなければ新規 UUID を生成）。
• existing：以前に保存したセッション ID がある場合のみ送る。
• none：セッション ID を送らない。

CLI が画像パスを受け取れるなら 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).

imageArg がない場合、OpenClaw はプロンプト末尾にファイルパスを付与します（path injection）。通常のパスからローカルファイルを読み込める CLI ならこれで十分です（Claude Code CLI の挙動）。

出力モード：

• output: "json"（デフォルト）：JSON を解析してテキスト + セッション ID を抽出。
• output: "jsonl"：JSONL ストリーム（Codex CLI の --json）を解析し、最後のアシスタントメッセージ + thread_id（あれば）を抽出。
• output: "text"：stdout を最終応答として扱う。

入力モード：

• input: "arg"（デフォルト）：プロンプトを最後の CLI 引数として渡す。
• input: "stdin"：stdin 経由でプロンプトを送る。
• プロンプトが長く maxPromptArgChars が設定されている場合は stdin を使う。

OpenClaw は内蔵デフォルトを持つため、通常は必要な箇所だけ上書きします。

claude-cli の内蔵デフォルト：

• command: "claude"
• args: ["-p", "--output-format", "json", "--dangerously-skip-permissions"]
• ReferenceGatewayCliBackendsPage.steps.defaults.claude.resumeArgs
• 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"]
• ReferenceGatewayCliBackendsPage.steps.defaults.codex.resumeArgs
• output: "jsonl"
• resumeOutput: "text"
• modelArg: "--model"
• imageArg: "--image"
• sessionMode: "existing"

必要な場合のみ上書き（多くは絶対 command パス）。

• OpenClaw ツールなし（CLI バックエンドはツール呼び出しを受け取りません）。ただし CLI 自体が独自ツールを動かす可能性はあります。
• ストリーミングなし（CLI 出力を集めてから返す）。
• 構造化出力は CLI の JSON 形式に依存します。
• Codex CLI セッションはテキスト出力（JSONL なし）で resume され、初回の --json 実行より構造化が弱いですが、OpenClaw セッションは通常問題ありません。

• CLI が見つからない：command をフルパスにする。
• モデル名が違う：modelAliases で provider/model → CLI モデルをマップ。
• セッション継続がない：sessionArg を設定し、sessionMode が none でないこと（Codex CLI は現状 JSON 出力の resume ができません）。
• 画像が無視される：imageArg を設定（CLI がファイルパスを扱えることも確認）。