跳到內容
OpenClaw

設定 OpenClaw 文字轉語音：串接 ElevenLabs、OpenAI 與 Microsoft

OpenClaw 可以幫你把回覆內容轉換成音訊，支援 ElevenLabs、Microsoft 或 OpenAI。只要是 OpenClaw 能傳送音訊的地方，這個功能都能運作。

支援的服務

Section titled “支援的服務”
  • ElevenLabs（主要或備援提供商）
  • Microsoft（主要或備援提供商；目前的內建實作使用 node-edge-tts）
  • OpenAI（主要或備援提供商；也用於摘要功能）

Microsoft 語音說明

Section titled “Microsoft 語音說明”

內建的 Microsoft 語音提供商目前透過 node-edge-tts 函式庫使用 Microsoft Edge 的線上神經 TTS 服務。這是一個託管服務（非本地端），使用 Microsoft 的端點，且不需要 API key。node-edge-tts 提供了語音設定選項和輸出格式，但並非所有選項都受該服務支援。使用 edge 的舊版設定和指令輸入仍然有效，並會被標準化為 microsoft。

因為這條路徑是沒有公開 SLA 或配額的公共 Web 服務，請將其視為「盡力而為」（best-effort）。如果你需要保證限制和支援，請使用 OpenAI 或 ElevenLabs。

選填的金鑰

Section titled “選填的金鑰”

如果你想使用 OpenAI 或 ElevenLabs：

  • ELEVENLABS_API_KEY（或 XI_API_KEY）
  • OPENAI_API_KEY

Microsoft 語音不需要 API key。

如果設定了多個提供商，系統會先使用選定的提供商，其他則作為備援選項。自動摘要會使用設定的 summaryModel（或 agents.defaults.model.primary），所以如果你啟用了摘要功能，該提供商也必須完成身分驗證。

服務連結

Section titled “服務連結”

預設有啟用嗎？

Section titled “預設有啟用嗎？”

沒有。自動 TTS 預設是關閉的。你可以在設定中透過 messages.tts.auto 啟用，或是針對特定對話使用 /tts always（別名：/tts on）。

當 messages.tts.provider 未設定時，OpenClaw 會按照註冊表的自動選擇順序，挑選第一個設定好的語音提供商。

設定 (Config)

Section titled “設定 (Config)”

TTS 設定位於 openclaw.json 中的 messages.tts 下。完整的 schema 可以在 Gateway configuration 找到。

最簡設定 (啟用 + provider)

Section titled “最簡設定 (啟用 + provider)”
{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
    },
  },
}

以 OpenAI 為主並使用 ElevenLabs 作為備援

Section titled “以 OpenAI 為主並使用 ElevenLabs 作為備援”
{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      providers: {
        openai: {
          apiKey: "openai_api_key",
          baseUrl: "https://api.openai.com/v1",
          model: "gpt-4o-mini-tts",
          voice: "alloy",
        },
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          voiceId: "voice_id",
          modelId: "eleven_multilingual_v2",
          seed: 42,
          applyTextNormalization: "auto",
          languageCode: "en",
          voiceSettings: {
            stability: 0.5,
            similarityBoost: 0.75,
            style: 0.0,
            useSpeakerBoost: true,
            speed: 1.0,
          },
        },
      },
    },
  },
}

Microsoft 為主 (無需 API key)

Section titled “Microsoft 為主 (無需 API key)”
{
  messages: {
    tts: {
      auto: "always",
      provider: "microsoft",
      providers: {
        microsoft: {
          enabled: true,
          voice: "en-US-MichelleNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
          rate: "+10%",
          pitch: "-5%",
        },
      },
    },
  },
}

停用 Microsoft 語音

Section titled “停用 Microsoft 語音”
{
  messages: {
    tts: {
      providers: {
        microsoft: {
          enabled: false,
        },
      },
    },
  },
}

自定義限制 + 偏好設定路徑

Section titled “自定義限制 + 偏好設定路徑”
{
  messages: {
    tts: {
      auto: "always",
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
    },
  },
}

僅在收到語音訊息後才以音訊回覆

Section titled “僅在收到語音訊息後才以音訊回覆”
{
  messages: {
    tts: {
      auto: "inbound",
    },
  },
}

停用長回覆的自動摘要

Section titled “停用長回覆的自動摘要”
{
  messages: {
    tts: {
      auto: "always",
    },
  },
}

接著執行：

/tts summary off

欄位說明

