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

​

Bắt đầu nhanh

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

​

Nhà cung cấp được hỗ trợ

​

Cấu hình

{
  messages: {
    tts: {
      auto: "always",
      provider: "azure-speech",
      providers: {
        "azure-speech": {
          apiKey: "${AZURE_SPEECH_KEY}",
          region: "eastus",
          speakerVoice: "en-US-JennyNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
          voiceNoteOutputFormat: "ogg-24khz-16bit-mono-opus",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
      providers: {
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          apiKey: "${GEMINI_API_KEY}",
          model: "gemini-3.1-flash-tts-preview",
          speakerVoice: "Kore",
          // Optional natural-language style prompts:
          // audioProfile: "Speak in a calm, podcast-host tone.",
          // speakerName: "Alex",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "gradium",
      providers: {
        gradium: {
          apiKey: "${GRADIUM_API_KEY}",
          speakerVoiceId: "YTpq7expH9539ERJ",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "inworld",
      providers: {
        inworld: {
          apiKey: "${INWORLD_API_KEY}",
          modelId: "inworld-tts-1.5-max",
          speakerVoiceId: "Sarah",
          temperature: 0.7,
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "tts-local-cli",
      providers: {
        "tts-local-cli": {
          command: "say",
          args: ["-o", "{{OutputPath}}", "{{Text}}"],
          outputFormat: "wav",
          timeoutMs: 120000,
        },
      },
    },
  },
}

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

{
  messages: {
    tts: {
      auto: "always",
      provider: "minimax",
      providers: {
        minimax: {
          apiKey: "${MINIMAX_API_KEY}",
          model: "speech-2.8-hd",
          speakerVoiceId: "English_expressive_narrator",
          speed: 1.0,
          vol: 1.0,
          pitch: 0,
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      providers: {
        openai: {
          apiKey: "${OPENAI_API_KEY}",
          model: "gpt-4o-mini-tts",
          speakerVoice: "alloy",
        },
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
          voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },
          applyTextNormalization: "auto",
          languageCode: "en",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "openrouter",
      providers: {
        openrouter: {
          apiKey: "${OPENROUTER_API_KEY}",
          model: "hexgrad/kokoro-82m",
          speakerVoice: "af_alloy",
          responseFormat: "mp3",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "volcengine",
      providers: {
        volcengine: {
          apiKey: "${VOLCENGINE_TTS_API_KEY}",
          resourceId: "seed-tts-1.0",
          speakerVoice: "en_female_anna_mars_bigtts",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "xai",
      providers: {
        xai: {
          apiKey: "${XAI_API_KEY}",
          speakerVoiceId: "eve",
          language: "en",
          responseFormat: "mp3",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "xiaomi",
      providers: {
        xiaomi: {
          apiKey: "${XIAOMI_API_KEY}",
          model: "mimo-v2.5-tts",
          speakerVoice: "mimo_default",
          format: "mp3",
        },
      },
    },
  },
}

​

Ghi đè giọng nói theo từng agent

{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
      providers: {
        elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", model: "eleven_multilingual_v2" },
      },
    },
  },
  agents: {
    list: [
      {
        id: "reader",
        tts: {
          providers: {
            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
      },
    ],
  },
}

1. messages.tts
2. agents.list[].tts đang hoạt động
3. ghi đè kênh, khi kênh hỗ trợ channels.<channel>.tts
4. ghi đè tài khoản, khi kênh truyền channels.<channel>.accounts.<id>.tts
5. tùy chọn /tts cục bộ cho máy chủ này
6. chỉ thị nội tuyến [[tts:...]] khi bật ghi đè theo mô hình

{
  messages: {
    tts: {
      provider: "openai",
      providers: {
        openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" },
      },
    },
  },
  channels: {
    feishu: {
      accounts: {
        english: {
          tts: {
            providers: {
              openai: { speakerVoice: "shimmer" },
            },
          },
        },
      },
    },
  },
}

​

Chân dung giọng nói

​

Chân dung giọng nói tối thiểu

{
  messages: {
    tts: {
      auto: "always",
      persona: "narrator",
      personas: {
        narrator: {
          label: "Narrator",
          provider: "elevenlabs",
          providers: {
            elevenlabs: {
              speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
              modelId: "eleven_multilingual_v2",
            },
          },
        },
      },
    },
  },
}

​

Chân dung giọng nói đầy đủ (lời nhắc trung lập với nhà cung cấp)

{
  messages: {
    tts: {
      auto: "always",
      persona: "alfred",
      personas: {
        alfred: {
          label: "Alfred",
          description: "Dry, warm British butler narrator.",
          provider: "google",
          fallbackPolicy: "preserve-persona",
          prompt: {
            profile: "A brilliant British butler. Dry, witty, warm, charming, emotionally expressive, never generic.",
            scene: "A quiet late-night study. Close-mic narration for a trusted operator.",
            sampleContext: "The speaker is answering a private technical request with concise confidence and dry warmth.",
            style: "Refined, understated, lightly amused.",
            accent: "British English.",
            pacing: "Measured, with short dramatic pauses.",
            constraints: ["Do not read configuration values aloud.", "Do not explain the persona."],
          },
          providers: {
            google: {
              model: "gemini-3.1-flash-tts-preview",
              speakerVoice: "Algieba",
              promptTemplate: "audio-profile-v1",
            },
            openai: { model: "gpt-4o-mini-tts", speakerVoice: "cedar" },
            elevenlabs: {
              speakerVoiceId: "voice_id",
              modelId: "eleven_multilingual_v2",
              seed: 42,
              voiceSettings: {
                stability: 0.65,
                similarityBoost: 0.8,
                style: 0.25,
                useSpeakerBoost: true,
                speed: 0.95,
              },
            },
          },
        },
      },
    },
  },
}

​

Phân giải chân dung giọng nói

1. tùy chọn cục bộ /tts persona <id>, nếu được đặt.
2. messages.tts.persona, nếu được đặt.
3. Không có chân dung giọng nói.

1. Ghi đè trực tiếp (CLI, Gateway, Talk, các chỉ thị TTS được phép).
2. tùy chọn cục bộ /tts provider <id>.
3. provider của chân dung giọng nói đang hoạt động.
4. messages.tts.provider.
5. Tự động chọn từ registry.

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Ghi đè yêu cầu đáng tin cậy
4. Ghi đè chỉ thị TTS do mô hình phát ra và được phép

​

Cách nhà cung cấp dùng lời nhắc chân dung giọng nói

​

Chính sách dự phòng

​

Chỉ thị do mô hình điều khiển

Here you go.

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

• provider (id nhà cung cấp đã đăng ký; yêu cầu allowProvider: true)
• speakerVoice / speakerVoiceId (bí danh cũ: voice, voiceName, voice_name, google_voice, voiceId)
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (âm lượng MiniMax, 0–10)
• pitch (cao độ số nguyên MiniMax, −12 đến 12; giá trị thập phân bị cắt bỏ phần lẻ)
• emotion (thẻ cảm xúc Volcengine)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

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

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

​

Lệnh gạch chéo

/tts off | on | status
/tts chat on | off | default
/tts latest
/tts provider <id>
/tts persona <id> | off
/tts limit <chars>
/tts summary off
/tts audio <text>

• /tts on ghi tùy chọn TTS cục bộ thành always; /tts off ghi nó thành off.
• /tts chat on|off|default ghi một ghi đè auto-TTS theo phạm vi phiên cho cuộc trò chuyện hiện tại.
• /tts persona <id> ghi tùy chọn chân dung giọng nói cục bộ; /tts persona off xóa tùy chọn đó.
• /tts latest đọc trả lời trợ lý mới nhất từ transcript phiên hiện tại và gửi nó dưới dạng âm thanh một lần. Nó chỉ lưu hash của trả lời đó trên mục phiên để ngăn gửi giọng nói trùng lặp.
• /tts audio tạo một trả lời âm thanh dùng một lần (không bật TTS).
• limit và summary được lưu trong tùy chọn cục bộ, không phải cấu hình chính.
• /tts status bao gồm chẩn đoán dự phòng cho lần thử mới nhất — Fallback: <primary> -> <used>, Attempts: ... và chi tiết từng lần thử (provider:outcome(reasonCode) latency).
• /status hiển thị chế độ TTS đang hoạt động cùng nhà cung cấp, mô hình, giọng đã cấu hình và siêu dữ liệu endpoint tùy chỉnh đã được làm sạch khi TTS được bật.

​

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

​

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

• Các kênh hỗ trợ ghi chú thoại: phản hồi dạng ghi chú thoại ưu tiên Opus (opus_48000_64 từ ElevenLabs, opus từ OpenAI).
  • 48kHz / 64kbps là sự cân bằng tốt cho tin nhắn thoại.
• Feishu / WhatsApp: khi phản hồi dạng ghi chú thoại được tạo dưới dạng MP3/WebM/WAV/M4A hoặc một tệp có khả năng là âm thanh khác, Plugin kênh chuyển mã tệp đó sang Ogg/Opus 48kHz bằng ffmpeg trước khi gửi tin nhắn thoại gốc. WhatsApp gửi kết quả qua tải trọng audio của Baileys với ptt: true và audio/ogg; codecs=opus. Nếu chuyển đổi thất bại, Feishu nhận tệp gốc dưới dạng tệp đính kèm; lượt gửi WhatsApp sẽ thất bại thay vì đăng một tải trọng PTT không tương thích.
• Các kênh khác: MP3 (mp3_44100_128 từ ElevenLabs, mp3 từ OpenAI).
  • 44.1kHz / 128kbps là mức cân bằng mặc định cho độ rõ của giọng nói.
• MiniMax: MP3 (mô hình speech-2.8-hd, tốc độ lấy mẫu 32kHz) cho tệp đính kèm âm thanh thông thường. Với các đích ghi chú thoại được kênh quảng bá, OpenClaw chuyển mã MP3 của MiniMax sang Opus 48kHz bằng ffmpeg trước khi phân phối khi kênh quảng bá khả năng chuyển mã.
• Xiaomi MiMo: mặc định là MP3, hoặc WAV khi được cấu hình. Với các đích ghi chú thoại được kênh quảng bá, OpenClaw chuyển mã đầu ra Xiaomi sang Opus 48kHz bằng ffmpeg trước khi phân phối khi kênh quảng bá khả năng chuyển mã.
• CLI cục bộ: sử dụng outputFormat đã cấu hình. Các đích ghi chú thoại được chuyển đổi sang Ogg/Opus và đầu ra thoại điện thoại được chuyển đổi sang PCM mono 16 kHz thô bằng ffmpeg.
• Google Gemini: TTS của Gemini API trả về PCM 24kHz thô. OpenClaw bọc nó dưới dạng WAV cho tệp đính kèm âm thanh, chuyển mã nó sang Opus 48kHz cho các đích ghi chú thoại, và trả về PCM trực tiếp cho Talk/thoại điện thoại.
• Gradium: WAV cho tệp đính kèm âm thanh, Opus cho các đích ghi chú thoại, và ulaw_8000 ở 8 kHz cho thoại điện thoại.
• Inworld: MP3 cho tệp đính kèm âm thanh thông thường, OGG_OPUS gốc cho các đích ghi chú thoại, và PCM thô ở 22050 Hz cho Talk/thoại điện thoại.
• xAI: mặc định là MP3; responseFormat có thể là mp3, wav, pcm, mulaw, hoặc alaw. OpenClaw sử dụng điểm cuối TTS REST theo lô của xAI và trả về một tệp đính kèm âm thanh hoàn chỉnh; WebSocket TTS phát trực tuyến của xAI không được dùng bởi đường dẫn nhà cung cấp này. Định dạng ghi chú thoại Opus gốc không được đường dẫn này hỗ trợ.
• Microsoft: sử dụng microsoft.outputFormat (mặc định audio-24khz-48kbitrate-mono-mp3).
  • Transport đi kèm chấp nhận outputFormat, nhưng không phải mọi định dạng đều có sẵn từ dịch vụ.
  • Giá trị định dạng đầu ra tuân theo các định dạng đầu ra Microsoft Speech (bao gồm Ogg/WebM Opus).
  • sendVoice của Telegram chấp nhận OGG/MP3/M4A; hãy dùng OpenAI/ElevenLabs nếu bạn cần tin nhắn thoại Opus được bảo đảm.
  • Nếu định dạng đầu ra Microsoft đã cấu hình thất bại, OpenClaw thử lại bằng MP3.

​

Hành vi Auto-TTS

• Bỏ qua TTS nếu phản hồi đã chứa phương tiện có cấu trúc.
• Bỏ qua các phản hồi rất ngắn (dưới 10 ký tự).
• Tóm tắt các phản hồi dài khi tính năng tóm tắt được bật, bằng summaryModel (hoặc agents.defaults.model.primary).
• Đính kèm âm thanh đã tạo vào phản hồi.
• Trong mode: "final", vẫn gửi TTS chỉ có âm thanh cho các phản hồi cuối cùng được phát trực tuyến sau khi luồng văn bản hoàn tất; phương tiện đã tạo đi qua cùng quy trình chuẩn hóa phương tiện kênh như các tệp đính kèm phản hồi thông thường.

Reply -> TTS enabled?
  no  -> send text
  yes -> has media / short?
          yes -> send text
          no  -> length > limit?
                   no  -> TTS -> attach audio
                   yes -> summary enabled?
                            no  -> send text
                            yes -> summarize -> TTS -> attach audio

​

Định dạng đầu ra theo kênh

• Chuyển mã Feishu / WhatsApp: Khi một trả lời bằng ghi chú thoại được nhận dưới dạng MP3/WebM/WAV/M4A, Plugin kênh sẽ chuyển mã sang Ogg/Opus 48 kHz bằng ffmpeg. WhatsApp gửi qua Baileys với ptt: true và audio/ogg; codecs=opus. Nếu chuyển đổi thất bại: Feishu quay về đính kèm tệp gốc; WhatsApp gửi thất bại thay vì đăng một tải trọng PTT không tương thích.
• MiniMax / Xiaomi MiMo: MP3 mặc định (32 kHz cho MiniMax speech-2.8-hd); được chuyển mã sang Opus 48 kHz cho các mục tiêu ghi chú thoại qua ffmpeg.
• CLI cục bộ: Sử dụng outputFormat đã cấu hình. Các mục tiêu ghi chú thoại được chuyển đổi sang Ogg/Opus và đầu ra điện thoại sang PCM mono 16 kHz thô.
• Google Gemini: Trả về PCM 24 kHz thô. OpenClaw bọc thành WAV cho tệp đính kèm, chuyển mã sang Opus 48 kHz cho các mục tiêu ghi chú thoại, trả về PCM trực tiếp cho Talk/điện thoại.
• Inworld: Tệp đính kèm MP3, ghi chú thoại OGG_OPUS gốc, PCM 22050 Hz thô cho Talk/điện thoại.
• xAI: MP3 theo mặc định; responseFormat có thể là mp3|wav|pcm|mulaw|alaw. Sử dụng endpoint REST hàng loạt của xAI — TTS WebSocket phát trực tuyến không được dùng. Định dạng ghi chú thoại Opus gốc không được hỗ trợ.
• Microsoft: Sử dụng microsoft.outputFormat (mặc định audio-24khz-48kbitrate-mono-mp3). Telegram sendVoice chấp nhận OGG/MP3/M4A; dùng OpenAI/ElevenLabs nếu bạn cần bảo đảm tin nhắn thoại Opus. Nếu định dạng Microsoft đã cấu hình thất bại, OpenClaw thử lại bằng MP3.

​

Tham chiếu trường

​

Công cụ agent

​

Gateway RPC

​

Liên kết dịch vụ

• Hướng dẫn chuyển văn bản thành giọng nói của OpenAI
• Tham chiếu OpenAI Audio API
• Chuyển văn bản thành giọng nói bằng Azure Speech REST
• Nhà cung cấp Azure Speech
• ElevenLabs Text to Speech
• Xác thực ElevenLabs
• Gradium
• Inworld TTS API
• MiniMax T2A v2 API
• Volcengine TTS HTTP API
• Tổng hợp giọng nói Xiaomi MiMo
• node-edge-tts
• Định dạng đầu ra Microsoft Speech
• xAI chuyển văn bản thành giọng nói

​

Liên quan

• Tổng quan về phương tiện
• Tạo nhạc
• Tạo video
• Lệnh slash
• Plugin cuộc gọi thoại