音訊 / 語音訊息 — 2026-01-17

目前支援的功能

媒體理解（音訊）：啟用音訊理解功能後（或自動偵測時），OpenClaw 會：
1. 找到第一個音訊附件（本機路徑或 URL），必要時下載。
2. 傳送給各模型項目前，檢查 maxBytes 限制。
3. 依序執行第一個符合條件的模型項目（provider 或 CLI）。
4. 若失敗或跳過（檔案過大/逾時），嘗試下一個項目。
5. 成功後，將 Body 替換為 [Audio] 區塊，並設定 {{Transcript}}。
指令解析：轉錄成功時，CommandBody/RawBody 會設為轉錄文字，斜線指令因此仍可正常運作。
詳細記錄：--verbose 模式下，會記錄轉錄執行時機及替換內容。

自動偵測（預設行為）

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

本機 CLI（若已安裝）
- sherpa-onnx-offline（需要 SHERPA_ONNX_MODEL_DIR，內含 encoder/decoder/joiner/tokens）
- whisper-cli（來自 whisper-cpp；使用 WHISPER_CPP_MODEL 或內建的 tiny 模型）
- whisper（Python CLI；自動下載模型）
Gemini CLI（gemini），使用 read_many_files
Provider 金鑰（OpenAI → Groq → Deepgram → Google）

停用自動偵測：設定 tools.media.audio.enabled: false。自訂設定：配置 tools.media.audio.models。注意：跨 macOS/Linux/Windows 的二進位偵測為盡力而為；請確保 CLI 在 PATH 中（支援展開 ~），或在 CLI 模型中指定完整的指令路徑。

設定範例

Provider + 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,
          },
        ],
      },
    },
  },
}

純 Provider 搭配範圍控制

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

純 Provider（Deepgram）

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

純 Provider（Mistral Voxtral）

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "mistral", model: "voxtral-mini-latest" }],
      },
    },
  },
}

回傳轉錄文字到聊天（需手動啟用）

{
  tools: {
    media: {
      audio: {
        enabled: true,
        echoTranscript: true, // 預設為 false
        echoFormat: '📝 "{transcript}"', // 可選，支援 {transcript}
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

注意事項與限制

Provider 驗證遵循標準模型驗證順序（auth profiles、環境變數、models.providers.*.apiKey）。
使用 provider: "deepgram" 時，Deepgram 會讀取 DEEPGRAM_API_KEY。
Deepgram 設定詳情：Deepgram（音訊轉錄）。
Mistral 設定詳情：Mistral。
音訊 provider 可透過 tools.media.audio 覆寫 baseUrl、headers 和 providerOptions。
預設大小上限為 20MB（tools.media.audio.maxBytes）。超過限制的音訊會跳過該模型，轉而嘗試下一個。
小於 1024 bytes 的微小/空白音訊檔會在 provider/CLI 轉錄前直接跳過。
音訊的預設 maxChars 為未設定（完整轉錄）。可透過 tools.media.audio.maxChars 或個別項目的 maxChars 來裁切輸出。
OpenAI 自動偵測預設使用 gpt-4o-mini-transcribe；設定 model: "gpt-4o-transcribe" 可提高準確度。
使用 tools.media.audio.attachments 可處理多個語音訊息（mode: "all" + maxAttachments）。
轉錄文字可透過 {{Transcript}} 在範本中使用。
tools.media.audio.echoTranscript 預設關閉；啟用後會在 agent 處理前，將轉錄確認訊息回傳到原始聊天。
tools.media.audio.echoFormat 可自訂回傳文字（佔位符：{transcript}）。
CLI 標準輸出上限為 5MB；請保持 CLI 輸出簡潔。

Proxy 環境支援

Provider 音訊轉錄會遵循標準的對外 proxy 環境變數：

HTTPS_PROXY
HTTP_PROXY
https_proxy
http_proxy

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

群組中的提及偵測

當群組聊天設定了 requireMention: true 時，OpenClaw 會先轉錄音訊再檢查提及。這樣即使語音訊息中包含提及，也能正確處理。

運作方式：

如果語音訊息沒有文字內容，且群組要求提及，OpenClaw 會執行「預檢」轉錄。
檢查轉錄文字中的提及模式（如 @BotName、表情觸發詞）。
偵測到提及後，訊息進入完整的回覆流程。
轉錄文字用於提及偵測，讓語音訊息也能通過提及閘門。

失敗時的處理：

預檢轉錄失敗時（逾時、API 錯誤等），訊息改以純文字提及偵測處理。
這確保混合訊息（文字 + 音訊）不會被錯誤丟棄。

Telegram 群組/話題個別停用：

設定 channels.telegram.groups.<chatId>.disableAudioPreflight: true 可跳過該群組的預檢轉錄提及檢查。
設定 channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight 可按話題覆寫（true 跳過，false 強制啟用）。
預設為 false（符合提及閘門條件時啟用預檢）。

範例： 使用者在設定了 requireMention: true 的 Telegram 群組中，送出一則語音訊息說「嘿 @Claude，今天天氣怎樣？」語音訊息被轉錄後，偵測到提及，agent 隨即回覆。

常見問題

範圍規則採用先匹配優先。chatType 會標準化為 direct、group 或 room。
確保你的 CLI 以 exit code 0 退出且輸出純文字；JSON 格式需透過 jq -r .text 轉換。
對於 parakeet-mlx，如果傳入 --output-dir，OpenClaw 會在 --output-format 為 txt（或未指定）時讀取 <output-dir>/<media-basename>.txt；非 txt 輸出格式則退回解析標準輸出。
逾時設定請保持合理（timeoutSeconds，預設 60 秒），避免阻塞回覆佇列。
預檢轉錄只處理第一個音訊附件以進行提及偵測。其餘音訊在主要媒體理解階段處理。