CLI backends（CLI バックエンド）（フォールバックランタイム）

OpenClaw は、API プロバイダーがダウン、レート制限、または一時的に不調な場合の テキスト専用フォールバック として ローカル 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

ゲートウェイが 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": {}
      }
    }
  }
}

注意事項：

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

設定概要

すべての CLI バックエンドは以下の配下にあります：

agents.defaults.cliBackends

各エントリは プロバイダー ID（例：claude-cli、my-cli）でキー付けされます。プロバイダー 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-5": "opus",
            "claude-sonnet-4-5": "sonnet"
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true
        }
      }
    }
  }
}

動作方法

  1. バックエンドを選択 プロバイダープレフィックス（claude-cli/...）に基づいて。
  2. システムプロンプトを構築 同じ OpenClaw プロンプト + ワークスペースコンテキストを使用。
  3. CLI を実行 セッション ID を使用（サポートされている場合）して、履歴が一貫性を保つようにします。
  4. 出力を解析（JSON またはプレーンテキスト）して、最終テキストを返します。
  5. セッション ID を永続化 バックエンドごとに、フォローアップが同じ CLI セッションを再利用するようにします。

セッション

  • CLI がセッションをサポートする場合は、sessionArg（例：--session-id）または sessionArgs（ID を複数のフラグに挿入する必要がある場合のプレースホルダー {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" はプロンプトを標準入力経由で送信します。
  • プロンプトが非常に長く、maxPromptArgChars が設定されている場合は、標準入力が使用されます。

デフォルト（組み込み）

OpenClaw には 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"

OpenClaw には 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 パス）。

制限事項

  • 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 がファイルパスをサポートしていることを確認してください）。
← ドキュメントに戻る