Đọc chính tả bằng giọng nói (Voice dictation)

Thay vì gõ, bạn có thể nói prompt trực tiếp trong Claude Code CLI. Giọng nói được phiên âm (transcribe) trực tiếp vào ô input, nên bạn có thể trộn giữa nói và gõ trong cùng một tin nhắn. Bật dictation bằng /voice, sau đó giữ một phím trong khi nói, hoặc gõ nhẹ một lần để bắt đầu và một lần nữa để gửi.

Ghi chú

Chế độ tap yêu cầu Claude Code v2.1.116 trở lên. Kiểm tra phiên bản bằng claude --version.

Dictation cũng hoạt động trong agent view. Giữ hoặc tap phím push-to-talk khi ô dispatch input hoặc ô reply trong peek-panel đang focus để đọc chính tả cho một phiên background.

Yêu cầu

Voice dictation stream audio bạn ghi âm tới server của Anthropic để phiên âm - audio không được xử lý tại chỗ (local). Cần đủ các điều kiện sau:

• Tài khoản Claude.ai: dịch vụ speech-to-text chỉ khả dụng khi bạn đăng nhập bằng tài khoản Claude.ai, không khả dụng khi Claude Code được cấu hình dùng trực tiếp Anthropic API key, Amazon Bedrock, Google Cloud’s Agent Platform, hoặc Microsoft Foundry.
• Tổ chức không bật HIPAA compliance: /voice hiện Voice mode is disabled by your organization's policy khi giới hạn này áp dụng.
• Microphone tại chỗ: voice dictation không hoạt động trong môi trường remote như Claude Code on the web hoặc phiên SSH.
• WSLg, nếu bạn chạy Claude Code trong WSL: WSLg đi kèm WSL2 khi cài từ Microsoft Store trên Windows 10/11. Nếu không có WSLg (ví dụ WSL1), chạy Claude Code trên Windows gốc thay vào đó.

Phiên âm không tốn message hay token của Claude, và không tính vào giới hạn hiển thị ở /usage. Xem data usage để biết Anthropic xử lý dữ liệu của bạn ra sao.

Ghi âm dùng native module tích hợp sẵn trên macOS, Linux, Windows. Trên Linux, nếu native module không load được, Claude Code fallback sang arecord (ALSA utils) hoặc rec (SoX). Nếu không có cái nào, /voice in ra lệnh cài đặt phù hợp với package manager của bạn.

VS Code extension của Claude Code cũng hỗ trợ voice dictation, với cùng yêu cầu tài khoản Claude.ai. Tính năng này không khả dụng trong phiên VS Code Remote (SSH, Dev Containers, Codespaces) vì microphone nằm ở máy local còn extension chạy trên host remote.

Bật voice dictation

Chạy /voice để bật dictation. Lần đầu bật, Claude Code chạy kiểm tra microphone; trên macOS việc này kích hoạt prompt xin quyền microphone hệ thống cho terminal của bạn nếu chưa từng được cấp.

/voice
Voice mode enabled (hold). Hold space to record. Dictation language: en (/config to change).

/voice nhận một tham số mode tuỳ chọn:

Lệnh	Hiệu ứng
/voice	Bật/tắt, giữ nguyên mode hiện tại
/voice hold	Bật ở hold mode
/voice tap	Bật ở tap mode
/voice off	Tắt

Voice dictation được lưu lại qua các phiên. Bạn có thể đặt trực tiếp trong file settings người dùng thay vì chạy /voice:

{
  "voice": {
    "enabled": true,
    "mode": "tap"
  }
}

Khi voice dictation đang bật, footer input hiện gợi ý hold space to speak lúc ô prompt trống. Gợi ý phản ánh binding voice:pushToTalk hiện tại và tự cập nhật nếu bạn rebind phím dictation. Gợi ý này không hiện nếu bạn đã cấu hình status line tuỳ chỉnh.

Phiên âm được tối ưu cho từ vựng lập trình ở cả hai mode. Các thuật ngữ dev phổ biến như regex, OAuth, JSON, localhost được nhận dạng đúng, và tên project + tên branch git hiện tại được tự động thêm làm gợi ý nhận dạng.

