> ## 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.

# Azure 語音服務

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](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`                                                                           |

## 開始使用

<Steps>
  <Step title="建立 Azure Speech 資源">
    在 Azure 入口網站中建立 Speech 資源。從
    Resource Management > Keys and Endpoint 複製 **KEY 1**，並複製資源位置，
    例如 `eastus`。

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

  <Step title="在 tts 中選取 Azure Speech">
    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      tts: {
        auto: "always",
        provider: "azure-speech",
        providers: {
          "azure-speech": {
            voice: "en-US-JennyNeural",
            lang: "en-US",
          },
        },
      },
    }
    ```
  </Step>

  <Step title="傳送訊息">
    透過任何已連線的通道傳送回覆。OpenClaw 會使用 Azure Speech 合成音訊，
    並為標準音訊傳送 MP3；當通道要求語音訊息時，則傳送 Ogg/Opus。
  </Step>
</Steps>

## 設定選項

所有選項都位於 `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，或明確設定。

## 注意事項

<AccordionGroup>
  <Accordion title="驗證">
    Azure Speech 使用 Speech 資源金鑰，而非 Azure OpenAI 金鑰。金鑰會以
    `Ocp-Apim-Subscription-Key` 傳送；除非你提供 `endpoint` 或
    `baseUrl`，否則 OpenClaw 會從 `region` 衍生
    `https://<region>.tts.speech.microsoft.com`。
  </Accordion>

  <Accordion title="語音名稱">
    請使用 Azure Speech 語音的 `ShortName` 值，例如
    `en-US-JennyNeural`。內建供應商可透過相同的 Speech 資源列出語音，
    並篩除標示為已棄用、已停用或已除役的語音。
  </Accordion>

  <Accordion title="音訊輸出">
    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`。
  </Accordion>

  <Accordion title="別名">
    為相容既有設定，可接受 `azure` 作為供應商別名，但新設定應使用
    `azure-speech`，以免與 Azure OpenAI 模型供應商混淆。
  </Accordion>
</AccordionGroup>

## 相關內容

<CardGroup cols={2}>
  <Card title="文字轉語音" href="/zh-TW/tools/tts" icon="waveform-lines">
    TTS 概觀、供應商及 `tts` 設定。
  </Card>

  <Card title="設定" href="/zh-TW/gateway/configuration" icon="gear">
    完整設定參考，包括 `tts` 設定。
  </Card>

  <Card title="供應商" href="/zh-TW/providers" icon="grid">
    所有內建的 OpenClaw 供應商。
  </Card>

  <Card title="疑難排解" href="/zh-TW/help/troubleshooting" icon="wrench">
    常見問題與偵錯步驟。
  </Card>
</CardGroup>