CLI バックエンド

• OpenClaw ツールは直接注入されませんが、bundleMcp: true のバックエンドは loopback MCP ブリッジを通じて Gateway ツールを受け取れます。
• 対応する CLI 向けの JSONL ストリーミング。
• セッションに対応しているため、後続ターンの一貫性が保たれます。
• CLI が画像パスを受け付ける場合、画像はそのまま渡されます。

​

クイックスタート

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

{
  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"],
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "claude-cli/claude-sonnet-4-6": {},
      },
    },
  },
}

​

設定

{
  agents: {
    defaults: {
      cliBackends: {
        "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",
          // Dedicated prompt-file flag:
          // systemPromptFileArg: "--system-file",
          // Codex-style config-override flag instead:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          // Opt in only if this backend may reseed invalidated sessions from
          // bounded raw OpenClaw transcript history before compaction.
          reseedFromRawTranscriptWhenUncompacted: true,
          serialize: true,
        },
      },
    },
  },
}

​

仕組み

1. プロバイダープレフィックス（claude-cli/...）でバックエンドを選択します。
2. 同じ OpenClaw プロンプトとワークスペースコンテキストを使ってシステムプロンプトを構築します。
3. セッション ID（対応している場合）を指定して CLI を実行し、履歴の一貫性を保ちます。バンドル済みの claude-cli バックエンドは、OpenClaw セッションごとに Claude stdio プロセスを生かし続け、後続ターンを stream-json stdin 経由で送信します。
4. 出力（JSON またはプレーンテキスト）を解析し、最終テキストを返します。
5. バックエンドごとにセッション ID を永続化し、後続ターンが同じ CLI セッションを再利用できるようにします。

​

Claude CLI の詳細

claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

​

セッション

• CLI がセッションに対応している場合は、sessionArg（例: --session-id）を設定します。ID を複数のフラグに入れる必要がある場合は、sessionArgs（プレースホルダー {sessionId}）を設定します。
• CLI が異なるフラグの resume サブコマンドを使う場合は、resumeArgs（再開時に args を置き換える）を設定し、必要に応じて非 JSON 再開用に resumeOutput を設定します。
• sessionMode:
  • always: 常にセッション ID を送信します（保存済みがなければ新しい UUID）。
  • existing: 以前に保存されたセッション ID がある場合のみ送信します。
  • none: セッション ID を送信しません。
• claude-cli はデフォルトで liveSession: "claude-stdio"、output: "jsonl"、input: "stdin" になるため、トランスポートフィールドを省略したカスタム設定を含め、アクティブな間は後続ターンがライブ Claude プロセスを再利用します。Gateway が再起動した場合、またはアイドルプロセスが終了した場合、OpenClaw は保存済みの Claude セッション ID から再開します。保存済みセッション ID は、再開前に読み取り可能なプロジェクトトランスクリプトに照合して検証されます。トランスクリプトがない場合は、--resume の下で暗黙に新規セッションを開始するのではなく、バインディングをクリアします（reason=transcript-missing としてログ記録）。
• Claude ライブセッションは、デフォルトでターンごとに 8 MiB と 20,000 行の生 JSONL 出力ガードを維持します。バックエンドごとに agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars と maxTurnLines で引き上げられます。OpenClaw はこれらの設定を 64 MiB と 100,000 行にクランプします。
• 保存済み CLI セッションは、プロバイダー所有の継続性です。暗黙の日次セッションリセットでは切断されません。/reset と明示的な session.reset ポリシーでは引き続き切断されます。
• 新しい CLI セッションは通常、OpenClaw の Compaction サマリーと Compaction 後の末尾だけから再シードします。Compaction 前に無効化された短いセッションを復旧するには、バックエンドが reseedFromRawTranscriptWhenUncompacted: true でオプトインできます。生トランスクリプトの再シードは、CLI トランスクリプトの欠落、孤立した tool-use 末尾、メッセージポリシー/システムプロンプト/cwd/MCP の変更、またはセッション期限切れリトライなど、安全な無効化に限定され、範囲も制限されます。認証プロファイルまたは認証情報 epoch の変更では、生トランスクリプト履歴は決して再シードされません。

