Tuỳ chỉnh phím tắt (Keybindings)

Claude Code hỗ trợ tuỳ chỉnh phím tắt. Chạy /keybindings để tạo hoặc mở file cấu hình tại ~/.claude/keybindings.json.

File cấu hình

File cấu hình keybindings là một object với mảng bindings. Mỗi block chỉ định một context và một map từ keystroke sang action.

Ghi chú

Thay đổi trong file keybindings được tự động phát hiện và áp dụng, không cần restart Claude Code.

Field	Mô tả
$schema	URL JSON Schema tuỳ chọn, để editor gợi ý autocomplete
$docs	URL tài liệu tuỳ chọn
bindings	Mảng các block binding theo context

Ví dụ này bind Ctrl+E để mở external editor trong context chat, và unbind Ctrl+U:

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "$docs": "https://code.claude.com/docs/en/keybindings",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+u": null
      }
    }
  ]
}

Các context

Mỗi block binding chỉ định một context nơi binding đó áp dụng:

Context	Mô tả
Global	Áp dụng ở mọi nơi trong app
Chat	Khu vực chat input chính
Autocomplete	Menu autocomplete đang mở
Settings	Menu settings
Confirmation	Dialog permission và confirmation
Tabs	Component điều hướng tab
Help	Menu help đang hiện
Transcript	Transcript viewer
HistorySearch	Chế độ tìm kiếm lịch sử (Ctrl+R)
Task	Background task đang chạy
ThemePicker	Dialog theme picker
Attachments	Điều hướng ảnh đính kèm trong dialog chọn
Footer	Điều hướng chỉ báo footer (task, team, diff, artifact)
MessageSelector	Chọn tin nhắn trong dialog rewind/summarize
DiffDialog	Điều hướng diff viewer
ModelPicker	Effort level trong model picker
Select	Component select/list dùng chung
Plugin	Dialog plugin (browse, discover, manage)
Scroll	Cuộn hội thoại và chọn text trong fullscreen mode

Trước v2.1.205, tồn tại một context Doctor và action doctor:fix cho màn hình chẩn đoán /doctor - đã bị gỡ.

Các action khả dụng

Action theo định dạng namespace:action, ví dụ chat:submit để gửi tin nhắn hoặc app:toggleTodos để hiện task list. Mỗi context có tập action riêng.

App actions

Action khả dụng trong context Global:

Action	Mặc định	Mô tả
app:interrupt	Ctrl+C	Huỷ thao tác hiện tại
app:exit	Ctrl+D	Thoát Claude Code. Nhấn hai lần trong 800ms để xác nhận
app:redraw	(chưa bind)	Buộc redraw terminal
app:toggleTodos	Ctrl+T	Bật/tắt checklist to-do của Claude. Không phải view /tasks cho background task
app:toggleTranscript	Ctrl+O	Bật/tắt transcript verbose

History actions

Action để điều hướng lịch sử lệnh:

Action	Mặc định	Mô tả
history:search	Ctrl+R	Mở tìm kiếm lịch sử
history:previous	Up	Mục lịch sử trước
history:next	Down	Mục lịch sử sau

Chat actions

Action khả dụng trong context Chat:

Action	Mặc định	Mô tả
chat:cancel	Escape	Huỷ input hiện tại
chat:clearInput	Ctrl+L	Buộc redraw toàn màn hình, giữ nguyên input. Ở fullscreen rendering, nhấn hai lần trong hai giây để chạy /clear
chat:clearScreen	Cmd+K	Ở fullscreen rendering, nhấn hai lần trong hai giây để chạy /clear
chat:killAgents	Ctrl+X Ctrl+K	Dừng mọi subagent background đang chạy trong phiên này
chat:cycleMode	Shift+Tab*	Cycle qua các permission mode
chat:modelPicker	Meta+P	Mở model picker
chat:fastMode	Meta+O	Bật/tắt fast mode
chat:thinkingToggle	Meta+T	Bật/tắt extended thinking
chat:submit	Enter	Gửi tin nhắn
chat:newline	Ctrl+J	Chèn dòng mới mà không submit
chat:undo	Ctrl+_, Ctrl+Shift+-	Undo hành động gần nhất
chat:externalEditor	Ctrl+G, Ctrl+X Ctrl+E	Mở bằng external editor
chat:stash	Ctrl+S	Stash prompt hiện tại
chat:imagePaste	Ctrl+V (Alt+V trên Windows/WSL)	Paste ảnh từ clipboard. Trên WSL, cả hai shortcut đều được bind mặc định

