跳轉到主要內容

​
音訊／語音備忘錄 — 2026-01-17

​
36. 可行項目

  • 媒體理解（音訊）：若已啟用（或自動偵測）音訊理解，OpenClaw 會：
    1. Locates the first audio attachment (local path or URL) and downloads it if needed.
    2. 在送交每個模型項目前強制執行 maxBytes。
    3. 依序執行第一個符合資格的模型項目（提供者或 CLI）。
      1. 若失敗或被略過（大小／逾時），會嘗試下一個項目。
    5. 成功時，將 Body 取代為 [Audio] 區塊，並設定 {{Transcript}}。
  • 指令解析：當轉寫成功時，會將 CommandBody／RawBody 設為轉寫內容，讓斜線指令仍可運作。
    1. 詳細日誌：在 --verbose 模式下，會記錄轉錄何時執行，以及何時取代本文。

​
自動偵測（預設）

如果你未設定模型，且 tools.media.audio.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. 提供者金鑰（OpenAI → Groq → Deepgram → Google）
若要停用自動偵測，請設定 tools.media.audio.enabled: false。 若要自訂，請設定 tools.media.audio.models。 注意：在 macOS／Linux／Windows 上，二進位檔偵測為盡力而為；請確保 CLI 位於 PATH（我們會展開 ~），或使用完整指令路徑設定明確的 CLI 模型。 To customize, set tools.media.audio.models. To customize, set tools.media.audio.models. 注意：二進位檔偵測在 macOS／Linux／Windows 上為最佳努力；請確保 CLI 位於 PATH（我們會展開 ~），或設定一個具有完整指令路徑的明確 CLI 模型。

​
設定範例

​
提供者 + CLI 備援（OpenAI + Whisper CLI）

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

​
41. 僅限供應商，並具備範圍閘控

{
  tools: {
    media: {
      audio: {
        enabled: true,
        scope: {
          default: "allow",
          rules: [{ action: "deny", match: { chatType: "group" } }],
        },
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

​
僅提供者（Deepgram）

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "deepgram", model: "nova-3" }],
      },
    },
  },
}

​
注意事項與限制

  • 提供者身分驗證遵循標準模型驗證順序（驗證設定檔、環境變數、models.providers.*.apiKey）。
  • 使用 provider: "deepgram" 時，Deepgram 會讀取 DEEPGRAM_API_KEY。
  • Deepgram 設定細節：Deepgram（音訊轉寫）。
  • 音訊提供者可透過 tools.media.audio 覆寫 baseUrl、headers 與 providerOptions。
  • 預設大小上限為 20MB（tools.media.audio.maxBytes）。 43. 超出大小限制的音訊會對該模型略過，並嘗試下一個項目。
  • 音訊的預設 maxChars 為 未設定（完整逐字稿）。 音訊的預設 maxChars 為 未設定（完整轉寫）。請設定 tools.media.audio.maxChars 或每個項目的 maxChars 以裁剪輸出。 音訊的預設 maxChars 為 未設定（完整轉寫）。請設定 tools.media.audio.maxChars 或每個項目的 maxChars 以裁剪輸出。
  • OpenAI 的自動預設為 gpt-4o-mini-transcribe；設定 model: "gpt-4o-transcribe" 可提升準確度。
  • 使用 tools.media.audio.attachments 以處理多個語音備忘錄（mode: "all" + maxAttachments）。
    1. 轉錄稿可在範本中以 {{Transcript}} 使用。
  • CLI stdout 具上限（5MB）；請保持 CLI 輸出精簡。

​
群組中的提及偵測

當在群組聊天中設定 requireMention: true 時，OpenClaw 現在會先轉錄音訊，再檢查是否包含提及。 這讓語音訊息即使包含提及，也能被處理。 運作方式：
  1. 如果語音訊息沒有文字內容，且群組需要提及，OpenClaw 會先執行一次「preflight」轉錄。
  2. 系統會檢查轉錄文字中是否包含提及模式（例如 @BotName、表情符號觸發）。
  3. 如果偵測到提及，訊息將進入完整的回覆流程。
  4. 系統會使用轉錄內容進行提及偵測，讓語音訊息能通過提及檢查門檻。
備援行為：
  • 如果在 preflight 期間轉錄失敗（逾時、API 錯誤等），訊息將改以僅文字的提及偵測方式處理。
  • 這可確保混合訊息（文字 + 音訊）不會被錯誤忽略。
範例： 使用者在一個設定 requireMention: true 的 Telegram 群組中傳送語音訊息：「Hey @Claude, what’s the weather?」 語音訊息會先被轉錄，偵測到提及後，代理程式即會回覆。

​
30. 注意事項

    1. 範圍規則採用先匹配者優先。 範圍規則採用先匹配者優先。 範圍規則採用「第一個符合者優先」。chatType 會正規化為 direct、group 或 room。
  • 請確保你的 CLI 以 0 結束並輸出純文字；若為 JSON，需透過 jq -r .text 進行處理。
  • 請將逾時設定保持在合理範圍（timeoutSeconds，預設 60 秒），以避免阻塞回覆佇列。
  • Preflight 轉錄僅會處理第一個音訊附件以進行提及偵測。 其他音訊會在主要的媒體理解階段中處理。