Text-to-speech (TTS)

OpenClaw có thể chuyển các phản hồi thành file âm thanh bằng ElevenLabs, OpenAI hoặc Edge TTS. Tính năng này hoạt động ở bất kỳ đâu OpenClaw có thể gửi audio; trên Telegram sẽ hiển thị dạng voice note tròn.

Các dịch vụ được hỗ trợ

  • ElevenLabs (provider chính hoặc dự phòng)
  • OpenAI (provider chính hoặc dự phòng; cũng dùng cho tóm tắt)
  • Edge TTS (provider chính hoặc dự phòng; dùng node-edge-tts, mặc định khi không có API key)

Lưu ý về Edge TTS

Edge TTS sử dụng dịch vụ TTS neural trực tuyến của Microsoft Edge thông qua thư viện node-edge-tts. Đây là dịch vụ hosted (không chạy local), dùng endpoint của Microsoft và không cần API key. node-edge-tts cung cấp các tùy chọn cấu hình giọng nói và định dạng đầu ra, nhưng không phải tất cả tùy chọn đều được Edge service hỗ trợ. citeturn2search0

Vì Edge TTS là dịch vụ web công cộng không có SLA hoặc quota công bố, các bạn nên coi đây là dịch vụ best-effort. Nếu cần giới hạn đảm bảo và hỗ trợ, hãy dùng OpenAI hoặc ElevenLabs. Speech REST API của Microsoft ghi nhận giới hạn 10 phút audio mỗi request; Edge TTS không công bố giới hạn, nên mình giả định giới hạn tương tự hoặc thấp hơn. citeturn0search3

API key tùy chọn

Nếu các bạn muốn dùng OpenAI hoặc ElevenLabs:

  • ELEVENLABS_API_KEY (hoặc XI_API_KEY)
  • OPENAI_API_KEY

Edge TTS không cần API key. Nếu không tìm thấy API key nào, OpenClaw sẽ mặc định dùng Edge TTS (trừ khi tắt qua messages.tts.edge.enabled=false).

Nếu cấu hình nhiều provider, provider được chọn sẽ được dùng trước và các provider khác là dự phòng. Tính năng tóm tắt tự động dùng summaryModel đã cấu hình (hoặc agents.defaults.model.primary), nên provider đó cũng phải được xác thực nếu các bạn bật tóm tắt.

Liên kết dịch vụ

Có bật mặc định không?

Không. Auto-TTS tắt theo mặc định. Các bạn bật trong config bằng messages.tts.auto hoặc theo session bằng /tts always (alias: /tts on).

Edge TTS được bật mặc định khi TTS đã bật, và tự động được dùng khi không có API key của OpenAI hoặc ElevenLabs.

Cấu hình

Cấu hình TTS nằm trong messages.tts của file openclaw.json. Schema đầy đủ xem tại Gateway configuration.

Cấu hình tối thiểu (bật + provider)

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

OpenAI chính với ElevenLabs dự phòng

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      openai: {
        apiKey: "openai_api_key",
        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 chính (không cần API key)

{
  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%",
      },
    },
  },
}

Tắt Edge TTS

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

Giới hạn tùy chỉnh + đường dẫn prefs

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

Chỉ trả lời bằng audio sau khi nhận voice note

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

Tắt tóm tắt tự động cho phản hồi dài

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

Sau đó chạy:

/tts summary off

