# Azure Speech

> 用于 OpenClaw 回复的 Azure AI Speech 文本转语音功能

- 网址：https://funcoding.ai/agents/openclaw/providers/azure-speech/
- 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/providers/azure-speech

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

| 详情                    | 值                                                                                                             |
| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| 提供商 ID               | `azure-speech`（别名：`azure`）                                                                |
| 网站                    | [Azure AI Speech](https://azure.microsoft.com/products/ai-services/ai-speech)                                  |
| 文档                    | [Speech REST 文本转语音](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech)     |
| 身份验证                | `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`。

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

**在 tts 中选择 Azure Speech**

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

**发送消息**

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

## 配置选项

所有选项均位于 `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`      | 请求超时覆盖值（毫秒）。回退到全局 `tts.timeoutMs`。                                               |

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

## 注意事项

<details>
<summary>身份验证</summary>

Azure Speech 使用 Speech 资源密钥，而不是 Azure OpenAI 密钥。该密钥
作为 `Ocp-Apim-Subscription-Key` 发送；除非你提供
`endpoint` 或 `baseUrl`，否则 OpenClaw 会从
`region` 派生 `https://<region>.tts.speech.microsoft.com`。

</details>

<details>
<summary>语音名称</summary>

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

</details>

<details>
<summary>音频输出</summary>

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`。

</details>

<details>
<summary>别名</summary>

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

</details>

## 相关内容

- [文本转语音](https://funcoding.ai/agents/openclaw/tools/tts/)：TTS 概览、提供商和 `tts` 配置。
- [配置](https://funcoding.ai/agents/openclaw/gateway/configuration/)：完整的配置参考，包括 `tts` 设置。
- [提供商](https://funcoding.ai/agents/openclaw/providers/)：所有内置的 OpenClaw 提供商。
- [故障排查](https://funcoding.ai/agents/openclaw/help/troubleshooting/)：常见问题和调试步骤。