Voice Mode

这是什么

Voice Mode 把语音转文本（STT）接到输入框上。默认在 Chat 上下文里按住 空格键开始录音，松开即停止；转录结果会自动填入并提交，等价于手动敲入一句话。 录音期间界面显示实时中间转录，松手后替换为最终文本。

提供两条互相独立的 STT 后端，差异只在「如何拿到识别服务」：

• Anthropic voice_stream（默认） —— 通过 WebSocket /api/ws/speech_to_text/voice_stream 流式识别，使用与 CLI 相同的 Anthropic OAuth 凭证，需要 Claude.ai 账号（OAuth），不支持 API key。
• 豆包 ASR（Doubao） —— 通过可选依赖 doubaoime-asr 的 AsyncGenerator 协议流式识别，读取本地凭证文件， 不需要 Anthropic 账号，可完全离线于 Anthropic 生态使用。

两条后端共享同一套音频录制与按键交互，仅门控条件、连接实现与语言处理不同。 豆包后端在录音期间即返回最终结果，松手后无需等待处理状态。

前置条件

音频录制后端按平台自动选择，无需手动指定采样参数（固定 16 kHz / 单声道 / 16-bit）：

安装启用

1. 确认 Voice Mode 特性已开启

   Build 产物默认包含 VOICE_MODE。使用 dev 模式时通过环境变量显式开启：

   Terminal 复制

   # dev 模式手动开启 VOICE_MODE 特性
   FEATURE_VOICE_MODE=1 bun run dev

   特性关闭时，/voice 命令会被隐藏，调用返回 Voice mode is not available.

2. （仅豆包后端）安装可选依赖

   doubaoime-asr 声明为 optionalDependencies，安装失败不影响 Anthropic 后端，仅在切换到豆包后端时才会被动态 import。

   Terminal 复制

   bun add doubaoime-asr

3. （仅豆包后端）准备凭证文件

   默认读取 ~/.claude/tts/doubao/credentials.json。首次连接时若文件缺失， SDK 会尝试自动生成；也可按下节格式手动创建。

4. 在会话中启用并授权麦克风

   执行 /voice（或 /voice doubao）。启用前会依次检查录音环境、 音频工具与麦克风权限；首次授权时同步弹出系统权限请求，避免第一次按住说话才触发。

5. 按住空格说话，松开提交

   按住 空格键开始录音，界面显示实时转录；松开后停止录音，最终文本自动提交。

配置

语音设置写入用户级 settings.json，跨会话生效，由 /voice 命令维护。

豆包凭证文件 —— ~/.claude/tts/doubao/credentials.json：

{
  "deviceId": "...",
  "installId": "...",
  "cdid": "...",
  "openudid": "...",
  "clientudid": "...",
  "token": "..."
}

语言映射（Anthropic 后端） —— language 会被归一化为服务端允许的 BCP-47 代码子集：en、es、fr、ja、 de、pt、it、ko、hi、 id、ru、pl、tr、nl、 uk、el、cs、da、sv、 no。无法识别时回退为 en 并在启用提示中给出说明。

重绑定按键 —— 默认是 Chat 上下文的 space。在用户 keybindings.json 中覆盖，最后一个生效：

[
  {
    "context": "Chat",
    "bindings": {
      "meta+k": "voice:pushToTalk"
    }
  }
]

常用命令与参数

相关环境变量：

实战示例

用 Anthropic 后端（已登录 Claude.ai）：

# 确保已通过 OAuth 登录（voice_stream 不支持 API key）
/login

# 启用语音模式（默认 Anthropic 后端），首次会弹麦克风授权
/voice
# → Voice mode enabled (Anthropic). Hold Space to record.

# 按住空格说话，松开自动提交

切换到豆包 ASR（无需 Anthropic 账号）：

# 首次使用：启用并选择豆包后端
/voice doubao
# → Voice mode enabled (Doubao ASR). Hold Space to record.

# 之后只想切换后端，同样一条命令即可（保持启用状态）
/voice doubao

# 切回 Anthropic STT
/voice anthropic

# 关闭语音模式（不带参数）
/voice

改听写语言（仅 Anthropic 后端）：

# 把 language 设为受支持的名称或代码（如 "japanese"、"ja"）
/config

# 不支持的语言会回退为英语，并在启用提示中说明

常见问题排错