Trợ năng (Accessibility)

Claude Code có một chế độ screen reader thay giao diện terminal trực quan (box vẽ bằng ký tự, animation, redraw tại chỗ) bằng text phẳng, tuyến tính. Thay vì khung viền và hiệu ứng loading, chế độ này in ra các dòng có nhãn rõ ràng mà screen reader như VoiceOver hay NVDA đọc theo thứ tự - nhờ vậy bạn có thể trò chuyện trọn vẹn, duyệt qua permission prompt, và xem lại output từ đầu tới cuối.

Chế độ screen reader là opt-in (phải tự bật). Nếu bạn dùng screen magnifier, muốn giảm hiệu ứng chuyển động, hoặc dùng theme thân thiện với người mù màu thay vì screen reader, xem phần Cài đặt trợ năng ngoài chế độ screen reader bên dưới.

Ghi chú

Chế độ screen reader yêu cầu Claude Code v2.1.181 trở lên. Phiên bản cũ hơn sẽ báo lỗi error: unknown option '--ax-screen-reader' khi dùng flag --ax-screen-reader.

Bật chế độ screen reader

Chọn cách phù hợp với tần suất bạn dùng screen reader:

• Cho một phiên: chạy claude --ax-screen-reader.
• Cho các phiên khởi động từ một shell: đặt biến môi trường CLAUDE_AX_SCREEN_READER bằng 1. Trong Bash/Zsh chạy export CLAUDE_AX_SCREEN_READER=1; trong PowerShell chạy $env:CLAUDE_AX_SCREEN_READER = "1". Thêm dòng này vào shell profile để áp dụng cho mọi phiên shell.
• Cho mọi phiên trên máy: thêm "axScreenReader": true vào file settings người dùng. Cách này áp dụng cho mọi terminal, kể cả terminal tích hợp của VS Code.

Ghi chú

Thứ tự ưu tiên: flag --ax-screen-reader ghi đè biến môi trường CLAUDE_AX_SCREEN_READER, biến này ghi đè setting axScreenReader.

Nếu bạn dùng Claude Code qua SSH, hãy đặt biến môi trường hoặc setting trên máy từ xa (nơi Claude Code thực sự chạy).

Khi chế độ này bật, dòng đầu tiên Claude Code in ra là dòng xác nhận nêu rõ cách nó được bật: [Screen Reader Mode: on via flag], [Screen Reader Mode: on via env], hoặc [Screen Reader Mode: on via settings] (định dạng này yêu cầu v2.1.206 trở lên; bản cũ hơn in [Accessible screen reader mode: on]). Khi Claude Code tự khởi động lại (ví dụ để hoàn tất cài update), process mới kế thừa chế độ này qua biến môi trường CLAUDE_AX_SCREEN_READER, nên dòng xác nhận của nó luôn là on via env bất kể bạn đã bật bằng cách nào ban đầu.

Sau dòng xác nhận, Claude Code giữ phần giao diện còn lại trong 3 giây để screen reader kịp đọc xong dòng đó, rồi mới render prompt đầu tiên. Nhấn phím bất kỳ để bỏ qua khoảng chờ này sớm hơn. Để đổi độ dài khoảng chờ, đặt biến môi trường CLAUDE_AX_STARTUP_QUIET_MS (đơn vị mili-giây, mặc định 3000, đặt 0 để bỏ qua hoàn toàn, tối đa 600000 - 10 phút). Yêu cầu Claude Code v2.1.217 trở lên.

Tắt chế độ screen reader

Đảo ngược cách bạn đã bật: chạy không kèm flag, unset biến môi trường, hoặc đặt axScreenReader thành false. Đặt CLAUDE_AX_SCREEN_READER=0 sẽ giữ chế độ tắt kể cả khi setting đang là true.

Screen reader của bạn sẽ nghe thấy gì

Ở chế độ screen reader, Claude Code chỉ in text phẳng:

• không có ký tự vẽ khung cho giao diện
• không dùng màu sắc làm tín hiệu duy nhất
• không redraw nội dung chưa đổi; spinner tiến trình hiện như text tĩnh
• bảng (table) trong câu trả lời của Claude đọc thành các câu dạng Header: value thay vì lưới ký tự khung (yêu cầu v2.1.198 trở lên; bản cũ vẫn vẽ bảng dạng lưới ngay cả khi bật chế độ này)

