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: "알프레드",          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입니다. /tts는 Discord 기본 제공 명령어이므로 OpenClaw는 Discord에서 /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를 사용하며, responseFormat은 mp3, wav, pcm, mulaw 또는 alaw일 수 있습니다. 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로 다시 시도합니다.
- 명시적인 음성 재정의가 설정되지 않고 기본 영어 음성을 사용하는 경우, 응답 텍스트에서 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

명령의 표준 출력과 생성 또는 변환된 오디오는 50 MiB로 제한됩니다. 진단용 표준 오류는 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 레거시 별칭입니다. openclaw doctor --fix를 실행하여 저장된 구성을 providers.microsoft로 다시 작성하십시오. OPENCLAW_DOCS_MARKER:paramClose:

MiniMax

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 설정되지 않은 경우 MINIMAX_API_KEY를 사용합니다. Token Plan 인증에는 MINIMAX_OAUTH_TOKEN, MINIMAX_CODE_PLAN_KEY 또는 MINIMAX_CODING_API_KEY를 사용합니다. 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