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

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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",
          voice: "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",
          voiceId: "EXAVITQu4vr4xnSDxMaL",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          apiKey: "${GEMINI_API_KEY}",
          model: "gemini-3.1-flash-tts-preview",
          voiceName: "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}",
          voiceId: "YTpq7expH9539ERJ",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "inworld",
      providers: {
        inworld: {
          apiKey: "${INWORLD_API_KEY}",
          modelId: "inworld-tts-1.5-max",
          voiceId: "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,
          voice: "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",
          voiceId: "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",
          voice: "alloy",
        },
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          voiceId: "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",
          voice: "af_alloy",
          responseFormat: "mp3",
        },
      },
    },
  },
}

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

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

{
  messages: {
    tts: {
      auto: "always",
      provider: "xiaomi",
      providers: {
        xiaomi: {
          apiKey: "${XIAOMI_API_KEY}",
          model: "mimo-v2.5-tts",
          voice: "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: { voiceId: "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: { voice: "shimmer" },
            },
          },
        },
      },
    },
  },
}

​

Persona

​

Persona tối thiểu

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

​

Persona đầy đủ (prompt 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",
              voiceName: "Algieba",
              promptTemplate: "audio-profile-v1",
            },
            openai: { model: "gpt-4o-mini-tts", voice: "cedar" },
            elevenlabs: {
              voiceId: "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 persona

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

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 persona đ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 đè từ chỉ thị TTS do mô hình phát ra và được phép

​

Cách nhà cung cấp dùng prompt persona

​

Chính sách dự phòng

​

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

Here you go.

[[tts:voiceId=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)
• 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 dấu 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 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 persona cục bộ; /tts persona off xóa tùy chọn đó.
• /tts latest đọc câu trả lời trợ lý mới nhất từ bản ghi phiên hiện tại và gửi nó dưới dạng âm thanh một lần. Nó chỉ lưu một hash của câu 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 câu trả lời âm thanh 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 nói đã 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ợ tin nhắn thoại: phản hồi bằng tin nhắn thoại ưu tiên Opus (opus_48000_64 từ ElevenLabs, opus từ OpenAI).
  • 48kHz / 64kbps là mức đánh đổi tốt cho tin nhắn thoại.
• Feishu / WhatsApp: khi phản hồi bằng tin nhắn thoại được tạo dưới dạng MP3/WebM/WAV/M4A hoặc một tệp có nhiều khả năng là âm thanh khác, Plugin kênh sẽ 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 payload 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; WhatsApp gửi thất bại thay vì đăng payload 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ần số lấy mẫu 32kHz) cho tệp đính kèm âm thanh thông thường. Với các mục tiêu tin nhắn thoại do kênh cô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 cô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 mục tiêu tin nhắn thoại do kênh công bố, OpenClaw chuyển mã đầu ra của Xiaomi sang Opus 48kHz bằng ffmpeg trước khi phân phối khi kênh công bố khả năng chuyển mã.
• CLI cục bộ: sử dụng outputFormat đã cấu hình. Các mục tiêu tin nhắn thoại được chuyển đổi sang Ogg/Opus và đầu ra đ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 mục tiêu tin nhắn thoại, và trả về PCM trực tiếp cho Talk/điện thoại.
• Gradium: WAV cho tệp đính kèm âm thanh, Opus cho mục tiêu tin nhắn thoại, và ulaw_8000 ở 8 kHz cho điện thoại.
• Inworld: MP3 cho tệp đính kèm âm thanh thông thường, OGG_OPUS gốc cho mục tiêu tin nhắn thoại, và PCM thô ở 22050 Hz cho Talk/đ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 endpoint TTS REST batch 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 đường dẫn nhà cung cấp này sử dụng. Định dạng tin nhắn 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 tất cả đị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 đảm bảo.
  • 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 hoặc chỉ thị MEDIA:.
• 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óm tắt được bật, bằng cách sử dụ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 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 của 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 / 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 phản hồi ghi âm thoại đến dưới dạng MP3/WebM/WAV/M4A, Plugin kênh 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 payload 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 mục tiêu ghi âm thoại qua ffmpeg.
• CLI cục bộ: Sử dụng outputFormat đã cấu hình. Mục tiêu ghi âm 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 mục tiêu ghi âm thoại, trả về PCM trực tiếp cho Talk/điện thoại.
• Inworld: Tệp đính kèm MP3, ghi âm thoại OGG_OPUS gốc, PCM thô 22050 Hz 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 theo lô của xAI — TTS WebSocket phát trực tuyến không được sử dụng. Định dạng ghi âm thoại Opus gốc không được hỗ trợ.
• Microsoft: Sử dụng microsoft.outputFormat (mặc định audio-24khz-48kbitrate-mono-mp3). sendVoice của Telegram 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
• Azure Speech REST chuyển văn bản thành giọng nói
• 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 phương tiện
• Tạo nhạc
• Tạo video
• Lệnh slash
• Plugin cuộc gọi thoại