Claude Code Voice Mode 完整教學 - 用嘴巴寫程式的正確姿勢

打了三個小時的 prompt，手指已經不是自己的了。這時候你的同事走過來：「欸你幹嘛不用說的？」

Claude Code 從 v2.1.69 開始支援 Voice Mode。按住空白鍵說話，放開就變成文字指令。聽起來簡單，但裡面有不少細節值得搞懂。

啟用方式

一行指令：

/voice

第一次啟用時，Claude Code 會跑一次麥克風檢查。macOS 使用者會看到系統權限彈窗，允許你的終端機存取麥克風就好。

啟用後，輸入區底部會出現 hold Space to speak 的提示。Voice Mode 是持久設定，關掉終端機下次開還在。要關掉就再打一次 /voice。

也可以直接寫進設定檔 ~/.claude/settings.json：

1
2
3

{
  "voiceEnabled": true
}

按住、說話、放開

操作流程：

按住空白鍵 — 底部會先顯示 keep holding...（這是暖機階段，偵測你是長按還是短按）
開始說話 — 暖機結束後出現波形動畫，語音即時串流到 Anthropic 伺服器做轉錄
放開空白鍵 — 語音轉文字結束，文字插入游標位置

暖機期間可能會多打幾個空格到輸入區，Claude Code 會在錄音啟動後自動清掉。短按空白鍵還是正常打空格，不會誤觸。

跳過暖機的方法

如果覺得暖機延遲煩人，改綁到修飾鍵組合就好。修飾鍵組合在第一次按下時就開始錄音，不需要等 key-repeat 偵測：

// ~/.claude/keybindings.json
{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "meta+k": "voice:pushToTalk",
        "space": null
      }
    }
  ]
}

"space": null 是移除預設綁定。如果想兩個鍵都能用，就不要加這行。

避免綁到一般字母鍵（像 v），因為暖機期間它會打字到輸入區。空白鍵或修飾鍵組合是最穩的選擇。

混合輸入：說一半打一半

Voice Mode 最實用的設計是它不會霸佔輸入。語音轉出來的文字會插入游標位置，你可以：

先打一段文字，再按住空白鍵補充語音
語音輸入後移動游標，在其他位置繼續打字
多次按住空白鍵，分段錄製拼成一個完整 prompt

1
2
3

> refactor the auth middleware to ▮
  # 按住空白鍵，說 "use the new token validation helper"
> refactor the auth middleware to use the new token validation helper▮

這對「大方向用說的、細節用打的」的工作模式很友善。你可以口述要做什麼，然後手動補上檔名、變數名這種打字比較精確的東西。

程式術語辨識

轉錄引擎針對程式開發做了調校。常見的開發術語像 regex、OAuth、JSON、localhost 都能正確辨識，不會變成奇怪的同音字。

更聰明的是，它會自動把你目前的專案名稱和 git branch 名稱加入辨識提示。如果你的 branch 叫 feature/auth-refactor，說出來的時候辨識率會比較高。

支援 20 種語言

Voice Mode 的語言設定跟 Claude Code 的 language 設定共用。完整支援清單：

英文、法文、德文、西班牙文、葡萄牙文、義大利文、荷蘭文、波蘭文、瑞典文、挪威文、丹麥文、捷克文、希臘文、土耳其文、俄文、烏克蘭文、印尼文、日文、韓文、印地文。

設定方式，在 /config 裡改，或直接寫設定檔：

1
2
3

{
  "language": "japanese"
}

如果你的 language 設定不在支援清單內，/voice 會提醒你並自動 fallback 到英文做語音辨識。Claude 的文字回覆不受影響。

中文呢？目前語音辨識的支援清單裡沒有中文。不過 Claude 的文字回覆語言不受此限制，你可以用英文語音輸入、然後讓 Claude 用中文回覆。有點繞，但能用。

哪些環境能用、哪些不行

能用的：

macOS（原生模組）
Linux（原生模組，fallback 到 arecord 或 rec）
Windows（原生模組）
WSL2 on Windows 11（透過 WSLg 存取音訊）

不能用的：

Claude Code on the Web（雲端版沒有本地麥克風）
SSH 遠端連線（音訊裝置不在遠端）
WSL1 或 Windows 10 的 WSL（沒有 WSLg 音訊支援）
使用 API Key 直接認證時（需要 Claude.ai 帳號）
Bedrock / Vertex AI / Foundry 用戶（語音轉文字服務只在 Claude.ai 帳號下可用）

最後兩點要特別注意——Voice Mode 的語音串流是送到 Anthropic 的伺服器做轉錄，所以只有用 Claude.ai 帳號登入才能用。企業用 Bedrock 或 Vertex 的需要另外 /login 切換帳號。

常見問題排除

**Voice mode requires a Claude.ai account**：你是用 API key 或第三方供應商認證的。跑 /login 用 Claude.ai 帳號重新登入。

**Microphone access is denied**：macOS 到系統設定 → 隱私權與安全性 → 麥克風，開啟你的終端機 app。Windows 到設定 → 隱私與安全性 → 麥克風，開啟桌面應用程式的麥克風存取。

macOS 找不到終端機 app 的麥克風權限：跑 tccutil reset Microphone com.apple.Terminal（或 iTerm2 用 com.googlecode.iterm2），然後完全退出終端機再重開，/voice 就會觸發新的權限彈窗。注意不要跑不帶 bundle ID 的 tccutil reset Microphone，那會重設所有 app 的麥克風權限，Zoom 開會中的同事會恨你。

Linux 找不到錄音工具：原生音訊模組載入失敗時，裝 SoX 就好：sudo apt-get install sox。

按住空白鍵沒反應，只是一直打空格：Voice Mode 沒開，跑 /voice 啟用。如果啟用了但還是沒反應，檢查 OS 層級的按鍵重複（key-repeat）有沒有被關掉——Voice Mode 靠偵測快速重複按鍵事件來判斷長按。

跟其他工具的語音功能比較

工具	語音輸入方式	程式術語最佳化	混合輸入	離線辨識
Claude Code	Push-to-Talk	有（含專案名稱提示）	有	無（雲端）
GitHub Copilot Voice	VS Code 語音擴充	有限	有限	無
Cursor	無原生支援	-	-	-
Kiro CLI	無原生支援	-	-	-