텍스트 음성 변환 (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 서비스가 모든 옵션을 지원하지는 않습니다. citeturn2search0

Edge TTS는 공개된 SLA나 쿼터가 없는 공개 웹 서비스이므로 최선 노력(best-effort)으로 취급하세요. 보장된 한도와 지원이 필요하면 OpenAI나 ElevenLabs를 사용하세요. Microsoft의 Speech REST API 문서에는 요청당 10분 오디오 제한이 명시되어 있으며, Edge TTS는 한도를 공개하지 않으므로 비슷하거나 낮은 한도를 가정하세요. citeturn0search3

선택적 키

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)을 사용하므로, 요약을 활성화하면 해당 공급자도 인증되어 있어야 합니다.

서비스 링크

기본적으로 활성화되어 있나요?

아닙니다. 자동 TTS는 기본적으로 꺼져 있습니다. 설정에서 messages.tts.auto로 활성화하거나, 세션별로 /tts always(별칭: /tts on)로 활성화하세요.

TTS가 켜지면 Edge TTS 는 기본적으로 활성화되며, OpenAI나 ElevenLabs API 키가 없을 때 자동으로 사용됩니다.

설정

TTS 설정은 openclaw.json의 messages.tts 아래에 있습니다. 전체 스키마는 Gateway 설정을 참고하세요.

최소 설정 (활성화 + 공급자)

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

OpenAI 주 공급자, ElevenLabs 폴백

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      openai: {
        apiKey: "openai_api_key",
        baseUrl: "https://api.openai.com/v1",
        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,
        },
      },
    },
  },
}

Edge TTS 주 공급자 (API 키 불필요)

{
  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%",
      },
    },
  },
}

Edge TTS 비활성화

