メディア理解

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

ベンダー Plugin は、機能メタデータ（各プロバイダーが対応するメディアタイプ、デフォルトモデル、優先順位）を登録します。OpenClaw コアは、共有 tools.media 設定、フォールバック順序、応答パイプライン統合を所有します。

仕組み

設定

tools.media には、機能タグ付きモデルリストを 1 つと、機能ごとの小規模な制御設定を保持します。

{  tools: {    media: {      concurrency: 2, // 同時実行する機能処理の最大数（デフォルト）      models: [        { provider: "openai", model: "gpt-4o-mini-transcribe", capabilities: ["audio"] },        { provider: "google", model: "gemini-3-flash-preview", capabilities: ["image", "video"] },      ],      image: { preferredModel: "google/gemini-3-flash-preview" },      audio: { enabled: true },      video: { enabled: true },    },  },}

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

プロンプト、上限、言語ヒント、リクエストの上書き、プロバイダーオプションは、機能のデフォルトとして設定することも、個々の tools.media.models[] エントリで上書きすることもできます。明示的なモデルが設定されていない場合、機能のデフォルトは自動検出されたプロバイダーにも適用されます。

モデルエントリ

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

{  type: "provider", // 省略時のデフォルト  provider: "openai",  model: "gpt-5.6-sol",  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",    "{{AttachmentPath}} のメディアを読み取り、{{MaxChars}} 文字以内で説明してください。",  ],  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 M2.x チャットメタデータが画像入力をサポートすると示している場合でも、minimax、minimax-cn、minimax-portal、minimax-portal-cn は常に、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 つのフォールバック（高品質モデル + より高速または低コストのモデル）を用意してください。
• CLI フォールバック（whisper-cli、whisper、gemini）は、プロバイダー API が利用できない場合に役立ちます。
• 既知のファイル出力モードが優先されます。推定された文字起こしファイルが空または存在しない場合、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" の場合、出力には [Image 1/2]、[Audio 2/2] などのラベルが付けられます。

添付ファイルの抽出

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

設定例

{  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",            "{{AttachmentPath}} のメディアを読み取り、{{MaxChars}} 文字以内で説明してください。",          ],          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", "{{AttachmentPath}}"],          },        ],      },      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",              "{{AttachmentPath}} のメディアを読み取り、{{MaxChars}} 文字以内で説明してください。",            ],          },        ],      },    },  },}

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

{  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 に機能ごとの概要行が含まれます。

📎 メディア: 画像 成功 (openai/gpt-5.6-sol) · 音声 成功 (whisper-cli 検出値=metal)

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

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

注記

• 理解処理はベストエフォートです。エラーが応答を妨げることはありません。
• 理解処理が無効でも、添付ファイルはモデルに渡されます。
• 理解処理を実行する場所を制限するには、scope を使用します（たとえば、DM のみ）。

関連項目

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