Tools

텍스트 음성 변환

OpenClaw는 아웃바운드 응답을 14개 음성 제공자를 통해 오디오로 변환합니다. Feishu, Matrix, Telegram, WhatsApp에서는 기본 음성 메시지로, 그 외에서는 오디오 첨부 파일로 제공하며, 전화 통신과 Talk에서는 PCM/Ulaw 스트림으로 제공합니다.

TTS는 Talk의 stt-tts 모드에서 음성 출력 부분을 담당합니다(talk.speak 호출도 이와 동일한 합성 경로를 사용합니다). 제공자 네이티브 realtime Talk 세션은 대신 실시간 제공자 내부에서 음성을 합성하며, transcription 세션은 어시스턴트의 음성 응답을 절대 합성하지 않습니다.

빠른 시작

제공자 선택

OpenAI와 ElevenLabs는 가장 안정적인 호스팅 옵션입니다. Microsoft와 로컬 CLI는 API 키 없이 작동합니다. 전체 목록은 제공자 매트릭스를 참조하십시오.

API 키 설정

제공자의 환경 변수를 내보내십시오(예: OPENAI_API_KEY, ELEVENLABS_API_KEY). Microsoft와 로컬 CLI에는 키가 필요하지 않습니다.

구성에서 활성화

messages.tts.auto: "always" 및 messages.tts.provider을 설정하십시오.

json5

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

채팅에서 사용해 보기

/tts status는 현재 상태를 표시합니다. /tts audio Hello from OpenClaw은 일회성 오디오 응답을 보냅니다.

지원되는 제공자

제공자	인증	참고
Azure Speech	`AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION` (또한 `AZURE_SPEECH_API_KEY`, `SPEECH_KEY`, `SPEECH_REGION`)	기본 Ogg/Opus 음성 메모 출력과 전화 통신을 지원합니다.
DeepInfra	`DEEPINFRA_API_KEY`	OpenAI 호환 TTS입니다. 기본값은 `hexgrad/Kokoro-82M`입니다.
ElevenLabs	`ELEVENLABS_API_KEY` 또는 `XI_API_KEY`	음성 복제, 다국어 및 `seed`을 통한 결정적 출력을 지원하며, Discord 음성 재생을 위해 스트리밍됩니다.
Google Gemini	`GEMINI_API_KEY` 또는 `GOOGLE_API_KEY`	Gemini API 배치 TTS이며, `promptTemplate: "audio-profile-v1"`을 통해 페르소나를 반영합니다.
Gradium	`GRADIUM_API_KEY`	음성 메모 및 전화 통신 출력을 지원합니다.
Inworld	`INWORLD_API_KEY`	스트리밍 TTS API입니다. 기본 Opus 음성 메모와 PCM 전화 통신을 지원합니다.
로컬 CLI	없음	구성된 로컬 TTS 명령을 실행합니다.
Microsoft	없음	`node-edge-tts`을 통한 공개 Edge 신경망 TTS입니다. 최선형 서비스이며 SLA는 없습니다.
MiniMax	`MINIMAX_API_KEY` (또는 토큰 요금제: `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`)	T2A v2 API입니다. 기본값은 `speech-2.8-hd`입니다.
OpenAI	`OPENAI_API_KEY`	자동 요약에도 사용되며, 페르소나 `instructions`을 지원합니다.
OpenRouter	`OPENROUTER_API_KEY` (`models.providers.openrouter.apiKey` 재사용 가능)	기본 모델은 `hexgrad/kokoro-82m`입니다.
Volcengine	`VOLCENGINE_TTS_API_KEY` 또는 `BYTEPLUS_SEED_SPEECH_API_KEY` (레거시 AppID/토큰: `VOLCENGINE_TTS_APPID`/`_TOKEN`)	BytePlus Seed Speech HTTP API입니다.
Vydra	`VYDRA_API_KEY`	이미지, 동영상, 음성을 함께 제공하는 제공자입니다.
xAI	`XAI_API_KEY`	xAI 배치 TTS입니다. 기본 Opus 음성 메모는 지원되지 않습니다.
Xiaomi MiMo	`XIAOMI_API_KEY`	Xiaomi 채팅 완성을 통한 MiMo TTS입니다.

여러 제공자가 구성된 경우 선택한 제공자를 먼저 사용하고 나머지는 대체 옵션으로 사용합니다. 자동 요약은 summaryModel(또는 agents.defaults.model.primary)을 사용하므로, 요약을 활성화한 상태로 유지하려면 해당 제공자도 인증해야 합니다.

구성

TTS 구성은 ~/.openclaw/openclaw.json의 messages.tts 아래에 있습니다. 프리셋을 선택하고 제공자 블록을 조정하십시오. 아래 표시된 speakerVoice/speakerVoiceId 필드는 표준 필드이며, 각 제공자 고유의 voice/voiceId/voiceName 필드 이름도 레거시 별칭으로 계속 작동합니다.

Azure Speech

json5

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

ElevenLabs

json5

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

Google Gemini

json5

