Claude Code gõ tiếng Việt bị lỗi: nguyên nhân và cách sửa

Claude Code dùng tiếng Việt được, nhưng "Claude Code gõ tiếng Việt bị lỗi" là chuyện có thật: nhiều người báo trên kho mã công khai của Anthropic rằng khi bật bộ gõ Telex hoặc VNI, dấu mất, ký tự bị nuốt hoặc chữ chỉ hiện sau khi chốt. Bài tách hai chuyện hay bị lẫn: Claude trả lời bằng tiếng Việt (có cách đặt cố định) và ô nhập của Claude Code nhận tiếng Việt qua bộ gõ (lỗi có báo cáo, chưa thấy bản sửa chính thức riêng cho tiếng Việt). Chúng tôi không tái hiện được mọi lỗi trên mọi máy và không có cách sửa bảo đảm. Bài có bảng triệu chứng, trạng thái các issue đã đọc, thứ tự thử và khối CLAUDE.md mẫu "luôn trả lời tiếng Việt".

Hai lớp cần tách: bộ gõ đưa chữ vào ô nhập, còn ngôn ngữ trả lời do cài đặt và CLAUDE.md. Sơ đồ: OPCAIOS.

Claude Code có dùng được tiếng Việt không?

Có, ở phần trả lời. Trang cài đặt chính thức mô tả khoá language là cách để Claude trả lời bằng ngôn ngữ khác tiếng Anh: giá trị được chuyển nguyên văn cho Claude làm chỉ dẫn, không có danh sách cố định, không kiểm tra chính tả. Đặt bằng /config trong phiên hoặc thêm "language": "vietnamese" vào tệp cài đặt ("vietnamese" là ví dụ của chúng tôi theo mẫu "japanese" trong tài liệu; mức tuân thủ chưa đo). Hai giới hạn theo tài liệu: nhập giọng nói /voice không có tiếng Việt trong 20 ngôn ngữ hỗ trợ, và giao diện chưa có bản tiếng Việt (yêu cầu #69741 đã đóng, không lên kế hoạch).

Lỗi gõ tiếng Việt trông như thế nào?

Lỗi nằm ở ô nhập của terminal, không nằm ở mô hình. Người báo cáo đoán ô nhập tự vẽ của Claude Code chưa khớp với cơ chế ghép chữ của bộ gõ; Anthropic chưa xác nhận điều này trong các issue chúng tôi đọc.

Triệu chứng	Nguyên nhân được nêu	Cách thử
Gõ "aa" không ra "â", dấu biến mất	Bộ gõ và ô nhập không đồng bộ (Windows Terminal, #7989, #44948)	Soạn ở nơi khác rồi dán
Chữ chỉ hiện sau khi bấm Space hoặc Enter	Chữ đang ghép không vẽ trực tiếp (Linux, #43381)	Đổi terminal, thử CLAUDE_CODE_NATIVE_CURSOR=1
Tiêu điểm nhảy sang cửa sổ khác	Người báo nghi bộ gõ toàn hệ thống khi mở 13 đến 14 phiên (Windows, #85238)	Giảm số phiên mở
Dấu lệch hoặc hiển thị sai	Chưa rõ, #34549 không nêu nguyên nhân	Chụp màn hình, báo kèm phiên bản
Lẫn chữ Hán giữa câu tiếng Việt	Hành vi mô hình, một trường hợp (#76351)	Nhắc trong CLAUDE.md, đọc lại bản trả lời

Đa số báo cáo ghi Windows. Có báo cáo trên macOS (#10429, #47269, #65250) nhưng cả ba bị đóng vì trùng lặp. Chúng tôi không có số liệu về tỉ lệ người gặp lỗi.

Các issue công khai hiện ở trạng thái nào?

Đọc ngày 04/11/2026 trên github.com/anthropics/claude-code. Các issue riêng cho tiếng Việt (#7989, #34549, #43381, #44948) đều đã đóng từ tháng 5/2026, do không hoạt động (nhãn stale) hoặc "not planned", không phải vì đã có bản sửa. Issue #1547 về bộ gõ gây chậm và ứng viên hiện hai lần (báo bằng tiếng Nhật, macOS) còn mở.

Nên thử theo thứ tự nào?

Thử từ ít can thiệp đến nhiều, dừng khi hết lỗi.

1. Gõ ở nơi khác rồi dán. Cách này người báo #44948 dùng được. Dán dài sẽ thu gọn thành nhãn "Pasted text" nhưng vẫn gửi đủ nội dung, theo tài liệu terminal.
2. Mở trình soạn ngoài bằng Ctrl+G, phím mà tài liệu ghi là mở lời nhắc trong trình soạn văn bản mặc định. Bộ gõ có chạy ổn trong trình soạn đó hay không, chúng tôi chưa kiểm.
3. Đổi terminal. Bảng terminal trong tài liệu nói về Shift+Enter, không nói về bộ gõ. Một bình luận trong #1547 ghi bản 2.1.84 sửa việc theo dõi con trỏ nên bộ gõ hiện trực tiếp trong Ghostty, còn Zellij vẫn lỗi (ý kiến cá nhân, về tiếng Nhật).
4. Thử CLAUDE_CODE_NATIVE_CURSOR=1, biến mà tài liệu mô tả là hiện con trỏ thật của terminal tại vị trí nhập. Tài liệu không nói nó sửa lỗi gõ tiếng Việt; chúng tôi chưa kiểm. Dễ gỡ vì chỉ áp dụng cho một lần chạy:

CLAUDE_CODE_NATIVE_CURSOR=1 claude

1. Đổi bộ gõ hoặc kiểu gõ. Không bảo đảm: người báo #10429 thử cả bộ gõ có sẵn của macOS lẫn bộ gõ bên thứ ba, đều lỗi trong iTerm2.
2. Cập nhật. claude --version cho biết bản đang dùng (máy chúng tôi ghi 2.1.317); claude update và claude doctor có trong claude --help, chúng tôi chỉ đối chiếu tên lệnh, không chạy.
3. Mở issue mới nếu vẫn lỗi: ghi phiên bản, hệ điều hành, terminal, bộ gõ, các bước làm lại và số issue cũ.

Vài bình luận giới thiệu tập lệnh vá của bên thứ ba; chúng tôi chưa chạy và không khuyên chạy mã chưa đọc.

Làm sao để Claude Code luôn trả lời tiếng Việt?

Dùng language như trên, và thêm tệp CLAUDE.md, tệp Markdown Claude đọc ở đầu mỗi phiên. Theo tài liệu, ./CLAUDE.md áp dụng cho một dự án, ~/.claude/CLAUDE.md áp dụng cho mọi dự án của bạn; nên dưới 200 dòng, và Claude coi đây là ngữ cảnh chứ không phải cấu hình cưỡng chế. Khối mẫu giả định, sao chép được:

# Ngôn ngữ và cách trả lời
- Luôn trả lời bằng tiếng Việt có dấu, câu ngắn.
- Giữ nguyên tên lệnh, tên tệp, tên biến và đoạn mã bằng tiếng Anh; không dịch chúng.
- Khi giải thích lỗi, nêu nguyên nhân trước, cách sửa sau.
- Nếu tôi gõ không dấu, vẫn hiểu và trả lời có dấu.
- Không chắc thì nói "chưa chắc", không đoán.

Dòng thứ tư cho phép gõ không dấu khi bộ gõ lỗi, đổi lại câu hỏi dễ mơ hồ hơn. Xem thêm CLAUDE.md là gì.

Kinh nghiệm của OPCAIOS

Nghĩa dùng Claude Code bằng tiếng Việt trên macOS để xây website opcaios.org. Giới hạn thật: chúng tôi không tái hiện được lỗi trên mọi hệ điều hành, terminal và bộ gõ, nên không khẳng định cách nào đã chữa được lỗi. Mô tả lỗi ở trên lấy từ tài liệu và issue công khai, không phải từ thử nghiệm của chúng tôi.

Câu hỏi thường gặp

Claude Code có hiểu và trả lời tiếng Việt không?

Có thể. Cách ổn định nhất là đặt khoá language rồi thêm một dòng trong CLAUDE.md yêu cầu trả lời tiếng Việt có dấu. Chất lượng và độ tuân thủ chúng tôi chưa đo, và báo cáo #76351 ghi một chữ Hán lọt vào câu tiếng Việt, nên hãy đọc lại bản trả lời. Giao diện Claude Code vẫn bằng tiếng Anh.

Vì sao gõ Telex trong Claude Code bị mất dấu?

Nguyên nhân chưa được Anthropic xác nhận trong các issue chúng tôi đọc. Người báo cáo đoán ô nhập tự vẽ xử lý chưa đúng chữ đang ghép của bộ gõ. Lỗi xuất hiện chủ yếu ở Windows Terminal, có báo cáo ở Linux và macOS. Cách tạm đơn giản nhất là gõ ở nơi khác rồi dán vào.

Có nhập tiếng Việt bằng giọng nói vào Claude Code được không?

Chưa theo tài liệu. /voice liệt kê 20 ngôn ngữ, không có tiếng Việt; đặt language ngoài danh sách thì Claude Code cảnh báo và nhập giọng nói quay về tiếng Anh, còn phần trả lời không đổi. Yêu cầu thêm tiếng Việt (#62185, #83743) đã đóng mà không có bản sửa.

Lỗi này có xảy ra trên macOS không?

Có báo cáo (#10429, #47269, #65250) nhưng đều bị đóng vì trùng, và đa số báo cáo còn lại ghi Windows. Nghĩa dùng trên macOS, nhưng đó là một người dùng, không phải thử nghiệm có hệ thống.

Học Claude Code bằng tiếng Việt ở đâu?

Đọc Claude Code là gì và Claude Code cho người mới bắt đầu, rồi dùng khối CLAUDE.md ở trên. Tài liệu gốc bằng tiếng Anh nên bạn có thể nhờ Claude giải thích từng đoạn bằng tiếng Việt, rồi đối chiếu bản gốc ở chỗ quan trọng.

Bước tiếp theo

Sao chép khối CLAUDE.md "luôn trả lời tiếng Việt" ở trên vào ~/.claude/CLAUDE.md, mở phiên mới và hỏi một câu để kiểm tra.

Nguồn: tài liệu Claude Code của Anthropic (settings, voice, terminal, interactive mode, env-vars, memory) và các issue công khai #1547, #7989, #10429, #34549, #43381, #44948, #47269, #62185, #65250, #69741, #76351, #83743, #85238 trên github.com/anthropics/claude-code, đọc ngày 04/11/2026; có chạy claude --version và claude --help. Chưa kiểm chứng: nguyên nhân gốc của lỗi gõ, hiệu quả của từng cách thử trên máy bạn, độ tuân thủ tiếng Việt của mô hình, tình trạng lỗi ở bản mới hơn. Kinh nghiệm là của OPCAIOS.