​

Chuyển văn bản thành giọng nói (TTS)

​

Dịch vụ hỗ trợ

• ElevenLabs (nhà cung cấp chính hoặc dự phòng)
• Microsoft (nhà cung cấp chính hoặc dự phòng; hiện tại sử dụng node-edge-tts, mặc định khi không có khóa API)
• OpenAI (nhà cung cấp chính hoặc dự phòng; cũng được sử dụng cho tóm tắt)

​

Ghi chú về giọng nói của Microsoft

​

Khóa tùy chọn

• ELEVENLABS_API_KEY (hoặc XI_API_KEY)
• OPENAI_API_KEY

​

Liên kết dịch vụ

• Hướng dẫn Text-to-Speech của OpenAI
• Tham khảo API âm thanh của OpenAI
• Text to Speech của ElevenLabs
• Xác thực ElevenLabs
• node-edge-tts
• Định dạng đầu ra giọng nói của Microsoft

​

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

​

Cấu hình

​

Cấu hình tối thiểu (bật + nhà cung cấp)

{
  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",
        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 chính (không cần khóa API)

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

​

Vô hiệu hóa giọng nói của Microsoft

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

​

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

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

​

Chỉ trả lời bằng âm thanh sau khi nhận ghi chú giọng nói

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

​

Vô hiệu hóa tóm tắt tự động cho các phản hồi dài

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

/tts summary off

​

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

• auto: chế độ auto-TTS (off, always, inbound, tagged).
  • inbound chỉ gửi âm thanh sau khi nhận ghi chú giọng nói.
  • tagged chỉ gửi âm thanh khi phản hồi có thẻ [[tts]].
• enabled: chuyển đổi cũ (bác sĩ di chuyển điều này sang auto).
• mode: "final" (mặc định) hoặc "all" (bao gồm công cụ/phản hồi khối).
• provider: id nhà cung cấp giọng nói như "elevenlabs", "microsoft", hoặc "openai" (dự phòng tự động).
• Nếu provider không được đặt, OpenClaw ưu tiên openai (nếu có khóa), sau đó elevenlabs (nếu có khóa), nếu không thì microsoft.
• summaryModel: mô hình rẻ tiền 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 bí danh mô hình đã cấu hình.
• modelOverrides: cho phép mô hình phát ra chỉ thị TTS (bật theo mặc định).
  • allowProvider mặc định là false (chuyển đổi nhà cung cấp là tùy chọn).
• maxTextLength: giới hạn cứng cho đầu vào TTS (ký tự). /tts audio thất bại nếu vượt quá.
• timeoutMs: thời gian chờ yêu cầu (ms).
• prefsPath: ghi đè đường dẫn JSON ưu tiên cục bộ (nhà cung cấp/giới hạn/tóm tắt).
• Giá trị apiKey dự phòng cho biến môi trường (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
• elevenlabs.baseUrl: ghi đè URL cơ sở API của ElevenLabs.
• openai.baseUrl: ghi đè điểm cuối TTS của OpenAI.
  • Thứ tự giải quyết: messages.tts.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
  • Các giá trị không mặc định được coi là điểm cuối TTS tương thích với OpenAI, vì vậy tên mô hình và giọng nói tùy chỉnh được chấp nhận.
• 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: mã ISO 639-1 gồm 2 chữ cái (ví dụ: en, de)
• elevenlabs.seed: số nguyên 0..4294967295 (xác định tốt nhất có thể)
• microsoft.enabled: cho phép sử dụng giọng nói của Microsoft (mặc định true; không cần khóa API).
• microsoft.voice: tên giọng nói thần kinh của Microsoft (ví dụ: en-US-MichelleNeural).
• microsoft.lang: mã ngôn ngữ (ví dụ: en-US).
• microsoft.outputFormat: định dạng đầu ra của Microsoft (ví dụ: audio-24khz-48kbitrate-mono-mp3).
  • Xem Định dạng đầu ra giọng nói của Microsoft để biết các giá trị hợp lệ; không phải tất cả các định dạng đều được hỗ trợ bởi phương tiện truyền tải dựa trên Edge.
• microsoft.rate / microsoft.pitch / microsoft.volume: chuỗi phần trăm (ví dụ: +10%, -5%).
• microsoft.saveSubtitles: ghi phụ đề JSON cùng với tệp âm thanh.
• microsoft.proxy: URL proxy cho các yêu cầu giọng nói của Microsoft.
• microsoft.timeoutMs: ghi đè thời gian chờ yêu cầu (ms).
• edge.*: bí danh cũ cho các cài đặt Microsoft tương tự.

​

Ghi đè theo mô hình (mặc định bật)

Đây là của bạn.

[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](cười) Đọc bài hát một lần nữa.[[/tts:text]]

• provider (id nhà cung cấp giọng nói đã đăng ký, ví dụ openai, elevenlabs, hoặc microsoft; yêu cầu allowProvider: true)
• voice (giọng nói OpenAI) hoặc voiceId (ElevenLabs)
• model (mô hình TTS của OpenAI hoặc id mô hình ElevenLabs)
• 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,
      },
    },
  },
}

