​

メディア理解 - 受信時 (2026-01-17)

​

目的

• 任意: より速いルーティングとより良いコマンド解析のために、受信メディアを事前に短いテキストへ要約する。
• 元のメディアを常にモデルへ渡すことを維持する。
• プロバイダーAPIとCLIフォールバックをサポートする。
• 順序付きフォールバック（エラー/サイズ/タイムアウト）を伴う複数モデルを許可する。

​

高レベルの動作

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

​

設定概要

• 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音声オプション
  • 音声文字起こしのecho制御（echoTranscript、デフォルトfalse、echoFormat）
  • 任意の機能ごとのmodelsリスト（共有モデルより優先）
  • attachmentsポリシー（mode、maxAttachments、prefer）
  • scope（channel/chatType/session keyによる任意の制御）
• tools.media.concurrency: 同時実行する機能処理数の上限（デフォルト2）。

{
  tools: {
    media: {
      models: [
        /* shared list */
      ],
      image: {
        /* optional overrides */
      },
      audio: {
        /* optional overrides */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* optional overrides */
      },
    },
  },
}

​

モデルエントリ

{
  type: "provider", // 省略時のデフォルト
  provider: "openai",
  model: "gpt-5.4-mini",
  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"],
}

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

​

デフォルトと上限

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

• メディアがmaxBytesを超える場合、そのモデルはスキップされ、次のモデルが試されます。
• 1024 bytes未満の音声ファイルは空/破損と見なされ、プロバイダー/CLI文字起こしの前にスキップされます。
• モデルがmaxCharsを超える出力を返した場合、出力は切り詰められます。
• promptのデフォルトは単純な「Describe the .」にmaxCharsの案内を加えたものです（画像/動画のみ）。
• アクティブなPrimary画像モデルがすでにネイティブにvisionをサポートしている場合、OpenClawは[Image]要約ブロックを省略し、代わりに元の画像をモデルへ渡します。
• <capability>.enabled: trueでもモデルが設定されていない場合、OpenClawはそのプロバイダーが機能をサポートしていればアクティブな応答モデルを試します。

​

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

1. そのプロバイダーが機能をサポートしている場合のアクティブな応答モデル。
2. **agents.defaults.imageModel**のprimary/fallback参照（画像のみ）。
3. ローカルCLI（音声のみ。インストール済みの場合）
   • sherpa-onnx-offline（SHERPA_ONNX_MODEL_DIRにencoder/decoder/joiner/tokensが必要）
   • whisper-cli（whisper-cpp。WHISPER_CPP_MODELまたは同梱tinyモデルを使用）
   • whisper（Python CLI。モデルを自動ダウンロード）
4. Gemini CLI（gemini）をread_many_files付きで使用
5. プロバイダー認証
   • 機能をサポートする設定済みのmodels.providers.*エントリは、 バンドル済みフォールバック順より先に試されます。
   • 画像対応モデルを持つ画像専用config providerは、バンドル済みベンダープラグインでなくても、自動的にメディア理解向けに登録されます。
   • バンドル済みフォールバック順:
     • 音声: OpenAI → Groq → Deepgram → Google → Mistral
     • 画像: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
     • 動画: Google → Qwen → Moonshot

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

​

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

• HTTPS_PROXY
• HTTP_PROXY
• https_proxy
• http_proxy

​

機能（任意）

• openai、anthropic、minimax: image
• minimax-portal: image
• moonshot: image + video
• openrouter: image
• google（Gemini API）: image + audio + video
• qwen: image + video
• mistral: audio
• zai: image
• groq: audio
• deepgram: audio
• 画像対応モデルを持つ任意のmodels.providers.<id>.models[]カタログ: image

​

プロバイダー対応表（OpenClaw統合）

• minimaxおよびminimax-portalの画像理解は、プラグイン所有の MiniMax-VL-01メディアプロバイダーから提供されます。
• バンドル済みMiniMaxテキストカタログは引き続きテキスト専用で始まります。明示的な models.providers.minimaxエントリにより、画像対応のM2.7チャット参照が具体化されます。

​

モデル選択ガイダンス

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

​

添付ファイルポリシー

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

• 抽出されたファイルテキストは、メディアプロンプトへ追加される前に 信頼できない外部コンテンツとしてラップされます。
• 注入されるブロックでは、次のような明示的な境界マーカーが使われます: <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>。さらに Source: Externalメタデータ行も含まれます。
• この添付ファイル抽出パスでは、メディアプロンプトが膨らみすぎないよう、 長いSECURITY NOTICE:バナーを意図的に省略します。それでも境界マーカーとメタデータは残ります。
• ファイルから抽出可能なテキストがない場合、OpenClawは[No extractable text]を注入します。
• このパスでPDFがレンダリング済みページ画像へフォールバックした場合、メディアプロンプトには [PDF content rendered to images; images not forwarded to model] というプレースホルダーが保持されます。これは、この添付ファイル抽出ステップが転送するのはテキストブロックであり、レンダリング済みPDF画像ではないためです。

​

設定例

​

1) 共有モデルリスト + 上書き

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.4-mini", 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.4-mini" },
          { 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) 単一エントリのマルチモーダル（明示的capabilities）

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

​

ステータス出力

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

​

注記

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

​

関連ドキュメント

• Configuration
• Image & Media Support