文字轉語音（TTS）

OpenClaw 可以透過 ElevenLabs、OpenAI 或 Edge TTS 將外送回覆轉換為語音。只要 OpenClaw 能傳送音訊的地方都能使用；Telegram 上會顯示為圓形語音訊息氣泡。

支援的服務

  • ElevenLabs（主要或備援供應商）
  • OpenAI（主要或備援供應商；也用於摘要）
  • Edge TTS（主要或備援供應商；使用 node-edge-tts，未設定 API 金鑰時的預設選項）

Edge TTS 備註

Edge TTS 透過 node-edge-tts 函式庫使用 Microsoft Edge 的線上神經 TTS 服務。它是託管服務（非本地執行），使用 Microsoft 的端點，不需要 API 金鑰。node-edge-tts 提供語音設定選項和輸出格式，但並非所有選項都受 Edge 服務支援。citeturn2search0

由於 Edge TTS 是沒有公開 SLA 或配額的公共網路服務，請視為盡力而為。如果你需要有保障的配額和支援，請使用 OpenAI 或 ElevenLabs。Microsoft 的 Speech REST API 每次請求有 10 分鐘的音訊限制；Edge TTS 沒有公佈限制，因此假設相同或更低的上限。citeturn0search3

選用金鑰

如果你想使用 OpenAI 或 ElevenLabs：

  • ELEVENLABS_API_KEY（或 XI_API_KEY）
  • OPENAI_API_KEY

Edge TTS 不需要 API 金鑰。如果找不到任何 API 金鑰，OpenClaw 預設使用 Edge TTS（除非透過 messages.tts.edge.enabled=false 停用）。

若設定了多個供應商，選定的供應商優先使用，其他作為備援。自動摘要使用已設定的 summaryModel（或 agents.defaults.model.primary），因此啟用摘要時該供應商也必須完成驗證。

服務連結

預設有開啟嗎？

沒有。自動 TTS 預設關閉。在設定中用 messages.tts.auto 啟用，或在工作階段中用 /tts always（別名：/tts on）啟用。

一旦 TTS 開啟，Edge TTS 預設啟用，在沒有 OpenAI 或 ElevenLabs API 金鑰時自動使用。

設定

TTS 設定位於 openclaw.json 的 messages.tts 區段。完整 schema 請參閱 Gateway 設定。

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

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

OpenAI 為主、ElevenLabs 為備援

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      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,
        },
      },
    },
  },
}

Edge TTS 為主（不需 API 金鑰）

{
  messages: {
    tts: {
      auto: "always",
      provider: "edge",
      edge: {
        enabled: true,
        voice: "en-US-MichelleNeural",
        lang: "en-US",
        outputFormat: "audio-24khz-48kbitrate-mono-mp3",
        rate: "+10%",
        pitch: "-5%",
      },
    },
  },
}

停用 Edge TTS

{
  messages: {
    tts: {
      edge: {
        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："elevenlabs"、"openai" 或 "edge"（備援自動處理）。
  • 若 provider 未設定，OpenClaw 優先使用 openai（若有金鑰）、再 elevenlabs（若有金鑰），否則用 edge。
  • summaryModel：選用的輕量模型，用於自動摘要；預設使用 agents.defaults.model.primary。
    • 接受 provider/model 或已設定的模型別名。
  • modelOverrides：允許模型發送 TTS 指令（預設開啟）。
    • allowProvider 預設為 false（供應商切換需主動啟用）。
  • maxTextLength：TTS 輸入的硬上限（字元數）。超過時 /tts audio 會失敗。
  • timeoutMs：請求逾時（毫秒）。
  • prefsPath：覆蓋本地偏好 JSON 路徑（供應商／限制／摘要）。
  • apiKey 值會退回到環境變數（ELEVENLABS_API_KEY/XI_API_KEY、OPENAI_API_KEY）。
  • elevenlabs.baseUrl：覆蓋 ElevenLabs API 基礎 URL。
  • openai.baseUrl：覆蓋 OpenAI TTS 端點。
    • 解析順序：messages.tts.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
    • 非預設值會被視為 OpenAI 相容的 TTS 端點，因此接受自訂模型和語音名稱。
  • elevenlabs.voiceSettings：
    • stability、similarityBoost、style：0..1
    • useSpeakerBoost：true|false
    • speed：0.5..2.0（1.0 = 正常速度）
  • elevenlabs.applyTextNormalization：auto|on|off
  • elevenlabs.languageCode：兩碼 ISO 639-1（例如 en、de）
  • elevenlabs.seed：整數 0..4294967295（盡力確保確定性）
  • edge.enabled：允許使用 Edge TTS（預設 true；不需 API 金鑰）。
  • edge.voice：Edge 神經語音名稱（例如 en-US-MichelleNeural）。
  • edge.lang：語言代碼（例如 en-US）。
  • edge.outputFormat：Edge 輸出格式（例如 audio-24khz-48kbitrate-mono-mp3）。
    • 有效值請參閱 Microsoft Speech 輸出格式；並非所有格式都受 Edge 支援。
  • edge.rate / edge.pitch / edge.volume：百分比字串（例如 +10%、-5%）。
  • edge.saveSubtitles：在音訊檔案旁寫入 JSON 字幕。
  • edge.proxy：Edge TTS 請求的代理 URL。
  • edge.timeoutMs：請求逾時覆蓋（毫秒）。

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

預設情況下，模型可以為單一回覆發送 TTS 指令。當 messages.tts.auto 為 tagged 時，必須有這些指令才會觸發語音。

啟用時，模型可以發送 [[tts:...]] 指令來覆蓋單一回覆的語音設定，以及選用的 [[tts:text]]...[[/tts:text]] 區塊來提供只應出現在語音中的表達性標籤（笑聲、歌唱提示等）。

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

回覆酬載範例：

Here you go.

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

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

  • provider（openai | elevenlabs | edge，需設定 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,
      },
    },
  },
}

