OpenClaw TTS 설정: ElevenLabs 및 OpenAI 연동 가이드

OpenClaw는 ElevenLabs, Microsoft 또는 OpenAI를 사용해서 나가는 답변을 오디오로 변환할 수 있어요. OpenClaw가 오디오를 보낼 수 있는 곳이라면 어디서든 작동해요.

지원되는 서비스

ElevenLabs (기본 또는 fallback provider)
Microsoft (기본 또는 fallback provider; 현재 번들 구현은 node-edge-tts를 사용해요)
OpenAI (기본 또는 fallback provider; 요약용으로도 사용돼요)

Microsoft speech 참고 사항

번들로 제공되는 Microsoft speech provider는 현재 node-edge-tts 라이브러리를 통해 Microsoft Edge의 온라인 neural TTS 서비스를 사용해요. 이는 로컬이 아닌 호스팅 서비스이며, Microsoft 엔드포인트를 사용하고 API key가 필요 없어요. node-edge-tts는 speech 설정 옵션과 출력 형식을 노출하지만, 서비스에서 모든 옵션을 지원하는 것은 아니에요. edge를 사용한 기존 설정과 지시어 입력은 여전히 작동하며 microsoft로 정규화되어 처리돼요.

이 경로는 공개된 SLA나 할당량(quota)이 없는 공개 웹 서비스이므로, 최선을 다하는 방식(best-effort)으로 취급해 주세요. 보장된 제한 사항과 지원이 필요하다면 OpenAI나 ElevenLabs를 사용하는 것을 추천해요.

선택적 키

OpenAI나 ElevenLabs를 사용하고 싶다면 다음 키를 설정해 주세요:

ELEVENLABS_API_KEY (또는 XI_API_KEY)
OPENAI_API_KEY

Microsoft speech는 API key가 필요하지 않습니다.

여러 provider가 설정된 경우, 선택된 provider가 먼저 사용되고 나머지는 fallback 옵션이 돼요. 자동 요약(Auto-summary)은 설정된 summaryModel (또는 agents.defaults.model.primary)을 사용하므로, 요약을 활성화하려면 해당 provider의 인증도 완료되어야 해요.

서비스 링크

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

아니요. Auto-TTS는 기본적으로 꺼져 있어요. 설정에서 messages.tts.auto를 사용하거나, 세션마다 /tts always (별칭: /tts on) 명령어로 활성화할 수 있어요.

messages.tts.provider가 설정되지 않은 경우, OpenClaw는 레지스트리 자동 선택 순서에 따라 구성된 첫 번째 speech provider를 선택해요.

AI Setup Assistant

설정

TTS 설정은 openclaw.json의 messages.tts 항목에서 관리해요. 전체 스키마가 궁금하다면 Gateway configuration 문서를 참고해 보세요.

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

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

ElevenLabs를 폴백으로 사용하는 OpenAI 기본 설정

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      providers: {
        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,
          },
        },
      },
    },
  },
}

Microsoft 기본 설정 (API 키 불필요)

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

Microsoft 음성 비활성화