Section titled “欄位說明”
  • auto: 自動 TTS 模式 (off, always, inbound, tagged)。
    • inbound 僅在收到語音訊息後發送音訊。
    • tagged 僅在回覆包含 [[tts]] 標籤時發送音訊。
  • enabled: 舊版開關 (doctor 會將此遷移至 auto)。
  • mode: "final" (預設) 或 "all" (包含工具/區塊回覆)。
  • provider: 語音供應商 ID，例如 "elevenlabs", "microsoft", 或 "openai" (會自動處理備援)。
  • 如果未設定 provider，OpenClaw 會使用註冊表自動選擇順序中的第一個語音供應商。
  • 舊有的 provider: "edge" 仍可運作，並會被標準化為 microsoft。
  • summaryModel: 用於自動摘要的選用廉價模型；預設為 agents.defaults.model.primary。
    • 接受 provider/model 或已設定的模型別名。
  • modelOverrides: 允許模型發出 TTS 指令 (預設開啟)。
    • allowProvider 預設為 false (切換供應商功能需手動開啟)。
  • providers.<id>: 由語音供應商 ID 索引的供應商專屬設定。
  • 舊版的直接供應商區塊 (messages.tts.openai, messages.tts.elevenlabs, messages.tts.microsoft, messages.tts.edge) 在載入時會自動遷移至 messages.tts.providers.<id>。
  • maxTextLength: TTS 輸入的硬性上限 (字元數)。超過時 /tts audio 會失敗。
  • timeoutMs: 請求逾時時間 (ms)。
  • prefsPath: 覆寫本地偏好設定 JSON 路徑 (供應商/限制/摘要)。
  • apiKey 的值若未設定，會回退到環境變數 (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY)。
  • providers.elevenlabs.baseUrl: 覆寫 ElevenLabs API 基礎 URL。
  • providers.openai.baseUrl: 覆寫 OpenAI TTS 端點。
    • 解析順序：messages.tts.providers.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
    • 非預設值會被視為相容 OpenAI 的 TTS 端點，因此接受自定義模型和語音名稱。
  • providers.elevenlabs.voiceSettings:
    • stability, similarityBoost, style: 0..1
    • useSpeakerBoost: true|false
    • speed: 0.5..2.0 (1.0 為正常)
  • providers.elevenlabs.applyTextNormalization: auto|on|off
  • providers.elevenlabs.languageCode: 2 位字母的 ISO 639-1 代碼 (例如 en, de)
  • providers.elevenlabs.seed: 整數 0..4294967295 (盡力實現確定性)
  • providers.microsoft.enabled: 允許使用 Microsoft 語音 (預設為 true；無需 API key)。
  • providers.microsoft.voice: Microsoft 神經網路語音名稱 (例如 en-US-MichelleNeural)。
  • providers.microsoft.lang: 語言代碼 (例如 en-US)。
  • providers.microsoft.outputFormat: Microsoft 輸出格式 (例如 audio-24khz-48kbitrate-mono-mp3)。
    • 參考 Microsoft Speech 輸出格式以獲取有效值；並非所有格式都受內建的 Edge 傳輸支援。
  • providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume: 百分比字串 (例如 +10%, -5%)。
  • providers.microsoft.saveSubtitles: 在音訊檔案旁寫入 JSON 字幕。
  • providers.microsoft.proxy: Microsoft 語音請求的代理伺服器 URL。
  • providers.microsoft.timeoutMs: 請求逾時覆寫 (ms)。
  • edge.*: 相同 Microsoft 設定的舊版別名。

模型驅動的覆寫 (預設開啟)

Section titled “模型驅動的覆寫 (預設開啟)”

預設情況下，模型可以針對單次回覆發出 TTS 指令。當 messages.tts.auto 設定為 tagged 時，必須有這些指令才會觸發音訊。

啟用後，模型可以發出 [[tts:...]] 指令來覆寫單次回覆的聲音，還能使用選用的 [[tts:text]]...[[/tts:text]] 區塊來提供表現力標籤（如笑聲、唱歌提示等），這些標籤只會出現在音訊中。

除非 modelOverrides.allowProvider: true，否則 provider=... 指令會被忽略。

範例回覆內容：

Here you go.


[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](laughs) Read the song once more.[[/tts:text]]

可用的指令鍵（啟用時）：

  • provider (已註冊的語音供應商 ID，例如 openai, elevenlabs 或 microsoft；需要 allowProvider: true)
  • voice (OpenAI 語音) 或 voiceId (ElevenLabs)
  • model (OpenAI TTS 模型或 ElevenLabs 模型 ID)
  • stability, similarityBoost, style, speed, useSpeakerBoost
  • applyTextNormalization (auto|on|off)
  • languageCode (ISO 639-1)
  • seed

停用所有模型覆寫：

{
  messages: {
    tts: {
      modelOverrides: {
        enabled: false,
      },
    },
  },
}

選用的允許清單（啟用供應商切換，同時保持其他參數可調）：

{
  messages: {
    tts: {
      modelOverrides: {
        enabled: true,
        allowProvider: true,
        allowSeed: false,
      },
    },
  },
}

個別用戶偏好設定

