OpenClaw 음성 합성 및 TTS 기능 설정

서문

텍스트가 AI 인터랙션의 유일한 형태는 아닙니다. OpenClaw에는 음성 합성(Text-to-Speech, TTS) 지원이 내장되어 있어, AI Agent가 음성 메시지 형태로 사용자에게 응답할 수 있습니다. Telegram에서 음성 메시지를 보내거나, Discord의 음성 채널에서 응답을 읽어주는 것까지, OpenClaw은 간단한 설정으로 구현할 수 있습니다.

이 글에서는 TTS 기능의 설정 방법, 지원 엔진 및 고급 활용법을 자세히 소개합니다.

TTS 기능 활성화

기본 설정

openclaw.json5에서 TTS를 활성화합니다:

{
  agents: {
    "my-agent": {
      tts: {
        enabled: true,
        // TTS 엔진
        engine: "openai",
        // 기본 음성
        voice: "alloy",
        // 오디오 형식
        format: "opus",  // opus / mp3 / aac / flac
        // 속도 (0.5-2.0)
        speed: 1.0
      }
    }
  }
}

지원 TTS 엔진

엔진	특징	설정 요구사항
`openai`	고품질, 다국어, 낮은 지연시간	OpenAI API Key 필요
`azure`	엔터프라이즈급, 매우 다양한 음성 선택	Azure Speech 구독 필요
`elevenlabs`	매우 자연스러움, 복제 지원	ElevenLabs API Key 필요
`edge`	무료, 괜찮은 품질	추가 설정 불필요
`local`	오프라인 실행, 프라이버시 우선	piper 또는 espeak 설치 필요

각 엔진 설정 예제

OpenAI TTS

{
  tts: {
    engine: "openai",
    voice: "nova",       // alloy, echo, fable, onyx, nova, shimmer
    model: "tts-1-hd",  // tts-1 (빠름) 또는 tts-1-hd (고품질)
    apiKey: "${OPENAI_API_KEY}"
  }
}

Azure TTS

{
  tts: {
    engine: "azure",
    voice: "zh-CN-XiaoxiaoNeural",  // 중국어 여성 음성
    region: "eastasia",
    subscriptionKey: "${AZURE_SPEECH_KEY}",
    // 선택사항: SSML 고급 제어
    ssml: {
      rate: "medium",
      pitch: "default"
    }
  }
}

ElevenLabs TTS

{
  tts: {
    engine: "elevenlabs",
    voiceId: "21m00Tcm4TlvDq8ikWAM",
    apiKey: "${ELEVENLABS_API_KEY}",
    // 음성 매개변수 조절
    stability: 0.5,
    similarityBoost: 0.75
  }
}

Edge TTS (무료)

{
  tts: {
    engine: "edge",
    voice: "zh-CN-YunxiNeural",  // 중국어 남성 음성
    // API Key 불필요
  }
}

음성 응답 모드

OpenClaw은 세 가지 음성 응답 모드를 지원합니다:

1. 음성 전용 모드

AI가 음성 메시지만 전송하고, 텍스트는 전송하지 않습니다:

{
  tts: {
    enabled: true,
    mode: "voice_only"
  }
}

2. 음성 + 텍스트 모드

음성과 텍스트 메시지를 동시에 전송합니다:

{
  tts: {
    enabled: true,
    mode: "voice_and_text"
  }
}

3. 온디맨드 트리거 모드 (권장)

기본적으로 텍스트를 전송하고, 사용자가 명령으로 음성을 요청할 수 있습니다:

{
  tts: {
    enabled: true,
    mode: "on_demand",
    // 음성을 트리거하는 키워드
    triggerWords: ["음성 응답", "읽어줘", "voice"]
  }
}

사용자 사용 방식:

사용자: voice 오늘 날씨 어때?
AI: [음성 메시지 전송] 오늘 서울은 맑음, 기온 15도에서 25도...

Voice 명령 시스템

OpenClaw은 /voice 명령 세트를 제공하여 사용자가 채팅에서 유연하게 음성 기능을 제어할 수 있습니다:

/voice on          - 음성 응답 활성화
/voice off         - 음성 응답 비활성화
/voice mode <모드> - 모드 전환 (voice_only / voice_and_text / on_demand)
/voice speed 1.5   - 속도 조절
/voice lang ko     - 음성 언어 설정
/voice list        - 사용 가능한 음성 나열
/voice set <name>  - 음성 캐릭터 변경

Voice 명령 설정

{
  agents: {
    "my-agent": {
      commands: {
        voice: {
          enabled: true,
          // 사용자가 조절할 수 있는 옵션
          allowUserControl: {
            speed: true,
            voice: true,
            mode: true,
            language: true
          }
        }
      }
    }
  }
}

