メディア理解

OpenClaw は、応答パイプラインが実行される前に受信メディア（画像/音声/動画）を要約できるため、コマンド解析とルーティングでは生のバイト列ではなく短いテキストを使用できます。メディア理解機能はローカルツールまたはプロバイダーキーを自動検出しますが、モデルを明示的に設定することもできます。元のメディアは常に通常どおりモデルへ渡されます。メディア理解に失敗した場合や無効になっている場合でも、応答フローは変更されずに続行されます。

ベンダー Plugin は、機能メタデータ（各メディアタイプをサポートするプロバイダー、デフォルトモデル、優先度）を登録します。OpenClaw コアは、共有の tools.media 設定、フォールバック順序、および応答パイプラインとの統合を管理します。

仕組み

設定

tools.media には、共有モデルリストと機能ごとのオーバーライドを指定します。

{  tools: {    media: {      concurrency: 2, // max concurrent capability runs (default)      models: [/* shared list, gate with capabilities */],      image: {/* optional overrides */},      audio: {        /* optional overrides */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {/* optional overrides */},    },  },}

機能ごとの（image/audio/video）キー:

Deepgram 固有のオプションは providerOptions.deepgram の下に指定します（トップレベルの deepgram: { detectLanguage, punctuate, smartFormat } フィールドは非推奨ですが、引き続き読み込まれます）。

モデルエントリ

各 models[] エントリは、プロバイダーエントリ（デフォルト）または CLI エントリです。

{  type: "provider", // default if omitted  provider: "openai",  model: "gpt-5.6-sol",  prompt: "Describe the image in <= 500 chars.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"], // optional, for multi-modal shared entries  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"],}

プロバイダー認証情報

プロバイダーによるメディア理解では、通常のモデル呼び出しと同じ認証解決順序（認証プロファイル、環境変数、models.providers.<providerId>.apiKey）を使用します。tools.media.*.models[] エントリでは、インラインの apiKey フィールドは使用できません。

{  models: {    providers: {      openai: { apiKey: "<OPENAI_API_KEY>" },      moonshot: { apiKey: "<MOONSHOT_API_KEY>" },    },  },}

プロファイル、環境変数、カスタムベース URL については、ツールとカスタムプロバイダーを参照してください。

ルールと動作

• maxBytes を超えるメディアでは、そのモデルをスキップして次のモデルを試します。
• 1024 バイト未満の音声ファイルは空または破損しているものとして扱われ、文字起こし前にスキップされます。代わりに、エージェントには決定的なプレースホルダー文字起こしが渡されます。
• 有効なプライマリ画像モデルがすでにネイティブに画像認識をサポートしている場合、OpenClaw は [Image] 要約ブロックを省略し、元の画像をモデルへ直接渡します。MiniMax は例外です。minimax、minimax-cn、minimax-portal、minimax-portal-cn は、従来の MiniMax M2.x チャットメタデータが画像入力に対応していると示している場合でも、常に Plugin が管理する MiniMax-VL-01 メディアプロバイダーを通じて画像理解を処理します（MiniMax-M3 以降のみがネイティブな画像認識対応として扱われます）。
• Gateway/WebChat のプライマリモデルがテキスト専用の場合、画像添付ファイルはオフロードされた media://inbound/* 参照として保持されるため、添付ファイルを失うことなく、画像/PDF ツールまたは設定済みの画像モデルで引き続き検査できます。
• 明示的な openclaw infer image describe --file <path> --model <provider/model>（エイリアス: openclaw capability image describe）は、その画像対応プロバイダー/モデルを直接実行します。models.providers.ollama.models[] に一致する画像対応モデルが設定されている場合は、ollama/qwen2.5vl:7b などの Ollama 参照も対象になります。
• <capability>.enabled が false ではなく、モデルが設定されていない場合、そのプロバイダーが機能をサポートしていれば、OpenClaw は有効な応答モデルを試します。

自動検出（デフォルト）

tools.media.<capability>.enabled が false ではなく、モデルが設定されていない場合、OpenClaw は次の順序で試し、最初に動作した選択肢で停止します。

機能の自動検出を無効にするには、次のように設定します。

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

プロキシサポート（音声/動画プロバイダー呼び出し）

プロバイダーによる音声および動画の理解では、NO_PROXY/no_proxy のバイパスルールを含む標準の送信プロキシ環境変数 HTTPS_PROXY、HTTP_PROXY、ALL_PROXY、https_proxy、http_proxy、all_proxy が使用されます。小文字の変数が大文字の変数より優先されます。いずれも設定されていない場合、メディア理解は直接外部へ接続します。プロキシ値の形式が不正な場合、OpenClaw は警告をログに記録し、直接取得へフォールバックします。画像理解では、このプロキシ経路は使用されません。

機能

models[] エントリに capabilities を設定すると、特定のメディアタイプに限定できます。共有リストの場合、OpenClaw は同梱プロバイダーごとにデフォルトを推測します。

CLI エントリでは、意図しない一致を避けるために capabilities を明示的に設定してください。省略すると、そのエントリは記載されているすべての機能リストで候補になります。

プロバイダー対応表

モデル選択の指針

• 品質と安全性が重要な場合は、各メディア機能で現行世代の最も高性能なモデルを優先してください。
• 信頼できない入力を処理するツール対応エージェントでは、古い、または性能の低いメディアモデルを避けてください。
• 可用性を確保するため、機能ごとに少なくとも 1 つのフォールバックを維持してください（高品質モデル + 高速または低コストのモデル）。
• プロバイダー API が利用できない場合は、CLI フォールバック（whisper-cli、whisper、gemini）が役立ちます。
• 既知のファイル出力モードが優先されます。推測された文字起こしファイルが空または存在しない場合、CLI の進捗出力へフォールバックせず、文字起こしは生成されません。
• parakeet-mlx: --output-dir およびデフォルトの {filename} 出力テンプレートとともに、--output-format txt（または all）を使用してください。アップストリームの PARAKEET_OUTPUT_FORMAT および PARAKEET_OUTPUT_TEMPLATE 環境変数も使用されます。OpenClaw は <output-dir>/<media-basename>.txt を読み取ります。デフォルトの srt 形式、その他の形式、カスタム出力テンプレートでは、引き続き標準出力が使用されます。

添付ファイルポリシー

機能ごとの attachments は、処理する添付ファイルを制御します。

mode: "all" の場合、出力には [画像 1/2]、[音声 2/2] などのラベルが付けられます。

添付ファイルからの抽出

• 抽出されたファイルテキストは、メディアプロンプトに追加される前に、信頼できない外部コンテンツとしてラップされます。<<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> のような境界マーカーと、Source: External メタデータ行が使用されます。
• この経路では、メディアプロンプトを短く保つため、長い SECURITY NOTICE: バナーを意図的に省略しています。境界マーカーとメタデータは引き続き適用されます。
• 抽出可能なテキストがないファイルには [抽出可能なテキストなし] が設定されます。
• PDF がレンダリング済みページ画像にフォールバックした場合、OpenClaw はそれらの画像を視覚対応の応答モデルに転送し、ファイルブロック内にプレースホルダー [PDF コンテンツは画像としてレンダリング済み] を保持します。

設定例

{  tools: {    media: {      models: [        { provider: "openai", model: "gpt-5.6-sol", 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,      },    },  },}

{  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.",            ],          },        ],      },    },  },}

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

{  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.6-sol) · audio ok (whisper-cli observed=metal)

事前確認用のインベントリには、openclaw capability audio providers を実行してください。ローカル行では、ローカルのフォールバック候補が、グローバルなプロバイダー選択、準備状態、および個別の対応可能、要求済み、観測済みバックエンドフィールドとは分けて表示されます。同じローカル選択は、情報レベルの doctor 検出結果としても確認できます。

openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

注記

• 理解処理はベストエフォートです。エラーが発生しても応答はブロックされません。
• 理解処理が無効でも、添付ファイルは引き続きモデルに渡されます。
• scope を使用して、理解処理を実行する場所を制限できます（たとえば、DM のみに限定）。

関連項目

• 設定
• 画像とメディアのサポート