Section titled “個別用戶偏好設定”

Slash 指令會將本地覆寫寫入 prefsPath（預設路徑為 ~/.openclaw/settings/tts.json，你可以透過 OPENCLAW_TTS_PREFS 或 messages.tts.prefsPath 來修改）。

儲存的欄位：

  • enabled
  • provider
  • maxLength（摘要門檻；預設 1500 字元）
  • summarize（預設為 true）

這些設定會覆寫該主機的 messages.tts.* 配置。

輸出格式（固定）

Section titled “輸出格式（固定）”
  • Feishu / Matrix / Telegram / WhatsApp: Opus 語音訊息（ElevenLabs 的 opus_48000_64，OpenAI 的 opus）。
    • 48kHz / 64kbps 是語音訊息在品質與大小之間的理想折衷。
  • 其他頻道: MP3（ElevenLabs 的 mp3_44100_128，OpenAI 的 mp3）。
    • 44.1kHz / 128kbps 是語音清晰度的預設平衡點。
  • Microsoft: 使用 microsoft.outputFormat（預設為 audio-24khz-48kbitrate-mono-mp3）。
    • 內建的傳輸機制接受 outputFormat，但並非所有格式都能從服務端取得。
    • 輸出格式的數值遵循 Microsoft Speech 輸出格式（包含 Ogg/WebM Opus）。
    • Telegram 的 sendVoice 接受 OGG/MP3/M4A；如果你需要保證輸出 Opus 語音訊息，請使用 OpenAI 或 ElevenLabs。
    • 如果設定的 Microsoft 輸出格式失敗，OpenClaw 會嘗試改用 MP3 重新執行。

OpenAI/ElevenLabs 的輸出格式是根據頻道固定的（見上方說明）。

Auto-TTS 行為

Section titled “Auto-TTS 行為”

當你開啟這個功能時，OpenClaw 會自動執行以下邏輯：

  • 如果回覆內容已經包含媒體檔案或 MEDIA: 指令，會直接跳過 TTS。
  • 跳過字數太短的回覆（少於 10 個字元）。
  • 當回覆太長且你開啟了摘要功能時，會使用 agents.defaults.model.primary（或 summaryModel）進行摘要。
  • 將產生的音訊檔案附加到回覆中。

如果回覆長度超過了 maxLength，但摘要功能處於關閉狀態（或沒有設定摘要模型的 API key），系統會跳過語音生成，直接傳送一般的文字回覆。

流程圖

Section titled “流程圖”
Reply -> TTS enabled?
  no  -> send text
  yes -> has media / MEDIA: / short?
          yes -> send text
          no  -> length > limit?
                   no  -> TTS -> attach audio
                   yes -> summary enabled?
                            no  -> send text
                            yes -> summarize (summaryModel or agents.defaults.model.primary)
                                      -> TTS -> attach audio

Slash command 使用方式

Section titled “Slash command 使用方式”

這裡只有一個指令：/tts。 關於如何啟用的細節，請參考 Slash commands。

Discord 筆記：因為 /tts 是 Discord 內建的指令，所以 OpenClaw 在那裡會註冊 /voice 作為原生指令。不過直接輸入文字 /tts ... 依然有效。

/tts off
/tts always
/tts inbound
/tts tagged
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Hello from OpenClaw

筆記：

  • 指令需要經過授權的發送者（allowlist/owner 規則依然適用）。
  • 必須啟用 commands.text 或原生指令註冊。
  • off|always|inbound|tagged 是針對每個 session 的切換開關（/tts on 是 /tts always 的別名）。
  • limit 和 summary 儲存在本地偏好設定（local prefs）中，而不是主設定檔。
  • /tts audio 會產生一次性的音訊回覆（不會切換 TTS 的開啟狀態）。
  • /tts status 包含最後一次嘗試的備援（fallback）狀態：
    • 成功備援：Fallback: <primary> -> <used> 加上 Attempts: ...
    • 失敗：Error: ... 加上 Attempts: ...
    • 詳細診斷資訊：Attempt details: provider:outcome(reasonCode) latency
  • OpenAI 和 ElevenLabs 的 API 失敗現在會包含解析後的 provider 錯誤詳情與 request id（如果 provider 有回傳的話），這些資訊會顯示在 TTS 錯誤或 log 中。

Agent 工具

Section titled “Agent 工具”

tts 工具會將文字轉換為語音，並回傳音訊附件來發送回覆。當頻道是 Feishu, Matrix, Telegram 或 WhatsApp 時，音訊會以語音訊息（voice message）的形式發送，而不是一般的檔案附件。

Gateway RPC

Section titled “Gateway RPC”

Gateway 方法：

  • tts.status
  • tts.enable
  • tts.disable
  • tts.convert
  • tts.setProvider
  • tts.providers
OpenClaw

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。