​

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

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

​

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

• Telegram: Ghi chú giọng nói Opus (opus_48000_64 từ ElevenLabs, opus từ OpenAI).
  • 48kHz / 64kbps là sự cân bằng tốt cho ghi chú giọng nói và cần thiết cho bong bóng tròn.
• Các kênh 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õ của giọng nói.
• Microsoft: sử dụng microsoft.outputFormat (mặc định audio-24khz-48kbitrate-mono-mp3).
  • Phương tiện truyền tải đi kèm chấp nhận một outputFormat, nhưng không phải tất cả các định dạng đều có sẵn từ dịch vụ.
  • Các giá trị định dạng đầu ra tuân theo Định dạng đầu ra giọng nói của Microsoft (bao gồm Ogg/WebM Opus).
  • Telegram sendVoice chấp nhận OGG/MP3/M4A; sử dụng OpenAI/ElevenLabs nếu bạn cần ghi chú giọng nói Opus đảm bảo.
  • Nếu định dạng đầu ra Microsoft được cấu hình thất bại, OpenClaw sẽ thử lại với MP3.

​

Hành vi Auto-TTS

• bỏ qua TTS nếu phản hồi đã chứa phương tiện hoặc chỉ thị MEDIA:.
• bỏ qua các phản hồi rất ngắn (< 10 ký tự).
• tóm tắt các phản hồi dài khi được bật bằng cách sử dụng agents.defaults.model.primary (hoặc summaryModel).
• đính kèm âm thanh đã tạo vào phản hồi.

​

Sơ đồ luồng

Phản hồi -> TTS được bật?
  không  -> gửi văn bản
  có -> có phương tiện / MEDIA: / ngắn?
          có -> gửi văn bản
          không  -> độ dài > giới hạn?
                   không  -> TTS -> đính kèm âm thanh
                   có -> tóm tắt được bật?
                            không  -> gửi văn bản
                            có -> tóm tắt (summaryModel hoặc agents.defaults.model.primary)
                                      -> TTS -> đính kèm âm thanh

​

Sử dụng lệnh gạch chéo

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

• Các lệnh yêu cầu người gửi được ủy quyền (quy tắc danh sách cho phép/chủ sở hữu vẫn áp dụng).
• commands.text hoặc đăng ký lệnh gốc phải được bật.
• off|always|inbound|tagged là các chuyển đổi theo phiên (/tts on là bí danh cho /tts always).
• limit và summary được lưu trữ trong ưu tiên cục bộ, không phải cấu hình chính.
• /tts audio tạo một phản hồi âm thanh một lần (không bật TTS).

​

Công cụ Agent

​

Gateway RPC

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