Skip to main content

​
Field reference

Provider apiKey fields, including personas.<id>.providers.<provider>.apiKey, can be raw strings or SecretRefs in global, per-agent, and Discord voice TTS config. During cold Gateway startup, an unavailable TTS SecretRef marks the built-in TTS capability configured-unavailable instead of stopping the Gateway. tts.speak then returns UNAVAILABLE with reason SECRET_SURFACE_UNAVAILABLE, and no provider request is sent. Status and doctor list the degraded TTS owner and its config paths. The explicit refs remain in the runtime snapshot, so environment or profile credentials cannot silently select a different account. Reloads and config-write preflight apply the owner-aware degradation policy: an unchanged eligible TTS owner may keep its last-known-good credentials as stale, while a new or changed failure becomes cold without blocking healthy owners. Structurally invalid refs and resolved values still fail startup or reject the update.
​
"off" | "always" | "inbound" | "tagged"
Auto-TTS mode. inbound only sends audio after an inbound voice message; tagged only sends audio when the reply includes [[tts:...]] directives or a [[tts:text]] block.
​
boolean
deprecated
Legacy toggle. openclaw doctor --fix migrates this to auto.
​
"final" | "all"
default:"final"
"all" includes tool/block replies in addition to final replies.
​
string
Speech provider id. When unset, OpenClaw uses the first configured provider in registry auto-select order. Legacy provider: "edge" is rewritten to "microsoft" by openclaw doctor --fix.
​
string
Active persona id from personas. Normalized to lowercase.
​
object
Stable spoken identity. Fields: label, description, provider, fallbackPolicy, providers.<provider>. See Personas.
​
string
Cheap model for auto-summary; defaults to agents.defaults.model.primary. Accepts provider/model or a configured model alias.
​
object
Allow the model to emit TTS directives. enabled defaults to true; allowProvider defaults to false.
​
object
Provider-owned settings keyed by speech provider id. Legacy direct blocks (tts.openai, .elevenlabs, .microsoft, .edge) are rewritten by openclaw doctor --fix; commit only tts.providers.<id>.
​
number
default:"4096"
Hard cap for TTS input characters. /tts audio, tts.convert, and tts.speak fail if exceeded.
​
number
default:"30000"
Request timeout in milliseconds. A per-call timeoutMs (agent tool, gateway) wins when set; otherwise an explicitly configured tts.timeoutMs wins over any plugin-authored provider default.
​
string
Env: AZURE_SPEECH_KEY, AZURE_SPEECH_API_KEY, or SPEECH_KEY.
​
string
Azure Speech region (e.g. eastus). Env: AZURE_SPEECH_REGION or SPEECH_REGION.
​
string
Optional Azure Speech endpoint override (alias baseUrl).
​
string
Azure voice ShortName. Default en-US-JennyNeural. Legacy alias: voice.
​
string
SSML language code. Default en-US.
​
string
Azure X-Microsoft-OutputFormat for standard audio. Default audio-24khz-48kbitrate-mono-mp3.
​
string
Azure X-Microsoft-OutputFormat for voice-note output. Default ogg-24khz-16bit-mono-opus.
​
string
Falls back to ELEVENLABS_API_KEY or XI_API_KEY.
​
string
Model id. Default eleven_multilingual_v2. Legacy ids eleven_turbo_v2_5/eleven_turbo_v2 are normalized to the matching flash model.
​
string
ElevenLabs voice id. Default pMsXgVXv3BLzUgSXRplE. Legacy alias: voiceId.
​
object
stability, similarityBoost, style (each 0..1, defaults 0.5/0.75/0), useSpeakerBoost (true|false, default true), speed (0.5..2.0, default 1.0).
​
"auto" | "on" | "off"
Text normalization mode.
​
string
2-letter ISO 639-1 (e.g. en, de).
​
number
Integer 0..4294967295 for best-effort determinism.
​
string
Override ElevenLabs API base URL.
​
string
Falls back to GEMINI_API_KEY / GOOGLE_API_KEY. If omitted, TTS can reuse models.providers.google.apiKey before env fallback.
​
string
Gemini TTS model. Default gemini-3.1-flash-tts-preview.
​
string
Gemini prebuilt voice name. Default Kore. Legacy aliases: voiceName, voice.
​
string
Natural-language style prompt prepended before spoken text.
​
string
Optional speaker label prepended before spoken text when your prompt uses a named speaker.
​
"audio-profile-v1"
Set to audio-profile-v1 to wrap active persona prompt fields in a deterministic Gemini TTS prompt structure.
​
string
Google-specific extra persona prompt text appended to the template’s Director’s Notes.
​
string
Only https://generativelanguage.googleapis.com is accepted.
​
string
Env: GRADIUM_API_KEY.
​
string
HTTPS Gradium API URL on api.gradium.ai. Default https://api.gradium.ai.
​
string
Default Emma (YTpq7expH9539ERJ). Legacy alias: voiceId.
​
string
Env: INWORLD_API_KEY.
​
string
Default https://api.inworld.ai.
​
string
Default inworld-tts-1.5-max. Also: inworld-tts-1.5-mini, inworld-tts-1-max, inworld-tts-1.
​
string
Default Sarah. Legacy alias: voiceId.
​
number
Sampling temperature 0..2 (exclusive of 0).
​
string
Local executable or command string for CLI TTS.
​
string[]
Command arguments. Supports {{Text}}, {{OutputPath}}, {{OutputDir}}, {{OutputBase}} placeholders.
​
"mp3" | "opus" | "wav"
Expected CLI output format. Default mp3 for audio attachments.
​
number
Command timeout in milliseconds. Overrides the resolved TTS request timeout when set. When omitted, follows the request timeout; the plugin default is 120000.
​
string
Optional command working directory.
​
Record<string, string>
Optional environment overrides for the command.
Command stdout and generated or converted audio are limited to 50 MiB. Diagnostic stderr is limited to 1 MiB. OpenClaw terminates the command and fails synthesis when either limit is exceeded.
​
boolean
default:"true"
Allow Microsoft speech usage.
​
string
Microsoft neural voice name (e.g. en-US-MichelleNeural). Legacy alias: voice. If the default English voice is in effect and reply text is CJK-dominant, OpenClaw auto-switches to zh-CN-XiaoxiaoNeural.
​
string
Language code (e.g. en-US).
​
string
Microsoft output format. Default audio-24khz-48kbitrate-mono-mp3. Not all formats are supported by the bundled Edge-backed transport.
​
string
Percent strings (e.g. +10%, -5%).
​
boolean
Write JSON subtitles alongside the audio file.
​
string
Proxy URL for Microsoft speech requests.
​
number
Request timeout override (ms).
​
object
deprecated
Legacy alias. Run openclaw doctor --fix to rewrite persisted config to providers.microsoft.
​
string
Falls back to MINIMAX_API_KEY. Token Plan auth via MINIMAX_OAUTH_TOKEN, MINIMAX_CODE_PLAN_KEY, or MINIMAX_CODING_API_KEY.
​
string
Default https://api.minimax.io. Env: MINIMAX_API_HOST.
​
string
Default speech-2.8-hd. Env: MINIMAX_TTS_MODEL.
​
string
Default English_expressive_narrator. Env: MINIMAX_TTS_VOICE_ID. Legacy alias: voiceId.
​
number
0.5..2.0. Default 1.0.
​
number
(0, 10]. Default 1.0.
​
number
Integer -12..12. Default 0. Fractional values are truncated before the request.
​
string
Falls back to OPENAI_API_KEY.
​
string
OpenAI TTS model id. Default gpt-4o-mini-tts.
​
string
Voice name (e.g. alloy, cedar). Default coral. Legacy alias: voice.
​
string
Explicit OpenAI instructions field. When set, persona prompt fields are not auto-mapped.
​
"mp3" | "opus" | "wav"
Explicit response format. When omitted, OpenClaw selects Opus for voice-note targets and MP3 otherwise. Use wav for compatible local endpoints that do not encode compressed audio.
​
Record<string, unknown>
Extra JSON fields merged into /audio/speech request bodies after generated OpenAI TTS fields. Use this for OpenAI-compatible endpoints such as Kokoro that require provider-specific keys like lang; unsafe prototype keys are ignored.
​
string
Override the OpenAI TTS endpoint. Resolution order: config → OPENAI_TTS_BASE_URL → https://api.openai.com/v1. Non-default values are treated as OpenAI-compatible TTS endpoints, so custom model and voice names are accepted, and speed loses its 0.25..4.0 range check.
​
string
Env: OPENROUTER_API_KEY. Can reuse models.providers.openrouter.apiKey.
​
string
Default https://openrouter.ai/api/v1. Legacy https://openrouter.ai/v1 is normalized.
​
string
Default hexgrad/kokoro-82m. Alias: modelId.
​
string
Default af_alloy. Legacy aliases: voice, voiceId.
​
"mp3" | "pcm"
Default mp3.
​
number
Provider-native speed override.
​
string
Env: VOLCENGINE_TTS_API_KEY or BYTEPLUS_SEED_SPEECH_API_KEY.
​
string
Default seed-tts-1.0. Env: VOLCENGINE_TTS_RESOURCE_ID. Use seed-tts-2.0 when your project has TTS 2.0 entitlement.
​
string
App key header. Default aGjiRDfUWi. Env: VOLCENGINE_TTS_APP_KEY.
​
string
Override the Seed Speech TTS HTTP endpoint. Env: VOLCENGINE_TTS_BASE_URL.
​
string
Voice type. Default en_female_anna_mars_bigtts. Env: VOLCENGINE_TTS_VOICE. Legacy alias: voice.
​
number
Provider-native speed ratio, 0.2..3.
​
string
Provider-native emotion tag.
​
string
deprecated
Legacy Volcengine Speech Console fields. Env: VOLCENGINE_TTS_APPID, VOLCENGINE_TTS_TOKEN, VOLCENGINE_TTS_CLUSTER (default volcano_tts).
​
string
Env: XAI_API_KEY.
​
string
Default https://api.x.ai/v1. Env: XAI_BASE_URL.
​
string
Default eve. With auth, openclaw infer tts voices --provider xai fetches the current built-in catalog; without auth it lists offline fallbacks ara, eve, leo, rex, and sal. Account custom voice IDs are forwarded even when absent from the built-in list. Legacy alias: voiceId.
​
string
BCP-47 language code or auto. Default en.
​
"mp3" | "wav" | "pcm" | "mulaw" | "alaw"
Default mp3.
​
number
Provider-native speed override, 0.7..1.5.
​
string
Env: XIAOMI_API_KEY.
​
string
Default https://api.xiaomimimo.com/v1. Env: XIAOMI_BASE_URL.
​
string
Default mimo-v2.5-tts. Env: XIAOMI_TTS_MODEL. Also supports mimo-v2.5-tts-voicedesign.
​
string
Default mimo_default for preset-voice models. Env: XIAOMI_TTS_VOICE. Legacy alias: voice. Not sent for mimo-v2.5-tts-voicedesign.
​
"mp3" | "wav"
Default mp3. Env: XIAOMI_TTS_FORMAT.
​
string
Optional natural-language style instruction sent as the user message; not spoken. For mimo-v2.5-tts-voicedesign, this is the voice-design prompt; OpenClaw supplies a default when omitted.