speech-recognition 实战：让 Agent 听懂人话，不止是语音转文字

为什么你需要这个技能

事情是这样的。上周五下午，Franky在车里发了条语音消息到工作群：「把下周要发的文章清单列给我。」

正常情况下，这条消息会沉在群里没人管。但有了 speech-recognition 技能之后，事情变成了这样：

语音消息 → 自动转文字 → Agent 识别意图 → 从 CMS 拉取排期 → 回复列表。

全程 4 秒。Franky 连车都没停。

这就是 speech-recognition 技能在 OpenClaw 里的真实价值——不是"把语音变成文字"这么简单，而是让 Agent 能响应语音输入，打通人机交互的最后一道障碍。

安装和基础配置

安装很简单，一行命令搞定：

clawhub install speech-recognition

安装完之后，在 OpenClaw 的配置文件里加上：

skills:
  speech-recognition:
    provider: whisper  # 默认用本地 Whisper 模型
    model: base         # 可选: tiny, base, small, medium, large-v3
    language: auto      # 自动检测语言，或指定 zh/en 等

这里有个关键选择：用本地 Whisper 还是云端 API？

我的建议很直接：如果你跑的是中文语音，用 large-v3 模型。base 模型对中文的识别率大概只有 65%，large-v3 能到 93% 以上。代价是内存占用——large-v3 需要大约 3GB 显存/内存。我们的 MS01 服务器跑 large-v3 毫无压力，但如果你的机器比较老，small 模型是个折中方案。

实战场景：语音消息自动处理

这是我们目前在 SFD 实验室的真实用法。

OpenClaw 的 Telegram bot 收到语音消息后，speech-recognition 技能会自动拦截，把语音转成文字，然后交给 Agent 的决策层处理。整个流程在 skills/speech-recognition/SKILL.md 里有完整说明，但实际落地时有几个配置细节文档里没写清楚：

细节一：音频格式转换。Telegram 发来的语音是 OGG 格式，Whisper 原生支持 OGG，但如果你用的是其他平台（比如微信、Slack），可能需要先转成 WAV 或 MP3。我们在 skill 里加了一个格式检测层，自动判断是否需要 ffmpeg 转换。

细节二：长音频分段处理。Whisper 对单段音频的长度有限制。超过 30 秒的语音，我们自动切成 25 秒的片段分别识别，再把结果拼接。拼接的时候要注意——Whisper 的每段输出开头可能有重复词，需要做一个去重处理。我们用的方案是：比较相邻片段的最后 5 个词和下一段的前 5 个词，重叠部分只保留一次。

# 伪代码示例
def merge_segments(segments):
    result = segments[0]
    for i in range(1, len(segments)):
        overlap = find_overlap(result[-50:], segments[i][:50])
        result += segments[i][overlap:]
    return result

细节三：说话人区分。如果一段语音里有多个人说话，Whisper 本身做不了说话人分离（diarization）。我们的方案是结合 pyannote.audio 做说话人标记，但这会显著增加处理时间。如果你的场景只需要转文字不需要区分谁说的，跳过这一步。

踩坑记录

说三个真实踩过的坑：

坑一：背景噪音吃掉识别率。有次 Franky 在咖啡厅发语音，识别率直接掉到 40%。解决方案是在 skill 配置里加一个降噪预处理步骤——用 noisereduce 库先处理音频再喂给 Whisper。加了降噪之后识别率从 40% 回到 85%。代价是多花了约 1.5 秒处理时间。

坑二：中英混合语音识别混乱。这是中文用户最常见的场景——一句话里夹杂着英文术语。Whisper large-v3 对中英混说的支持还不错，但有一个 trick：在 prompt 参数里指定主语言。比如 prompt="以下是中文为主的语音"，模型会优先按中文的语法结构去理解，英文术语作为"外来词"处理。不加这个提示，模型有时候会把整句话当成英文来识别。

坑三：内存泄漏。如果你用的是本地 Whisper 模型并且高频处理语音（比如我们这种一天几十条语音消息的场景），注意模型加载后不要每次都重新初始化。我们把模型实例做成了全局单例，只在启动时加载一次。这个问题在 small 模型上不严重，但 large-v3 每次加载要 10-15 秒，不缓存的话用户体验直接崩掉。

和 edge-tts 的组合拳

speech-recognition + edge-tts 是我们最常用的组合。speech-recognition 负责"听"，edge-tts 负责"说"。两个技能配合起来，Agent 就有了完整的语音交互能力。

实际应用场景：用户在 Telegram 发语音提问 → speech-recognition 转文字 → Agent 理解并回答 → edge-tts 把回答转成语音发回去。全程不需要用户打字。

这个组合对移动端用户特别友好。开车、走路、做饭的时候，语音交互比打字效率高太多。

和 smart-web-scraper 的配合

另一个实用组合：语音指令 + 网页抓取。比如你说「帮我查一下今天GitHub上 trending 的 Python 项目」，speech-recognition 转文字后，Agent 调用 smart-web-scraper 去抓取 GitHub Trending 页面，然后把结果用文字（或语音）返回给你。

这种"语音指令 → 自动执行 → 返回结果"的模式，才是语音识别技能真正发挥价值的地方。

SFD 编者注

今天测试 speech-recognition 的时候，小鹦鹉在旁边说了一句话：「如果 Agent 能听懂语音，那它算不算有了耳朵？」

我想了想，回答：「不算。耳朵只是硬件，听懂才是关键。Whisper 强就强在它真的『理解』语音的语义，而不只是机械地把声波转成文字。」