Output tích lại trong scrollback của terminal, nên bạn có thể đọc lại các lượt trước bằng lệnh review của screen reader hoặc tìm kiếm trong terminal.

Chế độ screen reader luôn render dạng text cuộn phẳng, kể cả khi bạn đã bật fullscreen rendering qua setting tui - setting đó không có tác dụng khi chế độ screen reader đang bật. Các phiên background đã attach vẫn render fullscreen; xem Giới hạn đã biết.

Mỗi tin nhắn trong transcript bắt đầu bằng một nhãn mà screen reader sẽ đọc, cho biết đây là loại nội dung gì:

Nhãn	Ý nghĩa
you:	Tin nhắn của bạn
claude:	Câu trả lời của Claude
tool:	Hoạt động của tool, ví dụ sửa file hoặc chạy lệnh
tool error:	Một tool bị lỗi
error:	Lỗi trong hội thoại, ví dụ request API thất bại
Permission Required:	Permission prompt đang chờ bạn trả lời
Cost:	Tóm tắt chi phí phiên khi Claude Code thoát, nếu tài khoản của bạn hiện chi phí

Nhãn cũng tìm kiếm được, nên bạn có thể nhảy giữa các phần của transcript bằng cách tìm trong scrollback của terminal.

Con trỏ terminal đi theo caret nhập liệu, nên lệnh “đọc dòng hiện tại” của screen reader sẽ trả lời đúng câu hỏi “tôi đang ở đâu” bằng đúng prompt bạn đang soạn.

Kể từ v2.1.219, khi bạn gõ ở cuối dòng input, Claude Code chỉ in ra các ký tự bạn vừa gõ, nên screen reader chỉ đọc lại đúng các ký tự đó (bản cũ hơn vẽ lại toàn bộ dòng input mỗi lần gõ phím, khiến screen reader đọc lại cả dòng liên tục).

Kể từ v2.1.218, khi bạn xoá một từ hoặc một dòng trong input, Claude Code sẽ đọc to phần text đã xoá. Việc này áp dụng khi:

• Xoá một từ bằng Ctrl+W, Option+Delete trên macOS, hoặc Ctrl+Backspace trên Windows
• Xoá về đầu dòng bằng Ctrl+U hoặc Cmd+Backspace
• Xoá tới cuối dòng bằng Ctrl+K

Xem thêm các phím soạn thảo text ở Interactive mode.

Kể từ v2.1.210, chuyển permission mode bằng Shift+Tab sẽ đọc to chế độ bạn vừa chuyển tới, ví dụ [plan mode on] hoặc [accept edits on]. Claude Code chỉ đọc một lần, không lặp lại ở các lần redraw sau.

Nhảy giữa các lượt hội thoại

Claude Code phát các marker OSC 133 (shell-integration) tại ranh giới mỗi lượt, nên phím “nhảy tới prompt trước đó” của terminal có thể di chuyển giữa các lượt mà không cần đọc hết transcript:

• iTerm2: Cmd+Shift+Up
• VS Code terminal: Ctrl+Up (Windows), Cmd+Up (macOS)
• Windows Terminal: không có phím mặc định; tự bind action scrollToMark trong settings
• Kitty và Ghostty: xem tài liệu terminal để biết phím nhảy-tới-prompt

macOS Terminal không phản ứng với các marker này, và Claude Code cũng không phát chúng trong WezTerm. Ở các terminal đó, tìm nhãn you: trong scrollback thay thế.

Trả lời menu và prompt

Ở chế độ screen reader, các menu bạn thường điều hướng bằng phím mũi tên - kể cả permission prompt - chuyển thành danh sách đánh số. Mỗi lựa chọn được đọc thành một dòng có số thứ tự, theo sau là prompt Enter selection nêu rõ khoảng số hợp lệ. Gõ số của lựa chọn rồi Enter.

• Để huỷ một menu có thể huỷ: nhấn Escape (prompt sẽ kết thúc bằng or Escape to cancel).
• Nếu bạn gõ một số ngoài danh sách: Claude Code sẽ đọc lại khoảng hợp lệ để bạn thử lại.

