Tts

---
summary: "아웃바운드 응답에 대한 음성 합성 (TTS)"
read_when:
  - 응답에 대한 음성 합성 활성화
  - TTS 프로바이더 또는 한계치 구성
  - /tts 명령어 사용
title: "음성 합성 (TTS)"
---

# 음성 합성 (TTS)

OpenClaw는 ElevenLabs, OpenAI 또는 Edge TTS를 사용하여 아웃바운드 응답을 오디오로 변환할 수 있습니다. 이는 OpenClaw가 오디오를 전송할 수 있는 모든 곳에서 작동하며, Telegram에서는 둥근 음성 노트 버블로 표시됩니다.

## 지원되는 서비스

- **ElevenLabs** (기본 또는 대체 프로바이더)
- **OpenAI** (기본 또는 대체 프로바이더; 요약에도 사용됨)
- **Edge TTS** (기본 또는 대체 프로바이더; `node-edge-tts` 사용, API 키가 없을 때 기본값)

### Edge TTS 주의사항

Edge TTS는 `node-edge-tts` 라이브러리를 통해 Microsoft Edge의 온라인 뉴럴 TTS 서비스를 사용합니다. 이는 호스팅된 서비스(로컬이 아님)이며, Microsoft의 엔드포인트를 사용하며 API 키가 필요하지 않습니다. `node-edge-tts`는 음성 구성 옵션과 출력 형식을 제공합니다, 하지만 모든 옵션이 Edge 서비스에서 지원되지는 않습니다.

Edge TTS는 공공 웹 서비스로 SLA 또는 쿼터가 공개되지 않았으므로 최선의 노력으로 취급해야 합니다. 보장된 한계치와 지원이 필요하다면 OpenAI나 ElevenLabs를 사용하십시오. Microsoft의 Speech REST API는 요청당 10분 오디오 한계를 문서화하고 있으며, Edge TTS는 한계를 공개하지 않으므로 비슷하거나 낮은 한계를 가정하십시오.

## 선택적 키

OpenAI나 ElevenLabs를 사용하려면:

- `ELEVENLABS_API_KEY` (또는 `XI_API_KEY`)
- `OPENAI_API_KEY`

Edge TTS는 **API 키가 필요하지 않습니다**. API 키가 발견되지 않으면, OpenClaw는 기본적으로 Edge TTS (활성화되지 않은 경우 `messages.tts.edge.enabled=false`를 통해 비활성화)로 설정됩니다.

여러 프로바이더가 구성된 경우, 선택된 프로바이더가 먼저 사용되고 다른 프로바이더는 대체 옵션으로 사용됩니다. 자동 요약은 구성된 `summaryModel` (또는 `agents.defaults.model.primary`)을 사용하며, 요약을 활성화한 경우 해당 프로바이더도 인증되어야 합니다.

## 서비스 링크

- [OpenAI 음성 합성 가이드](https://platform.openai.com/docs/guides/text-to-speech)
- [OpenAI 오디오 API 참조](https://platform.openai.com/docs/api-reference/audio)
- [ElevenLabs 음성 합성](https://elevenlabs.io/docs/api-reference/text-to-speech)
- [ElevenLabs 인증](https://elevenlabs.io/docs/api-reference/authentication)
- [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts)
- [Microsoft Speech 출력 형식](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)

## 기본으로 활성화된 상태인가요?

아니요. 자동 TTS는 기본적으로 **비활성화**되어 있습니다. `messages.tts.auto`를 사용해 구성에서 활성화하거나 `/tts always` (별칭: `/tts on`)를 사용해 세션별로 활성화하십시오.

TTS가 활성화되면 Edge TTS는 기본적으로 활성화되며, OpenAI 또는 ElevenLabs API 키가 없는 경우 자동으로 사용됩니다.

## 설정

TTS 설정은 `openclaw.json`의 `messages.tts`에 있습니다. 전체 스키마는 [Gateway 구성](/gateway/configuration)에 있습니다.

### 최소 설정 (활성화 + 프로바이더)

```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
    },
  },
}
```

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      openai: {
        apiKey: "openai_api_key",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "edge",
      edge: {
        enabled: true,
        voice: "en-US-MichelleNeural",
        lang: "en-US",
        outputFormat: "audio-24khz-48kbitrate-mono-mp3",
        rate: "+10%",
        pitch: "-5%",
      },
    },
  },
}

{
  messages: {
    tts: {
      edge: {
        enabled: false,
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
    },
  },
}

{
  messages: {
    tts: {
      auto: "inbound",
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
    },
  },
}

/tts summary off

Here you go.

[[tts:provider=elevenlabs voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](laughs) Read the song once more.[[/tts:text]]

{
  messages: {
    tts: {
      modelOverrides: {
        enabled: false,
      },
    },
  },
}

{
  messages: {
    tts: {
      modelOverrides: {
        enabled: true,
        allowProvider: false,
        allowSeed: false,
      },
    },
  },
}

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 (summaryModel or agents.defaults.model.primary)
                                      -> TTS -> attach audio

/tts off
/tts always
/tts inbound
/tts tagged
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Hello from OpenClaw