{
  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

필드 참고

auto: 자동 TTS 모드 (off, always, inbound, tagged).
- inbound는 수신 음성 메시지 이후에만 오디오를 전송합니다.
- tagged는 응답에 [[tts]] 태그가 포함된 경우에만 오디오를 전송합니다.
enabled: 레거시 토글 (doctor가 이를 auto로 마이그레이션).
mode: "final" (기본값) 또는 "all" (도구/블록 응답 포함).
provider: "elevenlabs", "openai", 또는 "edge" (폴백은 자동).
provider가 미설정이면 OpenClaw는 openai(키 있을 때), elevenlabs(키 있을 때), 아니면 edge 순으로 선택합니다.
summaryModel: 자동 요약용 경량 모델(선택). 기본값은 agents.defaults.model.primary.
- provider/model 또는 설정된 모델 별칭을 사용할 수 있습니다.
modelOverrides: 모델이 TTS 디렉티브를 생성할 수 있도록 허용 (기본: 활성).
- allowProvider는 기본적으로 false (공급자 전환은 옵트인).
maxTextLength: TTS 입력의 문자 수 하드 캡. 초과하면 /tts audio가 실패합니다.
timeoutMs: 요청 타임아웃 (ms).
prefsPath: 로컬 환경설정 JSON 경로 재정의 (공급자/제한/요약).
apiKey 값은 환경 변수로 폴백 (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
elevenlabs.baseUrl: ElevenLabs API 베이스 URL 재정의.
openai.baseUrl: OpenAI TTS 엔드포인트 재정의.
- 해석 순서: messages.tts.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
- 기본값이 아닌 값은 OpenAI 호환 TTS 엔드포인트로 취급되므로, 커스텀 모델과 음성 이름을 사용할 수 있습니다.
elevenlabs.voiceSettings:
- stability, similarityBoost, style: 0..1
- useSpeakerBoost: true|false
- speed: 0.5..2.0 (1.0 = 일반)
elevenlabs.applyTextNormalization: auto|on|off
elevenlabs.languageCode: 2자리 ISO 639-1 (예: en, de)
elevenlabs.seed: 정수 0..4294967295 (최선 노력 결정론)
edge.enabled: Edge TTS 사용 허용 (기본 true; API 키 불필요).
edge.voice: Edge 신경 음성 이름 (예: en-US-MichelleNeural).
edge.lang: 언어 코드 (예: en-US).
edge.outputFormat: Edge 출력 형식 (예: audio-24khz-48kbitrate-mono-mp3).
- 유효한 값은 Microsoft Speech 출력 형식을 참고하세요. Edge에서 모든 형식을 지원하지는 않습니다.
edge.rate / edge.pitch / edge.volume: 퍼센트 문자열 (예: +10%, -5%).
edge.saveSubtitles: 오디오 파일과 함께 JSON 자막을 저장합니다.
edge.proxy: Edge TTS 요청용 프록시 URL.
edge.timeoutMs: 요청 타임아웃 재정의 (ms).

모델 주도 재정의 (기본: 활성)

기본적으로 모델은 단일 응답에 대한 TTS 디렉티브를 생성할 수 있습니다. messages.tts.auto가 tagged이면 오디오 트리거를 위해 이 디렉티브가 필수입니다.

활성화 시, 모델은 [[tts:...]] 디렉티브로 단일 응답의 음성을 재정의하고, 선택적으로 [[tts:text]]...[[/tts:text]] 블록을 사용해 오디오에만 포함할 표현 태그(웃음, 노래 신호 등)를 제공할 수 있습니다.

provider=... 디렉티브는 modelOverrides.allowProvider: true가 아니면 무시됩니다.

응답 페이로드 예시:

Here you go.

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

활성화 시 사용 가능한 디렉티브 키:

provider (openai | elevenlabs | edge, allowProvider: true 필요)
voice (OpenAI 음성) 또는 voiceId (ElevenLabs)
model (OpenAI TTS 모델 또는 ElevenLabs 모델 ID)
stability, similarityBoost, style, speed, useSpeakerBoost
applyTextNormalization (auto|on|off)
languageCode (ISO 639-1)
seed

모든 모델 재정의 비활성화:

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

선택적 허용 목록 (공급자 전환은 허용하면서 다른 옵션은 조절 가능):

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

사용자별 환경설정

슬래시 명령은 prefsPath에 로컬 재정의를 저장합니다(기본값: ~/.openclaw/settings/tts.json, OPENCLAW_TTS_PREFS 또는 messages.tts.prefsPath로 재정의 가능).

저장되는 필드:

enabled
provider
maxLength (요약 임계값; 기본 1500자)
summarize (기본 true)

이 값은 해당 호스트에서 messages.tts.*를 재정의합니다.

출력 형식 (고정)

Telegram: Opus 음성 메시지 (ElevenLabs의 opus_48000_64, OpenAI의 opus).
- 48kHz / 64kbps는 음성 메시지에 적합한 균형이며 둥근 말풍선에 필요합니다.
기타 채널: MP3 (ElevenLabs의 mp3_44100_128, OpenAI의 mp3).
- 44.1kHz / 128kbps는 음성 선명도를 위한 기본 균형입니다.
Edge TTS: edge.outputFormat 사용 (기본 audio-24khz-48kbitrate-mono-mp3).
- node-edge-tts는 outputFormat을 받지만, Edge 서비스에서 모든 형식을 사용할 수 있는 것은 아닙니다. citeturn2search0
- 출력 형식 값은 Ogg/WebM Opus를 포함해 Microsoft Speech 출력 형식을 따릅니다. citeturn1search0
- Telegram sendVoice는 OGG/MP3/M4A를 지원합니다. 보장된 Opus 음성 메시지가 필요하면 OpenAI/ElevenLabs를 사용하세요. citeturn1search1
- 설정된 Edge 출력 형식이 실패하면 OpenClaw가 MP3로 재시도합니다.

OpenAI/ElevenLabs 형식은 고정이며, Telegram은 음성 메시지 UX를 위해 Opus를 기대합니다.

자동 TTS 동작

활성화 시 OpenClaw는:

응답에 이미 미디어나 MEDIA: 디렉티브가 포함되어 있으면 TTS를 건너뜁니다.
매우 짧은 응답(10자 미만)을 건너뜁니다.
활성화된 경우 agents.defaults.model.primary(또는 summaryModel)로 긴 응답을 요약합니다.
생성된 오디오를 응답에 첨부합니다.

응답이 maxLength를 초과하고 요약이 꺼져 있거나(또는 요약 모델용 API 키가 없으면) 오디오를 건너뛰고 일반 텍스트 응답을 전송합니다.

흐름도

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. 활성화 방법은 슬래시 명령을 참고하세요.

Discord 참고: /tts는 Discord 내장 명령이므로, OpenClaw는 네이티브 명령으로 /voice를 등록합니다. 텍스트 /tts ...는 여전히 동작합니다.

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

참고:

명령은 인가된 발신자만 사용할 수 있습니다(허용 목록/소유자 규칙 적용).
commands.text 또는 네이티브 명령 등록이 활성화되어 있어야 합니다.
off|always|inbound|tagged는 세션별 토글입니다(/tts on은 /tts always의 별칭).
limit과 summary는 메인 설정이 아닌 로컬 환경설정에 저장됩니다.
/tts audio는 일회성 오디오 응답을 생성합니다(TTS를 켜지는 않습니다).

에이전트 도구

tts 도구는 텍스트를 음성으로 변환하고 MEDIA: 경로를 반환합니다. 결과가 Telegram 호환이면 도구가 [[audio_as_voice]]를 포함해 Telegram에서 음성 말풍선으로 전송합니다.

Gateway RPC

Gateway 메서드:

tts.status
tts.enable
tts.disable
tts.convert
tts.setProvider
tts.providers