音频与语音

Audio Node（音频节点）为 Agent 提供语音输入和输出能力，包括语音转文字 STT（Speech-to-Text）和文字转语音 TTS（Text-to-Speech）。

启动音频节点

openclaw node --type audio

首次启动

系统会要求授予麦克风权限。macOS 用户需要在「系统设置 → 隐私与安全 → 麦克风」中允许终端应用访问。

语音识别（STT）

STT 将用户的语音输入转换为文本，再交给 Agent 处理。

支持的 STT 提供商

提供商	延迟	中文支持	特点
Deepgram	极低	✅	实时流式，推荐首选
OpenAI Whisper	中	✅	精度高，支持本地部署
Azure Speech	低	✅	企业级稳定性
Google Speech	低	✅	多语言混合识别
阿里云语音	低	✅	国内访问速度快

STT 配置

config.yaml

audio:
  stt:
    provider: deepgram           # STT 提供商
    api_key: ${DEEPGRAM_API_KEY} # 引用环境变量
    language: zh-CN              # 识别语言
    model: nova-2                # 模型版本
    interim_results: true        # 是否返回中间结果
    punctuate: true              # 自动添加标点
    encoding: opus               # 音频编码格式
    sample_rate: 16000           # 采样率 (Hz)

Whisper 本地配置

audio:
  stt:
    provider: whisper
    model: large-v3             # 模型大小: tiny/base/small/medium/large-v3
    device: cuda                # 推理设备: cpu/cuda
    language: zh
    local: true                 # 本地运行，不发送到云端

🇨🇳 中国用户须知

推荐使用阿里云语音识别或本地 Whisper 模型。Deepgram 在国内需要代理访问，延迟可能增加。

语音合成（TTS）

TTS 将 Agent 的文本回复转换为语音输出。

支持的 TTS 提供商

提供商	中文音色	特点
OpenAI TTS	有限	自然度高
Azure TTS	丰富	多音色，SSML 支持
ElevenLabs	有限	克隆音色
阿里云 TTS	丰富	国内低延迟

TTS 配置

audio:
  tts:
    provider: azure              # TTS 提供商
    api_key: ${AZURE_SPEECH_KEY}
    region: eastasia             # 服务区域
    voice: zh-CN-XiaoxiaoNeural  # 音色名称
    speed: 1.0                   # 语速 (0.5-2.0)
    format: audio-24khz-48kbitrate-mono-mp3

音频格式

OpenClaw 支持以下音频格式：

格式	编码	场景
Opus	有损压缩	实时流式传输（推荐）
WAV	无损	高质量录音存档
MP3	有损压缩	TTS 输出、文件传输

实时流式 vs 文件上传

OpenClaw 支持两种音频输入模式：

实时流式（推荐）

audio:
  mode: streaming
  chunk_size: 1024     # 每块大小（字节）
  vad: true            # 启用 VAD（Voice Activity Detection，语音活动检测）

• 延迟低，用户说完即开始识别
• 需要 WebSocket 持续连接
• 适合对话场景

文件上传

audio:
  mode: file
  max_duration: 300    # 最大录音时长（秒）
  max_size: 25MB       # 最大文件大小

• 录音完成后一次性上传
• 适合长段语音、离线场景

高级配置

噪声抑制

audio:
  noise_suppression: true
  noise_level: moderate    # low / moderate / aggressive

多声道支持

audio:
  channels: 1              # 单声道（推荐）
  # channels: 2            # 立体声

音频缓存

audio:
  cache:
    enabled: true
    tts_cache_size: 100    # 缓存最近 100 条 TTS 结果
    ttl: 3600              # 缓存过期时间（秒）

隐私提示

实时流式模式下，音频数据会发送到 STT 提供商的服务器。如果涉及敏感对话，建议使用本地 Whisper 模型，数据不会离开你的设备。

常用命令

# 测试麦克风输入
openclaw node --type audio --test

# 指定音频设备
openclaw node --type audio --device "MacBook Pro Microphone"

# 查看可用音频设备
openclaw node --type audio --list-devices

故障排查

问题	可能原因	解决方案
无法录音	麦克风权限未授予	检查系统权限设置
识别为空	采样率不匹配	确认 sample_rate 与设备匹配
TTS 无声	音频输出设备问题	检查系统默认输出设备
延迟过高	网络或提供商问题	切换提供商或使用本地模型

更多问题请参考 故障排查。