English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Gateway

CLIバックエンド

OpenClaw は、API プロバイダーが停止している、レート制限されている、または一時的に誤動作している場合のテキストのみのフォールバックとして、ローカル AI CLIを実行できます。 これは意図的に保守的な設計です。

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

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

ACP セッション制御、バックグラウンドタスク、スレッド/会話のバインディング、 永続的な外部コーディングセッションを備えた完全なハーネスランタイムが必要な場合は、 代わりに ACP Agents を使用してください。CLI バックエンドは ACP ではありません。

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

Claude Code CLI は設定なしで使用できます（バンドルされた Anthropic Plugin が デフォルトバックエンドを登録します）。

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

明示的なエージェントリストが設定されていない場合、main はデフォルトのエージェント ID です。 複数のエージェントを使う場合は、実行したいエージェント ID に置き換えてください。

Gateway が launchd/systemd の下で実行され、PATH が最小限の場合は、コマンドパスだけを追加します。

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

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

バンドルされた CLI バックエンドを Gateway ホスト上の主要メッセージプロバイダーとして使う場合、 OpenClaw は、設定がモデル参照または agents.defaults.cliBackends でそのバックエンドを 明示的に参照していると、所有元のバンドル Plugin を自動読み込みするようになりました。

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

CLI バックエンドをフォールバックリストに追加すると、主要モデルが失敗した場合にのみ実行されます。

