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
문서	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와 같은 리소스 위치를 복사하십시오.

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

messages.tts에서 Azure Speech 선택

{
  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는 Azure OpenAI 키가 아닌 Speech 리소스 키를 사용합니다. 키는 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는 채널이 추가적인 MP3 변환 없이 네이티브 음성 말풍선을 전송할 수 있도록 voice-note 대상에 Ogg/Opus를 요청하고, 전화 통신 대상에는 raw-8khz-8bit-mono-mulaw을 강제합니다.

별칭

기존 구성에서는 azure이 제공자 별칭으로 허용되지만, Azure OpenAI 모델 제공자와 혼동하지 않도록 새 구성에서는 azure-speech을 사용해야 합니다.

텍스트 음성 변환

TTS 개요, 제공자 및 messages.tts 구성입니다.

구성

messages.tts 설정을 포함한 전체 구성 참조입니다.

제공자

번들로 제공되는 모든 OpenClaw 제공자입니다.

문제 해결

일반적인 문제와 디버깅 단계입니다.

Overview

Concepts and configuration

Providers

Azure 음성 서비스

시작하기

구성 옵션

참고 사항

관련 항목

텍스트 음성 변환

구성

제공자

문제 해결

​시작하기

​구성 옵션

​참고 사항

​관련 항목

텍스트 음성 변환

구성

제공자

문제 해결

시작하기

구성 옵션

참고 사항

관련 항목