17. 키보드 단축키 커스터마이징
바인딩 구문·컨텍스트·수정자 키·충돌 해결 등 단축키 커스터마이징 레퍼런스
키보드 단축키 커스터마이징
keybindings 설정 파일을 사용하여 Claude Code의 키보드 단축키를 커스터마이징할 수 있습니다.
Claude Code는 커스터마이징 가능한 키보드 단축키를 지원합니다. /keybindings를 실행하면 ~/.claude/keybindings.json에 설정 파일을 생성하거나 열 수 있습니다.
설정 파일
keybindings 설정 파일은 bindings 배열을 가진 객체입니다. 각 블록은 컨텍스트와 키 입력-액션 매핑을 지정합니다.
참고: keybindings 파일의 변경 사항은 자동으로 감지되어 Claude Code를 재시작하지 않아도 적용됩니다.
| 필드 | 설명 |
|---|---|
$schema | 편집기 자동완성을 위한 선택적 JSON Schema URL |
$docs | 선택적 문서 URL |
bindings | 컨텍스트별 바인딩 블록 배열 |
이 예제는 Chat 컨텍스트에서 Ctrl+E를 외부 편집기 열기에 바인딩하고, 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
}
}
]
}
컨텍스트
각 바인딩 블록은 바인딩이 적용되는 컨텍스트를 지정합니다:
| 컨텍스트 | 설명 |
|---|---|
Global | 앱 전체에 적용 |
Chat | 메인 채팅 입력 영역 |
Autocomplete | 자동완성 메뉴가 열려 있을 때 |
Settings | 설정 메뉴 (Escape로만 닫기) |
Confirmation | 권한 및 확인 대화상자 |
Tabs | 탭 네비게이션 컴포넌트 |
Help | 도움말 메뉴가 표시되어 있을 때 |
Transcript | 트랜스크립트 뷰어 |
HistorySearch | 히스토리 검색 모드 (Ctrl+R) |
Task | 백그라운드 작업 실행 중 |
ThemePicker | 테마 선택 대화상자 |
Attachments | 이미지/첨부파일 바 네비게이션 |
Footer | 푸터 인디케이터 네비게이션 (작업, 팀, diff) |
MessageSelector | 되감기 및 요약 대화상자 메시지 선택 |
DiffDialog | Diff 뷰어 네비게이션 |
ModelPicker | 모델 선택기 노력 수준 |
Select | 일반 선택/목록 컴포넌트 |
Plugin | 플러그인 대화상자 (탐색, 발견, 관리) |
사용 가능한 액션
액션은 namespace:action 형식을 따릅니다. 예를 들어 chat:submit은 메시지를 전송하고, app:toggleTodos는 작업 목록을 표시합니다. 각 컨텍스트에는 사용 가능한 특정 액션이 있습니다.
App 액션
Global 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
app:interrupt | Ctrl+C | 현재 작업 취소 |
app:exit | Ctrl+D | Claude Code 종료 |
app:toggleTodos | Ctrl+T | 작업 목록 표시/숨기기 |
app:toggleTranscript | Ctrl+O | 상세 트랜스크립트 토글 |
History 액션
명령어 히스토리 탐색을 위한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
history:search | Ctrl+R | 히스토리 검색 열기 |
history:previous | Up | 이전 히스토리 항목 |
history:next | Down | 다음 히스토리 항목 |
Chat 액션
Chat 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
chat:cancel | Escape | 현재 입력 취소 |
chat:cycleMode | Shift+Tab* | 권한 모드 순환 |
chat:modelPicker | Cmd+P / Meta+P | 모델 선택기 열기 |
chat:thinkingToggle | Cmd+T / Meta+T | 확장 사고 토글 |
chat:submit | Enter | 메시지 전송 |
chat:undo | Ctrl+_ | 마지막 작업 실행 취소 |
chat:externalEditor | Ctrl+G | 외부 편집기에서 열기 |
chat:stash | Ctrl+S | 현재 프롬프트 임시 저장 |
chat:imagePaste | Ctrl+V (Alt+V on Windows) | 이미지 붙여넣기 |
*Windows에서 VT 모드가 없는 경우 (Node <24.2.0/<22.17.0, Bun <1.2.23), 기본값은 Meta+M입니다.
Autocomplete 액션
Autocomplete 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
autocomplete:accept | Tab | 제안 수락 |
autocomplete:dismiss | Escape | 메뉴 닫기 |
autocomplete:previous | Up | 이전 제안 |
autocomplete:next | Down | 다음 제안 |
Confirmation 액션
Confirmation 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
confirm:yes | Y, Enter | 작업 확인 |
confirm:no | N, Escape | 작업 거부 |
confirm:previous | Up | 이전 옵션 |
confirm:next | Down | 다음 옵션 |
confirm:nextField | Tab | 다음 필드 |
confirm:previousField | (미지정) | 이전 필드 |
confirm:cycleMode | Shift+Tab | 권한 모드 순환 |
confirm:toggleExplanation | Ctrl+E | 권한 설명 토글 |
Permission 액션
권한 대화상자에 대해 Confirmation 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
permission:toggleDebug | Ctrl+D | 권한 디버그 정보 토글 |
Transcript 액션
Transcript 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
transcript:toggleShowAll | Ctrl+E | 전체 내용 표시 토글 |
transcript:exit | Ctrl+C, Escape | 트랜스크립트 뷰 종료 |
History search 액션
HistorySearch 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
historySearch:next | Ctrl+R | 다음 일치 항목 |
historySearch:accept | Escape, Tab | 선택 수락 |
historySearch:cancel | Ctrl+C | 검색 취소 |
historySearch:execute | Enter | 선택한 명령어 실행 |
Task 액션
Task 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
task:background | Ctrl+B | 현재 작업을 백그라운드로 |
Theme 액션
ThemePicker 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
theme:toggleSyntaxHighlighting | Ctrl+T | 구문 강조 토글 |
Help 액션
Help 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
help:dismiss | Escape | 도움말 메뉴 닫기 |
Tabs 액션
Tabs 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
tabs:next | Tab, Right | 다음 탭 |
tabs:previous | Shift+Tab, Left | 이전 탭 |
Attachments 액션
Attachments 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
attachments:next | Right | 다음 첨부파일 |
attachments:previous | Left | 이전 첨부파일 |
attachments:remove | Backspace, Delete | 선택한 첨부파일 제거 |
attachments:exit | Down, Escape | 첨부파일 바 종료 |
Footer 액션
Footer 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
footer:next | Right | 다음 푸터 항목 |
footer:previous | Left | 이전 푸터 항목 |
footer:openSelected | Enter | 선택한 푸터 항목 열기 |
footer:clearSelection | Escape | 푸터 선택 해제 |
Message selector 액션
MessageSelector 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
messageSelector:up | Up, K | 목록에서 위로 |
messageSelector:down | Down, J | 목록에서 아래로 |
messageSelector:top | Ctrl+Up, Shift+Up, Meta+Up, Shift+K | 맨 위로 이동 |
messageSelector:bottom | Ctrl+Down, Shift+Down, Meta+Down, Shift+J | 맨 아래로 이동 |
messageSelector:select | Enter | 메시지 선택 |
Diff 액션
DiffDialog 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
diff:dismiss | Escape | Diff 뷰어 닫기 |
diff:previousSource | Left | 이전 diff 소스 |
diff:nextSource | Right | 다음 diff 소스 |
diff:previousFile | Up | diff에서 이전 파일 |
diff:nextFile | Down | diff에서 다음 파일 |
diff:viewDetails | Enter | Diff 상세 보기 |
diff:back | (컨텍스트별 지정) | Diff 뷰어에서 뒤로 |
Model picker 액션
ModelPicker 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
modelPicker:decreaseEffort | Left | 노력 수준 감소 |
modelPicker:increaseEffort | Right | 노력 수준 증가 |
Select 액션
Select 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
select:next | Down, J, Ctrl+N | 다음 옵션 |
select:previous | Up, K, Ctrl+P | 이전 옵션 |
select:accept | Enter | 선택 수락 |
select:cancel | Escape | 선택 취소 |
Plugin 액션
Plugin 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
plugin:toggle | Space | 플러그인 선택 토글 |
plugin:install | I | 선택한 플러그인 설치 |
Settings 액션
Settings 컨텍스트에서 사용 가능한 액션:
| 액션 | 기본값 | 설명 |
|---|---|---|
settings:search | / | 검색 모드 진입 |
settings:retry | R | 사용량 데이터 로딩 재시도 (오류 발생 시) |
키 입력 구문
수정자 키
+ 구분자를 사용하여 수정자 키를 조합합니다:
ctrl또는control- Control 키alt,opt, 또는option- Alt/Option 키shift- Shift 키meta,cmd, 또는command- Meta/Command 키
예시:
ctrl+k 수정자와 단일 키
shift+tab Shift + Tab
meta+p Command/Meta + P
ctrl+shift+c 다중 수정자
대문자
단독 대문자는 Shift를 포함합니다. 예를 들어, K는 shift+k와 동일합니다. 이는 대문자와 소문자 키가 다른 의미를 가지는 vim 스타일 바인딩에 유용합니다.
수정자와 함께 사용하는 대문자 (예: ctrl+K)는 스타일 표기로 취급되며 Shift를 포함하지 않습니다 — ctrl+K는 ctrl+k와 동일합니다.
코드
코드는 공백으로 구분된 키 입력 시퀀스입니다:
ctrl+k ctrl+s Ctrl+K를 누른 후 놓고, 그다음 Ctrl+S를 누릅니다
특수 키
escape또는esc- Escape 키enter또는return- Enter 키tab- Tab 키space- 스페이스 바up,down,left,right- 방향 키backspace,delete- 삭제 키
기본 단축키 해제
액션을 null로 설정하면 기본 단축키를 해제할 수 있습니다:
{
"bindings": [
{
"context": "Chat",
"bindings": {
"ctrl+s": null
}
}
]
}
예약된 단축키
다음 단축키는 다시 바인딩할 수 없습니다:
| 단축키 | 이유 |
|---|---|
| Ctrl+C | 하드코딩된 인터럽트/취소 |
| Ctrl+D | 하드코딩된 종료 |
터미널 충돌
일부 단축키는 터미널 멀티플렉서와 충돌할 수 있습니다:
| 단축키 | 충돌 |
|---|---|
| Ctrl+B | tmux 접두사 (전송하려면 두 번 누르기) |
| Ctrl+A | GNU screen 접두사 |
| Ctrl+Z | Unix 프로세스 일시 중지 (SIGTSTP) |
Vim 모드 상호작용
vim 모드가 활성화되면 (/vim), keybindings와 vim 모드는 독립적으로 작동합니다:
- Vim 모드는 텍스트 입력 수준에서 입력을 처리합니다 (커서 이동, 모드, 모션)
- Keybindings는 컴포넌트 수준에서 액션을 처리합니다 (할 일 목록 토글, 전송 등)
- vim 모드에서 Escape 키는 INSERT를 NORMAL 모드로 전환하며,
chat:cancel을 트리거하지 않습니다 - 대부분의 Ctrl+키 단축키는 vim 모드를 통과하여 keybinding 시스템으로 전달됩니다
- vim NORMAL 모드에서
?는 도움말 메뉴를 표시합니다 (vim 동작)
유효성 검사
Claude Code는 keybindings를 검증하고 다음과 같은 경고를 표시합니다:
- 파싱 오류 (잘못된 JSON 또는 구조)
- 잘못된 컨텍스트 이름
- 예약된 단축키 충돌
- 터미널 멀티플렉서 충돌
- 동일 컨텍스트 내 중복 바인딩
/doctor를 실행하면 keybinding 관련 경고를 확인할 수 있습니다.