Skip to main content

​
Voice (语音)

OpenClaw 支持语音输入和语音输出(TTS),通过节点(iOS/Android/macOS)或网关集成。

​
概述

  • 语音输入: 麦克风捕获 → 音频转录 → 代理处理文本
  • 语音输出: 代理回复 → TTS 合成 → 音频播放
  • 语音唤醒: 热词检测 → 触发代理回合

​
语音输入 (转录)

​
支持的提供商

OpenClaw 支持多种音频转录提供商:
  • OpenAI Whisper API (推荐)
  • Google Cloud Speech-to-Text
  • AssemblyAI
  • 本地 Whisper (通过 whisper.cpp)

​
配置转录

在 ~/.openclaw/openclaw.json 中: 
{
  tools: {
    media: {
      audio: {
        models: [
          { provider: "openai", model: "whisper-1" },
          { provider: "google", model: "default" }
        ]
      }
    }
  }
}

​
通过频道发送语音

大多数频道(WhatsApp、Telegram、Discord)自动转录语音消息:
  1. 发送语音消息到频道
  2. 网关接收音频文件
  3. 自动转录为文本
  4. 代理处理转录文本
  5. 回复发送回频道

​
语音输出 (TTS)

​
支持的 TTS 提供商

  • ElevenLabs (高质量,多语言)
  • OpenAI TTS (GPT-4 级别语音)
  • Google Cloud Text-to-Speech
  • System TTS (平台原生 TTS)

​
配置 TTS

{
  tools: {
    media: {
      tts: {
        provider: "elevenlabs",
        voice: "21m00Tcm4TlvDq8ikWAM", // ElevenLabs Rachel 语音
        model: "eleven_multilingual_v2"
      }
    }
  }
}

​
ElevenLabs 设置

  1. 获取 API 密钥: ElevenLabs
  2. 设置环境变量:
export ELEVENLABS_API_KEY=<你的密钥>
  1. 配置语音 ID(可选):
{
  tools: {
    media: {
      tts: {
        provider: "elevenlabs",
        voice: "<语音ID>"
      }
    }
  }
}
可用语音列表: 
curl -X GET "https://api.elevenlabs.io/v1/voices" \
  -H "xi-api-key: <你的密钥>"

​
OpenAI TTS 设置

{
  tools: {
    media: {
      tts: {
        provider: "openai",
        voice: "alloy", // alloy, echo, fable, onyx, nova, shimmer
        model: "tts-1-hd"
      }
    }
  }
}

​
语音唤醒

语音唤醒允许你通过说热词来触发代理。

​
macOS 语音唤醒

macOS 应用支持语音唤醒:
  1. 打开 macOS OpenClaw 应用
  2. 启用语音唤醒(设置 → 语音唤醒)
  3. 配置热词(默认: “Hey OpenClaw”)
  4. 说出热词后说出你的请求
配置文件设置: 
{
  voice: {
    wake: {
      enabled: true,
      keyword: "Hey OpenClaw",
      threshold: 0.5
    }
  }
}

​
iOS/Android 语音唤醒

iOS 和 Android 应用也支持语音唤醒(实验性):
  • 打开应用设置
  • 启用语音唤醒
  • 授予麦克风权限
  • 保持应用在前台(后台检测不可靠)

​
对话模式

对话模式支持连续的语音交互:
  1. 代理说话(TTS)
  2. 自动监听你的回复
  3. 转录并处理
  4. 循环继续

​
启用对话模式

在节点应用(iOS/Android/macOS)中:
  • 打开语音设置
  • 启用对话模式
  • 开始对话

​
通过 CLI 使用语音

​
发送语音消息

# 录制并发送语音消息
openclaw message send --channel whatsapp --to "+1234567890" \
  --voice "你好,这是语音消息测试"

​
播放 TTS 音频

# 生成并播放 TTS
openclaw tts --text "你好,世界!" --provider elevenlabs --play

​
故障排查

​
转录失败

  • 检查音频提供商凭据(API 密钥)
  • 确认音频文件格式受支持
  • 检查网关日志: openclaw logs --follow

​
TTS 无输出

  • 验证 TTS 提供商配置
  • 检查 API 密钥是否有效
  • 确认音频设备可用(节点)

​
语音唤醒未响应

  • 确认麦克风权限已授予
  • 调整唤醒词阈值
  • 检查应用是否在前台运行
  • 尝试更清晰地说出热词

​
音频质量差

  • 使用更高质量的 TTS 模型(例如 tts-1-hd)
  • 选择不同的语音
  • 检查网络连接(流式 TTS)

​
高级配置

​
自定义转录模型

{
  tools: {
    media: {
      audio: {
        models: [
          {
            provider: "openai",
            model: "whisper-1",
            language: "zh", // 强制中文
            prompt: "这是一段关于技术的对话" // 提示上下文
          }
        ]
      }
    }
  }
}

​
多语言 TTS

{
  tools: {
    media: {
      tts: {
        provider: "elevenlabs",
        model: "eleven_multilingual_v2",
        voice: "21m00Tcm4TlvDq8ikWAM"
      }
    }
  }
}

​
相关文档