​

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

• OpenClawのツールは直接注入されません。ただし bundleMcp: true のバックエンド（Claude CLIのデフォルト）は、local loopback MCPブリッジ経由でGatewayツールを受け取れます。
• JSONLストリーミング（Claude CLIは --output-format stream-json と --include-partial-messages を使用し、プロンプトはstdin経由で送信されます）。
• セッションに対応しています（そのため、後続ターンでも一貫性が保たれます）。
• CLIが画像パスを受け付ける場合、画像をそのまま渡せます。

​

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

openclaw agent --message "hi" --model claude-cli/claude-sonnet-4-6

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

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

​

フォールバックとして使う

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

• agents.defaults.models（allowlist）を使う場合は、claude-cli/... も含める必要があります。
• 主要プロバイダーが失敗した場合（認証、レート制限、タイムアウト）、OpenClawは次に CLIバックエンドを試します。
• 同梱のClaude CLIバックエンドは引き続き claude-cli/opus、claude-cli/opus-4.6、claude-cli/sonnet のような短いエイリアスも受け付けますが、 ドキュメントと設定例では正規の claude-cli/claude-* refを使用します。

​

設定概要

agents.defaults.cliBackends

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

​

仕組み

1. バックエンドを選択します。選択基準はprovider接頭辞（claude-cli/...）です。
2. 同じOpenClawプロンプト + ワークスペースコンテキストを使ってシステムプロンプトを構築します。
3. 対応している場合はセッションid付きでCLIを実行し、履歴の一貫性を保ちます。
4. 出力を解析し（JSONまたはプレーンテキスト）、最終テキストを返します。
5. バックエンドごとにセッションidを永続化し、後続ターンで同じCLIセッションを再利用します。

​

セッション

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

• serialize: true は、同一レーンでの実行順序を保ちます。
• ほとんどのCLIは、1つのproviderレーン上でシリアライズされます。
• claude-cli はより狭く、再開実行はClaudeセッションidごとにシリアライズされ、 新規実行はワークスペースパスごとにシリアライズされます。独立したワークスペースは並列実行できます。
• OpenClawは、バックエンドの認証状態が変化した場合、 relogin、トークンローテーション、またはauth profile credentialの変更を含めて、 保存済みCLIセッションの再利用を破棄します。

​

画像（そのまま渡す）

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

​

入力 / 出力

• output: "json"（デフォルト）は、JSONを解析し、テキスト + セッションidの抽出を試みます。
• Gemini CLIのJSON出力では、usage が欠けているか空の場合、 OpenClawは返信テキストを response から、usageを stats から読み取ります。
• output: "jsonl" はJSONLストリーム（たとえばClaude CLIの stream-json やCodex CLIの --json）を解析し、最終エージェントメッセージと、 存在する場合はセッション識別子を抽出します。
• output: "text" はstdoutを最終応答として扱います。

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

​

デフォルト（plugin所有）

• command: "claude"
• args: ["-p", "--output-format", "stream-json", "--include-partial-messages", "--verbose", "--permission-mode", "bypassPermissions"]
• resumeArgs: ["-p", "--output-format", "stream-json", "--include-partial-messages", "--verbose", "--permission-mode", "bypassPermissions", "--resume", "{sessionId}"]
• output: "jsonl"
• input: "stdin"
• modelArg: "--model"
• systemPromptArg: "--append-system-prompt"
• sessionArg: "--session-id"
• systemPromptWhen: "first"
• sessionMode: "always"

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

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

• 返信テキストはJSONの response フィールドから読み取られます。
• usage が存在しないか空の場合、usageは stats にフォールバックします。
• stats.cached はOpenClawの cacheRead に正規化されます。
• stats.input が欠けている場合、OpenClawは入力トークンを stats.input_tokens - stats.cached から導出します。

​

plugin所有のデフォルト

• pluginは api.registerCliBackend(...) でそれらを登録します。
• バックエンドの id が、モデルrefのprovider接頭辞になります。
• agents.defaults.cliBackends.<id> にあるユーザー設定は、引き続きpluginデフォルトを上書きします。
• バックエンド固有の設定クリーンアップは、オプションの normalizeConfig フックを通じてplugin所有のままです。

​

Bundle MCPオーバーレイ

• claude-cli: bundleMcp: true（デフォルト）
• codex-cli: bundle MCPオーバーレイなし
• google-gemini-cli: bundle MCPオーバーレイなし

• GatewayツールをCLIプロセスに公開するlocal loopback HTTP MCPサーバーを起動する
• セッションごとのトークン（OPENCLAW_MCP_TOKEN）でブリッジを認証する
• ツールアクセスを現在のセッション、アカウント、チャンネルコンテキストに限定する
• 現在のワークスペースで有効なbundle-MCPサーバーを読み込む
• それらを既存のバックエンド --mcp-config とマージする
• CLI引数を書き換えて --strict-mcp-config --mcp-config <generated-file> を渡す

​

制限事項

• OpenClawツール呼び出しの直接注入はありません。 OpenClawは CLIバックエンドプロトコルにツール呼び出しを注入しません。ただし、bundleMcp: true のバックエンド（Claude CLIのデフォルト）は、 local loopback MCPブリッジ経由でGatewayツールを受け取るため、 Claude CLIはネイティブMCPサポートを通じてOpenClawツールを呼び出せます。
• ストリーミングはバックエンド依存です。 Claude CLIはJSONLストリーミング （--include-partial-messages 付きの stream-json）を使いますが、ほかのCLIバックエンドは 終了までバッファリングされる場合があります。
• 構造化出力は、そのCLIのJSON形式に依存します。
• Codex CLIセッションはテキスト出力経由で再開されます（JSONLではありません）。これは 初回の --json 実行より構造化が弱いですが、OpenClawセッション自体は通常どおり動作します。

​

トラブルシューティング

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