媒體理解（接收端） — 2026-01-17

OpenClaw 可以在回覆流程執行前，摘要接收到的媒體（圖片/音訊/影片）。它會自動偵測本機工具或 provider 金鑰是否可用，也可以手動停用或自訂。理解功能關閉時，模型仍會照常收到原始檔案/URL。

目標

  • 選用功能：將接收的媒體預先轉換為簡短文字，加速路由並改善指令解析。
  • 始終保留原始媒體傳遞給模型。
  • 支援 provider API 和 CLI 備援。
  • 允許多個模型搭配順序備援（錯誤/大小/逾時）。

整體行為

  1. 收集接收的附件（MediaPaths、MediaUrls、MediaTypes）。
  2. 對每個已啟用的能力（image/audio/video），依策略選取附件（預設：第一個）。
  3. 選擇第一個符合條件的模型項目（大小 + 能力 + 驗證）。
  4. 如果模型失敗或媒體過大，備援到下一個項目。
  5. 成功時：
    • 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）
    • provider 覆寫（baseUrl、headers、providerOptions）
    • Deepgram 音訊選項透過 tools.media.audio.providerOptions.deepgram
    • 音訊轉錄回傳控制（echoTranscript，預設 false；echoFormat）
    • 可選的按能力 models 清單（優先於共用模型）
    • attachments 策略（mode、maxAttachments、prefer）
    • scope（可選，依 channel/chatType/session key 篩選）
  • tools.media.concurrency：最大並行能力執行數（預設 2）。
{
  tools: {
    media: {
      models: [
        /* 共用清單 */
      ],
      image: {
        /* 可選覆寫 */
      },
      audio: {
        /* 可選覆寫 */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* 可選覆寫 */
      },
    },
  },
}

模型項目

每個 models[] 項目可以是 provider 或 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 bytes 的音訊檔被視為空白/損毀，在 provider/CLI 轉錄前直接跳過。
  • 如果模型回傳超過 maxChars，輸出會被裁切。
  • prompt 預設為簡單的「Describe the {media}.」加上 maxChars 提示（僅圖片/影片）。
  • 如果 <capability>.enabled: true 但未設定模型，OpenClaw 會在 provider 支援該能力時，嘗試使用當前回覆模型。

自動偵測媒體理解（預設行為）

如果 tools.media.<capability>.enabled 未設為 false 且未設定模型，OpenClaw 會依以下順序自動偵測，找到第一個可用選項就停止：

  1. 本機 CLI（僅音訊；若已安裝）
    • sherpa-onnx-offline（需要 SHERPA_ONNX_MODEL_DIR，內含 encoder/decoder/joiner/tokens）
    • whisper-cli（whisper-cpp；使用 WHISPER_CPP_MODEL 或內建的 tiny 模型）
    • whisper（Python CLI；自動下載模型）
  2. Gemini CLI（gemini），使用 read_many_files
  3. Provider 金鑰
    • 音訊：OpenAI → Groq → Deepgram → Google
    • 圖片：OpenAI → Anthropic → Google → MiniMax
    • 影片：Google

停用自動偵測：

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

注意：跨 macOS/Linux/Windows 的二進位偵測為盡力而為；請確保 CLI 在 PATH 中（支援展開 ~），或在 CLI 模型中指定完整的指令路徑。

Proxy 環境支援（provider 模型）

當啟用 provider 的音訊和影片媒體理解功能時，OpenClaw 會遵循標準的對外 proxy 環境變數進行 provider HTTP 呼叫：

  • HTTPS_PROXY
  • HTTP_PROXY
  • https_proxy
  • http_proxy

未設定 proxy 環境變數時，媒體理解使用直連。Proxy 值格式錯誤時，OpenClaw 會記錄警告並退回直連。

能力（可選）

設定 capabilities 時，該項目只會針對指定的媒體類型執行。共用清單中，OpenClaw 可以推斷預設值：

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

CLI 項目請明確設定 capabilities，避免意外匹配。 省略 capabilities 時，該項目適用於它所在的清單。

Provider 支援矩陣（OpenClaw 整合）

能力Provider 整合備註
ImageOpenAI / Anthropic / Google / 其他透過 pi-ai登錄檔中任何具圖片能力的模型皆可。
AudioOpenAI、Groq、Deepgram、Google、MistralProvider 轉錄（Whisper/Deepgram/Gemini/Voxtral）。
VideoGoogle（Gemini API）Provider 影片理解。

模型選擇指引

  • 當品質與安全性很重要時，優先使用各媒體能力最強的最新世代模型。
  • 處理不信任輸入的工具型 agent，避免使用較舊/較弱的媒體模型。
  • 每個能力至少保留一個備援以確保可用性（品質模型 + 更快/更便宜的模型）。
  • CLI 備援（whisper-cli、whisper、gemini）在 provider API 不可用時很實用。
  • parakeet-mlx 注意事項：使用 --output-dir 時，OpenClaw 會在輸出格式為 txt（或未指定）時讀取 <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)

這會顯示各能力的結果及使用的 provider/模型。

注意事項

  • 理解功能為盡力而為。錯誤不會阻擋回覆。
  • 即使理解功能停用，附件仍會傳遞給模型。
  • 使用 scope 限制理解功能的執行範圍（如僅私訊）。

相關文件

arrow_back
上一頁
Troubleshooting
下一頁
Images
arrow_forward