Tools

텍스트 음성 변환

OpenClaw는 아웃바운드 답장을 14개 음성 제공자를 통해 오디오로 변환하고, Feishu, Matrix, Telegram, WhatsApp에서는 네이티브 음성 메시지로, 그 외 모든 곳에서는 오디오 첨부 파일로, 텔레포니와 Talk에는 PCM/Ulaw 스트림으로 전달할 수 있습니다.

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

빠른 시작

  • 제공자 선택

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

  • API 키 설정

    제공자의 환경 변수를 내보내세요(예: OPENAI_API_KEY, ELEVENLABS_API_KEY). Microsoft와 Local CLI에는 키가 필요 없습니다.

  • 설정에서 활성화

    messages.tts.auto: "always"messages.tts.provider를 설정하세요.

    {
      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를 통한 결정적 출력.
    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 텔레포니.
    Local CLI 없음 설정된 로컬 TTS 명령을 실행합니다.
    Microsoft 없음 node-edge-tts를 통한 공개 Edge 신경망 TTS. 최선 노력 기반, SLA 없음.
    MiniMax MINIMAX_API_KEY (또는 Token Plan: 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/token: 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.jsonmessages.tts 아래에 있습니다. 프리셋을 선택하고 제공자 블록을 조정하세요.

    Azure Speech

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

    ElevenLabs

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

    Google Gemini

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

    Gradium

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

    Inworld

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

    Local CLI

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

    Microsoft(키 없음)

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

    MiniMax

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

    OpenAI + ElevenLabs

    {
    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",
          voice: "alloy",
        },
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          voiceId: "EXAVITQu4vr4xnSDxMaL",
          voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },
          applyTextNormalization: "auto",
          languageCode: "en",
        },
      },
    },
    },
    }
    

    OpenRouter

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

    Volcengine

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

    xAI

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

    Xiaomi MiMo

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

    에이전트별 음성 재정의

    하나의 에이전트가 다른 제공자, 음성, 모델, 페르소나 또는 Auto-TTS 모드로 말해야 할 때 agents.list[].tts를 사용하세요. 에이전트 블록은 messages.tts 위에 딥 병합되므로 제공자 자격 증명은 전역 제공자 설정에 유지할 수 있습니다.

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

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

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

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

    채널 및 계정 재정의는 messages.tts와 같은 형태를 사용하며 이전 계층 위에 깊게 병합되므로, 공유 공급자 자격 증명은 messages.tts에 유지하면서 채널이나 봇 계정은 음성, 모델, 페르소나 또는 자동 모드만 변경할 수 있습니다.

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

    페르소나

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

    최소 페르소나

    {
      messages: {
        tts: {
          auto: "always",
          persona: "narrator",
          personas: {
            narrator: {
              label: "Narrator",
              provider: "elevenlabs",
              providers: {
                elevenlabs: { voiceId: "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",
                  voiceName: "Algieba",
                  promptTemplate: "audio-profile-v1",
                },
                openai: { model: "gpt-4o-mini-tts", voice: "cedar" },
                elevenlabs: {
                  voiceId: "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. 레지스트리 자동 선택.

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

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

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

    페르소나 프롬프트 필드(profile, scene, sampleContext, style, accent, pacing, constraints)는 공급자 중립입니다. 각 공급자는 이를 어떻게 사용할지 결정합니다.

    Google Gemini

    유효한 Google 공급자 구성이 promptTemplate: "audio-profile-v1" 또는 personaPrompt를 설정한 경우에만 페르소나 프롬프트 필드를 Gemini TTS 프롬프트 구조로 감쌉니다. 이전 audioProfilespeakerName 필드는 여전히 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]] 블록도 함께 사용할 수 있습니다.

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

    messages.tts.auto"tagged"이면 오디오를 트리거하려면 지시문이 필요합니다. 스트리밍 블록 전달은 인접한 블록에 걸쳐 분할된 경우에도 채널이 보기 전에 표시 텍스트에서 지시문을 제거합니다.

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

    사용 가능한 지시문 키:

    • provider(등록된 공급자 ID, allowProvider: true 필요)
    • 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. Discord에서는 /tts가 내장 Discord 명령이므로 OpenClaw가 /voice도 등록합니다. 텍스트 /tts ...는 계속 작동합니다.

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

    사용자별 기본 설정

    슬래시 명령은 로컬 재정의를 prefsPath에 기록합니다. 기본값은 ~/.openclaw/settings/tts.json입니다. OPENCLAW_TTS_PREFS env var 또는 messages.tts.prefsPath로 재정의할 수 있습니다.

    저장된 필드 효과
    auto 로컬 자동 TTS 재정의(always, off, …)
    provider 로컬 기본 공급자 재정의
    persona 로컬 페르소나 재정의
    maxLength 요약 임계값(기본값 1500자)
    summarize 요약 토글(기본값 true)

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

    출력 형식(고정)

    TTS 음성 전달은 채널 기능에 의해 결정됩니다. 채널 Plugin은 음성 스타일 TTS가 공급자에게 네이티브 voice-note 대상을 요청해야 하는지, 아니면 일반 audio-file 합성을 유지하고 호환되는 출력만 음성 전달용으로 표시해야 하는지를 알립니다.

    • 음성 메모 지원 채널: 음성 메모 답장은 Opus(ElevenLabs의 opus_48000_64, OpenAI의 opus)를 우선 사용합니다.
      • 48kHz / 64kbps는 음성 메시지에 적절한 절충값입니다.
    • Feishu / WhatsApp: 음성 메모 답장이 MP3/WebM/WAV/M4A 또는 다른 오디오 파일로 추정되는 형식으로 생성되면, 채널 Plugin은 네이티브 음성 메시지를 보내기 전에 ffmpeg로 48kHz Ogg/Opus로 트랜스코딩합니다. WhatsApp은 결과를 Baileys audio 페이로드를 통해 ptt: trueaudio/ogg; codecs=opus로 보냅니다. 변환에 실패하면 Feishu는 원본 파일을 첨부 파일로 받으며, WhatsApp 전송은 호환되지 않는 PTT 페이로드를 게시하는 대신 실패합니다.
    • BlueBubbles: 제공자 합성은 일반 오디오 파일 경로에 유지합니다. MP3 및 CAF 출력은 iMessage 음성 메모 전달용으로 표시됩니다.
    • 기타 채널: MP3(ElevenLabs의 mp3_44100_128, OpenAI의 mp3).
      • 44.1kHz / 128kbps는 음성 명료도를 위한 기본 균형값입니다.
    • MiniMax: 일반 오디오 첨부 파일에는 MP3(speech-2.8-hd 모델, 32kHz 샘플레이트)를 사용합니다. 채널이 알린 음성 메모 대상의 경우, 채널이 트랜스코딩을 알리면 OpenClaw는 전달 전에 MiniMax MP3를 ffmpeg로 48kHz Opus로 트랜스코딩합니다.
    • Xiaomi MiMo: 기본적으로 MP3를 사용하거나, 구성된 경우 WAV를 사용합니다. 채널이 알린 음성 메모 대상의 경우, 채널이 트랜스코딩을 알리면 OpenClaw는 전달 전에 Xiaomi 출력을 ffmpeg로 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를 사용합니다. responseFormatmp3, 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로 다시 시도합니다.

    OpenAI/ElevenLabs 출력 형식은 채널별로 고정되어 있습니다(위 참조).

    Auto-TTS 동작

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

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

    답장이 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 -> TTS -> attach audio
    

    채널별 출력 형식

    대상 형식
    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로 48 kHz Ogg/Opus로 트랜스코딩합니다. WhatsApp은 Baileys를 통해 ptt: trueaudio/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이며, responseFormatmp3|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로 재시도합니다.

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

    필드 참조

    최상위 messages.tts.*
    auto"off" | "always" | "inbound" | "tagged"

    자동 TTS 모드입니다. inbound는 인바운드 음성 메시지 이후에만 오디오를 보내고, tagged는 답장에 [[tts:...]] 지시문 또는 [[tts:text]] 블록이 포함된 경우에만 오디오를 보냅니다.

    enabledboolean

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

    mode"final" | "all"

    "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>만 커밋하세요.

    maxTextLengthnumber

    TTS 입력 문자에 대한 엄격한 상한입니다. 초과하면 /tts audio가 실패합니다.

    timeoutMsnumber

    요청 시간 제한(밀리초)입니다.

    prefsPathstring

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

    Azure Speech

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg Env: AZURE_SPEECH_KEY, AZURE_SPEECH_API_KEY 또는 SPEECH_KEY. OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InJlZ2lvbiIgdHlwZT0ic3RyaW5nIg Azure Speech 리전(예: eastus). Env: 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:IHBhdGg9InZvaWNlIiB0eXBlPSJzdHJpbmci Azure 음성 ShortName. 기본값 en-US-JennyNeural. 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, eleven_v3). OPENCLAW_DOCS_MARKER:paramClose:

    voiceIdstring
    voiceSettingsobject

    stability, similarityBoost, style(각각 0..1), useSpeakerBoost(true|false), 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는 env 폴백 전에 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:IHBhdGg9InZvaWNlTmFtZSIgdHlwZT0ic3RyaW5nIg Gemini 사전 구축 음성 이름. 기본값 Kore. 별칭: 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 Env: GRADIUM_API_KEY. OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 기본값 https://api.gradium.ai. OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlSWQiIHR5cGU9InN0cmluZyI 기본값 Emma(YTpq7expH9539ERJ). OPENCLAW_DOCS_MARKER:paramClose:

    Inworld

    Inworld 기본

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg Env: 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:IHBhdGg9InZvaWNlSWQiIHR5cGU9InN0cmluZyI 기본값 Sarah. OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InRlbXBlcmF0dXJlIiB0eXBlPSJudW1iZXIi 샘플링 온도 0..2. 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
    Microsoft (API 키 없음)
    enabledboolean

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlIiB0eXBlPSJzdHJpbmci Microsoft 신경망 음성 이름(예: en-US-MichelleNeural). 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로 대체됩니다. 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. Env: MINIMAX_API_HOST. OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsIiB0eXBlPSJzdHJpbmci 기본값 speech-2.8-hd. Env: MINIMAX_TTS_MODEL. OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlSWQiIHR5cGU9InN0cmluZyI 기본값 English_expressive_narrator. Env: MINIMAX_TTS_VOICE_ID. 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:IHBhdGg9InZvaWNlIiB0eXBlPSJzdHJpbmci 음성 이름(예: alloy, cedar). 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_URLhttps://api.openai.com/v1. 기본값이 아닌 값은 OpenAI 호환 TTS 엔드포인트로 처리되므로 사용자 지정 모델 및 음성 이름이 허용됩니다.

    OpenRouter

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg Env: 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:IHBhdGg9InZvaWNlIiB0eXBlPSJzdHJpbmci 기본값 af_alloy. 별칭: 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 Env: VOLCENGINE_TTS_API_KEY 또는 BYTEPLUS_SEED_SPEECH_API_KEY. OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InJlc291cmNlSWQiIHR5cGU9InN0cmluZyI 기본값 seed-tts-1.0. Env: VOLCENGINE_TTS_RESOURCE_ID. 프로젝트에 TTS 2.0 권한이 있으면 seed-tts-2.0을 사용하세요. OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwcEtleSIgdHlwZT0ic3RyaW5nIg 앱 키 헤더. 기본값 aGjiRDfUWi. Env: VOLCENGINE_TTS_APP_KEY. OPENCLAW_DOCS_MARKER:paramClose:

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

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlIiB0eXBlPSJzdHJpbmci 음성 유형. 기본값 en_female_anna_mars_bigtts. Env: VOLCENGINE_TTS_VOICE. OPENCLAW_DOCS_MARKER:paramClose:

    speedRationumber
    emotionstring

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwcElkIC8gdG9rZW4gLyBjbHVzdGVyIiB0eXBlPSJzdHJpbmciIGRlcHJlY2F0ZWQ 레거시 Volcengine Speech Console 필드. Env: VOLCENGINE_TTS_APPID, VOLCENGINE_TTS_TOKEN, VOLCENGINE_TTS_CLUSTER(기본값 volcano_tts). OPENCLAW_DOCS_MARKER:paramClose:

    xAI

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg Env: XAI_API_KEY. OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 기본값 https://api.x.ai/v1. Env: XAI_BASE_URL. OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlSWQiIHR5cGU9InN0cmluZyI 기본값 eve. 라이브 음성: ara, eve, leo, rex, sal, una. 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:

    speednumber
    Xiaomi MiMo

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg Env: XIAOMI_API_KEY. OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 기본값 https://api.xiaomimimo.com/v1. Env: XIAOMI_BASE_URL. OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsIiB0eXBlPSJzdHJpbmci 기본값 mimo-v2.5-tts. Env: XIAOMI_TTS_MODEL. mimo-v2-tts도 지원합니다. OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlIiB0eXBlPSJzdHJpbmci 기본값 mimo_default. Env: XIAOMI_TTS_VOICE. OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImZvcm1hdCIgdHlwZT0nIm1wMyIgfCAid2F2Iic 기본값 mp3. Env: XIAOMI_TTS_FORMAT. OPENCLAW_DOCS_MARKER:paramClose:

    stylestring

    에이전트 도구

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

    WhatsApp은 Baileys를 통해 오디오를 PTT 음성 노트(ptt: true가 있는 audio)로 보내며, 클라이언트가 음성 노트의 캡션을 일관되게 렌더링하지 않기 때문에 표시되는 텍스트를 PTT 오디오와 별도로 보냅니다.

    이 도구는 선택적 channeltimeoutMs 필드를 받습니다. timeoutMs는 호출별 제공자 요청 시간 제한(밀리초)입니다.

    Gateway RPC

    메서드 목적
    tts.status 현재 TTS 상태와 마지막 시도를 읽습니다.
    tts.enable 로컬 자동 기본 설정을 always로 설정합니다.
    tts.disable 로컬 자동 기본 설정을 off로 설정합니다.
    tts.convert 일회성 텍스트 → 오디오.
    tts.setProvider 로컬 제공자 기본 설정을 설정합니다.
    tts.setPersona 로컬 페르소나 기본 설정을 설정합니다.
    tts.providers 구성된 제공자와 상태를 나열합니다.

    서비스 링크

    관련 항목