Giữ phím để ghi âm

Hold mode là push-to-talk: ghi âm chạy khi bạn giữ phím và dừng khi thả ra. Đây là mode mặc định.

Giữ Space để bắt đầu ghi âm. Claude Code phát hiện phím đang giữ bằng cách theo dõi sự kiện key-repeat dồn dập từ terminal, nên có một khoảng warmup ngắn trước khi ghi âm thực sự bắt đầu. Footer hiện keep holding… trong lúc warmup, rồi chuyển sang waveform trực tiếp khi ghi âm đã kích hoạt.

Vài ký tự key-repeat đầu tiên sẽ gõ vào ô input trong lúc warmup và tự động bị xoá khi ghi âm kích hoạt. Một lần tap Space đơn lẻ vẫn gõ ra dấu cách bình thường, vì phát hiện giữ phím chỉ kích hoạt khi có key-repeat dồn dập.

Mẹo

Để bỏ qua warmup, chuyển sang tap mode bằng /voice tap, hoặc rebind sang tổ hợp phím modifier như meta+k - tổ hợp modifier bắt đầu ghi âm ngay từ lần nhấn đầu tiên.

Lời nói của bạn hiện ngay trong prompt khi bạn nói, mờ đi cho tới khi transcript hoàn tất. Thả Space để dừng ghi âm và chốt text. Transcript được chèn tại vị trí con trỏ, con trỏ ở lại cuối đoạn text vừa chèn, nên bạn có thể trộn gõ và nói theo bất kỳ thứ tự nào. Giữ Space lần nữa để nối thêm một đoạn ghi âm, hoặc di chuyển con trỏ trước để chèn giọng nói vào chỗ khác trong prompt:

> refactor the auth middleware to ▮
  # giữ space, nói "use the new token validation helper"
> refactor the auth middleware to use the new token validation helper▮

Mặc định, khi bạn thả phím, Claude Code chèn transcript và chờ bạn nhấn Enter. Đặt "autoSubmit": true trong object settings voice để tự động gửi prompt ngay khi bạn thả phím, miễn transcript dài ít nhất ba từ.

Gõ nhẹ để ghi âm và gửi

Tap mode bật/tắt ghi âm bằng một lần nhấn phím: tap một lần để bắt đầu, nói, rồi tap lần nữa để gửi prompt. Không có warmup, và bạn không cần giữ phím.

Bật tap mode bằng /voice tap. Với ô prompt đang trống, tap Space để bắt đầu ghi âm - footer hiện waveform trực tiếp trong lúc ghi. Tap Space lần nữa để dừng.

Claude Code chèn transcript và tự động gửi prompt nếu transcript dài ít nhất ba từ. Transcript ngắn hơn vẫn được chèn nhưng không gửi, để một cú tap nhầm không vô tình gửi đi một từ lạc.

Ngưỡng ba-từ đếm từ theo ngôn ngữ không phân tách bằng khoảng trắng. Từ v2.1.195, tiếng Nhật, tiếng Trung, và tiếng Thái đếm từng từ riêng lẻ, nên vẫn tự gửi được ở tap mode và ở hold mode có autoSubmit. Bản cũ hơn coi transcript không có khoảng trắng là một từ duy nhất và không bao giờ tự gửi.

Lần tap đầu tiên chỉ bắt đầu ghi âm khi ô prompt đang trống, nên bạn vẫn gõ dấu cách bình thường khi đang soạn tin nhắn. Lần tap thứ hai luôn dừng ghi âm bất kể input đang có gì. Ghi âm cũng tự dừng sau 15 giây im lặng hoặc tổng cộng hai phút.

Đổi ngôn ngữ dictation

Voice dictation dùng chung setting language với ngôn ngữ Claude trả lời. Nếu setting đó để trống, dictation mặc định dùng tiếng Anh. Trong VS Code extension, nếu language trống, dictation dùng setting accessibility.voice.speechLanguage của VS Code trước khi fallback về tiếng Anh.

Danh sách ngôn ngữ dictation được hỗ trợ