Ghi chú về các trường

  • auto: chế độ auto-TTS (off, always, inbound, tagged).
    • inbound chỉ gửi audio sau khi nhận voice note.
    • tagged chỉ gửi audio khi phản hồi có tag [[tts]].
  • enabled: toggle cũ (doctor sẽ migrate sang auto).
  • mode: "final" (mặc định) hoặc "all" (bao gồm cả phản hồi tool/block).
  • provider: "elevenlabs", "openai", hoặc "edge" (fallback tự động).
  • Nếu provider không được đặt, OpenClaw ưu tiên openai (nếu có key), sau đó elevenlabs (nếu có key), nếu không thì dùng edge.
  • summaryModel: model rẻ tùy chọn cho tóm tắt tự động; mặc định là agents.defaults.model.primary.
    • Chấp nhận provider/model hoặc alias model đã cấu hình.
  • modelOverrides: cho phép model phát ra TTS directive (bật mặc định).
  • maxTextLength: giới hạn cứng cho đầu vào TTS (ký tự). /tts audio sẽ fail nếu vượt quá.
  • timeoutMs: timeout request (ms).
  • prefsPath: ghi đè đường dẫn JSON prefs local (provider/limit/summary).
  • Giá trị apiKey fallback về biến môi trường (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
  • elevenlabs.baseUrl: ghi đè base URL của ElevenLabs API.
  • elevenlabs.voiceSettings:
    • stability, similarityBoost, style: 0..1
    • useSpeakerBoost: true|false
    • speed: 0.5..2.0 (1.0 = bình thường)
  • elevenlabs.applyTextNormalization: auto|on|off
  • elevenlabs.languageCode: ISO 639-1 2 chữ cái (ví dụ en, de)
  • elevenlabs.seed: số nguyên 0..4294967295 (tính xác định best-effort)
  • edge.enabled: cho phép dùng Edge TTS (mặc định true; không cần API key).
  • edge.voice: tên giọng neural của Edge (ví dụ en-US-MichelleNeural).
  • edge.lang: mã ngôn ngữ (ví dụ en-US).
  • edge.outputFormat: định dạng đầu ra Edge (ví dụ audio-24khz-48kbitrate-mono-mp3).
    • Xem Microsoft Speech output formats cho các giá trị hợp lệ; không phải tất cả định dạng đều được Edge hỗ trợ.
  • edge.rate / edge.pitch / edge.volume: chuỗi phần trăm (ví dụ +10%, -5%).
  • edge.saveSubtitles: ghi subtitle JSON cùng với file audio.
  • edge.proxy: URL proxy cho request Edge TTS.
  • edge.timeoutMs: ghi đè timeout request (ms).

Model-driven overrides (mặc định bật)

Mặc định, model có thể phát ra TTS directive cho một phản hồi đơn. Khi messages.tts.auto là tagged, các directive này bắt buộc để kích hoạt audio.

Khi được bật, model có thể phát ra directive [[tts:...]] để ghi đè giọng nói cho một phản hồi đơn, cộng với block [[tts:text]]...[[/tts:text]] tùy chọn để cung cấp tag biểu cảm (tiếng cười, gợi ý hát, v.v.) chỉ xuất hiện trong audio.

Ví dụ payload phản hồi:

Here you go.

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

Các key directive có sẵn (khi được bật):

  • provider (openai | elevenlabs | edge)
  • voice (giọng OpenAI) hoặc voiceId (ElevenLabs)
  • model (model TTS OpenAI hoặc model id ElevenLabs)
  • stability, similarityBoost, style, speed, useSpeakerBoost
  • applyTextNormalization (auto|on|off)
  • languageCode (ISO 639-1)
  • seed

Tắt tất cả model override:

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

Allowlist tùy chọn (tắt override cụ thể nhưng vẫn giữ tag):

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

Tùy chọn theo người dùng

Các lệnh slash ghi override local vào prefsPath (mặc định: ~/.openclaw/settings/tts.json, ghi đè bằng OPENCLAW_TTS_PREFS hoặc messages.tts.prefsPath).

Các trường được lưu:

  • enabled
  • provider
  • maxLength (ngưỡng tóm tắt; mặc định 1500 ký tự)
  • summarize (mặc định true)

Các giá trị này ghi đè messages.tts.* cho host đó.

Định dạng đầu ra (cố định)

  • Telegram: Opus voice note (opus_48000_64 từ ElevenLabs, opus từ OpenAI).
    • 48kHz / 64kbps là sự cân bằng tốt cho voice note và bắt buộc cho bubble tròn.
  • Các channel khác: MP3 (mp3_44100_128 từ ElevenLabs, mp3 từ OpenAI).
    • 44.1kHz / 128kbps là sự cân bằng mặc định cho độ rõ giọng nói.
  • Edge TTS: dùng edge.outputFormat (mặc định audio-24khz-48kbitrate-mono-mp3).
    • node-edge-tts chấp nhận outputFormat, nhưng không phải tất cả định dạng đều có sẵn từ Edge service. citeturn2search0
    • Giá trị định dạng đầu ra theo Microsoft Speech output formats (bao gồm Ogg/WebM Opus). citeturn1search0
    • Telegram sendVoice chấp nhận OGG/MP3/M4A; dùng OpenAI/ElevenLabs nếu các bạn cần voice note Opus đảm bảo. citeturn1search1
    • Nếu định dạng đầu ra Edge đã cấu hình fail, OpenClaw sẽ thử lại với MP3.

Định dạng OpenAI/ElevenLabs cố định; Telegram mong đợi Opus cho UX voice note.

Hành vi Auto-TTS

Khi được bật, OpenClaw:

  • bỏ qua TTS nếu phản hồi đã chứa media hoặc directive MEDIA:.
  • bỏ qua phản hồi rất ngắn (< 10 ký tự).
  • tóm tắt phản hồi dài khi được bật bằng agents.defaults.model.primary (hoặc summaryModel).
  • đính kèm audio đã tạo vào phản hồi.

Nếu phản hồi vượt quá maxLength và tóm tắt tắt (hoặc không có API key cho summary model), audio sẽ bị bỏ qua và phản hồi văn bản bình thường được gửi.

Sơ đồ luồng

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

Sử dụng lệnh slash

Có một lệnh duy nhất: /tts. Xem Slash commands để biết chi tiết cách bật.

Lưu ý Discord: /tts là lệnh built-in của Discord, nên OpenClaw đăng ký /voice làm lệnh native ở đó. Văn bản /tts ... vẫn hoạt động.

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

Lưu ý:

  • Lệnh yêu cầu người gửi được ủy quyền (quy tắc allowlist/owner vẫn áp dụng).
  • commands.text hoặc đăng ký lệnh native phải được bật.
  • off|always|inbound|tagged là toggle theo session (/tts on là alias của /tts always).
  • limit và summary được lưu trong prefs local, không phải config chính.
  • /tts audio tạo phản hồi audio một lần (không bật TTS).

Agent tool

Tool tts chuyển văn bản thành giọng nói và trả về đường dẫn MEDIA:. Khi kết quả tương thích với Telegram, tool bao gồm [[audio_as_voice]] để Telegram gửi voice bubble.

Gateway RPC

Các method Gateway:

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