*Trên Windows không có VT mode (Node <24.2.0/<22.17.0, Bun <1.2.23), mặc định là Meta+M.

Autocomplete actions

Action khả dụng trong context Autocomplete:

Action	Mặc định	Mô tả
autocomplete:accept	Tab	Chấp nhận gợi ý
autocomplete:dismiss	Escape	Đóng menu
autocomplete:previous	Up	Gợi ý trước
autocomplete:next	Down	Gợi ý sau

Confirmation actions

Action khả dụng trong context Confirmation:

Action	Mặc định	Mô tả
confirm:yes	Y, Enter	Xác nhận hành động
confirm:no	N, Escape	Từ chối hành động
confirm:previous	Up	Tuỳ chọn trước
confirm:next	Down	Tuỳ chọn sau
confirm:nextField	Tab	Field kế tiếp
confirm:previousField	(chưa bind)	Field trước
confirm:toggle	Space	Bật/tắt lựa chọn
confirm:cycleMode	Shift+Tab	Cycle permission mode
confirm:toggleExplanation	Ctrl+E	Bật/tắt giải thích do model sinh cho lệnh trên permission prompt của Bash/PowerShell

Permission actions

Action khả dụng trong context Confirmation cho dialog permission:

Action	Mặc định	Mô tả
permission:toggleDebug	(chưa bind)	Bật/tắt thông tin debug permission. Mặc định trước đây là Ctrl+D, bị gỡ ở v2.1.146 vì trùng với app:exit

Transcript actions

Action khả dụng trong context Transcript:

Action	Mặc định	Mô tả
transcript:toggleShowAll	Ctrl+E	Bật/tắt hiện toàn bộ nội dung
transcript:exit	q, Ctrl+C, Escape	Thoát transcript view

transcript:toggleShowAll chỉ áp dụng ở renderer mặc định; trong fullscreen rendering, transcript viewer không có toggle show-all.

History search actions

Action khả dụng trong context HistorySearch:

Action	Mặc định	Mô tả
historySearch:next	Ctrl+R	Kết quả khớp tiếp theo
historySearch:accept	Escape, Tab	Chấp nhận lựa chọn
historySearch:cancel	Ctrl+C	Huỷ tìm kiếm
historySearch:execute	Enter	Chạy lệnh đã chọn
historySearch:cycleScope	Ctrl+S	Cycle phạm vi: session, project, everywhere

Mặc định của historySearch:next, historySearch:accept, historySearch:cancel, historySearch:execute áp dụng cho tìm kiếm lịch sử inline ở renderer mặc định, vốn luôn tìm prompt từ mọi project. historySearch:cycleScope chỉ có tác dụng ở fullscreen rendering, nơi Ctrl+R mở một dialog tìm kiếm riêng và Ctrl+S cycle phạm vi của nó. Các phím khác trong dialog này cố định, không rebind được: Enter/Tab đặt kết quả đang chọn vào ô input, Esc huỷ.

Task actions

Action khả dụng trong context Task:

Action	Mặc định	Mô tả
task:background	Ctrl+B, Ctrl+X Ctrl+B	Đưa task hiện tại chạy background. Chord Ctrl+X Ctrl+B yêu cầu v2.1.169 trở lên, dùng để tránh xung đột prefix của tmux

Theme actions

Action khả dụng trong context ThemePicker:

Action	Mặc định	Mô tả
theme:toggleSyntaxHighlighting	Ctrl+T	Bật/tắt syntax highlighting

Help actions

Action khả dụng trong context Help:

Action	Mặc định	Mô tả
help:dismiss	Escape	Đóng menu help

Tabs actions

Action khả dụng trong context Tabs:

Action	Mặc định	Mô tả
tabs:next	Tab, Right	Tab tiếp theo
tabs:previous	Shift+Tab, Left	Tab trước

