OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Nodes and media

音訊與語音訊息

功能

啟用音訊理解功能（或自動偵測）時，OpenClaw 會：

  1. 找出第一個音訊附件（本機路徑或 URL），並在需要時下載。
  2. 傳送至每個模型項目之前，強制執行 maxBytes。
  3. 依序執行第一個符合條件的模型項目（供應商或命令列介面）；若某個項目失敗或遭略過（大小／逾時），則嘗試下一個項目。
  4. 成功時，將 Body 替換為 [Audio] 區塊，並設定 {{Transcript}}。

轉錄成功時，CommandBody/RawBody 也會設為轉錄文字，讓斜線命令仍可運作。使用 --verbose 時，日誌會顯示轉錄的執行時間，以及轉錄文字取代本文的時間。

自動偵測（預設）

如果你尚未設定模型，且 tools.media.audio.enabled 不是 false，OpenClaw 會依下列順序自動偵測，並在找到第一個可用選項時停止：

  1. 作用中的回覆模型，前提是其供應商支援音訊理解。
  2. 已設定的供應商驗證 — 任何具有可用驗證、且其供應商支援音訊轉錄的 models.providers.* 項目。此項會在本機命令列介面之前檢查，因此已設定的 API 金鑰永遠優先於 PATH 上的本機二進位檔。 設定多個供應商時的優先順序：Groq、OpenAI、xAI、Deepgram、Google、SenseAudio、ElevenLabs、Mistral。
  3. 本機命令列介面（僅限未解析出供應商驗證時）。OpenClaw 會建立依序排列的備援清單：
    • whisper-cli，僅當目前處理程序中較早的模型叫用觀察到 Metal 或 CUDA 時，才會排在 CPU 預設值之前
    • sherpa-onnx-offline 使用其預設 CPU 供應商（需要具備 tokens.txt、encoder.onnx、decoder.onnx 和 joiner.onnx 的 SHERPA_ONNX_MODEL_DIR）
    • 當 Metal/CUDA 僅具備建置能力，或選取的後端在其他情況下尚未被觀察到時，使用 whisper-cli
    • 在 Apple Silicon 上使用 parakeet-mlx（具備 MLX 能力；裝置使用情況仍未觀察）
    • whisper（Python 命令列介面；自動下載模型）

安裝／連結來源是能力證據，而不是執行證據。它本身絕不會讓候選項目的順位超越 CPU sherpa。OpenClaw 不會在設定或狀態檢查期間載入模型，只為探測後端。 自動偵測到的 whisper.cpp 會保持啟用其一般模型執行日誌，讓 OpenClaw 能記錄上游的 using … backend 行。明確設定的命令列介面項目則保留其設定的輸出旗標。

用於媒體理解的 Gemini CLI 自動偵測已由沙箱化的 Antigravity CLI（agy）備援取代，供影像／影片使用；除了上述本機二進位檔外，音訊不使用命令列介面備援。

若要停用自動偵測，請設定 tools.media.audio.enabled: false。若要自訂，請將具能力標籤的項目新增至 tools.media.models。

不轉錄音訊，直接檢查本機選擇：

bash
openclaw capability audio providersopenclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

供應商清單會將本機備援的勝出項目與全域供應商選擇分開報告，並列出具備能力、要求及觀察到的後端欄位。執行轉錄後，/status 會在媒體行中報告要求或觀察到的後端。明確設定且具備音訊能力的 tools.media.models 命令列介面項目仍會略過自動選擇；請使用其後端專用旗標，例如 sherpa 的 --provider=cuda，或 whisper.cpp 的 --no-gpu/--device。

設定範例

供應商 + 命令列介面備援（OpenAI + Whisper CLI）

json5
{  tools: {    media: {      models: [        { provider: "openai", model: "gpt-4o-transcribe", capabilities: ["audio"] },        {          type: "cli",          command: "whisper",          args: ["--model", "base", "{{AttachmentPath}}"],          timeoutSeconds: 45,          capabilities: ["audio"],        },      ],      audio: { enabled: true, preferredModel: "openai/gpt-4o-transcribe" },    },  },}

僅使用供應商（Deepgram）

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

僅使用供應商（Mistral Voxtral）

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

僅使用供應商（SenseAudio）

json5
{  tools: {    media: {      models: [        {          provider: "senseaudio",          model: "senseaudio-asr-pro-1.5-260319",          capabilities: ["audio"],        },      ],      audio: { enabled: true },    },  },}

將轉錄文字回顯至聊天（選擇性啟用）

json5
{  tools: {    media: {      audio: {        enabled: true,        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },    },  },}

