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는 음성 설정 옵션과 출력 형식을 노출하지만, 서비스에서 모든 옵션을 지원하는 것은 아니에요. 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를 선택합니다.

설정

TTS 설정은 openclaw.json 파일의 messages.tts 항목에서 관리해요. 전체 스키마에 대한 자세한 내용은 Gateway configuration에서 확인할 수 있어요.

최소 설정 (활성화 + provider)

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

ElevenLabs를 fallback으로 사용하는 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 key 불필요)

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

커스텀 제한 + prefs 경로 설정

{
  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" (tool/block 응답 포함).
provider: "elevenlabs", "microsoft", "openai"와 같은 음성 provider ID입니다 (fallback은 자동으로 이루어집니다).
provider가 설정되지 않은 경우, OpenClaw는 레지스트리 자동 선택 순서에 따라 구성된 첫 번째 음성 provider를 사용합니다.
레거시 provider: "edge"는 여전히 작동하며 microsoft로 정규화됩니다.
summaryModel: 자동 요약을 위한 선택 사항인 저렴한 모델입니다. 기본값은 agents.defaults.model.primary입니다.
- provider/model 형식이나 구성된 모델 alias를 사용할 수 있습니다.
modelOverrides: 모델이 TTS 지시어를 내보낼 수 있도록 허용합니다 (기본적으로 활성화됨).
- allowProvider 기본값은 false입니다 (provider 전환은 선택 사항입니다).
providers.<id>: 음성 provider ID별로 구분된 provider 전용 설정입니다.
레거시 직접 provider 블록(messages.tts.openai, messages.tts.elevenlabs, messages.tts.microsoft, messages.tts.edge)은 로드 시 messages.tts.providers.<id>로 자동 마이그레이션됩니다.
maxTextLength: TTS 입력의 최대 글자 수 제한입니다. 이를 초과하면 /tts audio가 실패합니다.
timeoutMs: 요청 타임아웃 시간(ms)입니다.
prefsPath: 로컬 설정 JSON 경로(provider/limit/summary)를 덮어씁니다.
apiKey 값은 환경 변수(ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY)를 fallback으로 사용합니다.
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: 2자리 ISO 639-1 코드 (예: en, de)
providers.elevenlabs.seed: 정수 0..4294967295 (결정론적 출력을 위한 최선의 노력)
providers.microsoft.enabled: Microsoft 음성 사용 허용 여부입니다 (기본값 true, API key 불필요).
providers.microsoft.voice: Microsoft neural 음성 이름 (예: 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 설정에 대한 레거시 alias입니다.

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

기본적으로 모델은 단일 응답에 대해 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 (등록된 음성 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,
      },
    },
  },
}

선택적 허용 목록 (다른 설정은 유지하면서 provider 전환만 활성화):

{
  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.* 설정을 덮어쓰게 돼요.

출력 형식 (고정)

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 동작 방식

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

답장에 이미 미디어나 MEDIA: 지시어가 포함되어 있다면 TTS를 건너뛰어요.
10자 미만의 아주 짧은 답장은 TTS를 생성하지 않아요.
답장이 길 경우, 활성화되어 있다면 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

Slash 커맨드 사용법

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

Discord에서는 /tts가 이미 내장된 커맨드이기 때문에, 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

참고할 사항:

커맨드를 사용하려면 권한이 있는 발신자여야 해요 (allowlist나 소유자 규칙이 그대로 적용돼요).
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 호출에 실패할 경우, 이제 공급자가 반환한 에러 상세 내용과 request 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에게 바로 물어보세요.