키보드 단축키 사용자 정의

사용자 정의 가능한 키보드 단축키는 Claude Code v2.1.18 이상이 필요합니다. claude --version으로 버전을 확인하세요.

Claude Code는 사용자 정의 가능한 키보드 단축키를 지원합니다. /keybindings를 실행하여 ~/.claude/keybindings.json에서 구성 파일을 만들거나 열 수 있습니다.

구성 파일

keybindings 구성 파일은 bindings 배열이 있는 객체입니다. 각 블록은 컨텍스트와 키 입력을 작업에 매핑하는 맵을 지정합니다.

keybindings 파일의 변경 사항은 자동으로 감지되고 Claude Code를 다시 시작하지 않고도 적용됩니다.

필드	설명
`$schema`	편집기 자동 완성을 위한 선택적 JSON Schema URL
`$docs`	선택적 설명서 URL
`bindings`	컨텍스트별 바인딩 블록 배열

이 예제는 채팅 컨텍스트에서 Ctrl+E를 외부 편집기를 열기에 바인딩하고 Ctrl+U를 바인딩 해제합니다:

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "$docs": "https://code.claude.com/docs/ko/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는 작업 목록을 표시합니다. 각 컨텍스트에는 사용 가능한 특정 작업이 있습니다.

앱 작업

Global 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`app:interrupt`	Ctrl+C	현재 작업 취소
`app:exit`	Ctrl+D	Claude Code 종료
`app:toggleTodos`	Ctrl+T	작업 목록 표시 여부 전환
`app:toggleTranscript`	Ctrl+O	상세 트랜스크립트 전환

기록 작업

명령 기록을 탐색하기 위한 작업:

작업	기본값	설명
`history:search`	Ctrl+R	기록 검색 열기
`history:previous`	Up	이전 기록 항목
`history:next`	Down	다음 기록 항목

채팅 작업

Chat 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`chat:cancel`	Escape	현재 입력 취소
`chat:killAgents`	Ctrl+X Ctrl+K	모든 백그라운드 에이전트 종료
`chat:cycleMode`	Shift+Tab*	권한 모드 순환
`chat:modelPicker`	Cmd+P / Meta+P	모델 선택기 열기
`chat:fastMode`	Meta+O	빠른 모드 전환
`chat:thinkingToggle`	Cmd+T / Meta+T	확장 사고 전환
`chat:submit`	Enter	메시지 제출
`chat:undo`	Ctrl+_	마지막 작업 실행 취소
`chat:externalEditor`	Ctrl+G, Ctrl+X Ctrl+E	외부 편집기에서 열기
`chat:stash`	Ctrl+S	현재 프롬프트 숨기기
`chat:imagePaste`	Ctrl+V (Windows에서 Alt+V)	이미지 붙여넣기

*VT 모드가 없는 Windows에서(Node <24.2.0/<22.17.0, Bun <1.2.23), 기본값은 Meta+M입니다.

자동 완성 작업

Autocomplete 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`autocomplete:accept`	Tab	제안 수락
`autocomplete:dismiss`	Escape	메뉴 닫기
`autocomplete:previous`	Up	이전 제안
`autocomplete:next`	Down	다음 제안

확인 작업

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	권한 설명 전환

권한 작업

권한 대화 상자의 Confirmation 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`permission:toggleDebug`	Ctrl+D	권한 디버그 정보 전환

트랜스크립트 작업

Transcript 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`transcript:toggleShowAll`	Ctrl+E	모든 콘텐츠 표시 전환
`transcript:exit`	Ctrl+C, Escape	트랜스크립트 보기 종료

기록 검색 작업

HistorySearch 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`historySearch:next`	Ctrl+R	다음 일치 항목
`historySearch:accept`	Escape, Tab	선택 수락
`historySearch:cancel`	Ctrl+C	검색 취소
`historySearch:execute`	Enter	선택한 명령 실행

작업 작업

Task 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`task:background`	Ctrl+B	현재 작업을 백그라운드로 이동

테마 작업

ThemePicker 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`theme:toggleSyntaxHighlighting`	Ctrl+T	구문 강조 전환

도움말 작업

Help 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`help:dismiss`	Escape	도움말 메뉴 닫기

탭 작업

Tabs 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`tabs:next`	Tab, Right	다음 탭
`tabs:previous`	Shift+Tab, Left	이전 탭

첨부 파일 작업

Attachments 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`attachments:next`	Right	다음 첨부 파일
`attachments:previous`	Left	이전 첨부 파일
`attachments:remove`	Backspace, Delete	선택한 첨부 파일 제거
`attachments:exit`	Down, Escape	첨부 파일 바 종료

바닥글 작업