注意事項與限制

  • 供應商驗證遵循標準模型驗證順序（驗證設定檔、環境變數、models.providers.*.apiKey）。
  • Groq 設定詳細資訊：Groq。
  • 使用 provider: "deepgram" 時，Deepgram 會取得 DEEPGRAM_API_KEY。設定詳細資訊：Deepgram。
  • Mistral 設定詳細資訊：Mistral。
  • 使用 provider: "senseaudio" 時，SenseAudio 會取得 SENSEAUDIO_API_KEY。設定詳細資訊：SenseAudio。
  • 音訊供應商可以使用 tools.media.audio 下的預設值，或在其 tools.media.models[] 項目上覆寫 baseUrl、headers、providerOptions 及限制。
  • 內建音訊大小上限為 20MB。項目層級的 maxBytes 覆寫可變更此限制；超出大小的音訊會針對該模型略過，並嘗試下一個項目。
  • 小於 1024 位元組的音訊檔案會在供應商／命令列介面轉錄之前遭到略過。
  • 音訊的預設 maxChars 為未設定（完整轉錄文字）。設定 tools.media.audio.maxChars 或每個項目的 maxChars 可截短輸出。
  • OpenAI 自動偵測的預設值為 gpt-4o-transcribe；設定 model: "gpt-4o-mini-transcribe" 可使用成本更低／速度更快的選項。
  • 範本可透過 {{Transcript}} 取得轉錄文字。
  • tools.media.audio.echoTranscript 預設為關閉；echoFormat 接受 {transcript} 預留位置。
  • 命令列介面標準輸出上限為 5MB；請保持命令列介面輸出精簡。
  • 命令列介面的 args 應使用 {{AttachmentPath}} 作為本機音訊檔案路徑。執行 openclaw doctor --fix，可遷移舊版 audio.transcription.command 設定中已棄用的 {input} 預留位置（已停用的鍵：audio.transcription，由 tools.media.models 取代）。{{MediaPath}} 仍是已棄用的相容性別名。
  • tools.media.concurrency 限制媒體工作；它不是 GPU 排程器。

常駐本機 STT

自動偵測的本機 STT 仍採每個要求一個處理程序。OpenClaw 目前不管理常駐 whisper.cpp 伺服器，因為標準 Homebrew whisper-cpp 套件會停用該伺服器，而上游範例並未設定有界的准入佇列。由外掛擁有的常駐生命週期，需要一個受維護的套件化工作程式，具備健康狀態／啟動、模型常駐、有界佇列、取消／逾時、僅限回送且無驗證的運作方式，以及不使用雲端備援，才能安全啟用。

代理環境支援

供應商型音訊轉錄會遵循標準對外代理環境變數，與 undici 的 EnvHttpProxyAgent 語意一致：

  • HTTPS_PROXY / https_proxy
  • HTTP_PROXY / http_proxy
  • ALL_PROXY / all_proxy

小寫變數的優先順序高於大寫變數；NO_PROXY/no_proxy 項目（主機名稱、*.suffix 或 host:port）會略過代理。如果未設定代理環境變數，則使用直接對外連線。如果代理設定失敗（URL 格式錯誤），OpenClaw 會記錄警告，並退回直接擷取。

群組中的提及偵測

在支援音訊預檢的頻道上，若群組聊天設定了 requireMention: true，OpenClaw 會在檢查提及之前轉錄音訊。這可讓沒有說明文字的語音訊息，在其轉錄文字包含已設定的提及模式時通過提及關卡。特定頻道的文件會說明哪些傳輸方式改為要求輸入文字提及。

運作方式：

  1. 如果語音訊息沒有文字本文，且群組要求提及，OpenClaw 會對第一個音訊附件執行預檢轉錄。
  2. 系統會檢查轉錄文字中的提及模式（例如 @BotName、表情符號觸發條件）。
  3. 如果找到提及，訊息就會進入完整回覆流水線。

**備援行為：**如果預檢轉錄失敗（逾時、API 錯誤等），訊息會退回僅文字提及偵測，因此混合訊息（文字 + 音訊）絕不會遭到捨棄。

依 Telegram 群組／主題選擇停用：

  • 設定 channels.telegram.groups.<chatId>.disableAudioPreflight: true，可略過該群組的預檢轉錄文字提及檢查。
  • 設定 channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight，可依主題覆寫（使用 true 略過，使用 false 強制啟用）。
  • 預設值為 false（符合提及關卡條件時啟用預檢）。

**範例：**使用者在設有 requireMention: true 的 Telegram 群組中傳送語音訊息，內容為 “嗨，@Claude，天氣如何？”。系統會轉錄語音訊息、偵測提及，然後代理程式進行回覆。

常見陷阱

  • 範圍規則採用第一個相符項目優先；chatType 會正規化為 direct、group 或 channel。
  • 請確保你的命令列介面以 0 結束，並輸出純文字；JSON 輸出需要透過 jq -r .text 進行處理。
  • 已知的檔案輸出模式具有最高權威性：推斷的轉錄檔案若為空或不存在，將不會產生轉錄文字，而不會退回命令列介面的進度輸出。
  • 針對 parakeet-mlx，請搭配 --output-dir 與預設 {filename} 輸出範本使用 --output-format txt（或 all）。也會遵循上游的 PARAKEET_OUTPUT_FORMAT 和 PARAKEET_OUTPUT_TEMPLATE 環境變數。OpenClaw 會讀取 <output-dir>/<media-basename>.txt；預設 srt 格式、其他格式及自訂輸出範本則繼續使用標準輸出。
  • 請保持合理的逾時設定（timeoutSeconds，預設 60s），以免阻塞回覆佇列。
  • 預檢轉錄只會處理第一個音訊附件以進行提及偵測。其他音訊附件會在主要媒體理解階段進行處理。

相關內容

Was this useful?
On this page

On this page