CLI バックエンド

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​

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

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

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

​

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

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

• agents.defaults.models（許可リスト）を使用している場合は、そこにも CLI バックエンドモデルを含める必要があります。
• 主要プロバイダーが失敗した場合（認証、レート制限、タイムアウト）、OpenClaw は次に CLI バックエンドを試します。

​

設定概要

agents.defaults.cliBackends

<provider>/<model>

​

設定例

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "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. プロバイダープレフィックス（codex-cli/...）に基づいてバックエンドを選択します。
2. 同じ OpenClaw プロンプト + ワークスペースコンテキストを使用して、システムプロンプトを構築します。
3. 履歴の一貫性を保つため、対応している場合はセッション ID 付きで CLI を実行します。 同梱の claude-cli バックエンドは OpenClaw セッションごとに Claude stdio プロセスを維持し、後続ターンを stream-json stdin 経由で送信します。
4. 出力を解析（JSON またはプレーンテキスト）し、最終テキストを返します。
5. 後続ターンで同じ CLI セッションを再利用できるように、バックエンドごとにセッション ID を永続化します。

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

​

セッション

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

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

​

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

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

​

画像（パススルー）

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

​

入力 / 出力

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

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

​

デフォルト（Plugin 所有）

• command: "codex"
• args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
• resumeArgs: ["exec","resume","{sessionId}","-c","sandbox_mode=\"workspace-write\"","--skip-git-repo-check"]
• output: "jsonl"
• resumeOutput: "text"
• modelArg: "--model"
• imageArg: "--image"
• sessionMode: "existing"

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

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

​

Plugin 所有のデフォルト

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

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" },
  ],
});

​

バンドル MCP オーバーレイ

• claude-cli: 生成済みの厳格な MCP 設定ファイル
• codex-cli: mcp_servers のインライン設定上書き。生成済みの OpenClaw ループバックサーバーは、Codex のサーバー単位ツール承認モードでマークされるため、 MCP 呼び出しがローカル承認プロンプトで停止することはありません
• google-gemini-cli: 生成済みの Gemini システム設定ファイル

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

​

制限事項

• OpenClaw ツール呼び出しの直接利用はありません。 OpenClaw は CLI バックエンドプロトコルにツール呼び出しを注入しません。バックエンドは bundleMcp: true にオプトインした場合にのみ Gateway ツールを認識します。
• ストリーミングはバックエンド固有です。 一部のバックエンドは JSONL をストリーミングし、他は終了までバッファリングします。
• 構造化出力 は CLI の JSON 形式に依存します。
• Codex CLI セッション はテキスト出力で再開されます（JSONL ではありません）。これは初回の --json 実行より構造化度が低くなります。OpenClaw セッションは引き続き通常どおり動作します。

​

トラブルシューティング

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

​

関連

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