本地 Whisper
将语音转录切换为设备端的 whisper.cpp。无需 API 密钥、无网络请求、无逐条消息费用。
功能特性
- 完全在设备端通过 whisper.cpp 运行，数据不会离开你的机器
- 无需 API 密钥，无逐条消息费用
- 在 Apple Silicon 上，base 模型处理约 30 秒音频仅需不到 1 秒
- 支持多种模型尺寸，可在精度和速度之间灵活取舍
- 自动检测语言，支持任何语言的语音消息
前置条件
- 已安装并运行 NanoClaw
- 已应用语音转录技能（WhatsApp 通道）
- 推荐 macOS 配合 Apple Silicon（M1 及以上）
- 已安装 Homebrew
安装
/use-local-whisper 工作原理
/use-local-whisper 技能将 OpenAI Whisper API 替换为本地的 whisper.cpp 二进制文件来进行语音消息转录。语音消息不再发送到 OpenAI 的服务器，而是完全在你的机器上处理。智能体仍然以相同的 [Voice: <transcript>] 格式接收消息——这一变更对智能体和你来说都是透明的。
该技能通过 Homebrew 安装两个依赖：whisper-cpp（提供 whisper-cli 二进制文件）和 ffmpeg（用于音频格式转换）。然后下载一个 GGML 模型文件，并修改 src/transcription.ts 以调用本地二进制文件而非 OpenAI API。
模型尺寸
技能默认使用 base 模型，在速度和精度之间取得良好平衡。如果你需要更高的转录质量，可以选择更大的模型：
| 模型 | 大小 | 速度（M1，30 秒音频） | 适用场景 |
|---|---|---|---|
| Base | 148 MB | < 1 秒 | 大多数场景 |
| Small | 466 MB | 约 2 秒 | 口音较重的语音，精度更高 |
| Medium | 1.5 GB | 约 5 秒 | 最佳精度，多语言支持 |
模型文件存放在 data/models/ 中，可以随时通过下载不同的模型并更新 WHISPER_MODEL 环境变量来切换。
费用对比
使用 OpenAI Whisper API 时，转录费用大约为每分钟音频 $0.006。轻度使用时这几乎可以忽略，但如果你每天处理大量语音消息，费用会累积。使用本地 Whisper 后，除了一次性的模型下载外没有任何费用。代价是由你的机器来承担计算工作，而非 OpenAI 的服务器。
配置
可以在 .env 中设置两个可选的环境变量：
WHISPER_BIN— whisper-cli 二进制文件的路径。默认为whisper-cli（通过 PATH 查找）。WHISPER_MODEL— GGML 模型文件的路径。默认为data/models/ggml-base.bin。
故障排查
开发环境可以转录但服务模式不行。 launchd 服务运行时使用的 PATH 受限，可能不包含 /opt/homebrew/bin/。技能在设置时会检查并修复此问题，但如果你重新安装了 Homebrew 或移动了二进制文件，请检查 ~/Library/LaunchAgents/com.nanoclaw.plist 中的 PATH。
语言检测错误。 whisper.cpp 从音频中自动检测语言。要强制使用特定语言，请在 .env 中设置 WHISPER_LANG，并修改 src/transcription.ts 以向二进制文件传递 -l $WHISPER_LANG 参数。
转录速度慢。 base 模型在 M1 及以上设备上处理 30 秒音频应在 1 秒以内完成。如果速度更慢，请检查 CPU 使用率——可能有其他进程在争夺资源。升级到更小的模型并不会有帮助；降级反而会。
使用建议
- 此技能目前仅支持 WhatsApp。其他通道需要先实现各自的音频下载逻辑，本地 Whisper 才能为其服务。
- 你可以随时切换回 OpenAI API，方法是恢复
src/transcription.ts的改动或重新应用语音转录技能。 - 非常短的语音消息（不到 1 秒）有时会产生空白或不准确的转录结果。这是 Whisper 模型本身的局限性，并非本地版本特有的问题。