讓你的機器人看懂圖片與聽懂語音：OpenClaw 媒體理解指南

當你在開發聊天機器人時，最頭痛的往往不是處理文字，而是處理使用者丟過來的圖片、語音訊息或長影片。直接把原始檔案丟給模型處理，有時候會因為檔案太大而超時，或者模型無法精準抓到媒體內容的重點，導致後續的指令解析出錯。

如果能在模型正式回覆之前，先有一個「預處理」階段把這些媒體內容轉化為簡短的文字摘要，不僅能加速路由判斷，還能讓機器人更聰明地理解使用者的意圖。OpenClaw 的 Media Understanding 功能就是為了幫你解決這個問題。

需要準備的東西

• OpenClaw 環境
• 已配置的 Provider API Key（如 OpenAI, Google, Anthropic, Groq, Deepgram）
• （選配）本地 CLI 工具（如 whisper-cli, gemini CLI, sherpa-onnx-offline）

快速開始

OpenClaw 會自動偵測可用的工具。如果你什麼都不設定，它會嘗試按順序尋找本地 CLI 或已配置的 Provider。

1. 基礎配置

最簡單的方式是在你的設定檔中加入 tools.media。你可以設定共用的模型列表，並指定它們具備的能力：

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.2", capabilities: ["image"] },
        {
          provider: "google",
          model: "gemini-3-flash-preview",
          capabilities: ["image", "audio", "video"],
        },
      ],
      image: {
        maxChars: 500,
        maxBytes: 10485760, // 10MB
      },
    },
  },
}

2. 使用本地 CLI 工具

如果你想節省 API 費用，可以使用本地的 CLI 工具來處理媒體。OpenClaw 支援模板語法來帶入檔案路徑：

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

3. 附件處理策略

你可以決定要處理多少個附件。預設只會處理第一個，但你可以修改 attachments 策略：

{
  tools: {
    media: {
      audio: {
        attachments: {
          mode: "all",
          maxAttachments: 2,
          prefer: "first"
        },
      },
    },
  },
}

運作邏輯

1. 收集附件：OpenClaw 會抓取傳入的 MediaPaths 或 MediaUrls。
2. 選擇模型：根據媒體類型（圖片/音訊/影片）選擇符合能力且檔案大小在限制內的模型。
3. 自動回退 (Fallback)：如果第一個模型執行失敗或檔案太大，會自動嘗試清單中的下一個模型。
4. 注入內容：成功後，原本的訊息 Body 會加入 [Image] 等標籤。如果是音訊，會設定 {{Transcript}} 供後續使用。

如果你想關閉特定類型的自動偵測，可以手動停用：

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

檢查狀態

你可以透過 /status 指令來確認媒體理解的執行結果：

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

這會告訴你哪個部分成功、哪個部分因為超過檔案限制而被跳過。

疑難排解

• 媒體理解失敗：別擔心，這是一個 best-effort 功能。如果理解過程出錯，回覆流程依然會繼續，原始的附件還是會傳送給最終的回覆模型。
• 檔案被跳過：檢查 maxBytes 設定。如果媒體檔案超過該模型的限制，OpenClaw 會嘗試下一個模型，如果都沒有符合的則會跳過理解。
• 找不到 CLI 工具：確保你的 CLI 工具已加入 PATH，或者在設定中提供完整的執行檔路徑。
• 輸出文字被截斷：如果模型回傳的內容超過 maxChars，OpenClaw 會自動進行截斷。

有任何配置問題嗎？試試 AI Setup Assistant。

下一步

• Configuration
• Image & Media Support