Footer 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`footer:next`	Right	다음 바닥글 항목
`footer:previous`	Left	이전 바닥글 항목
`footer:openSelected`	Enter	선택한 바닥글 항목 열기
`footer:clearSelection`	Escape	바닥글 선택 지우기

메시지 선택기 작업

MessageSelector 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`messageSelector:up`	Up, K, Ctrl+P	목록에서 위로 이동
`messageSelector:down`	Down, J, Ctrl+N	목록에서 아래로 이동
`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 뷰어에서 뒤로 이동

모델 선택기 작업

ModelPicker 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`modelPicker:decreaseEffort`	Left	노력 수준 감소
`modelPicker:increaseEffort`	Right	노력 수준 증가

선택 작업

Select 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`select:next`	Down, J, Ctrl+N	다음 옵션
`select:previous`	Up, K, Ctrl+P	이전 옵션
`select:accept`	Enter	선택 수락
`select:cancel`	Escape	선택 취소

플러그인 작업

Plugin 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`plugin:toggle`	Space	플러그인 선택 전환
`plugin:install`	I	선택한 플러그인 설치

설정 작업

Settings 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`settings:search`	/	검색 모드 진입
`settings:retry`	R	사용량 데이터 다시 로드(오류 시)

음성 작업

음성 받아쓰기가 활성화되었을 때 Chat 컨텍스트에서 사용 가능한 작업:

작업	기본값	설명
`voice:pushToTalk`	Space	프롬프트를 받아쓰기 위해 누르고 있기

키 입력 구문

수정자

+ 구분자로 수정자 키를 사용합니다:

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 - Delete 키

기본 단축키 바인딩 해제

작업을 null로 설정하여 기본 단축키를 바인딩 해제합니다:

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

예약된 단축키

이러한 단축키는 다시 바인딩할 수 없습니다:

단축키	이유
Ctrl+C	하드코딩된 중단/취소
Ctrl+D	하드코딩된 종료
Ctrl+M	터미널의 Enter와 동일(둘 다 CR 전송)

터미널 충돌

일부 단축키는 터미널 멀티플렉서와 충돌할 수 있습니다:

단축키	충돌
Ctrl+B	tmux 접두사(두 번 눌러서 보내기)
Ctrl+A	GNU screen 접두사
Ctrl+Z	Unix 프로세스 일시 중단(SIGTSTP)

Vim 모드 상호 작용

vim 모드가 활성화되면(/vim), 키바인딩과 vim 모드는 독립적으로 작동합니다:

Vim 모드는 텍스트 입력 수준에서 입력을 처리합니다(커서 이동, 모드, 동작).
키바인딩은 구성 요소 수준에서 작업을 처리합니다(작업 전환, 제출 등).
vim 모드의 Escape 키는 INSERT를 NORMAL 모드로 전환합니다. chat:cancel을 트리거하지 않습니다.
대부분의 Ctrl+key 단축키는 vim 모드를 통과하여 키바인딩 시스템으로 이동합니다.
vim NORMAL 모드에서 ?는 도움말 메뉴를 표시합니다(vim 동작).

유효성 검사

Claude Code는 키바인딩을 검증하고 다음에 대한 경고를 표시합니다:

구문 분석 오류(잘못된 JSON 또는 구조)
잘못된 컨텍스트 이름
예약된 단축키 충돌
터미널 멀티플렉서 충돌
동일한 컨텍스트의 중복 바인딩

/doctor를 실행하여 키바인딩 경고를 확인합니다.

구성

​구성 파일

​컨텍스트

​사용 가능한 작업

​앱 작업

​기록 작업

​채팅 작업

​자동 완성 작업

​확인 작업

​권한 작업

​트랜스크립트 작업

​기록 검색 작업

​작업 작업

​테마 작업

​도움말 작업

​탭 작업

​첨부 파일 작업

​바닥글 작업

​메시지 선택기 작업

​Diff 작업

​모델 선택기 작업

​선택 작업

​플러그인 작업

​설정 작업

​음성 작업

​키 입력 구문

​수정자

​대문자

​코드

​특수 키

​기본 단축키 바인딩 해제

​예약된 단축키

​터미널 충돌

​Vim 모드 상호 작용

​유효성 검사

구성 파일

컨텍스트

사용 가능한 작업

앱 작업

기록 작업

채팅 작업

자동 완성 작업

확인 작업

권한 작업

트랜스크립트 작업

기록 검색 작업

작업 작업

테마 작업

도움말 작업

탭 작업

첨부 파일 작업

바닥글 작업

메시지 선택기 작업

Diff 작업

모델 선택기 작업

선택 작업

플러그인 작업

설정 작업

음성 작업

키 입력 구문

수정자

대문자

코드

특수 키

기본 단축키 바인딩 해제

예약된 단축키

터미널 충돌

Vim 모드 상호 작용

유효성 검사