OpenClaw CLIバックエンド設定：API障害時の自動フォールバック構築

開発を進めている最中に、お気に入りの AI API が突然ダウンしたり、レート制限に引っかかって作業が止まってしまったりすることはありませんか？そんな時、ローカルで動く CLI がバックアップとして控えていてくれたら心強いですよね。

OpenClaw では、API プロバイダーが利用できない場合や、一時的に動作が不安定な場合の「テキスト専用フォールバック」として、ローカル AI CLI を実行できます。これは意図的に保守的な設計になっています。

ツールは無効化されます（ツール呼び出しは行われません）。
テキスト入力 → テキスト出力（高い信頼性）。
セッションをサポート（後続のやり取りの整合性を維持）。
画像のパススルーが可能（CLI が画像パスを受け付ける場合）。

これはメインの経路というよりも、セーフティネットとして設計されています。外部 API に依存せず、「常に動作する」テキストレスポンスが必要な場合に使用してください。

初心者向けのクイックスタート

Claude Code CLI は、設定なしですぐに使用できます（同梱の Anthropic プラグインがデフォルトのバックエンドを登録します）。

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

Codex CLI も、同梱の OpenAI プラグイン経由でそのまま動作します。

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

Gateway を launchd や systemd で実行しており、PATH が最小限の場合は、コマンドのフルパスだけを追加してください。

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

設定はこれだけです。CLI 自体の認証以外に、API キーや追加の認証設定は必要ありません。

同梱の CLI バックエンドを Gateway ホストのプライマリメッセージプロバイダーとして使用する場合、設定内のモデル参照や agents.defaults.cliBackends でそのバックエンドが明示的に参照されると、OpenClaw は自動的に対応するプラグインをロードします。

フォールバックとしての利用

プライマリモデルが失敗したときにのみ実行されるよう、フォールバックリストに CLI バックエンドを追加しましょう。

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

注意点：

agents.defaults.models（許可リスト）を使用する場合は、claude-cli/... を含める必要があります。
プライマリプロバイダーが失敗（認証エラー、レート制限、タイムアウトなど）した場合、OpenClaw は次に CLI バックエンドを試行します。

設定の概要

すべての CLI バックエンドは以下の配下に設定します。

agents.defaults.cliBackends

各エントリは provider id（例：claude-cli, my-cli）をキーとします。この provider id がモデル参照の左側になります。

<provider>/<model>

設定例

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "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",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

動作の仕組み

プロバイダーのプレフィックス（claude-cli/...）に基づいてバックエンドを選択します。
OpenClaw のプロンプトとワークスペースのコンテキストを使用して、システムプロンプトを構築します。
セッション ID（サポートされている場合）を指定して CLI を実行し、履歴の整合性を保ちます。
出力をパース（JSON またはプレーンテキスト）し、最終的なテキストを返します。
バックエンドごとに セッション ID を保持するため、後続のやり取りで同じ CLI セッションを再利用できます。

セッション

CLI がセッションをサポートしている場合は、sessionArg（例：--session-id）を設定します。複数のフラグに ID を挿入する必要がある場合は sessionArgs（プレースホルダー {sessionId}）を使用してください。
CLI が異なるフラグを持つ resume サブコマンドを使用する場合は、resumeArgs（再開時に args を置き換える）を設定します。必要に応じて resumeOutput（JSON 以外の再開用）も設定可能です。
sessionMode:
- always: 常にセッション ID を送信します（保存されていない場合は新しい UUID を生成）。
- existing: セッション ID が保存されている場合のみ送信します。
- none: セッション ID を送信しません。

画像のパススルー

CLI が画像パスを受け付ける場合は、imageArg を設定してください。

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

OpenClaw は base64 画像を一時ファイルに書き出します。imageArg が設定されている場合、それらのパスが CLI 引数として渡されます。imageArg がない場合、OpenClaw はパスをプロンプトに直接追加（パスインジェクション）します。これは、プレーンなパスからローカルファイルを自動ロードする 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 が使用されます。

プラグインによるデフォルト設定

同梱の Anthropic プラグインは、claude-cli 用のデフォルトを登録しています。

command: "claude"
args: ["-p", "--output-format", "json", "--permission-mode", "bypassPermissions"]
resumeArgs: ["-p", "--output-format", "json", "--permission-mode", "bypassPermissions", "--resume", "{sessionId}"]
modelArg: "--model"
systemPromptArg: "--append-system-prompt"
sessionArg: "--session-id"
systemPromptWhen: "first"
sessionMode: "always"

同梱の OpenAI プラグインも、codex-cli 用のデフォルトを登録しています。

command: "codex"
args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
output: "jsonl"
resumeOutput: "text"
modelArg: "--model"
imageArg: "--image"
sessionMode: "existing"

同梱の Google プラグインも、google-gemini-cli 用のデフォルトを登録しています。

command: "gemini"
args: ["--prompt", "--output-format", "json"]
resumeArgs: ["--resume", "{sessionId}", "--prompt", "--output-format", "json"]
modelArg: "--model"
sessionMode: "existing"
sessionIdFields: ["session_id", "sessionId"]

これらは必要な場合のみ上書きしてください（よくある例：command を絶対パスにする）。

プラグイン固有のデフォルト設定

CLI バックエンドのデフォルト設定は、プラグインの機能の一部となりました。

プラグインは api.registerCliBackend(...) でこれらを登録します。
バックエンドの id が、モデル参照におけるプロバイダーのプレフィックスになります。
agents.defaults.cliBackends.<id> に記述されたユーザー設定は、引き続きプラグインのデフォルトを上書きします。
バックエンド固有の設定のクリーンアップは、オプションの normalizeConfig フックを通じてプラグイン側で管理されます。

制限事項

OpenClaw ツールは使用不可: CLI バックエンドはツール呼び出しを受け取りません。ただし、一部の CLI は独自のツールを実行する場合があります。
ストリーミング非対応: CLI の出力はすべて収集された後に返されます。
構造化出力: CLI の JSON フォーマットに依存します。
Codex CLI のセッション: テキスト出力（JSONL ではない）経由で再開されるため、最初の --json 実行時よりも構造化が弱くなります。OpenClaw のセッション自体は正常に動作します。

トラブルシューティング

CLI が見つからない: command にフルパスを設定してください。
モデル名が正しくない: modelAliases を使用して provider/model を CLI 用のモデル名にマッピングしてください。
セッションが継続しない: sessionArg が設定されており、sessionMode が none になっていないか確認してください（Codex CLI は現在 JSON 出力での再開ができません）。
画像が無視される: imageArg を設定してください（また、CLI がファイルパスをサポートしているか確認してください）。

AI Setup Assistant

次のステップ

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。