​

claude-cli セッションからのフォールバック前置き

• 前置きは最新の /compact サマリーまたは compact_boundary マーカーを優先し、その後、文字数予算まで境界後の最新ターンを追加します。境界前のターンは、すでにサマリーで表現されているため破棄されます。
• ツールブロックは、プロンプト予算を正直に保つため、コンパクトな (tool call: name) と (tool result: …) ヒントに統合されます。大きすぎるサマリーは切り詰められ、(truncated) とラベル付けされます。
• 同一プロバイダーの claude-cli から claude-cli へのフォールバックは、Claude 自身の --resume に依存し、前置きをスキップします。
• このシードは既存の Claude セッションファイルパス検証を再利用するため、任意のパスを読み取ることはできません。

​

画像

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

​

入力と出力

• output: "text"（デフォルト）は stdout を最終応答として扱います。
• output: "json" は JSON の解析を試み、テキストとセッション ID を抽出します。
• output: "jsonl" は JSONL ストリームを解析し、最終エージェントメッセージと、存在する場合はセッション識別子を抽出します。
• Gemini CLI の JSON 出力では、usage がないか空の場合、OpenClaw は返信テキストを response から、使用量を stats から読み取ります。バンドル済み Gemini CLI のデフォルトは stream-json を使います。古い --output-format json 上書きは引き続き JSON パーサーを使います。

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

​

Plugin 所有のデフォルト

• Plugin は api.registerCliBackend(...) でそれらを登録します。
• バックエンドの id はモデル参照内のプロバイダープレフィックスになります。
• agents.defaults.cliBackends.<id> のユーザー設定は、引き続き Plugin デフォルトを上書きします。
• バックエンド固有の設定クリーンアップは、任意の normalizeConfig フックを通じて Plugin 所有のままです。

• デフォルトの stream-json パーサーは、アシスタントの message イベント、ツールイベント、最終 result の使用量、致命的な Gemini エラーイベントを読み取ります。
• Gemini の引数を --output-format json に上書きした場合、OpenClaw はそのバックエンドを output: "json" に正規化し、JSON の response フィールドから返信テキストを読み取ります。
• usage が存在しないか空の場合、使用量は stats にフォールバックします。stats.cached は OpenClaw の cacheRead に正規化され、stats.input が欠落している場合、入力トークンは stats.input_tokens - stats.cached から導出されます。

​

テキスト変換オーバーレイ

api.registerTextTransforms({
  input: [{ from: /red basket/g, to: "blue basket" }],
  output: [{ from: /blue basket/g, to: "red basket" }],
});

​

ネイティブ Compaction の所有権

api.registerCliBackend({ id: "my-cli", ownsNativeCompaction: true /* ... */ });

​

バンドル MCP オーバーレイ

• claude-cli: 生成された厳格な MCP 設定ファイル。
• google-gemini-cli: 生成された Gemini システム設定ファイル。

• CLI プロセスに Gateway ツールを公開する loopback HTTP MCP サーバーを起動し、セッションごとのトークン（OPENCLAW_MCP_TOKEN）で認証します。
• ツールアクセスを現在のセッション、アカウント、チャネルコンテキストにスコープします。
• 現在のワークスペースで有効なバンドル MCP サーバーを読み込み、既存のバックエンド MCP 設定/設定形状とマージします。
• 所有 Plugin からのバックエンド所有の統合モードを使って起動設定を書き換えます。

​

再シード履歴上限

​

制限事項

• OpenClaw ツール呼び出しを直接使用できません: OpenClaw は CLI バックエンドプロトコルにツール呼び出しを注入しません。バックエンドが Gateway ツールを参照できるのは、bundleMcp: true にオプトインした場合のみです。
• ストリーミングはバックエンド固有です: 一部のバックエンドは JSONL をストリーミングし、他は終了までバッファリングします。
• 構造化出力は CLI 自身の JSON 形式に依存します。

​

トラブルシューティング

​

関連

• Gateway ランブック
• ローカルモデル