Attachments actions

Action khả dụng trong context Attachments:

Action	Mặc định	Mô tả
attachments:next	Right	Ảnh đính kèm tiếp theo
attachments:previous	Left	Ảnh đính kèm trước
attachments:remove	Backspace, Delete	Xoá ảnh đính kèm đang chọn
attachments:exit	Down, Escape	Thoát điều hướng ảnh đính kèm

Footer actions

Action khả dụng trong context Footer:

Action	Mặc định	Mô tả
footer:next	Right	Mục footer tiếp theo
footer:previous	Left	Mục footer trước
footer:up	Up	Di chuyển lên trong footer (bỏ chọn khi ở trên cùng)
footer:down	Down	Di chuyển xuống trong footer
footer:openSelected	Enter	Mở mục footer đang chọn
footer:clearSelection	Escape	Bỏ chọn footer
footer:dismiss	Backspace, Delete	Bỏ link artifact đang chọn khỏi footer; artifact đã publish không bị ảnh hưởng. Ở các hàng footer khác, phím này không có tác dụng. Yêu cầu v2.1.217 trở lên

Message selector actions

Action khả dụng trong context MessageSelector:

Action	Mặc định	Mô tả
messageSelector:up	Up, K, Ctrl+P	Di chuyển lên trong danh sách
messageSelector:down	Down, J, Ctrl+N	Di chuyển xuống trong danh sách
messageSelector:top	Ctrl+Up, Shift+Up, Meta+Up, Shift+K	Nhảy lên đầu
messageSelector:bottom	Ctrl+Down, Shift+Down, Meta+Down, Shift+J	Nhảy xuống cuối
messageSelector:select	Enter	Chọn tin nhắn

Diff actions

Action khả dụng trong context DiffDialog:

Action	Mặc định	Mô tả
diff:dismiss	Escape	Đóng diff viewer; từ detail view, quay lại danh sách file thay vì đóng hẳn
diff:previousSource	Left	Nguồn diff trước
diff:nextSource	Right	Nguồn diff sau
diff:previousFile	Up, K	File trước trong danh sách; cuộn lên một dòng trong detail view
diff:nextFile	Down, J	File sau trong danh sách; cuộn xuống một dòng trong detail view
diff:viewDetails	Enter	Xem chi tiết diff
diff:back	(chưa bind)	Quay lại trong diff viewer. Escape thực hiện việc này qua diff:dismiss. Mặc định trước đây là Left ở detail view, đã bị gỡ ở v2.1.203

Detail view của diff cũng bind các phím kiểu pager theo scroll actions chuẩn. Các binding này thuộc context DiffDialog, chỉ áp dụng ở detail view; mặc định của context Scroll liệt kê ở Scroll actions không đổi.

Action	Mặc định	Mô tả
scroll:pageUp	PageUp	Cuộn lên nửa viewport
scroll:pageDown	PageDown	Cuộn xuống nửa viewport
scroll:fullPageUp	Shift+Space, B	Cuộn lên một viewport đầy
scroll:fullPageDown	Space	Cuộn xuống một viewport đầy
scroll:top	G, Home	Nhảy lên đầu
scroll:bottom	Shift+G, End	Nhảy xuống cuối

Model picker actions

Action khả dụng trong context ModelPicker:

Action	Mặc định	Mô tả
modelPicker:decreaseEffort	Left	Giảm effort level
modelPicker:increaseEffort	Right	Tăng effort level
modelPicker:thisSessionOnly	s	Áp dụng model đang chọn chỉ cho phiên này

Select actions

Action khả dụng trong context Select:

Action	Mặc định	Mô tả
select:next	Down, J, Ctrl+N	Tuỳ chọn tiếp theo
select:previous	Up, K, Ctrl+P	Tuỳ chọn trước
select:accept	Enter	Chấp nhận lựa chọn
select:cancel	Escape	Huỷ lựa chọn

Plugin actions

Action khả dụng trong context Plugin:

Action	Mặc định	Mô tả
plugin:toggle	Space	Bật/tắt chọn plugin
plugin:install	I	Cài các plugin đang chọn
plugin:favorite	F	Đánh dấu yêu thích plugin đang chọn để nó sắp gần đầu tab Installed

