メディア理解（インバウンド）— 2026-01-17

OpenClaw は返信パイプラインが実行される前にインバウンドメディアを要約できます。ローカルツールまたはプロバイダーキーが利用可能な場合は自動検出でき、無効化またはカスタマイズできます。理解がオフの場合でも、モデルは通常どおり元のファイル/URL を受信します。

目標

  • オプション: より高速なルーティング + より良いコマンド解析のために、インバウンドメディアを短いテキストに事前消化します。
  • モデルへの元のメディア配信を保持します（常に）。
  • プロバイダー API と CLI フォールバックをサポートします。
  • 順序付きフォールバック（エラー/サイズ/タイムアウト）で複数のモデルを許可します。

高レベルの動作

  1. インバウンド添付ファイル（MediaPaths、MediaUrls、MediaTypes）を収集します。
  2. 有効な各機能（画像/音声/動画）について、ポリシーごとに添付ファイルを選択します（デフォルト: 最初）。
  3. 最初の適格なモデルエントリを選択します（サイズ + 機能 + 認証）。
  4. モデルが失敗するか、メディアが大きすぎる場合、次のエントリにフォールバックします。
  5. 成功時:
    • Body は [Image]、[Audio]、または [Video] ブロックになります。
    • 音声は {{Transcript}} を設定します。キャプションテキストが存在する場合はコマンド解析に使用され、 それ以外の場合はトランスクリプトを使用します。
    • キャプションはブロック内で User text: として保持されます。

理解が失敗または無効の場合、返信フローは元の本文 + 添付ファイルで続行されます。

設定の概要

tools.media は共有モデルと機能ごとのオーバーライドをサポートします:

  • tools.media.models: 共有モデルリスト（capabilities を使用してゲート）。
  • tools.media.image / tools.media.audio / tools.media.video:
    • デフォルト（prompt、maxChars、maxBytes、timeoutSeconds、language）
    • プロバイダーオーバーライド（baseUrl、headers、providerOptions）
    • tools.media.audio.providerOptions.deepgram 経由の Deepgram 音声オプション
    • オプションの機能ごとの models リスト（共有モデルの前に優先）
    • attachments ポリシー（mode、maxAttachments、prefer）
    • scope（チャネル/chatType/セッションキーによるオプションのゲーティング）
  • tools.media.concurrency: 最大同時機能実行数（デフォルト 2）。
{
  tools: {
    media: {
      models: [ /* 共有リスト */ ],
      image: { /* オプションのオーバーライド */ },
      audio: { /* オプションのオーバーライド */ },
      video: { /* オプションのオーバーライド */ }
    }
  }
}

モデルエントリ

各 models[] エントリはプロバイダーまたは CLI にできます:

{
  type: "provider",        // 省略時のデフォルト
  provider: "openai",
  model: "gpt-5.2",
  prompt: "画像を <= 500 文字で説明してください。",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"], // オプション、マルチモーダルエントリに使用
  profile: "vision-profile",
  preferredProfile: "vision-fallback"
}

{
  type: "cli",
  command: "gemini",
  args: [
    "-m",
    "gemini-3-flash",
    "--allowed-tools",
    "read_file",
    "{{MediaPath}} のメディアを読み取り、<= {{MaxChars}} 文字で説明してください。"
  ],
  maxChars: 500,
  maxBytes: 52428800,
  timeoutSeconds: 120,
  capabilities: ["video", "image"]
}

CLI テンプレートは次も使用できます:

  • {{MediaDir}}（メディアファイルを含むディレクトリ）
  • {{OutputDir}}（この実行用に作成されたスクラッチディレクトリ）
  • {{OutputBase}}（スクラッチファイルのベースパス、拡張子なし）

デフォルトと制限

推奨デフォルト:

  • maxChars: 画像/動画には 500（短く、コマンドフレンドリー）
  • maxChars: 音声には 未設定（制限を設定しない限り完全なトランスクリプト）
  • maxBytes:
    • 画像: 10MB
    • 音声: 20MB
    • 動画: 50MB

ルール:

  • メディアが maxBytes を超えると、そのモデルはスキップされ、次のモデルが試行されます。
  • モデルが maxChars を超える出力を返した場合、出力は切り詰められます。
  • prompt のデフォルトは、シンプルな「{media} を説明してください。」と maxChars ガイダンス（画像/動画のみ）です。
  • <capability>.enabled: true だがモデルが設定されていない場合、OpenClaw は プロバイダーが機能をサポートしている場合、アクティブな返信モデルを試行します。

メディア理解の自動検出（デフォルト）

tools.media.<capability>.enabled が false に設定されておらず、 モデルを設定していない場合、OpenClaw は次の順序で自動検出し、最初に 動作するオプションで停止します:

  1. ローカル CLI（音声のみ; インストールされている場合）
    • sherpa-onnx-offline（encoder/decoder/joiner/tokens を含む SHERPA_ONNX_MODEL_DIR が必要）
    • whisper-cli（whisper-cpp; WHISPER_CPP_MODEL またはバンドルされた tiny モデルを使用）
    • whisper（Python CLI; モデルを自動ダウンロード）
  2. Gemini CLI（gemini）read_many_files を使用
  3. プロバイダーキー
    • 音声: OpenAI → Groq → Deepgram → Google
    • 画像: OpenAI → Anthropic → Google → MiniMax
    • 動画: Google

