OpenClaw语音合成与TTS功能配置

前言

文字并非 AI 交互的唯一形式。OpenClaw 内置了语音合成（Text-to-Speech, TTS）支持，让你的 AI Agent 能够以语音消息的形式回复用户。无论是在 Telegram 上发送语音条，还是在 Discord 的语音频道中朗读回复，OpenClaw 都能通过简单的配置实现。

本文将详细介绍 TTS 功能的配置方法、支持的引擎以及高级用法。

启用 TTS 功能

基本配置

在 openclaw.json5 中启用 TTS：

{
  agents: {
    "my-agent": {
      tts: {
        enabled: true,
        // TTS 引擎
        engine: "openai",
        // 默认语音
        voice: "alloy",
        // 音频格式
        format: "opus",  // opus / mp3 / aac / flac
        // 语速（0.5-2.0）
        speed: 1.0
      }
    }
  }
}

支持的 TTS 引擎

引擎	特点	配置要求
`openai`	高质量、多语言、低延迟	需要 OpenAI API Key
`azure`	企业级、超多语音选择	需要 Azure Speech 订阅
`elevenlabs`	极其自然、支持克隆	需要 ElevenLabs API Key
`edge`	免费、质量不错	无需额外配置
`local`	离线运行、隐私优先	需安装 piper 或 espeak

各引擎配置示例

OpenAI TTS

{
  tts: {
    engine: "openai",
    voice: "nova",       // alloy, echo, fable, onyx, nova, shimmer
    model: "tts-1-hd",  // tts-1 (快速) 或 tts-1-hd (高质量)
    apiKey: "${OPENAI_API_KEY}"
  }
}

Azure TTS

{
  tts: {
    engine: "azure",
    voice: "zh-CN-XiaoxiaoNeural",  // 中文女声
    region: "eastasia",
    subscriptionKey: "${AZURE_SPEECH_KEY}",
    // 可选：SSML高级控制
    ssml: {
      rate: "medium",
      pitch: "default"
    }
  }
}

ElevenLabs TTS

{
  tts: {
    engine: "elevenlabs",
    voiceId: "21m00Tcm4TlvDq8ikWAM",
    apiKey: "${ELEVENLABS_API_KEY}",
    // 语音参数调节
    stability: 0.5,
    similarityBoost: 0.75
  }
}

Edge TTS（免费）

{
  tts: {
    engine: "edge",
    voice: "zh-CN-YunxiNeural",  // 中文男声
    // 无需API Key
  }
}

语音回复模式

OpenClaw 支持三种语音回复模式：

1. 仅语音模式

AI 只发送语音消息，不发送文字：

{
  tts: {
    enabled: true,
    mode: "voice_only"
  }
}

2. 语音 + 文字模式

同时发送语音和文字消息：

{
  tts: {
    enabled: true,
    mode: "voice_and_text"
  }
}

3. 按需触发模式（推荐）

默认发送文字，用户可以通过指令请求语音：

{
  tts: {
    enabled: true,
    mode: "on_demand",
    // 触发语音的关键词
    triggerWords: ["语音回复", "读给我听", "voice"]
  }
}

用户使用方式：

用户：voice 今天的天气怎么样？
AI：[发送语音消息] 今天北京晴，气温15到25度...

Voice 指令系统

OpenClaw 提供了一套 /voice 指令，让用户在聊天中灵活控制语音功能：

/voice on          - 开启语音回复
/voice off         - 关闭语音回复
/voice mode <模式> - 切换模式（voice_only / voice_and_text / on_demand）
/voice speed 1.5   - 调整语速
/voice lang zh     - 设置语音语言
/voice list        - 列出可用语音
/voice set <name>  - 切换语音角色

配置 Voice 指令

{
  agents: {
    "my-agent": {
      commands: {
        voice: {
          enabled: true,
          // 允许用户调整的选项
          allowUserControl: {
            speed: true,
            voice: true,
            mode: true,
            language: true
          }
        }
      }
    }
  }
}

语音输入识别（STT）

OpenClaw 不仅支持语音输出，还支持语音输入识别。当用户发送语音消息时，OpenClaw 可以自动将其转换为文字：

{
  agents: {
    "my-agent": {
      stt: {
        enabled: true,
        engine: "openai",  // 使用 Whisper 模型
        model: "whisper-1",
        language: "zh",    // 优先识别的语言
        // 识别后是否显示转写文本
        showTranscription: true
      }
    }
  }
}

完整的语音对话流程：

用户 → [发送语音消息] → OpenClaw STT → 转写为文字 → AI 处理
                                                        ↓
用户 ← [收到语音回复] ← OpenClaw TTS ← 文字回复 ← AI 生成

平台适配

不同聊天平台对语音消息的支持程度不同：

平台	语音发送	语音接收(STT)	最大时长	格式
Telegram	支持	支持	60分钟	OGG/Opus
Discord	支持	支持	不限	Opus
WhatsApp	支持	支持	不限	OGG/Opus
Slack	部分支持	支持	不限	MP3
WeChat	支持	支持	60秒	AMR/Silk
WebChat	支持	支持	不限	MP3/WAV

OpenClaw 会自动根据目标平台选择最佳的音频格式和编码参数。

微信特殊处理

微信的语音消息有 60 秒限制，OpenClaw 会自动处理：

{
  tts: {
    platformOverrides: {
      wechat: {
        // 超过60秒时自动分割为多条语音
        autoSplit: true,
        // 或者超长内容降级为文字
        fallbackToText: true,
        maxDuration: 55  // 留5秒缓冲
      }
    }
  }
}

音频缓存

为了减少 TTS API 调用和降低延迟，OpenClaw 支持音频缓存：

{
  tts: {
    cache: {
      enabled: true,
      // 缓存目录
      dir: "./cache/tts",
      // 缓存过期时间（秒）
      ttl: 86400,  // 24小时
      // 最大缓存大小（MB）
      maxSize: 500
    }
  }
}

缓存策略：相同文本 + 相同语音配置 = 命中缓存，直接返回已生成的音频文件，跳过 TTS API 调用。

高级：SSML 标记

对于需要精确控制语音效果的场景，可以在系统提示词中指导 AI 使用 SSML 标记：

{
  tts: {
    engine: "azure",
    ssmlEnabled: true
  }
}

AI 可以在回复中嵌入 SSML 指令：

<speak>
  <prosody rate="slow" pitch="+2st">
    这段话会用较慢的速度和较高的音调朗读。
  </prosody>
  <break time="500ms"/>
  <emphasis level="strong">重点内容</emphasis>会被强调。
</speak>

成本优化

TTS 服务按字符数计费，以下是一些优化建议：

启用缓存：避免重复生成相同内容的音频
使用按需模式：不是每条消息都需要语音
限制语音长度：对超长回复自动降级为文字
选择合适的引擎：Edge TTS 免费但质量稍低，OpenAI TTS 收费但质量高

{
  tts: {
    // 超过500字符的回复不生成语音
    maxChars: 500,
    // 超限时的降级策略
    fallback: "text_with_summary_voice"
    // 先发文字全文，再发语音摘要
  }
}

小结

OpenClaw 的语音功能让 AI Agent 突破了纯文字交互的限制。通过灵活的 TTS 引擎选择、多种回复模式、Voice 指令系统以及语音输入识别，你可以构建出真正支持语音对话的 AI 助手。结合平台适配和缓存优化，语音功能可以在保证体验的同时控制成本。