{
  messages: {
    tts: {
      providers: {
        microsoft: {
          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: 레거시 토글이에요 (시스템이 이를 auto로 자동 마이그레이션해요).
mode: "final" (기본값) 또는 "all" (도구/블록 응답 포함) 중 선택할 수 있어요.
provider: "elevenlabs", "microsoft", "openai"와 같은 음성 제공자 ID예요 (폴백은 자동으로 처리돼요).
provider가 설정되지 않은 경우, OpenClaw는 레지스트리 자동 선택 순서에 따라 구성된 첫 번째 음성 제공자를 사용해요.
레거시 provider: "edge" 설정도 여전히 작동하며 microsoft로 정규화돼요.
summaryModel: 자동 요약을 위한 선택 사항인 저렴한 모델이에요. 기본값은 agents.defaults.model.primary를 따라가요.
- provider/model 형식이나 설정된 모델 별칭(alias)을 사용할 수 있어요.
modelOverrides: 모델이 TTS 지시어를 내보낼 수 있도록 허용해요 (기본적으로 켜져 있어요).
- allowProvider 기본값은 false예요 (제공자 전환은 직접 허용해야 해요).
providers.<id>: 음성 제공자 ID별로 지정된 설정이에요.
레거시 직접 제공자 블록(messages.tts.openai, messages.tts.elevenlabs 등)은 로드 시 messages.tts.providers.<id>로 자동 마이그레이션돼요.
maxTextLength: TTS 입력의 최대 글자 수 제한이에요. 이 수치를 넘으면 /tts audio 명령이 실패해요.
timeoutMs: 요청 타임아웃 시간(ms)이에요.
prefsPath: 로컬 설정 JSON 경로(제공자/제한/요약)를 덮어써요.
apiKey 값은 환경 변수(ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY)를 폴백으로 사용해요.
providers.elevenlabs.baseUrl: ElevenLabs API 베이스 URL을 변경할 때 사용해요.
providers.openai.baseUrl: OpenAI TTS 엔드포인트를 변경할 때 사용해요.
- 확인 순서: messages.tts.providers.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
- 기본값이 아닌 값은 OpenAI 호환 TTS 엔드포인트로 취급되므로, 커스텀 모델 및 음성 이름을 사용할 수 있어요.
providers.elevenlabs.voiceSettings:
- stability, similarityBoost, style: 0..1 사이의 값을 가져요.
- useSpeakerBoost: true|false로 설정해요.
- speed: 0.5..2.0 (1.0이 일반 속도) 사이의 값을 가져요.
providers.elevenlabs.applyTextNormalization: auto|on|off 중 선택해요.
providers.elevenlabs.languageCode: ISO 639-1 형식의 2자리 언어 코드예요 (예: en, de).
providers.elevenlabs.seed: 0..4294967295 사이의 정수예요 (결과물의 일관성을 위해 사용해요).
providers.microsoft.enabled: Microsoft 음성 사용 허용 여부예요 (기본값 true, API 키가 필요 없어요).
providers.microsoft.voice: Microsoft 신경망 음성 이름이에요 (예: en-US-MichelleNeural).
providers.microsoft.lang: 언어 코드예요 (예: en-US).
providers.microsoft.outputFormat: Microsoft 출력 포맷 설정이에요 (예: audio-24khz-48kbitrate-mono-mp3).
- Microsoft Speech 출력 포맷 문서를 확인하세요. 모든 포맷이 내장된 Edge 기반 전송 방식에서 지원되는 것은 아니에요.
providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume: 퍼센트 문자열을 사용해요 (예: +10%, -5%).
providers.microsoft.saveSubtitles: 오디오 파일과 함께 JSON 자막을 저장해요.
providers.microsoft.proxy: Microsoft 음성 요청을 위한 프록시 URL이에요.
providers.microsoft.timeoutMs: 요청 타임아웃 시간을 별도로 설정해요 (ms).
edge.*: 동일한 Microsoft 설정에 대한 레거시 별칭이에요.

모델 기반 오버라이드 (기본 활성화)

기본적으로 모델은 단일 응답에 대해 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 (등록된 음성 제공자 ID, 예: openai, elevenlabs, microsoft. 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,
      },
    },
  },
}

사용자별 환경 설정

Slash commands를 사용하면 prefsPath에 로컬 설정이 덮어씌워져요. 기본 경로는 ~/.openclaw/settings/tts.json이지만, OPENCLAW_TTS_PREFS나 messages.tts.prefsPath 환경 변수를 사용해 경로를 직접 지정할 수도 있습니다.

저장되는 필드는 다음과 같아요:

enabled
provider
maxLength (요약을 시작하는 글자 수 제한, 기본값 1500자)
summarize (기본값 true)

이 필드들은 해당 호스트에 설정된 기존 messages.tts.* 값보다 우선적으로 적용됩니다.

출력 형식 (고정)

Feishu / Matrix / Telegram / WhatsApp: Opus 음성 메시지를 사용해요. ElevenLabs는 opus_48000_64, OpenAI는 opus 형식을 사용합니다. 48kHz / 64kbps 설정이 음성 메시지 용도로는 아주 적절한 사양이에요.
기타 채널: MP3 형식을 사용합니다. ElevenLabs는 mp3_44100_128, OpenAI는 mp3를 써요. 44.1kHz / 128kbps 설정이 목소리의 선명도를 유지하는 가장 기본적인 밸런스입니다.
Microsoft: microsoft.outputFormat 설정을 사용하며, 기본값은 audio-24khz-48kbitrate-mono-mp3입니다.
- 함께 제공되는 transport가 outputFormat을 받아들이긴 하지만, 서비스에서 모든 형식을 지원하는 것은 아니니 주의해야 해요.
- 출력 형식 값은 Microsoft Speech 출력 형식을 따릅니다 (Ogg/WebM Opus 포함).
- Telegram의 sendVoice는 OGG, MP3, M4A 형식을 지원해요. 만약 확실한 Opus 음성 메시지 결과물이 필요하다면 OpenAI나 ElevenLabs를 사용하는 것이 좋습니다.
- 설정된 Microsoft 출력 형식으로 생성에 실패하면, OpenClaw가 MP3로 재시도합니다.

OpenAI와 ElevenLabs의 출력 형식은 위에서 설명한 대로 채널별로 고정되어 있습니다.

Auto-TTS 동작 방식

OpenClaw에서 Auto-TTS 기능을 활성화하면 다음과 같이 작동해요.

답변에 이미 미디어가 포함되어 있거나 MEDIA: 지시어가 있다면 TTS를 건너뛰어요.
10자 미만의 아주 짧은 답변은 TTS를 생성하지 않아요.
답변이 길 경우 agents.defaults.model.primary (또는 summaryModel)를 사용해 내용을 요약해요.
생성된 오디오는 답변에 바로 첨부돼요.

만약 답변이 maxLength를 초과했는데 요약 기능이 꺼져 있거나 요약 모델을 위한 API key가 없다면, 오디오는 생략하고 일반 텍스트 답변만 보내게 돼요.

흐름도

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

Slash 커맨드 사용법

사용할 수 있는 커맨드는 /tts 하나예요. 활성화와 관련된 자세한 내용은 Slash commands 문서를 참고해 주세요.

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 설정은 메인 config가 아니라 로컬 설정(local prefs)에 저장돼요.
/tts audio는 일회성 오디오 답변을 생성하며, TTS 기능을 활성화 상태로 바꾸지는 않아요.
/tts status에는 최근 시도에 대한 폴백(fallback) 가시성 정보가 포함돼요:
- 성공 시: Fallback: <primary> -> <used> 및 Attempts: ...
- 실패 시: Error: ... 및 Attempts: ...
- 상세 진단 정보: Attempt details: provider:outcome(reasonCode) latency
OpenAI 및 ElevenLabs API 실패 시, 이제 공급자가 반환한 에러 상세 내용과 요청 ID(전달받은 경우)가 포함되어 TTS 에러나 로그에 표시돼요.

Agent 도구

tts 도구는 텍스트를 음성으로 변환하고 답변 전달을 위해 오디오 첨부 파일을 반환해요. 채널이 Feishu, Matrix, Telegram 또는 WhatsApp인 경우, 오디오는 일반 파일 첨부가 아닌 음성 메시지 형태로 전달된답니다.

Gateway RPC

Gateway 메소드 목록이에요:

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

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.