自動検出を無効にするには、次を設定します:

{
  tools: {
    media: {
      audio: {
        enabled: false
      }
    }
  }
}

注意: バイナリ検出は macOS/Linux/Windows で最善努力ベースです。CLI が PATH 上にあることを確認してください（~ を展開します）、または完全なコマンドパスで明示的な CLI モデルを設定してください。

機能（オプション）

capabilities を設定すると、エントリはそれらのメディアタイプに対してのみ実行されます。共有 リストの場合、OpenClaw はデフォルトを推測できます:

  • openai、anthropic、minimax: image
  • google（Gemini API）: image + audio + video
  • groq: audio
  • deepgram: audio

CLI エントリの場合、驚きのマッチを避けるため、capabilities を明示的に設定してください。 capabilities を省略すると、エントリは表示されるリストに適格です。

プロバイダーサポートマトリックス（OpenClaw 統合）

機能プロバイダー統合注意
画像OpenAI / Anthropic / Google / pi-ai 経由のその他レジストリ内の画像対応モデルはすべて機能します。
音声OpenAI、Groq、Deepgram、Googleプロバイダー文字起こし（Whisper/Deepgram/Gemini）。
動画Google（Gemini API）プロバイダー動画理解。

推奨プロバイダー

画像

  • 画像をサポートしている場合は、アクティブなモデルを優先します。
  • 良いデフォルト: openai/gpt-5.2、anthropic/claude-opus-4-5、google/gemini-3-pro-preview。

音声

  • openai/gpt-4o-mini-transcribe、groq/whisper-large-v3-turbo、または deepgram/nova-3。
  • CLI フォールバック: whisper-cli（whisper-cpp）または whisper。
  • Deepgram セットアップ: Deepgram（音声文字起こし）。

動画

  • google/gemini-3-flash-preview（高速）、google/gemini-3-pro-preview（より豊富）。
  • CLI フォールバック: gemini CLI（動画/音声で read_file をサポート）。

添付ファイルポリシー

機能ごとの attachments は、どの添付ファイルが処理されるかを制御します:

  • mode: first（デフォルト）または all
  • maxAttachments: 処理される数の上限（デフォルト 1）
  • prefer: first、last、path、url

mode: "all" の場合、出力は [Image 1/2]、[Audio 2/2] などとラベル付けされます。

設定例

1) 共有モデルリスト + オーバーライド

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.2", capabilities: ["image"] },
        { provider: "google", model: "gemini-3-flash-preview", capabilities: ["image", "audio", "video"] },
        {
          type: "cli",
          command: "gemini",
          args: [
            "-m",
            "gemini-3-flash",
            "--allowed-tools",
            "read_file",
            "{{MediaPath}} のメディアを読み取り、<= {{MaxChars}} 文字で説明してください。"
          ],
          capabilities: ["image", "video"]
        }
      ],
      audio: {
        attachments: { mode: "all", maxAttachments: 2 }
      },
      video: {
        maxChars: 500
      }
    }
  }
}

2) 音声 + 動画のみ（画像オフ）

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          {
            type: "cli",
            command: "whisper",
            args: ["--model", "base", "{{MediaPath}}"]
          }
        ]
      },
      video: {
        enabled: true,
        maxChars: 500,
        models: [
          { provider: "google", model: "gemini-3-flash-preview" },
          {
            type: "cli",
            command: "gemini",
            args: [
              "-m",
              "gemini-3-flash",
              "--allowed-tools",
              "read_file",
              "{{MediaPath}} のメディアを読み取り、<= {{MaxChars}} 文字で説明してください。"
            ]
          }
        ]
      }
    }
  }
}

3) オプションの画像理解

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.2" },
          { provider: "anthropic", model: "claude-opus-4-5" },
          {
            type: "cli",
            command: "gemini",
            args: [
              "-m",
              "gemini-3-flash",
              "--allowed-tools",
              "read_file",
              "{{MediaPath}} のメディアを読み取り、<= {{MaxChars}} 文字で説明してください。"
            ]
          }
        ]
      }
    }
  }
}

4) マルチモーダル単一エントリ（明示的な機能）

{
  tools: {
    media: {
      image: { models: [{ provider: "google", model: "gemini-3-pro-preview", capabilities: ["image", "video", "audio"] }] },
      audio: { models: [{ provider: "google", model: "gemini-3-pro-preview", capabilities: ["image", "video", "audio"] }] },
      video: { models: [{ provider: "google", model: "gemini-3-pro-preview", capabilities: ["image", "video", "audio"] }] }
    }
  }
}

ステータス出力

メディア理解が実行されると、/status には短い要約行が含まれます:

📎 Media: image ok (openai/gpt-5.2) · audio skipped (maxBytes)

これは、機能ごとの結果と、該当する場合に選択されたプロバイダー/モデルを示します。

注意

  • 理解はベストエフォートです。エラーは返信をブロックしません。
  • 理解が無効になっている場合でも、添付ファイルはモデルに渡されます。
  • scope を使用して、理解が実行される場所を制限します（例: DM のみ）。

関連ドキュメント

← ドキュメントに戻る