メディア理解（受信） — 2026-01-17

OpenClaw は返信パイプラインの実行前に、受信メディア（画像/音声/動画）を要約できます。ローカルツールやプロバイダキーが利用可能な場合に自動検出し、無効化やカスタマイズも可能です。理解がオフの場合でも、モデルは元のファイル/URL をそのまま受け取ります。

目的

オプション機能: 受信メディアを短いテキストに事前処理し、ルーティングの高速化とコマンド解析の改善を実現。
元のメディアのモデルへの配信は常に保持。
プロバイダ API と CLI フォールバックをサポート。
順序付きフォールバック（エラー/サイズ/タイムアウト）で複数モデルに対応。

全体の動作

受信添付ファイルを収集（MediaPaths、MediaUrls、MediaTypes）。
有効な各機能（画像/音声/動画）について、ポリシーに従い添付ファイルを選択（デフォルト: 最初の 1 つ）。
対象の最初のモデルエントリを選択（サイズ + 機能 + 認証）。
モデルが失敗、またはメディアが大きすぎる場合は、次のエントリにフォールバック。
成功時:
- 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）
- Deepgram の音声オプション: tools.media.audio.providerOptions.deepgram
- 音声トランスクリプトのエコー制御（echoTranscript、デフォルト false。echoFormat）
- オプションの機能ごとの models リスト（共有モデルより優先）
- attachments ポリシー（mode、maxAttachments、prefer）
- scope（チャンネル/chatType/セッションキーによるオプションのゲーティング）
tools.media.concurrency: 最大同時実行数（デフォルト 2）。

{
  tools: {
    media: {
      models: [
        /* 共有リスト */
      ],
      image: {
        /* オプションのオーバーライド */
      },
      audio: {
        /* オプションのオーバーライド */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* オプションのオーバーライド */
      },
    },
  },
}

モデルエントリ

各 models[] エントリはプロバイダまたは CLI のいずれかです。

{
  type: "provider", // 省略時のデフォルト
  provider: "openai",
  model: "gpt-5.2",
  prompt: "Describe the image in <= 500 chars.",
  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",
    "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
  ],
  maxChars: 500,
  maxBytes: 52428800,
  timeoutSeconds: 120,
  capabilities: ["video", "image"],
}

CLI テンプレートでは以下も使用できます。

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

デフォルトと制限

推奨デフォルト:

maxChars: 画像/動画は 500（短く、コマンド向け）
maxChars: 音声は未設定（制限を設定しない限り全文）
maxBytes:
- 画像: 10MB
- 音声: 20MB
- 動画: 50MB

ルール:

メディアが maxBytes を超えた場合、そのモデルはスキップされ、次のモデルが試行されます。
1024 バイト未満の音声ファイルは空/破損として扱われ、プロバイダ/CLI の文字起こし前にスキップされます。
モデルの出力が maxChars を超えた場合、出力はトリミングされます。
prompt のデフォルトは「{media} を説明してください」+ maxChars のガイダンス（画像/動画のみ）。
<capability>.enabled: true でモデルが未設定の場合、OpenClaw はそのプロバイダが機能をサポートしていれば アクティブな返信モデルを試行します。

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

tools.media.<capability>.enabled が false に設定されておらず、モデルも設定していない場合、OpenClaw は以下の順序で自動検出し、最初に動作したものを使用します。

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

自動検出を無効にするには:

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

注意: バイナリの検出は macOS/Linux/Windows でベストエフォートです。CLI が PATH 上にあることを確認するか（~ は展開されます）、フルパスで CLI モデルを明示的に指定してください。

プロキシ環境のサポート（プロバイダモデル）

プロバイダベースの音声および動画メディア理解が有効な場合、OpenClaw はプロバイダ HTTP 呼び出しで標準のアウトバウンドプロキシ環境変数に対応します。

HTTPS_PROXY
HTTP_PROXY
https_proxy
http_proxy

プロキシ環境変数が設定されていない場合、メディア理解は直接通信を使用します。プロキシ値が不正な場合、OpenClaw は警告をログに記録し、直接フェッチにフォールバックします。

ケーパビリティ（オプション）

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

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

CLI エントリの場合、予期しないマッチを避けるために capabilities を明示的に設定してください。 capabilities を省略すると、そのエントリは所属するリストの対象になります。

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

機能	プロバイダ連携	備考
Image	OpenAI / Anthropic / Google / その他 `pi-ai` 経由	レジストリ内の画像対応モデルはすべて使用可能。
Audio	OpenAI, Groq, Deepgram, Google, Mistral	プロバイダ文字起こし（Whisper/Deepgram/Gemini/Voxtral）。
Video	Google（Gemini API）	プロバイダ動画理解。

モデル選択のガイダンス

品質と安全性が重要な場合、各メディア機能に最新世代の最強モデルを推奨します。
信頼できない入力を処理するツール対応エージェントでは、古い/弱いメディアモデルを避けてください。
可用性のため、機能ごとに少なくとも 1 つのフォールバックを確保してください（品質モデル + 高速/低コストモデル）。
CLI フォールバック（whisper-cli、whisper、gemini）はプロバイダ API が利用できない場合に有用です。
parakeet-mlx の注意点: --output-dir を指定すると、出力形式が txt（または未指定）の場合、OpenClaw は <output-dir>/<media-basename>.txt を読み取ります。txt 以外の形式では標準出力にフォールバックします。

添付ファイルポリシー

機能ごとの 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",
            "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
          ],
          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",
              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
            ],
          },
        ],
      },
    },
  },
}

3) 画像理解（オプション）

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.2" },
          { provider: "anthropic", model: "claude-opus-4-6" },
          {
            type: "cli",
            command: "gemini",
            args: [
              "-m",
              "gemini-3-flash",
              "--allowed-tools",
              "read_file",
              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
            ],
          },
        ],
      },
    },
  },
}

4) マルチモーダル単一エントリ（明示的なケーパビリティ）

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

ステータス出力

メディア理解の実行時、/status に短い要約行が含まれます。

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

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

補足

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