{messages: {tts: {  auto: "always",  provider: "google",  providers: {    google: {      apiKey: "${GEMINI_API_KEY}",      model: "gemini-3.1-flash-tts-preview",      speakerVoice: "Kore",      // 선택적인 자연어 스타일 프롬프트:      // audioProfile: "차분한 팟캐스트 진행자 어조로 말합니다.",      // speakerName: "Alex",    },  },},},}

Gradium

json5

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

Inworld

json5

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

로컬 CLI

json5

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

Microsoft(키 없음)

json5

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

MiniMax

json5

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

OpenAI + ElevenLabs

json5

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

OpenRouter

json5

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

Volcengine

json5

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

xAI

json5

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

Xiaomi MiMo

json5

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

Xiaomi mimo-v2.5-tts-voicedesign의 경우 speakerVoice을 생략하고 style을 음성 디자인 프롬프트로 설정하십시오. OpenClaw는 해당 프롬프트를 TTS user 메시지로 보내며 voicedesign 모델에는 audio.voice을 보내지 않습니다.

에이전트별 음성 재정의

한 에이전트가 다른 제공자, 음성, 모델, 페르소나 또는 자동 TTS 모드로 말해야 할 때는 agents.list[].tts을 사용하십시오. 에이전트 블록은 messages.tts 위에 심층 병합되므로 제공자 자격 증명은 전역 제공자 구성에 유지할 수 있습니다.

json5

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

에이전트별 페르소나를 고정하려면 제공자 구성과 함께 agents.list[].tts.persona을 설정하십시오. 이 설정은 해당 에이전트에 대해서만 전역 messages.tts.persona을 재정의합니다.

자동 응답, /tts audio, /tts status 및 tts 에이전트 도구의 우선순위:

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

채널 및 계정 재정의는 messages.tts과 동일한 형태를 사용하며 이전 계층 위에 심층 병합됩니다. 따라서 공유 제공자 자격 증명은 messages.tts에 유지하면서 채널이나 봇 계정에서는 화자 음성, 모델, 페르소나 또는 자동 모드만 변경할 수 있습니다.

json5

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

페르소나

페르소나는 여러 제공자에 걸쳐 결정론적으로 적용할 수 있는 안정적인 음성 정체성입니다. 특정 제공자를 선호하고, 제공자 중립적인 프롬프트 의도를 정의하며, 음성, 모델, 프롬프트 템플릿, 시드 및 음성 설정에 대한 제공자별 바인딩을 포함할 수 있습니다.

최소 페르소나

json5

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

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

json5

{  messages: {    tts: {      auto: "always",      persona: "alfred",      personas: {        alfred: {          label: "Alfred",          description: "건조하면서도 따뜻한 영국인 집사 내레이터.",          provider: "google",          fallbackPolicy: "preserve-persona",          prompt: {            profile: "명석한 영국인 집사. 건조하고 재치 있으며 따뜻하고 매력적이고 감정 표현이 풍부하며, 절대 몰개성적이지 않습니다.",            scene: "조용한 심야의 서재. 신뢰하는 운영자를 위한 근접 마이크 내레이션.",            sampleContext: "화자는 비공개 기술 요청에 간결한 자신감과 건조한 따뜻함으로 답하고 있습니다.",            style: "세련되고 절제되어 있으며 살짝 즐거워합니다.",            accent: "영국 영어.",            pacing: "속도를 조절하며 짧고 극적인 쉼을 둡니다.",            constraints: ["구성 값을 소리 내어 읽지 마십시오.", "페르소나를 설명하지 마십시오."],          },          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,              },            },          },        },      },    },  },}

페르소나 결정

활성 페르소나는 결정론적으로 선택됩니다.

설정된 경우 /tts persona <id> 로컬 기본 설정.
설정된 경우 messages.tts.persona.
페르소나 없음.

제공자 선택은 명시적 설정을 우선합니다.

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

각 제공자 시도에서 OpenClaw는 다음 순서로 구성을 병합합니다.

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

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

페르소나 프롬프트 필드(profile, scene, sampleContext, style, accent, pacing, constraints)는 제공자 중립적입니다. 각 제공자는 이를 사용할 방식을 결정합니다.

Google Gemini

유효한 Google 제공자 구성에 promptTemplate: "audio-profile-v1" 또는 personaPrompt이 설정된 경우에만 페르소나 프롬프트 필드를 Gemini TTS 프롬프트 구조로 감쌉니다. 이전 audioProfile 및 speakerName 필드는 여전히 Google 전용 프롬프트 텍스트로 앞에 추가됩니다. [[tts:text]] 블록 안의 [whispers] 또는 [laughs] 같은 인라인 오디오 태그는 Gemini 트랜스크립트 안에 보존됩니다. OpenClaw는 이러한 태그를 생성하지 않습니다.

OpenAI

명시적인 OpenAI instructions이 구성되지 않은 경우에만 페르소나 프롬프트 필드를 요청의 instructions 필드에 매핑합니다. 명시적인 instructions이 항상 우선합니다.

기타 제공자

personas.<id>.providers.<provider> 아래의 제공자별 페르소나 바인딩만 사용합니다. 제공자가 자체 페르소나 프롬프트 매핑을 구현하지 않는 한 페르소나 프롬프트 필드는 무시됩니다.

대체 정책

fallbackPolicy은 시도한 제공자에 대한 바인딩이 없는 페르소나의 동작을 제어합니다.

정책	동작
`preserve-persona`	기본값. 제공자 중립적 프롬프트 필드는 계속 사용할 수 있으며, 제공자는 이를 사용하거나 무시할 수 있습니다.
`provider-defaults`	해당 시도의 프롬프트 준비에서 페르소나를 생략합니다. 다른 제공자로 계속 대체하는 동안 해당 제공자는 중립적 기본값을 사용합니다.
`fail`	`reasonCode: "not_configured"` 및 `personaBinding: "missing"`과 함께 해당 제공자 시도를 건너뜁니다. 대체 제공자는 계속 시도합니다.

시도한 모든 제공자를 건너뛰거나 모두 실패한 경우에만 전체 TTS 요청이 실패합니다.

Talk 세션의 제공자 선택은 세션 범위입니다. Talk 클라이언트는 talk.catalog에서 제공자 ID, 모델 ID, 음성 ID 및 로캘을 선택하여 Talk 세션이나 핸드오프 요청을 통해 전달해야 합니다. 음성 세션을 열 때 messages.tts 또는 전역 Talk 제공자 기본값을 변경해서는 안 됩니다.

모델 기반 지시문

기본적으로 어시스턴트는 단일 응답의 음성, 모델 또는 속도를 재정의하는 [[tts:...]] 지시문과 오디오에만 나타나야 하는 표현 단서를 위한 선택적 [[tts:text]]...[[/tts:text]] 블록을 생성할 수 있습니다.

text

여기 있습니다. [[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](웃음) 노래를 한 번 더 읽어 주세요.[[/tts:text]]

messages.tts.auto이 "tagged"이면 오디오를 트리거하려면 지시문이 필요합니다. 스트리밍 블록 전송은 인접한 블록에 걸쳐 나뉘어 있더라도 채널이 보기 전에 표시 텍스트에서 지시문을 제거합니다.

modelOverrides.allowProvider: true이 아니면 provider=...은 무시됩니다. 응답에서 provider=...을 선언하면 해당 지시문의 다른 키는 그 제공자만 파싱합니다. 지원하지 않는 키는 제거되고 TTS 지시문 경고로 보고됩니다.

사용 가능한 지시문 키:

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

모델 재정의를 완전히 비활성화:

json5

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

다른 조정 항목의 구성 가능성을 유지하면서 제공자 전환 허용:

json5

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

슬래시 명령어

단일 명령어 /tts. Discord에서는 /tts이 Discord 내장 명령어이므로 OpenClaw가 /voice도 등록합니다. 텍스트 /tts ...은 계속 작동합니다.

text

/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를 켜거나 끄지 않습니다.
/tts limit <chars>은 100–4096을 허용합니다(4096은 Telegram 캡션/메시지 최댓값). 이 범위를 벗어난 값은 거부됩니다.
limit 및 summary은 주 구성 파일이 아니라 로컬 기본 설정에 저장됩니다.
/tts status에는 최신 시도에 대한 대체 진단인 Fallback: <primary> -> <used>, Attempts: ... 및 시도별 세부 정보(provider:outcome(reasonCode) latency)가 포함됩니다.
/status은 TTS가 활성화된 경우 활성 TTS 모드와 구성된 제공자, 모델, 음성 및 정리된 사용자 지정 엔드포인트 메타데이터를 표시합니다.

사용자별 기본 설정

슬래시 명령어는 로컬 재정의를 prefsPath에 기록합니다. 기본값은 ~/.openclaw/settings/tts.json이며, OPENCLAW_TTS_PREFS 환경 변수 또는 messages.tts.prefsPath로 재정의할 수 있습니다.

저장된 필드	효과
`auto`	로컬 자동 TTS 재정의(`always`, `off`, …)
`provider`	로컬 기본 제공자 재정의
`persona`	로컬 페르소나 재정의
`maxLength`	요약/잘림 임계값(기본값 `1500`자, `/tts limit` 범위 100–4096)
`summarize`	요약 전환(기본값 `true`)

이 값들은 해당 호스트의 messages.tts 및 활성 agents.list[].tts 블록에서 가져온 유효 구성을 재정의합니다.

출력 형식

TTS 음성 전송은 채널 기능에 따라 결정됩니다. 채널 Plugin은 음성 스타일 TTS가 제공자에 네이티브 voice-note 대상을 요청해야 하는지, 일반 audio-file 합성을 유지해야 하는지, 그리고 채널이 전송 전에 비네이티브 출력을 트랜스코딩하는지를 알립니다.

대상	형식
Feishu / Matrix / Telegram / WhatsApp	음성 메시지 응답에는 Opus(ElevenLabs의 `opus_48000_64`, OpenAI의 `opus`)를 우선 사용합니다. 48 kHz / 64 kbps는 선명도와 크기의 균형을 맞춥니다.
기타 채널	MP3(ElevenLabs의 `mp3_44100_128`, OpenAI의 `mp3`). 44.1 kHz / 128 kbps는 음성에 대한 기본 균형값입니다.
Talk / 전화 통신	제공자 네이티브 PCM(Inworld 22050 Hz, Google 24 kHz) 또는 전화 통신용 Gradium의 `ulaw_8000`.

제공자별 참고 사항:

Feishu / WhatsApp 트랜스코딩: 음성 메시지 응답이 MP3/WebM/WAV/M4A 또는 다른 오디오로 추정되는 파일로 생성되면, 채널 Plugin은 네이티브 음성 메시지를 전송하기 전에 ffmpeg(libopus, 64 kbps)을 사용하여 48 kHz Ogg/Opus로 트랜스코딩합니다. WhatsApp은 ptt: true 및 audio/ogg; codecs=opus이 포함된 Baileys audio 페이로드를 통해 결과를 전송합니다. 트랜스코딩 실패 시 Feishu는 오류를 포착하고 원본 파일을 일반 첨부 파일로 전송하는 방식으로 대체합니다. WhatsApp에는 대체 동작이 없으므로 호환되지 않는 PTT 페이로드를 게시하는 대신 전송 자체가 실패합니다.
MiniMax: 일반 오디오 첨부 파일에는 MP3(speech-2.8-hd 모델, 32 kHz 샘플링 속도)를 사용하며, 채널에서 알린 음성 메시지 대상에는 ffmpeg을 사용하여 48 kHz Opus로 트랜스코딩합니다.
Xiaomi MiMo: 기본적으로 MP3를 사용하며, 구성된 경우 WAV를 사용합니다. 채널에서 알린 음성 메시지 대상에는 ffmpeg을 사용하여 48 kHz Opus로 트랜스코딩합니다.
로컬 CLI: 구성된 outputFormat을 사용합니다. 음성 메시지 대상은 Ogg/Opus로 변환하고, 전화 통신 출력은 ffmpeg을 사용하여 원시 16 kHz 모노 PCM으로 변환합니다.
Google Gemini: 원시 24 kHz PCM을 반환합니다. OpenClaw는 오디오 첨부 파일의 경우 이를 WAV로 래핑하고, 음성 메시지 대상에는 48 kHz Opus로 트랜스코딩하며, Talk/전화 통신에는 PCM을 직접 반환합니다.
Gradium: 오디오 첨부 파일에는 WAV, 음성 메시지 대상에는 Opus, 전화 통신에는 8 kHz의 ulaw_8000을 사용합니다.
Inworld: 일반 오디오 첨부 파일에는 MP3, 음성 메시지 대상에는 네이티브 OGG_OPUS, Talk/전화 통신에는 22050 Hz의 원시 PCM을 사용합니다.
xAI: 기본적으로 MP3를 사용합니다. 오디오 파일 합성에서는 버퍼링 출력과 스트리밍 출력 모두에 mp3, wav, pcm, mulaw 또는 alaw을 사용할 수 있습니다. xAI의 pcm, mulaw 및 alaw 출력은 헤더가 없는 원시 오디오이므로, 음성 메시지 대상은 스트리밍 및 버퍼링 대체 동작에 MP3를 사용합니다. 버퍼링 합성은 xAI의 배치 REST /v1/tts 엔드포인트를 사용하며, textToSpeechStream은 네이티브 wss://api.x.ai/v1/tts을 사용합니다. 이는 실시간 음성 계약이 아닙니다. 네이티브 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로 다시 시도합니다.
- 명시적인 음성 재정의가 설정되지 않고 기본 영어 음성이 사용되는 경우, 응답 텍스트에서 CJK 문자가 대부분을 차지하면 OpenClaw는 중국어 신경망 음성(zh-CN-XiaoxiaoNeural, zh-CN 로캘)으로 자동 전환합니다.

OpenAI 및 ElevenLabs 출력 형식은 위에 나열된 대로 채널별로 고정됩니다.

자동 TTS 동작

messages.tts.auto이 활성화되면 OpenClaw는 다음을 수행합니다.

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

응답이 maxLength을 초과해도 OpenClaw는 오디오를 완전히 건너뛰지 않습니다.

요약 켜짐(기본값)이고 요약 모델을 사용할 수 있는 경우: 텍스트를 약 maxLength자로 요약한 후 요약문을 음성으로 합성합니다.
요약 꺼짐, 요약 실패 또는 요약 모델에 사용할 수 있는 API 키가 없는 경우: 텍스트를 maxLength자로 잘라낸 후 잘린 텍스트를 음성으로 합성합니다.

text

응답 -> TTS가 활성화되었습니까?  아니요 -> 텍스트 전송  예     -> 미디어가 있거나 짧습니까?              예     -> 텍스트 전송              아니요 -> 길이 > 제한입니까?                           아니요 -> TTS -> 오디오 첨부                           예     -> 요약이 활성화되어 있고 사용할 수 있습니까?                                      아니요 -> 잘라내기 -> TTS -> 오디오 첨부                                      예     -> 요약 -> TTS -> 오디오 첨부

필드 참조

최상위 messages.tts.*

auto"off" | "always" | "inbound" | "tagged"

자동 TTS 모드입니다. inbound은 수신 음성 메시지 이후에만 오디오를 전송하고, tagged은 응답에 [[tts:...]] 지시문 또는 [[tts:text]] 블록이 포함된 경우에만 오디오를 전송합니다.

enabledboolean

레거시 토글입니다. openclaw doctor --fix은 이를 auto으로 마이그레이션합니다.

mode"final" | "all"default: final

"all"에는 최종 응답뿐만 아니라 도구/블록 응답도 포함됩니다.

providerstring

음성 제공자 ID입니다. 설정하지 않으면 OpenClaw는 레지스트리 자동 선택 순서에서 구성된 첫 번째 제공자를 사용합니다. 레거시 provider: "edge"은 openclaw doctor --fix에 의해 "microsoft"으로 다시 작성됩니다.

personastring

personas의 활성 페르소나 ID입니다. 소문자로 정규화됩니다.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InBlcnNvbmFzLjxpZA " type="object"> 일관된 음성 정체성입니다. 필드: label, description, provider, fallbackPolicy, prompt, providers.<provider>. 페르소나를 참조하십시오.

summaryModelstring

자동 요약용 저비용 모델이며, 기본값은 agents.defaults.model.primary입니다. provider/model 또는 구성된 모델 별칭을 사용할 수 있습니다.

modelOverridesobject

모델이 TTS 지시문을 출력하도록 허용합니다. enabled의 기본값은 true이고, allowProvider의 기본값은 false입니다.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InByb3ZpZGVycy48aWQ " type="object"> 음성 제공자 ID를 키로 사용하는 제공자 소유 설정입니다. 레거시 직접 블록(messages.tts.openai, .elevenlabs, .microsoft, .edge)은 openclaw doctor --fix에 의해 다시 작성됩니다. messages.tts.providers.<id>만 커밋하십시오.

maxTextLengthnumberdefault: 4096

TTS 입력 문자 수의 최대 한도입니다. 초과하면 /tts audio, tts.convert, tts.speak이 실패합니다.

timeoutMsnumberdefault: 30000

요청 제한 시간(밀리초)입니다. 호출별 timeoutMs(에이전트 도구, Gateway)이 설정된 경우 해당 값이 우선하며, 그렇지 않으면 명시적으로 구성된 messages.tts.timeoutMs이 Plugin에서 지정한 제공자 기본값보다 우선합니다.

prefsPathstring

로컬 환경설정 JSON 경로(제공자/제한/요약)를 재정의합니다. 기본값은 ~/.openclaw/settings/tts.json입니다.

Azure Speech

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 환경 변수: AZURE_SPEECH_KEY, AZURE_SPEECH_API_KEY 또는 SPEECH_KEY. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InJlZ2lvbiIgdHlwZT0ic3RyaW5nIg Azure Speech 지역(예: eastus)입니다. 환경 변수: AZURE_SPEECH_REGION 또는 SPEECH_REGION. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImVuZHBvaW50IiB0eXBlPSJzdHJpbmci 선택적 Azure Speech 엔드포인트 재정의입니다(별칭: baseUrl). OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWFrZXJWb2ljZSIgdHlwZT0ic3RyaW5nIg Azure 음성 ShortName입니다. 기본값은 en-US-JennyNeural입니다. 레거시 별칭: voice. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImxhbmciIHR5cGU9InN0cmluZyI SSML 언어 코드입니다. 기본값은 en-US입니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im91dHB1dEZvcm1hdCIgdHlwZT0ic3RyaW5nIg 표준 오디오용 Azure X-Microsoft-OutputFormat입니다. 기본값은 audio-24khz-48kbitrate-mono-mp3입니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlTm90ZU91dHB1dEZvcm1hdCIgdHlwZT0ic3RyaW5nIg 음성 메모 출력용 Azure X-Microsoft-OutputFormat입니다. 기본값은 ogg-24khz-16bit-mono-opus입니다. OPENCLAW_DOCS_MARKER:paramClose:

ElevenLabs

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg ELEVENLABS_API_KEY 또는 XI_API_KEY을 대체 값으로 사용합니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsIiB0eXBlPSJzdHJpbmci 모델 ID입니다. 기본값은 eleven_multilingual_v2입니다. 레거시 ID eleven_turbo_v2_5/eleven_turbo_v2은 일치하는 flash 모델로 정규화됩니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWFrZXJWb2ljZUlkIiB0eXBlPSJzdHJpbmci ElevenLabs 음성 ID입니다. 기본값은 pMsXgVXv3BLzUgSXRplE입니다. 레거시 별칭: voiceId. OPENCLAW_DOCS_MARKER:paramClose:

voiceSettingsobject

stability, similarityBoost, style(각각 0..1, 기본값 0.5/0.75/0), useSpeakerBoost(true|false, 기본값 true), speed(0.5..2.0, 기본값 1.0).

applyTextNormalization"auto" | "on" | "off"

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Imxhbmd1YWdlQ29kZSIgdHlwZT0ic3RyaW5nIg 2자리 ISO 639-1 코드(예: en, de)입니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNlZWQiIHR5cGU9Im51bWJlciI 최선의 결정성을 위한 정수 0..4294967295입니다. OPENCLAW_DOCS_MARKER:paramClose:

baseUrlstring

Google Gemini

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg GEMINI_API_KEY / GOOGLE_API_KEY을 대체 값으로 사용합니다. 생략하면 환경 변수 대체 값을 사용하기 전에 TTS에서 models.providers.google.apiKey을 재사용할 수 있습니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsIiB0eXBlPSJzdHJpbmci Gemini TTS 모델입니다. 기본값은 gemini-3.1-flash-tts-preview입니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWFrZXJWb2ljZSIgdHlwZT0ic3RyaW5nIg Gemini 사전 구축 음성 이름입니다. 기본값은 Kore입니다. 레거시 별칭: voiceName, voice. OPENCLAW_DOCS_MARKER:paramClose:

audioProfilestring

speakerNamestring

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InByb21wdFRlbXBsYXRlIiB0eXBlPSciYXVkaW8tcHJvZmlsZS12MSIn 활성 페르소나 프롬프트 필드를 결정론적 Gemini TTS 프롬프트 구조로 래핑하려면 audio-profile-v1로 설정합니다. OPENCLAW_DOCS_MARKER:paramClose:

personaPromptstring

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI https://generativelanguage.googleapis.com만 허용됩니다. OPENCLAW_DOCS_MARKER:paramClose:

Gradium

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 환경 변수: GRADIUM_API_KEY. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI api.gradium.ai의 HTTPS Gradium API URL입니다. 기본값은 https://api.gradium.ai입니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWFrZXJWb2ljZUlkIiB0eXBlPSJzdHJpbmci 기본값은 Emma(YTpq7expH9539ERJ)입니다. 레거시 별칭: voiceId. OPENCLAW_DOCS_MARKER:paramClose:

Inworld

Inworld 기본 설정

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 환경 변수: INWORLD_API_KEY. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 기본값은 https://api.inworld.ai입니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsSWQiIHR5cGU9InN0cmluZyI 기본값은 inworld-tts-1.5-max입니다. 추가 지원: inworld-tts-1.5-mini, inworld-tts-1-max, inworld-tts-1. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWFrZXJWb2ljZUlkIiB0eXBlPSJzdHJpbmci 기본값은 Sarah입니다. 레거시 별칭: voiceId. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InRlbXBlcmF0dXJlIiB0eXBlPSJudW1iZXIi 샘플링 온도 0..2(0 제외)입니다. OPENCLAW_DOCS_MARKER:paramClose:

로컬 CLI (tts-local-cli)

commandstring

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFyZ3MiIHR5cGU9InN0cmluZ1tdIg 명령 인수입니다. {{Text}}, {{OutputPath}}, {{OutputDir}}, {{OutputBase}} 플레이스홀더를 지원합니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im91dHB1dEZvcm1hdCIgdHlwZT0nIm1wMyIgfCAib3B1cyIgfCAid2F2Iic 예상되는 CLI 출력 형식입니다. 오디오 첨부 파일의 기본값은 mp3입니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InRpbWVvdXRNcyIgdHlwZT0ibnVtYmVyIg 명령 제한 시간(밀리초)입니다. 기본값은 120000입니다. OPENCLAW_DOCS_MARKER:paramClose:

cwdstring

envRecord<string, string��-��W\��4

명령의 stdout과 생성되거나 변환된 오디오는 50 MiB로 제한됩니다. 진단용 stderr는 1 MiB로 제한됩니다. 어느 한도든 초과하면 OpenClaw가 명령을 종료하고 음성 합성을 실패 처리합니다.

Microsoft (API 키 불필요)

enabledbooleandefault: true

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWFrZXJWb2ljZSIgdHlwZT0ic3RyaW5nIg Microsoft 신경망 음성 이름입니다(예: en-US-MichelleNeural). 레거시 별칭: voice. 기본 영어 음성이 적용 중이고 답변 텍스트에서 CJK 문자가 주를 이루면 OpenClaw가 자동으로 zh-CN-XiaoxiaoNeural로 전환합니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImxhbmciIHR5cGU9InN0cmluZyI 언어 코드입니다(예: en-US). OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im91dHB1dEZvcm1hdCIgdHlwZT0ic3RyaW5nIg Microsoft 출력 형식입니다. 기본값은 audio-24khz-48kbitrate-mono-mp3입니다. 번들로 제공되는 Edge 기반 전송 계층에서 모든 형식을 지원하는 것은 아닙니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InJhdGUgLyBwaXRjaCAvIHZvbHVtZSIgdHlwZT0ic3RyaW5nIg 백분율 문자열입니다(예: +10%, -5%). OPENCLAW_DOCS_MARKER:paramClose:

saveSubtitlesboolean

proxystring

timeoutMsnumber

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImVkZ2UuKiIgdHlwZT0ib2JqZWN0IiBkZXByZWNhdGVk 레거시 별칭입니다. 영구 저장된 구성을 providers.microsoft로 다시 작성하려면 openclaw doctor --fix을 실행하십시오. OPENCLAW_DOCS_MARKER:paramClose:

MiniMax

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg MINIMAX_API_KEY을 대체 값으로 사용합니다. MINIMAX_OAUTH_TOKEN, MINIMAX_CODE_PLAN_KEY 또는 MINIMAX_CODING_API_KEY을 통한 Token Plan 인증을 지원합니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 기본값은 https://api.minimax.io입니다. 환경 변수: MINIMAX_API_HOST. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsIiB0eXBlPSJzdHJpbmci 기본값은 speech-2.8-hd입니다. 환경 변수: MINIMAX_TTS_MODEL. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWFrZXJWb2ljZUlkIiB0eXBlPSJzdHJpbmci 기본값은 English_expressive_narrator입니다. 환경 변수: MINIMAX_TTS_VOICE_ID. 레거시 별칭: voiceId. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWVkIiB0eXBlPSJudW1iZXIi 0.5..2.0. 기본값은 1.0입니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvbCIgdHlwZT0ibnVtYmVyIg (0, 10]. 기본값은 1.0입니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InBpdGNoIiB0eXBlPSJudW1iZXIi 정수 -12..12. 기본값은 0입니다. 소수 값은 요청 전에 잘립니다. OPENCLAW_DOCS_MARKER:paramClose:

OpenAI

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg OPENAI_API_KEY을 대체 값으로 사용합니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsIiB0eXBlPSJzdHJpbmci OpenAI TTS 모델 ID입니다. 기본값은 gpt-4o-mini-tts입니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWFrZXJWb2ljZSIgdHlwZT0ic3RyaW5nIg 음성 이름입니다(예: alloy, cedar). 기본값은 coral입니다. 레거시 별칭: voice. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Imluc3RydWN0aW9ucyIgdHlwZT0ic3RyaW5nIg 명시적 OpenAI instructions 필드입니다. 설정하면 페르소나 프롬프트 필드가 자동으로 매핑되지 않습니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImV4dHJhQm9keSAvIGV4dHJhX2JvZHkiIHR5cGU9IlJlY29yZDxzdHJpbmcsIHVua25vd24 ">생성된 OpenAI TTS 필드 다음에 /audio/speech 요청 본문으로 병합되는 추가 JSON 필드입니다. lang과 같은 제공자별 키가 필요한 Kokoro 등의 OpenAI 호환 엔드포인트에 사용하십시오. 안전하지 않은 프로토타입 키는 무시됩니다. OPENCLAW_DOCS_MARKER:paramClose:

baseUrlstring

OpenAI TTS 엔드포인트를 재정의합니다. 확인 순서: 구성 → OPENAI_TTS_BASE_URL → https://api.openai.com/v1. 기본값이 아닌 값은 OpenAI 호환 TTS 엔드포인트로 처리되므로 사용자 지정 모델 및 음성 이름이 허용되며, speed에는 0.25..4.0 범위 검사가 적용되지 않습니다.

OpenRouter

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 환경 변수: OPENROUTER_API_KEY. models.providers.openrouter.apiKey을 재사용할 수 있습니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 기본값은 https://openrouter.ai/api/v1입니다. 레거시 https://openrouter.ai/v1은 정규화됩니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsIiB0eXBlPSJzdHJpbmci 기본값은 hexgrad/kokoro-82m입니다. 별칭: modelId. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWFrZXJWb2ljZSIgdHlwZT0ic3RyaW5nIg 기본값은 af_alloy입니다. 레거시 별칭: voice, voiceId. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InJlc3BvbnNlRm9ybWF0IiB0eXBlPScibXAzIiB8ICJwY20iJw 기본값은 mp3입니다. OPENCLAW_DOCS_MARKER:paramClose:

speednumber

Volcengine (BytePlus Seed Speech)

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 환경 변수: VOLCENGINE_TTS_API_KEY 또는 BYTEPLUS_SEED_SPEECH_API_KEY. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InJlc291cmNlSWQiIHR5cGU9InN0cmluZyI 기본값은 seed-tts-1.0입니다. 환경 변수: VOLCENGINE_TTS_RESOURCE_ID. 프로젝트에 TTS 2.0 사용 권한이 있으면 seed-tts-2.0을 사용하십시오. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwcEtleSIgdHlwZT0ic3RyaW5nIg 앱 키 헤더입니다. 기본값은 aGjiRDfUWi입니다. 환경 변수: VOLCENGINE_TTS_APP_KEY. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI Seed Speech TTS HTTP 엔드포인트를 재정의합니다. 환경 변수: VOLCENGINE_TTS_BASE_URL. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWFrZXJWb2ljZSIgdHlwZT0ic3RyaW5nIg 음성 유형입니다. 기본값은 en_female_anna_mars_bigtts입니다. 환경 변수: VOLCENGINE_TTS_VOICE. 레거시 별칭: voice. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWVkUmF0aW8iIHR5cGU9Im51bWJlciI 제공자 네이티브 속도 비율 0.2..3입니다. OPENCLAW_DOCS_MARKER:paramClose:

emotionstring

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwcElkIC8gdG9rZW4gLyBjbHVzdGVyIiB0eXBlPSJzdHJpbmciIGRlcHJlY2F0ZWQ 레거시 Volcengine Speech Console 필드입니다. 환경 변수: VOLCENGINE_TTS_APPID, VOLCENGINE_TTS_TOKEN, VOLCENGINE_TTS_CLUSTER(기본값 volcano_tts). OPENCLAW_DOCS_MARKER:paramClose:

xAI

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 환경 변수: XAI_API_KEY. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 기본값은 https://api.x.ai/v1입니다. 환경 변수: XAI_BASE_URL. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWFrZXJWb2ljZUlkIiB0eXBlPSJzdHJpbmci 기본값은 eve입니다. 인증이 있으면 openclaw infer tts voices --provider xai이 현재 내장 카탈로그를 가져오며, 인증이 없으면 오프라인 대체 항목인 ara, eve, leo, rex, sal을 나열합니다. 계정의 사용자 지정 음성 ID는 내장 목록에 없더라도 전달됩니다. 레거시 별칭: voiceId. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Imxhbmd1YWdlIiB0eXBlPSJzdHJpbmci BCP-47 언어 코드 또는 auto입니다. 기본값은 en입니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InJlc3BvbnNlRm9ybWF0IiB0eXBlPScibXAzIiB8ICJ3YXYiIHwgInBjbSIgfCAibXVsYXciIHwgImFsYXciJw 기본값은 mp3입니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWVkIiB0eXBlPSJudW1iZXIi 제공자 네이티브 속도 재정의 0.7..1.5입니다. OPENCLAW_DOCS_MARKER:paramClose:

Xiaomi MiMo

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 환경 변수: XIAOMI_API_KEY. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 기본값은 https://api.xiaomimimo.com/v1입니다. 환경 변수: XIAOMI_BASE_URL. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsIiB0eXBlPSJzdHJpbmci 기본값은 mimo-v2.5-tts입니다. 환경 변수: XIAOMI_TTS_MODEL. mimo-v2-tts 및 mimo-v2.5-tts-voicedesign도 지원합니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWFrZXJWb2ljZSIgdHlwZT0ic3RyaW5nIg 프리셋 음성 모델의 기본값은 mimo_default입니다. 환경 변수: XIAOMI_TTS_VOICE. 레거시 별칭: voice. mimo-v2.5-tts-voicedesign에는 전송되지 않습니다. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImZvcm1hdCIgdHlwZT0nIm1wMyIgfCAid2F2Iic 기본값은 mp3입니다. 환경 변수: XIAOMI_TTS_FORMAT. OPENCLAW_DOCS_MARKER:paramClose:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InN0eWxlIiB0eXBlPSJzdHJpbmci 사용자 메시지로 전송되지만 발화되지 않는 선택적 자연어 스타일 지침입니다. mimo-v2.5-tts-voicedesign에서는 음성 설계 프롬프트이며, 생략하면 OpenClaw가 기본값을 제공합니다. OPENCLAW_DOCS_MARKER:paramClose:

에이전트 도구

tts 도구는 텍스트를 음성으로 변환하고 답변 전달을 위한 오디오 첨부 파일을 반환합니다. Feishu, Matrix, Telegram 및 WhatsApp에서는 오디오가 파일 첨부가 아닌 음성 메시지로 전달됩니다. 이 경로에서 ffmpeg을 사용할 수 있으면 Feishu와 WhatsApp이 Opus가 아닌 TTS 출력을 트랜스코딩할 수 있습니다.

WhatsApp은 Baileys를 통해 오디오를 PTT 음성 메모(ptt: true이 적용된 audio)로 전송하며, 클라이언트가 음성 메모의 캡션을 일관되게 렌더링하지 않으므로 표시되는 텍스트를 PTT 오디오와 별도로 전송합니다.

이 도구는 선택적 channel 및 timeoutMs 필드를 허용하며, timeoutMs은 호출별 제공자 요청 제한 시간(밀리초)입니다. 호출별 값은 messages.tts.timeoutMs을 재정의하며, 구성된 TTS 제한 시간은 Plugin이 작성한 모든 제공자 기본값을 재정의합니다.

Gateway RPC

메서드	용도
`tts.status`	현재 TTS 상태와 마지막 시도 정보를 읽습니다.
`tts.enable`	로컬 자동 설정을 `always`(으)로 지정합니다.
`tts.disable`	로컬 자동 설정을 `off`(으)로 지정합니다.
`tts.convert`	일회성 텍스트 → 오디오 변환입니다.
`tts.setProvider`	로컬 제공자 설정을 지정합니다.
`tts.personas`	구성된 페르소나와 현재 활성화된 페르소나를 나열합니다.
`tts.setPersona`	로컬 페르소나 설정을 지정합니다.
`tts.providers`	구성된 제공자와 상태를 나열합니다.

빠른 시작

제공자 선택

API 키 설정

구성에서 활성화

채팅에서 사용해 보기

지원되는 제공자

구성

Azure Speech

ElevenLabs

Google Gemini

Gradium

Inworld

로컬 CLI

Microsoft(키 없음)

MiniMax

OpenAI + ElevenLabs

OpenRouter

Volcengine

xAI

Xiaomi MiMo

에이전트별 음성 재정의

페르소나

최소 페르소나

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

페르소나 결정

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

대체 정책

모델 기반 지시문

슬래시 명령어

사용자별 기본 설정

출력 형식

자동 TTS 동작

필드 참조

Inworld 기본 설정

에이전트 도구

Gateway RPC

서비스 링크

관련 항목

On this page