處理語音訊息與音檔 (Audio / Voice Notes)

每次收到語音訊息卻不方便點開來聽的時候，總是希望能直接看到文字內容。對開發者來說，處理這些音檔通常很麻煩，要考慮格式轉換、模型串接還有檔案大小限制。

OpenClaw 內建了音檔理解功能，可以自動幫你把語音訊息轉成文字，讓你像處理普通文字訊息一樣操作它們。

需要準備的東西

• OpenClaw：已安裝並完成基礎設定。
• Provider API Key：例如 OpenAI, Groq, Deepgram 或 Google（如果你打算用雲端轉錄）。
• 本地 CLI 工具：例如 whisper 或 sherpa-onnx-offline（如果你偏好在地端處理）。

快速開始

OpenClaw 預設會開啟自動偵測（Auto-detection）。如果你沒有特別設定 models，它會按照以下順序尋找可用的工具並直接執行：

1. 本地 CLIs：檢查 sherpa-onnx-offline、whisper-cpp 或 Python 版 whisper。
2. Gemini CLI：使用 gemini 指令。
3. Provider API：依序嘗試 OpenAI → Groq → Deepgram → Google。

如果你想手動指定轉錄方案，可以在 config.json5 中設定。這是一個結合 OpenAI 與本地 Whisper CLI 作為備援的範例：

{
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520, // 20MB 限制
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          {
            type: "cli",
            command: "whisper",
            args: ["--model", "base", "{{MediaPath}}"],
            timeoutSeconds: 45,
          },
        ],
      },
    },
  },
}

設定完成後，當機器人收到音檔，它會自動將內容轉為文字並存入 {{Transcript}} 變數。如果轉錄成功，原本的 CommandBody 也會被替換成轉錄內容，這代表你的斜線指令（Slash Commands）在語音訊息裡也能運作。

常用配置與限制

• 檔案大小：預設上限是 20MB (maxBytes)。如果音檔超過大小，系統會跳過該模型並嘗試下一個。
• 自動偵測：如果你想完全停用音檔處理，請設定 tools.media.audio.enabled: false。
• Deepgram 專屬設定：如果你使用 provider: "deepgram"，系統會自動尋找 DEEPGRAM_API_KEY 環境變數。
• 多個附件：如果你想一次處理多個語音訊息，可以設定 tools.media.audio.attachments 的 mode: "all"。

疑難排解

• 音檔被跳過：檢查檔案是否超過 maxBytes (預設 20MB)。如果是 CLI 模式，請確認該工具是否在你的 PATH 路徑中。
• 群組訊息沒反應：檢查 scope 規則。如果你設定了 match: { chatType: "group" } 為 deny，機器人就不會處理群組內的音檔。
• 轉錄超時：預設超時時間為 60 秒。如果你的音檔很長或本地機器效能較弱，請增加 timeoutSeconds。
• CLI 輸出錯誤：確保你的 CLI 工具直接輸出純文字。如果輸出的是 JSON，你需要用 jq -r .text 之類的指令處理。

有任何設定上的疑問嗎？你可以詢問 AI Setup Assistant 獲取即時協助。

下一步

• Deepgram 設定指南
• 查看所有支援的 Media 參數