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

Documentation Index

Fetch the complete documentation index at: https://docs.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 dòng [[tts:...]] khi bật ghi đè do model điều khiển

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

​

Chân dung

​

Chân dung tối thiểu

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

​

Chân dung đầ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",
              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 chân dung

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ó chân dung.

1. Ghi đè trực tiếp (CLI, gateway, Talk, chỉ thị TTS được phép).
2. Tùy chọn cục bộ /tts provider <id>.
3. provider của chân dung đ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 tin cậy
4. Ghi đè chỉ thị TTS do mô hình phát ra được phép

​

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

​

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 độ nguyên MiniMax, −12 đến 12; giá trị thập phân bị cắt bỏ)
• 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 slash

/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 chân dung cục bộ; /tts persona off xóa nó.
• /tts latest đọc phản hồ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 hash của phản hồ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 phản hồ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 theo 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ợ ghi chú thoại: câu trả lời ghi chú thoại ưu tiên Opus (opus_48000_64 từ ElevenLabs, opus từ OpenAI).
  • 48kHz / 64kbps là mức đánh đổi phù hợp cho tin nhắn thoại.
• Feishu / WhatsApp: khi câu trả lời 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 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 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 tải trọng PTT không tương thích.
• BlueBubbles: giữ quá trình tổng hợp của nhà cung cấp trên đường dẫn tệp âm thanh thông thường; đầu ra MP3 và CAF được đánh dấu để gửi bản ghi nhớ thoại iMessage.
• 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. Đối với các mục tiêu ghi chú thoại do 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. Đối với các mục tiêu ghi chú thoại do 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 mục tiêu ghi chú thoại được chuyển đổi sang Ogg/Opus và đầu ra điện thoại được chuyển đổi sang PCM đơn âm 16 kHz thô bằng ffmpeg.
• Google Gemini: TTS API Gemini 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ã sang Opus 48kHz cho mục tiêu ghi chú 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 ghi chú 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 ghi chú 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 đ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 đường dẫn nhà cung cấp này sử dụng. Đường dẫn này không hỗ trợ định dạng ghi chú thoại Opus gốc.
• Microsoft: sử dụng microsoft.outputFormat (mặc định audio-24khz-48kbitrate-mono-mp3).
  • Phương thức truyền tải đ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).
  • Telegram sendVoice 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 câu trả lời đã chứa phương tiện hoặc chỉ thị MEDIA:.
• Bỏ qua các câu trả lời rất ngắn (dưới 10 ký tự).
• Tóm tắt các câu trả lời dài khi tính năng tóm tắt được bật, sử dụng summaryModel (hoặc agents.defaults.model.primary).
• Đính kèm âm thanh đã tạo vào câu trả lời.
• Trong mode: "final", vẫn gửi TTS chỉ có âm thanh cho các câu trả lờ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 quá trình chuẩn hóa phương tiện của kênh như các tệp đính kèm câu trả lờ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 tin nhắn thoại đến dưới dạng MP3/WebM/WAV/M4A, Plugin kênh chuyển mã sang 48 kHz Ogg/Opus 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 lại đính kèm tệp gốc; WhatsApp gửi thất bại thay vì đăng tải payload PTT không tương thích.
• MiniMax / Xiaomi MiMo: Mặc định MP3 (32 kHz cho MiniMax speech-2.8-hd); được chuyển mã sang 48 kHz Opus cho các đích tin nhắn thoại qua ffmpeg.
• CLI cục bộ: Sử dụng outputFormat đã cấu hình. Các đích tin nhắn 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 thô 24 kHz. OpenClaw bọc dưới dạng WAV cho tệp đính kèm, chuyển mã sang 48 kHz Opus cho các đích tin nhắn thoại, trả về PCM trực tiếp cho Talk/điện thoại.
• Inworld: Tệp đính kèm MP3, tin nhắn thoại OGG_OPUS gốc, PCM thô 22050 Hz cho Talk/điện thoại.
• xAI: Mặc định MP3; responseFormat có thể là mp3|wav|pcm|mulaw|alaw. Sử dụng endpoint batch REST của xAI — TTS WebSocket phát trực tuyến không được dùng. Định dạng tin nhắn 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 tin nhắn thoại Opus được đảm bảo. Nếu định dạng Microsoft đã cấu hình thất bại, OpenClaw thử lại với 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
• Tài liệu tham khảo 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 về phương tiện
• Tạo nhạc
• Tạo video
• Lệnh slash
• Plugin gọi thoại