OpenClawでメディア理解（Media Understanding）を自動化する

ユーザーから送られてくる画像や音声、動画の処理に頭を悩ませたことはありませんか？ 送られてきたファイルをそのままモデルに渡すだけでは、ルーティングやコマンドの解析がうまくいかないことがあります。事前に内容を把握し、テキストとして要約しておくことで、その後の処理をよりスムーズに進めることができます。

OpenClawのメディア理解機能を使えば、返信パイプラインが動く前にインバウンドメディアを自動で解析できます。プロバイダーの API やローカルの CLI ツールを賢く使い分ける方法を見ていきましょう。

必要なもの

この機能を利用するには、以下の準備が必要です。

• tools.media の設定（models リストの定義など）
• サポートされている Provider の API キー（OpenAI, Anthropic, Google, Groq, Deepgram）
• または、ローカルの CLI ツール（whisper-cli, gemini CLI, sherpa-onnx-offline など）
• 解析対象のメディア（MediaPaths, MediaUrls, MediaTypes）

クイックスタート

OpenClawは、画像・音声・動画を自動的に検出し、設定されたモデルを使って要約を作成します。5分で始められる基本的な設定例を紹介します。

デフォルトでは、以下の順序で動作します。

1. メディアの添付ファイルを収集します。
2. 有効な機能（画像/音声/動画）ごとに、ポリシーに従ってファイルを選択します。
3. 利用可能なモデルの中から、サイズや権限が一致するものを選択します。
4. 処理が成功すると、Body に [Image] などのブロックが追加され、音声の場合は {{Transcript}} がセットされます。

設定例：共有モデルリストと上書き

複数のメディアタイプに対応した、おすすめの構成です。

{
  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,
      },
    },
  },
}

特定の機能をオフにしたい場合は、以下のように設定してください。

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

トラブルシューティング

設定や実行時に問題が発生した場合は、以下の点を確認してください。

• メディアがスキップされる: ファイルサイズが maxBytes を超えている場合、そのモデルはスキップされ、リスト内の次のモデルが試行されます。
• 解析が失敗する: モデルがエラーを返したりタイムアウトしたりしても、OpenClawは元のメッセージと添付ファイルを保持したまま返信フローを続行します。
• 期待したモデルが動かない: capabilities が正しく設定されているか確認してください。CLI エントリの場合は、明示的に指定することをおすすめします。
• バイナリが見つからない: CLI ツールを使用する場合、PATH が通っているか、フルパスでコマンドを指定しているか確認してください。

/status コマンドを実行すると、メディア理解の実行結果を以下のように確認できます。 📎 Media: image ok (openai/gpt-5.2) · audio skipped (maxBytes)

設定に迷ったときは、AI Setup Assistant も活用してください。

次のステップ

• Configuration
• Image & Media Support