키보드 단축키 사용자 정의

keybindings 구성 파일을 사용하여 Claude Code에서 키보드 단축키를 사용자 정의합니다.

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

구성 파일

keybindings 구성 파일은 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
      }
    }
  ]
}

컨텍스트

각 바인딩 블록은 바인딩이 적용되는 컨텍스트를 지정합니다:

사용 가능한 작업

작업은 namespace:action 형식을 따릅니다. 예를 들어 chat:submit은 메시지를 보내고 app:toggleTodos는 작업 목록을 표시합니다. 각 컨텍스트에는 사용 가능한 특정 작업이 있습니다.

앱 작업

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

기록 작업

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

채팅 작업

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

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

자동 완성 작업

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

확인 작업

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

권한 작업

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

트랜스크립트 작업

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

기록 검색 작업

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

작업 작업

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

테마 작업

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

도움말 작업

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

탭 작업

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

첨부 파일 작업

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

바닥글 작업

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

메시지 선택기 작업

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

Diff 작업

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

모델 선택기 작업

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

선택 작업

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

플러그인 작업

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

설정 작업

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

Doctor 작업

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

음성 작업

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

스크롤 작업

전체 화면 렌더링이 활성화되었을 때 Scroll 컨텍스트에서 사용 가능한 작업:

키 입력 구문

수정자

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

• ctrl 또는 control - Control 키
• shift - Shift 키
• alt, opt, option, 또는 meta - Windows 및 Linux의 Alt 키, macOS의 Option 키
• cmd, command, super, 또는 win - macOS의 Command 키, Windows의 Windows 키, Linux의 Super 키

cmd 그룹은 Kitty 키보드 프로토콜 또는 xterm의 modifyOtherKeys 모드를 지원하는 것과 같이 Super 수정자를 보고하는 터미널에서만 감지됩니다. 대부분의 터미널은 이를 전송하지 않으므로 모든 곳에서 작동하기를 원하는 바인딩에는 ctrl 또는 meta를 사용합니다.

예를 들어:

ctrl+k          Ctrl + K
shift+tab       Shift + Tab
meta+p          macOS의 Option + P, 다른 곳의 Alt + 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
      }
    }
  ]
}

이는 코드 바인딩에도 작동합니다. 접두사를 공유하는 모든 코드를 바인딩 해제하면 해당 접두사를 단일 키 바인딩으로 사용할 수 있습니다:

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

접두사의 일부 코드만 바인딩 해제하고 다른 코드는 바인딩 해제하지 않으면 접두사를 누르면 여전히 남은 바인딩에 대해 코드 대기 모드로 진입합니다.

예약된 단축키

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

터미널 충돌

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

Vim 모드 상호 작용

vim 모드가 /config → 편집기 모드를 통해 활성화되면 키바인딩과 vim 모드는 독립적으로 작동합니다:

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

유효성 검사

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

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

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