使用者偏好

斜線命令會將本地覆寫寫入 prefsPath（預設：~/.openclaw/settings/tts.json，可透過 OPENCLAW_TTS_PREFS 或 messages.tts.prefsPath 覆蓋）。

儲存的欄位：

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

這些設定會覆蓋該主機上的 messages.tts.*。

輸出格式（固定）

  • Telegram：Opus 語音訊息（ElevenLabs 的 opus_48000_64、OpenAI 的 opus）。
    • 48kHz / 64kbps 是語音訊息的良好平衡，也是顯示圓形氣泡的必要條件。
  • 其他頻道：MP3（ElevenLabs 的 mp3_44100_128、OpenAI 的 mp3）。
    • 44.1kHz / 128kbps 是語音清晰度的預設平衡。
  • Edge TTS：使用 edge.outputFormat（預設 audio-24khz-48kbitrate-mono-mp3）。
    • node-edge-tts 接受 outputFormat，但並非所有格式都可從 Edge 服務取得。citeturn2search0
    • 輸出格式值遵循 Microsoft Speech 輸出格式（包含 Ogg/WebM Opus）。citeturn1search0
    • Telegram sendVoice 接受 OGG/MP3/M4A；若需要保證 Opus 語音訊息，請使用 OpenAI/ElevenLabs。citeturn1search1
    • 如果設定的 Edge 輸出格式失敗，OpenClaw 會用 MP3 重試。

OpenAI/ElevenLabs 的格式是固定的；Telegram 需要 Opus 才能呈現語音訊息的 UX。

自動 TTS 行為

啟用後，OpenClaw 會：

  • 如果回覆已包含媒體或 MEDIA: 指令，跳過 TTS。
  • 跳過過短的回覆（< 10 字元）。
  • 啟用摘要時，使用 agents.defaults.model.primary（或 summaryModel）摘要長回覆。
  • 將產生的音訊附加到回覆。

如果回覆超過 maxLength 且摘要已關閉（或摘要模型沒有 API 金鑰），音訊會被跳過，直接傳送純文字回覆。

流程圖

回覆 -> TTS 啟用？
  否  -> 傳送文字
  是  -> 有媒體 / MEDIA: / 太短？
          是 -> 傳送文字
          否 -> 長度 > 上限？
                   否 -> TTS -> 附加音訊
                   是 -> 摘要啟用？
                            否 -> 傳送文字
                            是 -> 摘要（summaryModel 或 agents.defaults.model.primary）
                                      -> TTS -> 附加音訊

斜線命令用法

只有一個命令：/tts。啟用方式請參閱斜線命令。

Discord 注意事項：/tts 是 Discord 的內建命令，因此 OpenClaw 在 Discord 上註冊為 /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

備註：

  • 命令需要已授權的發話者（白名單／擁有者規則仍適用）。
  • commands.text 或原生命令註冊必須已啟用。
  • off|always|inbound|tagged 是按工作階段的開關（/tts on 是 /tts always 的別名）。
  • limit 和 summary 儲存在本地偏好，不在主設定檔中。
  • /tts audio 產生一次性語音回覆（不會開啟 TTS）。

Agent 工具

tts 工具將文字轉為語音，回傳 MEDIA: 路徑。當結果與 Telegram 相容時，工具會包含 [[audio_as_voice]]，讓 Telegram 傳送語音氣泡。

Gateway RPC

Gateway 方法：

  • tts.status
  • tts.enable
  • tts.disable
  • tts.convert
  • tts.setProvider
  • tts.providers
arrow_back
上一頁
Location Command
下一頁
Providers
arrow_forward