텍스트 음성 변환

​

빠른 시작

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

​

지원되는 제공자

​

구성

{
  messages: {
    tts: {
      auto: "always",
      provider: "azure-speech",
      providers: {
        "azure-speech": {
          apiKey: "${AZURE_SPEECH_KEY}",
          region: "eastus",
          speakerVoice: "en-US-JennyNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
          voiceNoteOutputFormat: "ogg-24khz-16bit-mono-opus",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
      providers: {
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          apiKey: "${GEMINI_API_KEY}",
          model: "gemini-3.1-flash-tts-preview",
          speakerVoice: "Kore",
          // Optional natural-language style prompts:
          // audioProfile: "Speak in a calm, podcast-host tone.",
          // speakerName: "Alex",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "gradium",
      providers: {
        gradium: {
          apiKey: "${GRADIUM_API_KEY}",
          speakerVoiceId: "YTpq7expH9539ERJ",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "inworld",
      providers: {
        inworld: {
          apiKey: "${INWORLD_API_KEY}",
          modelId: "inworld-tts-1.5-max",
          speakerVoiceId: "Sarah",
          temperature: 0.7,
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "tts-local-cli",
      providers: {
        "tts-local-cli": {
          command: "say",
          args: ["-o", "{{OutputPath}}", "{{Text}}"],
          outputFormat: "wav",
          timeoutMs: 120000,
        },
      },
    },
  },
}

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

{
  messages: {
    tts: {
      auto: "always",
      provider: "minimax",
      providers: {
        minimax: {
          apiKey: "${MINIMAX_API_KEY}",
          model: "speech-2.8-hd",
          speakerVoiceId: "English_expressive_narrator",
          speed: 1.0,
          vol: 1.0,
          pitch: 0,
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      providers: {
        openai: {
          apiKey: "${OPENAI_API_KEY}",
          model: "gpt-4o-mini-tts",
          speakerVoice: "alloy",
        },
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
          voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },
          applyTextNormalization: "auto",
          languageCode: "en",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "openrouter",
      providers: {
        openrouter: {
          apiKey: "${OPENROUTER_API_KEY}",
          model: "hexgrad/kokoro-82m",
          speakerVoice: "af_alloy",
          responseFormat: "mp3",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "volcengine",
      providers: {
        volcengine: {
          apiKey: "${VOLCENGINE_TTS_API_KEY}",
          resourceId: "seed-tts-1.0",
          speakerVoice: "en_female_anna_mars_bigtts",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "xai",
      providers: {
        xai: {
          apiKey: "${XAI_API_KEY}",
          speakerVoiceId: "eve",
          language: "en",
          responseFormat: "mp3",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "xiaomi",
      providers: {
        xiaomi: {
          apiKey: "${XIAOMI_API_KEY}",
          model: "mimo-v2.5-tts",
          speakerVoice: "mimo_default",
          format: "mp3",
        },
      },
    },
  },
}

​

에이전트별 음성 재정의

{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
      providers: {
        elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", model: "eleven_multilingual_v2" },
      },
    },
  },
  agents: {
    list: [
      {
        id: "reader",
        tts: {
          providers: {
            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
      },
    ],
  },
}

1. messages.tts
2. 활성 agents.list[].tts
3. 채널이 channels.<channel>.tts를 지원하는 경우 채널 재정의
4. 채널이 channels.<channel>.accounts.<id>.tts를 전달하는 경우 계정 재정의
5. 이 호스트의 로컬 /tts 환경설정
6. 모델 재정의가 활성화된 경우 인라인 [[tts:...]] 지시문

{
  messages: {
    tts: {
      provider: "openai",
      providers: {
        openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" },
      },
    },
  },
  channels: {
    feishu: {
      accounts: {
        english: {
          tts: {
            providers: {
              openai: { speakerVoice: "shimmer" },
            },
          },
        },
      },
    },
  },
}

​

페르소나

​

최소 페르소나

{
  messages: {
    tts: {
      auto: "always",
      persona: "narrator",
      personas: {
        narrator: {
          label: "Narrator",
          provider: "elevenlabs",
          providers: {
            elevenlabs: {
              speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
              modelId: "eleven_multilingual_v2",
            },
          },
        },
      },
    },
  },
}

​

전체 페르소나(제공자 중립 프롬프트)

{
  messages: {
    tts: {
      auto: "always",
      persona: "alfred",
      personas: {
        alfred: {
          label: "Alfred",
          description: "Dry, warm British butler narrator.",
          provider: "google",
          fallbackPolicy: "preserve-persona",
          prompt: {
            profile: "A brilliant British butler. Dry, witty, warm, charming, emotionally expressive, never generic.",
            scene: "A quiet late-night study. Close-mic narration for a trusted operator.",
            sampleContext: "The speaker is answering a private technical request with concise confidence and dry warmth.",
            style: "Refined, understated, lightly amused.",
            accent: "British English.",
            pacing: "Measured, with short dramatic pauses.",
            constraints: ["Do not read configuration values aloud.", "Do not explain the persona."],
          },
          providers: {
            google: {
              model: "gemini-3.1-flash-tts-preview",
              speakerVoice: "Algieba",
              promptTemplate: "audio-profile-v1",
            },
            openai: { model: "gpt-4o-mini-tts", speakerVoice: "cedar" },
            elevenlabs: {
              speakerVoiceId: "voice_id",
              modelId: "eleven_multilingual_v2",
              seed: 42,
              voiceSettings: {
                stability: 0.65,
                similarityBoost: 0.8,
                style: 0.25,
                useSpeakerBoost: true,
                speed: 0.95,
              },
            },
          },
        },
      },
    },
  },
}

​

페르소나 결정

1. 설정된 경우 /tts persona <id> 로컬 환경설정.
2. 설정된 경우 messages.tts.persona.
3. 페르소나 없음.

1. 직접 재정의(CLI, Gateway, Talk, 허용된 TTS 지시문).
2. /tts provider <id> 로컬 환경설정.
3. 활성 페르소나의 provider.
4. messages.tts.provider.
5. 레지스트리 자동 선택.

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. 신뢰할 수 있는 요청 재정의
4. 허용된 모델 생성 TTS 지시문 재정의

​

제공자가 페르소나 프롬프트를 사용하는 방식

​

폴백 정책

​

모델 기반 지시문

Here you go.

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

• provider(등록된 제공자 ID, allowProvider: true 필요)
• speakerVoice / speakerVoiceId(레거시 별칭: voice, voiceName, voice_name, google_voice, voiceId)
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume(MiniMax 볼륨, 0-10)
• pitch(MiniMax 정수 피치, -12~12, 소수 값은 버림)
• emotion(Volcengine 감정 태그)
• applyTextNormalization(auto|on|off)
• languageCode(ISO 639-1)
• seed

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

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

​

슬래시 명령

/tts off | on | status
/tts chat on | off | default
/tts latest
/tts provider <id>
/tts persona <id> | off
/tts limit <chars>
/tts summary off
/tts audio <text>

• /tts on은 로컬 TTS 환경설정을 always로 기록하고, /tts off는 off로 기록합니다.
• /tts chat on|off|default는 현재 채팅에 대해 세션 범위 자동 TTS 재정의를 기록합니다.
• /tts persona <id>는 로컬 페르소나 환경설정을 기록하고, /tts persona off는 이를 지웁니다.
• /tts latest는 현재 세션 전사에서 최신 어시스턴트 응답을 읽고 이를 한 번 오디오로 전송합니다. 중복 음성 전송을 억제하기 위해 세션 항목에 해당 응답의 해시만 저장합니다.
• /tts audio는 일회성 오디오 응답을 생성합니다(TTS를 켜지 않습니다).
• limit 및 summary는 기본 구성이 아니라 로컬 환경설정에 저장됩니다.
• /tts status에는 최신 시도의 폴백 진단이 포함됩니다. Fallback: <primary> -> <used>, Attempts: ..., 그리고 시도별 세부 정보(provider:outcome(reasonCode) latency)입니다.
• /status는 TTS가 활성화된 경우 구성된 제공자, 모델, 음성, 삭제 처리된 사용자 지정 엔드포인트 메타데이터와 함께 활성 TTS 모드를 표시합니다.

​

사용자별 환경설정

​

출력 형식(고정)

• 음성 메모 지원 채널: 음성 메모 답장은 Opus(ElevenLabs의 opus_48000_64, OpenAI의 opus)를 우선 사용합니다.
  • 48kHz / 64kbps는 음성 메시지에 적합한 균형점입니다.
• Feishu / WhatsApp: 음성 메모 답장이 MP3/WebM/WAV/M4A 또는 다른 오디오 파일일 가능성이 높은 형식으로 생성되면, 채널 Plugin은 기본 음성 메시지를 보내기 전에 ffmpeg로 48kHz Ogg/Opus로 트랜스코딩합니다. WhatsApp은 결과물을 Baileys audio 페이로드와 ptt: true, audio/ogg; codecs=opus를 사용해 보냅니다. 변환에 실패하면 Feishu는 원본 파일을 첨부 파일로 받으며, WhatsApp은 호환되지 않는 PTT 페이로드를 게시하는 대신 전송에 실패합니다.
• 기타 채널: MP3(ElevenLabs의 mp3_44100_128, OpenAI의 mp3).
  • 44.1kHz / 128kbps는 음성 명료도를 위한 기본 균형입니다.
• MiniMax: 일반 오디오 첨부 파일에는 MP3(speech-2.8-hd 모델, 32kHz 샘플 레이트)를 사용합니다. 채널이 알리는 음성 메모 대상의 경우, 채널이 트랜스코딩을 알리면 OpenClaw는 전달 전에 ffmpeg로 MiniMax MP3를 48kHz Opus로 트랜스코딩합니다.
• Xiaomi MiMo: 기본적으로 MP3를 사용하며, 구성된 경우 WAV를 사용합니다. 채널이 알리는 음성 메모 대상의 경우, 채널이 트랜스코딩을 알리면 OpenClaw는 전달 전에 ffmpeg로 Xiaomi 출력을 48kHz Opus로 트랜스코딩합니다.
• 로컬 CLI: 구성된 outputFormat을 사용합니다. 음성 메모 대상은 Ogg/Opus로 변환되고, 전화 통신 출력은 ffmpeg로 원시 16 kHz 모노 PCM으로 변환됩니다.
• Google Gemini: Gemini API TTS는 원시 24kHz PCM을 반환합니다. OpenClaw는 오디오 첨부 파일용으로 이를 WAV로 감싸고, 음성 메모 대상용으로 48kHz Opus로 트랜스코딩하며, Talk/전화 통신용으로는 PCM을 직접 반환합니다.
• Gradium: 오디오 첨부 파일에는 WAV, 음성 메모 대상에는 Opus, 전화 통신에는 8 kHz의 ulaw_8000을 사용합니다.
• Inworld: 일반 오디오 첨부 파일에는 MP3, 음성 메모 대상에는 네이티브 OGG_OPUS, Talk/전화 통신에는 22050 Hz의 원시 PCM을 사용합니다.
• xAI: 기본적으로 MP3를 사용하며, responseFormat은 mp3, wav, pcm, mulaw, alaw 중 하나일 수 있습니다. OpenClaw는 xAI의 배치 REST TTS 엔드포인트를 사용하고 완전한 오디오 첨부 파일을 반환합니다. xAI의 스트리밍 TTS WebSocket은 이 공급자 경로에서 사용되지 않습니다. 네이티브 Opus 음성 메모 형식은 이 경로에서 지원되지 않습니다.
• Microsoft: microsoft.outputFormat(기본값 audio-24khz-48kbitrate-mono-mp3)을 사용합니다.
  • 번들 전송 계층은 outputFormat을 받지만, 서비스에서 모든 형식을 사용할 수 있는 것은 아닙니다.
  • 출력 형식 값은 Microsoft Speech 출력 형식(Ogg/WebM Opus 포함)을 따릅니다.
  • Telegram sendVoice는 OGG/MP3/M4A를 받습니다. 보장된 Opus 음성 메시지가 필요하면 OpenAI/ElevenLabs를 사용하세요.
  • 구성된 Microsoft 출력 형식이 실패하면 OpenClaw는 MP3로 재시도합니다.

​

Auto-TTS 동작

• 답장에 이미 구조화된 미디어가 포함되어 있으면 TTS를 건너뜁니다.
• 매우 짧은 답장(10자 미만)을 건너뜁니다.
• 요약이 활성화된 경우 긴 답장을 summaryModel(또는 agents.defaults.model.primary)을 사용해 요약합니다.
• 생성된 오디오를 답장에 첨부합니다.
• mode: "final"에서는 텍스트 스트림이 완료된 뒤에도 스트리밍된 최종 답장에 대해 오디오 전용 TTS를 보냅니다. 생성된 미디어는 일반 답장 첨부 파일과 동일한 채널 미디어 정규화를 거칩니다.

Reply -> TTS enabled?
  no  -> send text
  yes -> has media / short?
          yes -> send text
          no  -> length > limit?
                   no  -> TTS -> attach audio
                   yes -> summary enabled?
                            no  -> send text
                            yes -> summarize -> TTS -> attach audio

​

채널별 출력 형식

• Feishu / WhatsApp 트랜스코딩: 음성 메모 답장이 MP3/WebM/WAV/M4A로 도착하면, 채널 Plugin은 ffmpeg로 48 kHz Ogg/Opus로 트랜스코딩합니다. WhatsApp은 Baileys를 통해 ptt: true 및 audio/ogg; codecs=opus로 보냅니다. 변환에 실패하면 Feishu는 원본 파일 첨부로 폴백하고, WhatsApp은 호환되지 않는 PTT 페이로드를 게시하는 대신 전송에 실패합니다.
• MiniMax / Xiaomi MiMo: 기본값은 MP3(MiniMax speech-2.8-hd의 경우 32 kHz)이며, 음성 메모 대상에는 ffmpeg를 통해 48 kHz Opus로 트랜스코딩됩니다.
• 로컬 CLI: 구성된 outputFormat을 사용합니다. 음성 메모 대상은 Ogg/Opus로 변환되고, 전화 통신 출력은 원시 16 kHz 모노 PCM으로 변환됩니다.
• Google Gemini: 원시 24 kHz PCM을 반환합니다. OpenClaw는 첨부 파일용으로 WAV로 감싸고, 음성 메모 대상용으로 48 kHz Opus로 트랜스코딩하며, Talk/전화 통신용으로는 PCM을 직접 반환합니다.
• Inworld: MP3 첨부 파일, 네이티브 OGG_OPUS 음성 메모, Talk/전화 통신용 원시 PCM 22050 Hz를 사용합니다.
• xAI: 기본값은 MP3이며, responseFormat은 mp3|wav|pcm|mulaw|alaw일 수 있습니다. xAI의 배치 REST 엔드포인트를 사용하며, 스트리밍 WebSocket TTS는 사용되지 않습니다. 네이티브 Opus 음성 메모 형식은 지원되지 않습니다.
• Microsoft: microsoft.outputFormat(기본값 audio-24khz-48kbitrate-mono-mp3)을 사용합니다. Telegram sendVoice는 OGG/MP3/M4A를 받습니다. 보장된 Opus 음성 메시지가 필요하면 OpenAI/ElevenLabs를 사용하세요. 구성된 Microsoft 형식이 실패하면 OpenClaw는 MP3로 재시도합니다.

​

필드 참조

​

에이전트 도구

​

Gateway RPC

​

서비스 링크

• OpenAI 텍스트 음성 변환 가이드
• OpenAI Audio API 참조
• Azure Speech REST 텍스트 음성 변환
• Azure Speech 제공자
• ElevenLabs 텍스트 음성 변환
• ElevenLabs 인증
• Gradium
• Inworld TTS API
• MiniMax T2A v2 API
• Volcengine TTS HTTP API
• Xiaomi MiMo 음성 합성
• node-edge-tts
• Microsoft Speech 출력 형식
• xAI 텍스트 음성 변환

​

관련 항목

• 미디어 개요
• 음악 생성
• 동영상 생성
• 슬래시 명령
• 음성 통화 Plugin