음성 입력 인식 (STT)

OpenClaw은 음성 출력뿐만 아니라 음성 입력 인식도 지원합니다. 사용자가 음성 메시지를 보내면, OpenClaw이 자동으로 텍스트로 변환할 수 있습니다:

{
  agents: {
    "my-agent": {
      stt: {
        enabled: true,
        engine: "openai",  // Whisper 모델 사용
        model: "whisper-1",
        language: "ko",    // 우선 인식 언어
        // 인식 후 전사 텍스트 표시 여부
        showTranscription: true
      }
    }
  }
}

전체 음성 대화 흐름:

사용자 → [음성 메시지 전송] → OpenClaw STT → 텍스트로 전사 → AI 처리
                                                        ↓
사용자 ← [음성 응답 수신] ← OpenClaw TTS ← 텍스트 응답 ← AI 생성

플랫폼 적응

각 채팅 플랫폼의 음성 메시지 지원 정도가 다릅니다:

플랫폼	음성 전송	음성 수신(STT)	최대 시간	형식
Telegram	지원	지원	60분	OGG/Opus
Discord	지원	지원	무제한	Opus
WhatsApp	지원	지원	무제한	OGG/Opus
Slack	부분 지원	지원	무제한	MP3
WeChat	지원	지원	60초	AMR/Silk
WebChat	지원	지원	무제한	MP3/WAV

OpenClaw은 대상 플랫폼에 따라 자동으로 최적의 오디오 형식과 인코딩 매개변수를 선택합니다.

WeChat 특수 처리

WeChat의 음성 메시지에는 60초 제한이 있으며, OpenClaw이 자동으로 처리합니다:

{
  tts: {
    platformOverrides: {
      wechat: {
        // 60초 초과 시 자동으로 여러 음성으로 분할
        autoSplit: true,
        // 또는 초장 콘텐츠를 텍스트로 다운그레이드
        fallbackToText: true,
        maxDuration: 55  // 5초 버퍼 유지
      }
    }
  }
}

오디오 캐시

TTS API 호출을 줄이고 지연시간을 낮추기 위해 OpenClaw은 오디오 캐시를 지원합니다:

{
  tts: {
    cache: {
      enabled: true,
      // 캐시 디렉토리
      dir: "./cache/tts",
      // 캐시 만료 시간 (초)
      ttl: 86400,  // 24시간
      // 최대 캐시 크기 (MB)
      maxSize: 500
    }
  }
}

캐시 전략: 동일한 텍스트 + 동일한 음성 설정 = 캐시 적중, 이미 생성된 오디오 파일을 직접 반환하고 TTS API 호출을 건너뜁니다.

고급: SSML 마크업

정밀한 음성 효과 제어가 필요한 시나리오에서는 시스템 프롬프트에서 AI가 SSML 마크업을 사용하도록 안내할 수 있습니다:

{
  tts: {
    engine: "azure",
    ssmlEnabled: true
  }
}

AI는 응답에 SSML 명령을 포함할 수 있습니다:

<speak>
  <prosody rate="slow" pitch="+2st">
    이 부분은 느린 속도와 높은 음높이로 읽힙니다.
  </prosody>
  <break time="500ms"/>
  <emphasis level="strong">핵심 내용</emphasis>이 강조됩니다.
</speak>

비용 최적화

TTS 서비스는 문자 수 기준으로 과금되며, 다음은 몇 가지 최적화 제안입니다:

캐시 활성화: 동일한 콘텐츠의 오디오를 반복 생성하지 않음
온디맨드 모드 사용: 모든 메시지에 음성이 필요한 것은 아님
음성 길이 제한: 초장 응답은 자동으로 텍스트로 다운그레이드
적합한 엔진 선택: Edge TTS는 무료지만 품질이 약간 낮고, OpenAI TTS는 유료지만 품질이 높음

{
  tts: {
    // 500자를 초과하는 응답은 음성을 생성하지 않음
    maxChars: 500,
    // 초과 시 다운그레이드 전략
    fallback: "text_with_summary_voice"
    // 텍스트 전문을 먼저 전송하고, 음성 요약을 전송
  }
}

마무리

OpenClaw의 음성 기능은 AI Agent가 순수 텍스트 인터랙션의 한계를 넘어설 수 있게 합니다. 유연한 TTS 엔진 선택, 다양한 응답 모드, Voice 명령 시스템 및 음성 입력 인식을 통해 진정한 음성 대화를 지원하는 AI 어시스턴트를 구축할 수 있습니다. 플랫폼 적응과 캐시 최적화를 결합하면, 경험을 보장하면서 비용도 제어할 수 있습니다.