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

OpenClawは、APIプロバイダーがダウン、レート制限、または一時的な不具合の際に、ローカルAI CLIをテキストオンリーのフォールバックとして実行できます。意図的に保守的な設計です：

  • ツールは無効（ツール呼び出しなし）
  • テキスト入力 → テキスト出力（確実）
  • セッション対応（フォローアップのターンも一貫性を保つ）
  • 画像の受け渡し可能（CLIが画像パスを受け付ける場合）

これは主要パスではなく、セーフティネットとして設計されています。外部APIに依存せず「常に動作する」テキスト応答が必要な場合に使用してください。

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

Claude Code CLIは設定なしで使用できます（OpenClawにはビルトインのデフォルトが含まれています）：

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

Codex CLIもそのまま動作します：

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

ゲートウェイがlaunchd/systemdで実行されていてPATHが最小限の場合は、コマンドパスだけを追加します：

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

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

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

プライマリモデルが失敗した場合にのみ実行されるよう、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

各エントリはプロバイダー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-6": "opus",
            "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. セッションID（対応している場合）を使用してCLIを実行し、履歴の一貫性を維持。
  4. 出力をパース（JSONまたはプレーンテキスト）し、最終テキストを返却。
  5. バックエンドごとにセッションIDを永続化し、フォローアップで同じCLIセッションを再利用。

セッション

  • CLIがセッションをサポートする場合、sessionArg（例：--session-id）を設定するか、IDを複数のフラグに挿入する必要がある場合はsessionArgs（プレースホルダー{sessionId}）を設定します。
  • CLIが再開サブコマンドで異なるフラグを使用する場合は、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が使用されます。

デフォルト（ビルトイン）

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

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がファイルパスをサポートしていることも確認）。
arrow_back
前へ
Tools Invoke HTTP API
次へ
Local Models
arrow_forward