Ngôn ngữ	Mã
Czech	cs
Danish	da
Dutch	nl
English	en
French	fr
German	de
Greek	el
Hindi	hi
Indonesian	id
Italian	it
Japanese	ja
Korean	ko
Norwegian	no
Polish	pl
Portuguese	pt
Russian	ru
Spanish	es
Swedish	sv
Turkish	tr
Ukrainian	uk

Đặt ngôn ngữ trong /config hoặc trực tiếp trong settings - dùng mã ngôn ngữ BCP 47 hoặc tên ngôn ngữ:

{
  "language": "japanese"
}

Nếu setting language của bạn không nằm trong danh sách hỗ trợ, /voice sẽ cảnh báo khi bật và fallback về tiếng Anh cho dictation - câu trả lời dạng text của Claude không bị ảnh hưởng bởi fallback này.

Rebind phím dictation

Phím dictation được bind vào action voice:pushToTalk trong context Chat, mặc định là Space. Cùng một binding điều khiển cả hold mode lẫn tap mode. Rebind trong ~/.claude/keybindings.json:

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

Action voice:pushToTalk chỉ dùng một phím tại một thời điểm. Khi bạn bind một phím tuỳ chỉnh, nó thay thế binding Space mặc định thay vì thêm một trigger thứ hai, nên dòng "space": null trong ví dụ trên chỉ để rõ ràng và có thể bỏ qua mà không đổi hành vi.

Ở hold mode, tránh bind một phím chữ cái đơn lẻ như v vì cơ chế phát hiện giữ phím dựa vào key-repeat, và chữ đó sẽ gõ vào prompt trong lúc warmup. Dùng Space, hoặc dùng tổ hợp modifier như meta+k để bắt đầu ghi âm ngay từ lần nhấn đầu, không warmup. Tap mode không có warmup nên hầu hết phím đều dùng được.

Một số phím không được gửi tới ứng dụng terminal nên không thể bind, ví dụ Caps Lock sẽ báo lỗi nếu bạn thử bind. Xem customize keyboard shortcuts để biết đầy đủ cú pháp keybinding và danh sách shortcut bị reserved.

Xử lý sự cố

Các vấn đề thường gặp khi voice dictation không kích hoạt hoặc không ghi âm được:

