CLI バックエンド

• ツール実行は無効（ツール呼び出しは行われません）。
• テキスト入力 → テキスト出力 の確実な動作。
• セッションをサポート（継続的なターンの文脈を維持）。
• 画像のパススルーに対応（CLI が画像パスを受け入れ可能な場合）。

​

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

openclaw agent --message "こんにちは" --model claude-cli/opus-4.6

openclaw agent --message "こんにちは" --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/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 バックエンドを試行します。

​

構成の概要

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-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 が異なるフラグを持つ 再開（resume）用のサブコマンド を使用する場合は、resumeArgs (再開時に args を置き換え) を設定し、必要に応じて JSON 以外の再開出力に対応するための resumeOutput も設定します。
• sessionMode:
  • always: 常にセッション ID を送信（保存された ID がなければ新規 UUID を生成）。
  • existing: 以前に保存された ID がある場合にのみ送信。
  • none: セッション ID を送信しない。

​

画像 (パススルー)

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

​

入出力

• output: "json" (デフォルト): JSON をパースし、テキストとセッション ID を抽出します。
• output: "jsonl": JSONL ストリーム (Codex CLI の --json 等) をパースし、最後のエージェントメッセージと、存在すれば thread_id を抽出します。
• output: "text": 標準出力をそのまま最終回答として扱います。

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

​

組み込みのデフォルト設定

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

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

​

制限事項

• OpenClaw ツールの利用不可: CLI バックエンド側で OpenClaw のツール呼び出しを受け取ることはありません（CLI 自体が独自のツール実行機能を備えている場合は、そちらが動作することがあります）。
• 非ストリーミング: CLI の出力をすべて収集した後に返信が行われます。
• 構造化出力: 抽出精度は CLI 側の JSON フォーマットに依存します。
• Codex CLI セッション: 再開時はテキスト出力 (JSONL ではない) となるため、初回の --json 実行時よりも構造化の度合いが低下します。OpenClaw のセッション管理自体は通常通り機能します。

​

トラブルシューティング

• CLI が見つからない: command に絶対パスを設定してください。
• モデル名が正しくない: modelAliases を使用して provider/model → CLI 用のモデル名へとマッピングしてください。
• セッションが継続しない: sessionArg が正しく、かつ sessionMode が none 以外であることを確認してください（なお、Codex CLI は現在 JSON 出力での再開に対応していません）。
• 画像が無視される: imageArg を設定し、かつ CLI 側がファイルパスからの画像ロードに対応しているか確認してください。