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

文字轉語音 (TTS)

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

支援的服務

ElevenLabs（主要或備援提供商）
Microsoft（主要或備援提供商；目前內建實作使用 node-edge-tts）
OpenAI（主要或備援提供商；也用於摘要功能）

Microsoft 語音注意事項

內建的 Microsoft 語音提供商目前透過 node-edge-tts 函式庫使用 Microsoft Edge 的線上神經網路 TTS 服務。這是一個託管服務（非本地端），使用 Microsoft 的端點，而且不需要 API key。node-edge-tts 提供了語音配置選項和輸出格式，但並非所有選項都受到該服務支援。如果你使用舊版的 edge 配置或指令，系統仍會正常運作並自動轉換為 microsoft。

因為這是一個公開的網路服務，沒有保證的 SLA 或額度限制，請將其視為「盡力而為」（best-effort）。如果你需要穩定的限制和支援，建議使用 OpenAI 或 ElevenLabs。

選填的金鑰

如果你想使用 OpenAI 或 ElevenLabs：

ELEVENLABS_API_KEY (或 XI_API_KEY)
OPENAI_API_KEY

Microsoft 語音不需要 API key。

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

服務連結

預設有啟用嗎？

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

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

設定

TTS 設定位於 openclaw.json 中的 messages.tts 下。完整的 Schema 請參考 Gateway configuration。

最簡設定（啟用 + 供應商）

{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
    },
  },
}

以 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）

{
  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 語音

{
  messages: {
    tts: {
      providers: {
        microsoft: {
          enabled: false,
        },
      },
    },
  },
}

自定義限制 + 偏好路徑

{
  messages: {
    tts: {
      auto: "always",
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
    },
  },
}

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

{
  messages: {
    tts: {
      auto: "inbound",
    },
  },
}

針對長回覆停用自動摘要

{
  messages: {
    tts: {
      auto: "always",
    },
  },
}

接著執行：

/tts summary off

欄位說明

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, zh）
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 設定的舊版別名。

模型驅動的覆寫（預設開啟）

預設情況下，模型可以針對單次回覆發出 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,
      },
    },
  },
}

AI Setup Assistant

個人偏好設定

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

儲存的欄位包含：

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

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

輸出格式（固定）

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 行為機制

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

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

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

流程圖

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 指令用法

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

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 儲存在本地偏好設定中，而不是主設定檔。
/tts audio 會產生一次性的音訊回覆（不會切換 TTS 開關）。
/tts status 包含最後一次嘗試的備援可見性：
- 成功備援：Fallback: <primary> -> <used> 加上 Attempts: ...
- 失敗：Error: ... 加上 Attempts: ...
- 詳細診斷：Attempt details: provider:outcome(reasonCode) latency
OpenAI 和 ElevenLabs 的 API 失敗現在包含解析後的供應商錯誤詳情和 request id（如果供應商有回傳的話），這些資訊會顯示在 TTS 錯誤或日誌中。

Agent 工具

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

Gateway RPC

Gateway 方法：

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

OpenClaw Expert

還是卡住了？

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