• Voice mode requires a Claude.ai account: bạn đang đăng nhập bằng API key hoặc provider bên thứ ba. Chạy /login để đăng nhập bằng tài khoản Claude.ai.
• Voice mode is disabled by your organization's policy: cấu hình compliance của tổ chức tắt voice dictation, như mô tả ở Yêu cầu. Liên hệ admin tổ chức để xác nhận.
• Microphone access is denied: cấp quyền microphone cho terminal trong system settings. macOS: System Settings → Privacy & Security → Microphone, bật app terminal của bạn rồi chạy lại /voice. Windows: Settings → Privacy & security → Microphone, bật quyền cho desktop app rồi chạy lại /voice. Nếu terminal của bạn không xuất hiện trong settings macOS, xem Terminal không xuất hiện trong Microphone settings của macOS.
• No audio recording tool found trên Linux: native audio module không load được và không có fallback nào được cài. Cài SoX theo lệnh trong thông báo lỗi, ví dụ sudo apt-get install sox.
• Voice mode requires a microphone, but SoX could not open an audio capture device: SoX đã cài nhưng máy không có thiết bị ghi âm, ví dụ server headless hoặc container. Chạy Claude Code trên máy có microphone. (Từ v2.1.195, Claude Code trên Linux báo đúng thông báo này trong trường hợp đó; bản cũ hơn yêu cầu cài SoX kể cả khi đã cài rồi.)
• Voice mode could not find a working audio recorder in WSL: WSLg route audio qua PulseAudio thay vì thiết bị ALSA, nên SoX cần cài thêm backend PulseAudio. Chạy sudo apt install sox libsox-fmt-pulse - chỉ cài sox thôi sẽ kéo theo backend ALSA, không ghi âm được trên WSL vì không có /dev/snd.
• Voice input is failing repeatedly and has been paused: voice dictation gặp liên tiếp nhiều lần lỗi capture và dừng thử phiên mới cho tới khi có một lần thành công. Thường do microphone hoặc audio stack của máy không capture được, ví dụ server headless, remote shell không có audio passthrough, hoặc quyền microphone bị từ chối. Xác nhận thiết bị input hoạt động, khắc phục nguyên nhân gốc từ các mục trên, rồi thử lại. (Trước v2.1.202, chỉ lỗi lúc khởi động mới tính vào việc pause.)
• Giữ Space ở hold mode nhưng không có gì xảy ra: quan sát ô prompt trong lúc giữ. Nếu dấu cách cứ xuất hiện liên tục, voice dictation có thể đang tắt - chạy /voice hold để bật. Nếu chỉ một hai dấu cách xuất hiện rồi dừng, voice dictation đang bật nhưng phát hiện giữ phím không kích hoạt (terminal của bạn có thể đã tắt key-repeat ở cấp OS) - chuyển sang tap mode bằng /voice tap để tránh yêu cầu key-repeat.
• Tap Space chỉ gõ ra dấu cách thay vì ghi âm ở tap mode: lần tap đầu chỉ bắt đầu ghi âm khi ô input trống. Xoá input trước, hoặc kiểm tra bạn đang ở tap mode bằng /voice tap.
• No audio detected from microphone: ghi âm đã chạy nhưng chỉ thu được im lặng. Kiểm tra đúng thiết bị input đang là mặc định hệ thống và mức input không bị mute hoặc quá thấp.
• Voice connection failed: bản ghi không tới được service phiên âm do lỗi kết nối. Kiểm tra mạng và thử lại. (Từ v2.1.200, một bản ghi không thu được audio sẽ báo No audio detected from microphone thay vì lỗi này; trước đó, microphone im lặng có thể báo lỗi kết nối gây hiểu nhầm là vấn đề mạng.)
• No speech detected: audio đã tới service phiên âm nhưng không nhận diện được từ nào. Nói gần microphone hơn, giảm tiếng ồn nền, và kiểm tra ngôn ngữ dictation khớp với ngôn ngữ bạn đang nói.
• Phiên âm bị sai/lộn xộn hoặc sai ngôn ngữ: dictation mặc định tiếng Anh - nếu bạn nói ngôn ngữ khác, đặt lại trong /config trước. Xem Đổi ngôn ngữ dictation.

Terminal không xuất hiện trong Microphone settings của macOS

Nếu app terminal của bạn không xuất hiện trong System Settings → Privacy & Security → Microphone, không có toggle nào để bật. Reset trạng thái quyền cho terminal đó để lần chạy /voice tiếp theo kích hoạt lại prompt quyền của macOS.

1. Reset quyền microphone cho terminal: chạy tccutil reset Microphone <bundle-id>, thay <bundle-id> bằng định danh terminal của bạn - com.apple.Terminal cho Terminal có sẵn, com.googlecode.iterm2 cho iTerm2. Với terminal khác, tra bằng osascript -e 'id of app "AppName"'.

   Chú ý

   Bạn có thể chạy tccutil reset Microphone không kèm bundle ID, nhưng khi đó nó thu hồi quyền microphone của MỌI app trên máy, kể cả Zoom hay Slack. Mỗi app sẽ phải xin quyền lại lần dùng tiếp theo - đừng chạy lệnh này trong lúc đang có cuộc gọi.

2. Thoát hẳn và mở lại terminal: macOS không hỏi lại quyền cho một process đang chạy sẵn. Thoát app terminal bằng Cmd+Q (không chỉ đóng cửa sổ), rồi mở lại.

3. Kích hoạt prompt mới: mở Claude Code và chạy /voice. macOS sẽ hỏi quyền microphone - cho phép.

Xem thêm

• Customize keyboard shortcuts: rebind voice:pushToTalk và các action bàn phím CLI khác
• Configure settings: tham chiếu đầy đủ cho voice, language, và các setting khác
• Interactive mode: phím tắt, input mode, và các điều khiển phiên
• Commands: tham chiếu cho /voice, /config, và các lệnh khác

Chú ý

Danh sách flag, setting, và số phiên bản tối thiểu ở trên có thể đã thay đổi - kiểm tra lại với tài liệu gốc hoặc claude --version nếu có gì không khớp.

Nguồn

Dịch và biên soạn từ Voice dictation.