古法编程

Free Claude Code 的语音笔记功能允许你在 Discord 或 Telegram 中发送语音消息，代理会自动将其转写为文字，然后作为编程指令交给 Claude Code 处理。要实现这一功能，核心是配置 VOICE_NOTE_ENABLED=true 并选择并安装一个转写后端（本地 Whisper 或 NVIDIA NIM 云端）。本文将引导你完成从安装依赖到验证功能的完整流程。

Free Claude Code 语音笔记转写：Discord/Telegram 语音消息自动处理

Free Claude Code 的语音笔记功能将即时通讯软件变成了编程指令的语音输入口。你在 Discord 或 Telegram 里用语音下达的“任务”，会被自动转译为文字，再由 Claude Code 解释并执行。这为在移动场景或不便打字时下达编程指令提供了便利。

核心工作流程

整个流程始于聊天窗口，终于任务执行结果，自动化程度很高。

你发送语音消息 (Discord/Telegram)
        ↓
Free Claude Code 接收音频文件
        ↓
Whisper 转写为文字（本地或 NVIDIA NIM）
        ↓
转写文字作为编程指令交给 Claude Code CLI
        ↓
执行结果回传到聊天窗口

这个流程图清晰地表明，语音功能并非独立存在，它深度依赖于已配置的消息平台机器人（Discord/Telegram）和 Claude Code CLI 的正常运行。

第一步：启用语音功能

要使用语音转写，你需要在 Free Claude Code 项目中进行两步基础配置。

1. 安装转写依赖

根据你选择的转写后端（本地或云端），使用 uv 安装对应的 Python 依赖包。你可以选择一种，也可以都安装。

# 方案 A：仅安装本地 Whisper 依赖（CPU/CUDA，完全免费）
uv sync --extra voice_local

# 方案 B：仅安装 NVIDIA NIM 云端转写依赖
uv sync --extra voice

# 方案 C：两者都安装（灵活切换）
uv sync --extra voice --extra voice_local

2. 配置环境变量

在项目的 .env 文件中，启用语音笔记功能。

VOICE_NOTE_ENABLED=true

完成这两步后，系统就具备了接收和处理语音消息的基础能力。接下来需要配置具体的转写引擎。

第二步：选择并配置转写后端

Free Claude Code 提供两种转写后端，你可以在 .env 文件中通过环境变量进行选择和配置。

选项一：本地 Whisper (voice_local)

本地 Whisper 适合拥有 NVIDIA GPU 或不希望数据传出本机的用户。它使用 Hugging Face 的 transformers 库运行 Whisper 模型。

核心配置：

# 选择设备：CPU 或 CUDA（使用 NVIDIA GPU 加速）
WHISPER_DEVICE="cpu"      # 或 "cuda"

# 选择 Whisper 模型大小，平衡速度与准确度
WHISPER_MODEL="base"      # 可选值：tiny / base / small / medium / large-v2 / large-v3

# 可选：Hugging Face Token（用于下载部分受限制的模型）
HF_TOKEN=""

模型选择参考：

模型 大小 速度 准确度
tiny ~75MB 最快 低
base ~150MB 快 中
small ~500MB 中 较高
medium ~1.5GB 慢 高
large-v2/v3 ~3GB 最慢 最高

配置建议： 日常交流指令使用 base 模型即可，它在 CPU 上也能较快响应。如果需要处理专业术语或对准确度要求极高，可以选择 medium 或 large-v3。

选项二：NVIDIA NIM 云端转写

NVIDIA NIM 提供云端托管的 Whisper 服务，不消耗你本地的计算资源，转写速度快且模型版本较新。

核心配置：

# 指定使用 NVIDIA NIM 后端
WHISPER_DEVICE="nvidia_nim"

# 选择 NIM 上的 Whisper 模型
WHISPER_MODEL="openai/whisper-large-v3"  # 或 nvidia/parakeet-ctc-1.1b-asr

使用此功能前，你必须在 .env 中配置 NVIDIA_NIM_API_KEY，并且确保该账户有权访问语音转写服务。这里有一个设计上的灵活性：语音转写服务和你的聊天主模型（由 MODEL 变量指定，如 DeepSeek）是独立的。你可以用 NVIDIA NIM 进行语音转写，同时让聊天对话走 OpenRouter 或其他后端。

两种后端的技术路径对比：

  • 当 WHISPER_DEVICE 设置为 "cpu" 或 "cuda" 时，系统调用本地 Hugging Face transformers 加载的 Whisper 模型，整个过程离线完成。
  • 当 WHISPER_DEVICE 设置为 "nvidia_nim" 时，系统将通过 NVIDIA NIM 的 Riva gRPC 服务进行云端转写。

第三步：验证功能

配置完成后，按照以下步骤验证语音转写功能是否生效：

  1. 确保前置条件就绪：Free Claude Code 代理已经启动，并且你选择的消息平台（Discord 或 Telegram）机器人已经正确配置并在线。
  2. 发送语音消息：在对应的聊天窗口中，直接发送一条语音消息。内容可以简单如“帮我写一个 Hello World 的 Python 脚本”。
  3. 观察系统响应：正常的响应流程是，机器人会先回复一段转写后的文字消息（例如：“用户语音：帮我写一个 Hello World 的 Python 脚本”），随后立即开始执行对应的编程任务，并将最终结果（如代码或执行日志）回传到聊天窗口。

如果机器人没有响应或报错，请先检查消息平台的连接状态，再确认 .env 文件中的 VOICE_NOTE_ENABLED 和转写后端相关配置是否正确。

FAQ

Q: 语音转写支持哪些语言？ A: Whisper 模型支持超过 100 种语言，中英文转写都没有问题。不过，使用本地 tiny 模型处理中文时准确度较低，建议至少使用 base 模型。NVIDIA NIM 的 Whisper 服务同样支持多语言。

Q: 在 CPU 上运行本地 Whisper 太慢了怎么办？ A: 有两个优化方向。第一，如果机器有 NVIDIA GPU，将 WHISPER_DEVICE 从 "cpu" 改为 "cuda" 以启用 GPU 加速。第二，可以考虑切换到 NVIDIA NIM 云端转写，它能提供稳定的转写速度。在纯 CPU 环境下，base 模型通常在几秒内完成转写，而 large-v3 模型可能需要十几秒甚至更久。

Q: 我可以只使用语音功能，而不配置 Discord 或 Telegram 吗？ A: 不可以。语音功能的完整流程依赖于消息平台作为输入和输出的通道。它需要从 Discord 或 Telegram 接收音频文件，并将转写结果和执行结果回传。因此，必须先完成消息平台机器人的配置。