json5
{  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.models（許可リスト）を使う場合は、CLI バックエンドモデルもそこに含める必要があります。
  • 主要プロバイダーが失敗した場合（認証、レート制限、タイムアウト）、OpenClaw は 次に CLI バックエンドを試します。

設定の概要

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

Code
agents.defaults.cliBackends

各エントリーはプロバイダー ID（例: claude-cli, my-cli）でキー付けされます。 プロバイダー ID はモデル参照の左側になります。

Code
<provider>/<model>

設定例

json5
{  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",          // For CLIs with a dedicated prompt-file flag:          // systemPromptFileArg: "--system-file",          // Codex-style CLIs can point at a prompt file instead:          // systemPromptFileConfigArg: "-c",          // systemPromptFileConfigKey: "model_instructions_file",          systemPromptWhen: "first",          imageArg: "--image",          imageMode: "repeat",          // Opt in only if this backend may reseed safe 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 セッションを再利用します。

バンドルされた Anthropic の claude-cli バックエンドは、OpenClaw Skills について Claude Code のネイティブ Skills リゾルバーを優先します。現在の Skills スナップショットに、実体化されたパスを持つ選択済み skill が少なくとも 1 つ含まれる場合、 OpenClaw は一時的な Claude Code Plugin を --plugin-dir 付きで渡し、重複する OpenClaw Skills カタログを 追記されるシステムプロンプトから省略します。スナップショットに実体化された Plugin skill がない場合、OpenClaw は フォールバックとしてプロンプトカタログを維持します。Skill の環境/API キー上書きは、実行時に OpenClaw によって 子プロセス環境へ引き続き適用されます。

Claude CLI には独自の非対話権限モードもあります。OpenClaw は、Claude 固有のポリシー設定を追加するのではなく、 それを既存の exec ポリシーにマップします。OpenClaw 管理の Claude ライブセッションでは、有効な OpenClaw exec ポリシーが 権威となります。YOLO（tools.exec.security: "full" と tools.exec.ask: "off"）では Claude が --permission-mode bypassPermissions で起動され、制限的な有効 exec ポリシーでは Claude が --permission-mode default で起動されます。エージェントごとの agents.list[].tools.exec 設定は、 そのエージェントについてグローバルな tools.exec を上書きします。生の Claude バックエンド引数に --permission-mode が含まれていても、ライブ Claude 起動ではそのフラグが有効な OpenClaw exec ポリシーに合わせて正規化されます。

バンドルされた Anthropic の claude-cli バックエンドは、OpenClaw の /think レベルも、off 以外のレベルについて Claude Code のネイティブ --effort フラグにマップします。minimal と low は low に、adaptive と medium は medium にマップされ、high、xhigh、max は直接マップされます。他の CLI バックエンドでは、 /think が起動される CLI に影響できるようになる前に、所有元 Plugin が同等の argv マッパーを宣言する必要があります。

OpenClaw がバンドルされた claude-cli バックエンドを使用する前に、Claude Code 自体が同じホストですでに ログイン済みである必要があります。

bash
claude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

Docker インストールでは、Claude Code はホスト上だけでなく、永続化されたコンテナホーム内にインストールされ、 ログイン済みである必要があります。 Docker の Claude CLI backend を参照してください。

agents.defaults.cliBackends.claude-cli.command は、claude バイナリがまだ PATH 上にない場合にのみ使用してください。

セッション

  • CLI がセッションに対応している場合は、ID を複数のフラグに挿入する必要があるときに、 sessionArg（例: --session-id）または sessionArgs（プレースホルダー {sessionId}）を設定します。
  • CLI が異なるフラグを持つ再開サブコマンドを使用する場合は、resumeArgs（再開時に args を置き換える）と、 必要に応じて resumeOutput（非 JSON 再開用）を設定します。
  • sessionMode:
    • always: 常にセッション ID を送信します（保存済みがなければ新しい UUID）。
    • existing: 以前に保存されたセッション ID がある場合のみ送信します。
    • none: セッション ID を送信しません。
  • claude-cli はデフォルトで liveSession: "claude-stdio"、output: "jsonl"、 input: "stdin" になっているため、アクティブな間は後続ターンがライブ Claude プロセスを再利用します。 トランスポートフィールドを省略したカスタム設定を含め、warm stdio が現在のデフォルトです。Gateway が再起動するか アイドルプロセスが終了した場合、OpenClaw は保存済み Claude セッション ID から再開します。保存済みセッション ID は、 再開前に既存の読み取り可能なプロジェクトトランスクリプトに照らして検証されるため、実体のないバインディングは --resume の下で新しい Claude CLI セッションを暗黙に開始するのではなく、reason=transcript-missing でクリアされます。
  • Claude ライブセッションは、境界付き JSONL 出力ガードを維持します。デフォルトでは、1 ターンあたり最大 8 MiB と 20,000 生 JSONL 行が許可されます。ツールが多い Claude ターンでは、バックエンドごとに 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 でオプトインできます。OpenClaw はそれでも、生トランスクリプトの 再シードを境界付きに保ち、CLI トランスクリプトの欠落、システムプロンプト/MCP 変更、session-expired 再試行などの 安全な無効化に限定します。認証プロファイルまたは資格情報エポックの変更では、生トランスクリプト履歴を再シードしません。

シリアライズに関する注記:

  • serialize: true は同じレーンの実行順序を維持します。
  • ほとんどの CLI は 1 つのプロバイダーレーンでシリアライズします。
  • OpenClaw は、選択された認証 ID が変わった場合、保存済み CLI セッションの再利用を破棄します。 これには、認証プロファイル ID、静的 API キー、静的トークン、または CLI が公開する場合の OAuth アカウント ID の変更が含まれます。 OAuth アクセストークンとリフレッシュトークンのローテーションでは、保存済み CLI セッションは切断されません。 CLI が安定した OAuth アカウント ID を公開しない場合、OpenClaw はその CLI に再開権限の強制を任せます。

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

claude-cli の試行が agents.defaults.model.fallbacks 内の非 CLI 候補へフェイルオーバーする場合、 OpenClaw は ~/.claude/projects/ にある Claude Code のローカル JSONL トランスクリプトから収集したコンテキスト前置きで 次の試行をシードします。このシードがないと、OpenClaw 自身のセッショントランスクリプトは claude-cli 実行では空のため、 フォールバックプロバイダーはコールドスタートになります。

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

画像（パススルー）

CLI が画像パスを受け付ける場合は、imageArg を設定します。

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

OpenClaw は base64 画像を一時ファイルに書き込みます。imageArg が設定されている場合、それらのパスは CLI 引数として渡されます。 imageArg がない場合、OpenClaw はファイルパスをプロンプトに追記します（パス注入）。これは、プレーンなパスからローカルファイルを 自動読み込みする CLI には十分です。

入力 / 出力

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

入力モード:

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

デフォルト (Plugin 所有)

バンドルされた CLI バックエンドのデフォルトは、それを所有する Plugin にあります。たとえば、 Anthropic は claude-cli を所有し、Google は google-gemini-cli を所有します。OpenAI Codex agent 実行は openai/* 経由で Codex app-server harness を使用します。OpenClaw は バンドルされた codex-cli バックエンドを登録しなくなりました。

バンドルされた Anthropic Plugin は claude-cli のデフォルトを登録します。

  • command: "claude"
  • args: ["-p","--output-format","stream-json","--include-partial-messages","--verbose", ...]
  • output: "jsonl"
  • input: "stdin"
  • modelArg: "--model"
  • sessionMode: "always"

バンドルされた Google Plugin も google-gemini-cli のデフォルトを登録します。

  • command: "gemini"
  • args: ["--skip-trust", "--approval-mode", "auto_edit", "--output-format", "stream-json", "--prompt", "{prompt}"]
  • resumeArgs: ["--skip-trust", "--approval-mode", "auto_edit", "--resume", "{sessionId}", "--output-format", "stream-json", "--prompt", "{prompt}"]
  • output: "jsonl"
  • resumeOutput: "jsonl"
  • jsonlDialect: "gemini-stream-json"
  • imageArg: "@"
  • imagePathScope: "workspace"
  • modelArg: "--model"
  • sessionMode: "existing"
  • sessionIdFields: ["session_id", "sessionId"]

前提条件: ローカルの Gemini CLI がインストールされ、PATH 上で gemini として利用可能である必要があります (brew install gemini-cli または npm install -g @google/gemini-cli)。

Gemini CLI 出力に関する注記:

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

必要な場合にのみ上書きしてください (一般的なのは絶対 command パス)。

Plugin 所有のデフォルト

CLI バックエンドのデフォルトは、現在 Plugin サーフェスの一部です。

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

小さなプロンプト/メッセージ互換 shim が必要な Plugin は、 provider や CLI バックエンドを置き換えずに双方向テキスト変換を宣言できます。

typescript
api.registerTextTransforms({  input: [    { from: /red basket/g, to: "blue basket" },    { from: /paper ticket/g, to: "digital ticket" },    { from: /left shelf/g, to: "right shelf" },  ],  output: [    { from: /blue basket/g, to: "red basket" },    { from: /digital ticket/g, to: "paper ticket" },    { from: /right shelf/g, to: "left shelf" },  ],});

input は CLI に渡されるシステムプロンプトとユーザープロンプトを書き換えます。output は、OpenClaw が自身の制御マーカーとチャネル配信を処理する前に、 ストリーミングされた assistant テキストとパース済みの最終テキストを書き換えます。provider-backed のモデル呼び出しでは、 output は、ストリーム修復後、tool 実行前に、構造化された tool-call 引数内の文字列値も復元します。生の provider JSON フラグメントは 変更されません。consumer は、構造化された partial、end、または result ペイロードを使用してください。

provider 固有の JSONL イベントを出力する CLI では、その バックエンドの設定に jsonlDialect を設定します。サポートされる dialect は、Claude Code 互換ストリーム用の claude-stream-json と、Gemini CLI stream-json イベント用の gemini-stream-json です。

ネイティブ Compaction の所有権

一部の CLI バックエンドは 自身の transcript を圧縮する agent を実行するため、OpenClaw は それらに対してセーフガード summarizer を実行してはいけません。そうするとバックエンド自身の compaction と競合し、ターンが hard-fail する可能性があります。

claude-cli には harness エンドポイントがありません。Claude Code は内部で圧縮するため、 ownsNativeCompaction: true を宣言し、OpenClaw は compaction パスから no-op を返します。 Codex のようなネイティブ harness セッションは、代わりに harness compaction エンドポイントへルーティングを続けます。

バックエンドが compaction を所有するため、claude-cli セッションで OpenClaw のセーフガードが発火しないようにする目的だけで contextTokens: 1_000_000 を設定していた古い暫定策は 不要になりました。この opt-out がそれを置き換えます。

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

ownsNativeCompaction は、本当に自身の compaction を所有するバックエンドにのみ宣言してください。そのバックエンドは、 context window に近づいたときに自身の transcript を確実に制限し、再開可能なセッション (例: --resume / --session-id) を永続化する必要があります。そうでない場合、延期されたセッションが 予算超過のまま残る可能性があります。一致する agentHarnessId セッションは引き続き harness エンドポイントへルーティングされます。

バンドル MCP オーバーレイ

CLI バックエンドは OpenClaw tool call を直接受け取りませんが、バックエンドは bundleMcp: true により生成された MCP 設定オーバーレイを opt-in できます。

現在のバンドル動作:

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

bundle MCP が有効な場合、OpenClaw は次を行います。

  • gateway tool を CLI プロセスに公開する loopback HTTP MCP server を生成します
  • セッションごとの token (OPENCLAW_MCP_TOKEN) でブリッジを認証します
  • tool アクセスを現在のセッション、アカウント、チャネル context にスコープします
  • 現在の workspace で有効な bundle-MCP server を読み込みます
  • 既存のバックエンド MCP config/settings shape とマージします
  • 所有する extension のバックエンド所有 integration mode を使用して起動設定を書き換えます

MCP server が有効でない場合でも、バックエンドが bundle MCP に opt-in していれば、 OpenClaw は background 実行が分離されたままになるよう strict config を注入します。

セッションスコープのバンドル MCP runtime はセッション内で再利用するためにキャッシュされ、その後 mcp.sessionIdleTtlMs ミリ秒のアイドル時間後に回収されます (デフォルトは 10 分、無効にするには 0 を設定)。auth probe、 slug 生成、active-memory recall などの one-shot embedded 実行は、実行終了時にクリーンアップを要求するため、stdio child や Streamable HTTP/SSE stream が実行より長く残りません。

履歴再シード上限

新しい CLI セッションが以前の OpenClaw transcript からシードされる場合 (たとえば session_expired retry の後)、レンダリングされる <conversation_history> ブロックには、reseed prompt が 肥大化しないよう上限が適用されます。デフォルトは 12288 文字 (約 3000 token) です。

Claude CLI バックエンドは、解決された Claude context tier から導出されたより大きな上限を自動的に使用します。標準の 200K-token Claude 実行ではより大きな transcript slice を保持し、1M-token Claude 実行ではさらに大きな slice を保持します。一方、他の CLI バックエンドは保守的なデフォルトを維持します。

  • この上限は、reseed prompt の prior-history ブロックだけを管理します。live-session 出力上限は reliability.outputLimits の下で別途調整されます (Sessions を参照)。

制限事項

  • OpenClaw tool call を直接注入しません。 OpenClaw は CLI バックエンドプロトコルへ tool call を注入しません。バックエンドは bundleMcp: true に opt-in した場合にのみ gateway tool を認識します。
  • Streaming はバックエンド固有です。 一部のバックエンドは JSONL を stream し、他のバックエンドは exit まで buffer します。
  • 構造化出力 は CLI の JSON 形式に依存します。

トラブルシューティング

  • CLI が見つからない: command を完全なパスに設定します。
  • モデル名が間違っている: modelAliases を使用して provider/model → CLI model にマッピングします。
  • セッション継続性がない: sessionArg が設定され、sessionMode が none ではないことを確認します。
  • 画像が無視される: imageArg を設定します (そして CLI が file path をサポートしていることを確認します)。

関連

Was this useful?
On this page

On this page