Settings actions

Action khả dụng trong context Settings. select:accept và confirm:no tái sử dụng từ context Select và Confirmation với hành vi riêng cho Settings: thay đổi áp dụng ngay khi bạn đổi một setting, nên Escape đóng panel với thay đổi đã lưu chứ không phải từ chối.

Action	Mặc định	Mô tả
settings:search	/	Vào chế độ tìm kiếm
settings:retry	R	Thử tải lại dữ liệu usage khi lỗi
select:accept	Enter, Space	Đổi setting đang chọn hoặc mở submenu
confirm:no	Escape	Đóng panel - thay đổi đã được lưu sẵn

Voice actions

Action khả dụng trong context Chat khi voice dictation đang bật:

Action	Mặc định	Mô tả
voice:pushToTalk	Space	Đọc chính tả một prompt. Giữ hoặc tap tuỳ mode của /voice

Scroll actions

Action khả dụng trong context Scroll khi fullscreen rendering đang bật:

Action	Mặc định	Mô tả
scroll:lineUp	(chưa bind)	Cuộn lên một dòng. Cuộn chuột kích hoạt action này
scroll:lineDown	(chưa bind)	Cuộn xuống một dòng. Cuộn chuột kích hoạt action này
scroll:pageUp	PageUp	Cuộn lên nửa chiều cao viewport
scroll:pageDown	PageDown	Cuộn xuống nửa chiều cao viewport
scroll:top	Ctrl+Home	Nhảy tới đầu hội thoại
scroll:bottom	Ctrl+End	Nhảy tới tin nhắn mới nhất và bật lại auto-follow
scroll:halfPageUp	(chưa bind)	Cuộn lên nửa chiều cao viewport. Giống scroll:pageUp, có sẵn để rebind kiểu vi
scroll:halfPageDown	(chưa bind)	Cuộn xuống nửa chiều cao viewport. Giống scroll:pageDown, có sẵn để rebind kiểu vi
scroll:fullPageUp	(chưa bind)	Cuộn lên một viewport đầy
scroll:fullPageDown	(chưa bind)	Cuộn xuống một viewport đầy
selection:copy	Ctrl+Shift+C / Cmd+C	Copy text đang chọn vào clipboard
selection:clear	(chưa bind)	Bỏ chọn text hiện tại
selection:extendLeft	Shift+Left	Mở rộng vùng chọn sang trái một cột
selection:extendRight	Shift+Right	Mở rộng vùng chọn sang phải một cột
selection:extendUp	Shift+Up	Mở rộng vùng chọn lên một hàng. Cuộn viewport khi vùng chọn chạm mép trên
selection:extendDown	Shift+Down	Mở rộng vùng chọn xuống một hàng. Cuộn viewport khi vùng chọn chạm mép dưới
selection:extendLineStart	Shift+Home	Mở rộng vùng chọn tới đầu dòng
selection:extendLineEnd	Shift+End	Mở rộng vùng chọn tới cuối dòng

Cú pháp keystroke

Modifier

Dùng phím modifier với dấu +:

• ctrl hoặc control - phím Control
• shift - phím Shift
• alt, opt, option, hoặc meta - phím Alt trên Windows/Linux, phím Option trên macOS
• cmd, command, super, hoặc win - phím Command trên macOS, phím Windows trên Windows, phím Super trên Linux

Nhóm cmd chỉ được phát hiện ở terminal báo cáo modifier Super, ví dụ terminal hỗ trợ Kitty keyboard protocol hoặc chế độ modifyOtherKeys của xterm. Hầu hết terminal không gửi nó, nên dùng ctrl hoặc meta cho binding bạn muốn hoạt động ở mọi nơi.

Ví dụ:

ctrl+k          Ctrl + K
shift+tab       Shift + Tab
meta+p          Option + P trên macOS, Alt + P nơi khác
ctrl+shift+c    Nhiều modifier

Chữ hoa

Một chữ cái viết hoa đơn lẻ ngầm định kèm Shift. Ví dụ K tương đương shift+k. Hữu ích cho binding kiểu vim, nơi chữ hoa/thường có ý nghĩa khác nhau.

