语音助手

为您的 OpenClaw agent 提供实时语音接口。与您的 agent 对话，并即时听到其语音回复 —— 支持可配置的 STT（语音转文本）和 TTS（文本转语音）服务提供商，全链路流式处理，首段音频延迟低于 2 秒。

架构

浏览器麦克风 → WebSocket → STT（Deepgram / ElevenLabs）→ 文本
  → OpenClaw 网关（/v1/chat/completions，流式响应）→ 响应文本
  → TTS（Deepgram Aura / ElevenLabs）→ 音频分块 → 浏览器扬声器

该语音接口连接至您正在运行的 OpenClaw 网关所暴露的 OpenAI 兼容端点。它使用的是同一套 agent，具备全部上下文、工具与记忆能力，仅新增了语音交互能力。

快速开始

cd {baseDir}
cp .env.example .env
# 填写您的 API 密钥和网关 URL
uv run scripts/server.py
# 打开 http://localhost:7860 并点击麦克风按钮

支持的服务提供商

STT（语音转文本）

TTS（文本转语音）

配置

所有配置均通过 .env 文件中的环境变量完成：

# === 必需项 ===
OPENCLAW_GATEWAY_URL=http://localhost:4141/v1    # 您的 OpenClaw 网关地址
OPENCLAW_MODEL=claude-sonnet-4-5-20250929        # 网关路由所用模型

# === STT 提供商（二选一）===
VOICE_STT_PROVIDER=deepgram                      # 可选 "deepgram" 或 "elevenlabs"
DEEPGRAM_API_KEY=your-key-here                   # 若 STT=deepgram，则必需
ELEVENLABS_API_KEY=your-key-here                 # 若 STT=elevenlabs，则必需

# === TTS 提供商（二选一）===
VOICE_TTS_PROVIDER=elevenlabs                    # 可选 "deepgram" 或 "elevenlabs"
# 使用与上述相同的 API 密钥

# === 可选调优项 ===
VOICE_TTS_VOICE=rachel                           # ElevenLabs 语音名称/ID
VOICE_TTS_VOICE_DG=aura-2-theia-en              # Deepgram Aura 语音标识
VOICE_VAD_SILENCE_MS=400                         # 转换轮次前的静音阈值（毫秒）
VOICE_SAMPLE_RATE=16000                          # 音频采样率
VOICE_SERVER_PORT=7860                           # 服务端口
VOICE_SYSTEM_PROMPT=""                           # 可选：系统提示词覆盖

服务提供商组合方案

工作原理

1. 浏览器采集麦克风音频：通过 Web Audio API 获取原始 PCM 音频，并经由 WebSocket 实时流式上传
2. 服务端接收音频：将音频流转发至所配置 STT 提供商的流式接口
3. STT 实时返回片段化文本：在用户语句结束时，将完整文本发送至 OpenClaw 网关
4. OpenClaw 网关流式响应：通过 SSE（Server-Sent Events）逐 token 流式返回 LLM 响应
5. 分句累积并转发至 TTS：将响应 tokens 按句子粒度切分后，流式提交给 TTS 提供商
6. TTS 返回音频分块：生成的音频分块立即通过同一 WebSocket 转发至浏览器
7. 浏览器播放音频：使用 Web Audio API 播放，并内置抖动缓冲区（jitter buffer）保障流畅性

中断处理（Barge-In）

当用户在 agent 正在说话时开始发言：

• 当前 TTS 音频立即中止
• agent 停止当前响应流程
• 新建 STT 会话，开始捕获用户的中断语音

使用示例

用户："嘿，帮我配置语音助手"
→ OpenClaw 执行：cd {baseDir} && cp .env.example .env
→ 自动打开 .env 文件，提示用户填写 API 密钥
→ 执行：uv run scripts/server.py

用户："启动语音聊天"
→ 在浏览器中打开 http://localhost:7860

用户："切换 TTS 到 Deepgram"
→ 将 .env 中 VOICE_TTS_PROVIDER 修改为 deepgram
→ 重启服务端

故障排查

• 无音频输出？ 请确认 TTS API 密钥有效，且服务提供商配置正确
• 延迟过高？ 建议 STT 和 TTS 均使用 Deepgram；同时确保网关与客户端处于同一网络环境
• 语音被意外截断？ 将 VOICE_VAD_SILENCE_MS 增加至 600–800ms
• 存在回声或啸叫？ 建议佩戴耳机，或在浏览器 UI 中启用内置回声消除功能

延迟预算