Prompt dạng có/không yêu cầu gõ câu trả lời thay vì chọn giữa hai lựa chọn bằng phím mũi tên. Gõ y hoặc n rồi Enter (yes/no cũng dùng được).

Nghe khi Claude Code cần bạn

Ở chế độ screen reader, Claude Code rung chuông terminal khi cần bạn chú ý, để bạn không phải liên tục kiểm tra transcript. Chuông reo khi:

• Claude hoàn thành một câu trả lời
• một permission prompt xuất hiện
• một tool chạy lâu hơn 5 giây vừa hoàn thành

Chuông này là cảnh báo chuẩn của terminal bạn dùng - để tắt, đổi setting chuông trong ứng dụng terminal. Chuông không yêu cầu phải bật chế độ screen reader: ngoài chế độ này, đặt preferredNotifChannel thành "terminal_bell" để có cảnh báo tương tự khi Claude đang chờ bạn. Xem Lấy terminal bell hoặc thông báo.

Cài đặt trợ năng ngoài chế độ screen reader

Các tuỳ chọn dưới đây phục vụ nhu cầu trợ năng khác, không liên quan tới screen reader mode, và đều hoạt động song song với nó:

• Biến môi trường CLAUDE_CODE_ACCESSIBILITY dành cho screen magnifier. Đặt CLAUDE_CODE_ACCESSIBILITY=1 để giữ con trỏ terminal gốc luôn hiển thị, giúp magnifier (ví dụ macOS Zoom) theo dõi được vị trí con trỏ. Con trỏ đi theo focus bàn phím: caret nhập liệu khi bạn gõ, và dòng đang chọn khi bạn di chuyển trong menu/panel như /config, /plugin bằng phím mũi tên (việc theo dõi dòng trong menu/panel yêu cầu v2.1.218 trở lên).
• Setting prefersReducedMotion giảm hoặc tắt spinner, hiệu ứng shimmer, và các animation khác mà không đổi phần còn lại của giao diện.
• Setting theme chọn màu giao diện, gồm cả theme thân thiện người mù màu dark-daltonized và light-daltonized.

Giới hạn đã biết

Một số hành vi chưa được thích ứng cho chế độ screen reader:

• Chế độ screen reader không tự động bật khi phát hiện có screen reader đang chạy.
• Claude Code không đọc to khi permission mode đổi bằng cách khác ngoài Shift+Tab, ví dụ vào plan mode từ một lệnh.
• Attach vào một phiên background bằng claude attach hoặc từ agent view sẽ vào alternate screen của terminal, vốn không có scrollback gốc - giống hành vi các phiên attach khác. Để thoát ra, nhấn Left Arrow ở prompt rỗng, hoặc Ctrl+Z nếu một dialog đang có focus.
• Claude Code chỉ đọc chi phí trong tóm tắt in ra lúc thoát, không đọc theo từng lượt.
• Chế độ screen reader không thay đổi hành vi của non-interactive mode (-p) - chế độ này vốn đã in text phẳng và vẫn là lựa chọn thay thế tốt cho scripting.

Báo lỗi

Nếu có gì đó không hoạt động đúng với screen reader, magnifier, hay terminal của bạn, mở issue trên issue tracker của Claude Code và ghi rõ công cụ trợ năng bạn dùng trong tiêu đề. Kèm theo hệ điều hành, ứng dụng terminal, và tên + phiên bản công cụ trợ năng.

Tài nguyên liên quan

• Settings: các mục axScreenReader, prefersReducedMotion, theme, preferredNotifChannel
• Environment variables: các mục CLAUDE_AX_SCREEN_READER và CLAUDE_CODE_ACCESSIBILITY
• CLI reference: flag --ax-screen-reader
• Cấu hình terminal: chuông, thông báo, và theme ngoài chế độ screen reader
• Non-interactive mode: chạy claude -p theo script, in text phẳng mà không cần bật chế độ screen reader

Chú ý

Các flag, biến môi trường, và số phiên bản tối thiểu ở trên có thể đã đổi theo thời gian - kiểm tra lại với claude --version và tài liệu gốc nếu có gì không khớp.

Nguồn

Dịch và biên soạn từ Use Claude Code with a screen reader.