Chữ hoa kèm modifier (ví dụ ctrl+K) chỉ mang tính stylistic, không ngầm định Shift: ctrl+K giống hệt ctrl+k.

Chord

Chord là chuỗi keystroke cách nhau bằng dấu cách:

ctrl+k ctrl+s   Nhấn Ctrl+K, nhả ra, rồi Ctrl+S

Phím đặc biệt

• escape hoặc esc - phím Escape
• enter hoặc return - phím Enter
• tab - phím Tab
• space - phím Space
• up, down, left, right - phím mũi tên
• backspace, delete - phím xoá

Unbind shortcut mặc định

Đặt một action thành null để unbind shortcut mặc định:

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+s": null
      }
    }
  ]
}

Cách này cũng dùng được cho chord binding. Unbind hết các chord chung một prefix sẽ giải phóng prefix đó để dùng làm single-key binding. Một chord ở bất kỳ context nào đang active vẫn giữ prefix của nó, nên bạn phải unbind từng chord ở đúng context đã định nghĩa nó.

Nhóm Ctrl+X mặc định trải trên hai context: ctrl+x ctrl+k và ctrl+x ctrl+e ở Chat, và ctrl+x ctrl+b ở Task. Để giành lại ctrl+x làm single-key binding, unbind tất cả:

{
  "bindings": [
    {
      "context": "Task",
      "bindings": {
        "ctrl+x ctrl+b": null
      }
    },
    {
      "context": "Chat",
      "bindings": {
        "ctrl+x ctrl+k": null,
        "ctrl+x ctrl+e": null,
        "ctrl+x": "chat:newline"
      }
    }
  ]
}

Nếu bạn chỉ unbind một phần chord trên một prefix, nhấn prefix vẫn vào chế độ chờ chord cho các binding còn lại.

Shortcut reserved

Các shortcut sau không thể rebind:

Shortcut	Lý do
Ctrl+C	Interrupt/cancel hardcoded
Ctrl+D	Exit hardcoded
Ctrl+M	Giống hệt Enter trong terminal (cả hai đều gửi CR)
Caps Lock	Không được gửi tới ứng dụng terminal

Xung đột với terminal

Một số shortcut có thể xung đột với terminal multiplexer:

Shortcut	Xung đột
Ctrl+B	Prefix của tmux (nhấn hai lần để gửi)
Ctrl+A	Prefix của GNU screen
Ctrl+Z	Tạm dừng process Unix (SIGTSTP)

Tương tác với Vim mode

Khi vim mode được bật qua /config → Editor mode, keybinding và vim mode hoạt động độc lập:

• Vim mode xử lý input ở cấp text input (di chuyển con trỏ, mode, motion)
• Keybinding xử lý action ở cấp component (toggle todos, submit…)
• Phím Escape trong vim mode chuyển INSERT sang NORMAL mode; nó không kích hoạt chat:cancel
• Hầu hết shortcut Ctrl+phím đi xuyên qua vim mode tới hệ thống keybinding
• Phím vim không remap được qua file keybindings. Để map một chuỗi hai phím ở INSERT mode như jj thành Escape, dùng setting vimInsertModeRemaps
• Ở vim NORMAL mode, ? hiện help menu (hành vi vim)
• Ở vim NORMAL mode, / mở tìm kiếm lịch sử, giống Ctrl+R ở chế độ thường

Validation

Claude Code validate file keybindings của bạn và cảnh báo với:

• Lỗi parse (JSON hoặc cấu trúc không hợp lệ)
• Tên context không hợp lệ
• Xung đột với shortcut reserved
• Xung đột với terminal multiplexer
• Binding trùng lặp trong cùng một context

Claude Code báo cảnh báo khi file load và ghi từng cảnh báo vào debug log. Chạy Claude Code với --debug để xem chi tiết.

Chú ý

Danh sách action, phím mặc định, và context ở trên khá dài và có thể thay đổi giữa các phiên bản Claude Code - nếu một binding không hoạt động như mô tả, đối chiếu lại với tài liệu gốc hoặc chạy /keybindings để xem cấu hình thực tế trên máy bạn.

Nguồn

Dịch và biên soạn từ Customize keyboard shortcuts.