快速开始

Azure Speech

Azure Speech 是内置的 Azure AI Speech 文本转语音提供商。OpenClaw 使用 SSML 直接调用 Azure Speech REST API，为标准回复合成 MP3，为语音消息合成原生 Ogg/Opus，并为 Voice Call 等电话渠道合成 8 kHz mulaw。请求通过 X-Microsoft-OutputFormat 标头发送由提供商定义的输出格式。

详细信息	值
提供商 ID	`azure-speech`（别名：`azure`）
网站	Azure AI Speech
文档	Speech REST 文本转语音
身份验证	`AZURE_SPEECH_KEY` 加 `AZURE_SPEECH_REGION`
默认语音	`en-US-JennyNeural`
默认文件输出	`audio-24khz-48kbitrate-mono-mp3`
默认语音消息文件	`ogg-24khz-16bit-mono-opus`

入门指南

创建 Azure Speech 资源

在 Azure 门户中创建 Speech 资源。从 Resource Management > Keys and Endpoint 复制 KEY 1，并复制资源位置，例如 eastus。

Code

AZURE_SPEECH_KEY=<speech-resource-key>AZURE_SPEECH_REGION=eastus

在 messages.tts 中选择 Azure Speech

json5

{  messages: {    tts: {      auto: "always",      provider: "azure-speech",      providers: {        "azure-speech": {          voice: "en-US-JennyNeural",          lang: "en-US",        },      },    },  },}

发送消息

通过任意已连接的渠道发送回复。OpenClaw 使用 Azure Speech 合成音频，为标准音频提供 MP3；当渠道需要语音消息时，则提供 Ogg/Opus。

配置选项

所有选项均位于 messages.tts.providers["azure-speech"] 下。

选项	描述
`apiKey`	Azure Speech 资源密钥。回退到 `AZURE_SPEECH_KEY`、`AZURE_SPEECH_API_KEY` 或 `SPEECH_KEY`。
`region`	Azure Speech 资源区域。回退到 `AZURE_SPEECH_REGION` 或 `SPEECH_REGION`。
`endpoint`	可选的 Azure Speech 端点覆盖。回退到受信任的 `AZURE_SPEECH_ENDPOINT`。
`baseUrl`	可选的 Azure Speech 基础 URL 覆盖。
`voice`	Azure 语音 ShortName（默认值为 `en-US-JennyNeural`）。旧版别名：`voiceId`。
`lang`	SSML 语言代码（默认值为 `en-US`）。
`outputFormat`	音频文件输出格式（默认值为 `audio-24khz-48kbitrate-mono-mp3`）。
`voiceNoteOutputFormat`	语音消息输出格式（默认值为 `ogg-24khz-16bit-mono-opus`）。
`timeoutMs`	以毫秒为单位的请求超时覆盖。回退到全局 `messages.tts.timeoutMs`。

设置 apiKey，并设置 region、endpoint 或 baseUrl 中的任意一个后，即视为已配置该提供商。仅当配置键未设置时，才会检查环境变量作为回退。工作区的 .env 文件无法设置 AZURE_SPEECH_ENDPOINT；请使用进程环境、全局运行时 dotenv 或显式配置进行端点路由。

注意事项

身份验证

Azure Speech 使用 Speech 资源密钥，而非 Azure OpenAI 密钥。该密钥以 Ocp-Apim-Subscription-Key 的形式发送；除非你提供 endpoint 或 baseUrl，否则 OpenClaw 会根据 region 推导出 https://<region>.tts.speech.microsoft.com。

语音名称

使用 Azure Speech 语音的 ShortName 值，例如 en-US-JennyNeural。内置提供商可通过同一 Speech 资源列出语音，并过滤掉标记为已弃用、已停用或已禁用的语音。

音频输出

Azure 接受 audio-24khz-48kbitrate-mono-mp3、ogg-24khz-16bit-mono-opus 和 riff-24khz-16bit-mono-pcm 等输出格式。OpenClaw 为 voice-note 目标请求 Ogg/Opus，使渠道无需额外转换 MP3 即可发送原生语音气泡，并对电话目标强制使用 raw-8khz-8bit-mono-mulaw。

别名

为兼容现有配置，接受 azure 作为提供商别名，但新配置应使用 azure-speech，以避免与 Azure OpenAI 模型提供商混淆。