> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 키보드 단축키 사용자 정의

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

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

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

## 구성 파일

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

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

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

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

```json theme={null}
{
  "$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`        | 설정 메뉴                      |
| `Confirmation`    | 권한 및 확인 대화 상자              |
| `Tabs`            | 탭 네비게이션 구성 요소              |
| `Help`            | 도움말 메뉴가 표시됨                |
| `Transcript`      | 트랜스크립트 뷰어                  |
| `HistorySearch`   | 기록 검색 모드(Ctrl+R)           |
| `Task`            | 백그라운드 작업이 실행 중             |
| `ThemePicker`     | 테마 선택기 대화 상자               |
| `Attachments`     | 이미지 첨부 파일 네비게이션 선택 대화 상자   |
| `Footer`          | 바닥글 표시기 네비게이션(작업, 팀, diff) |
| `MessageSelector` | 되돌리기 및 요약 대화 상자 메시지 선택     |
| `DiffDialog`      | Diff 뷰어 네비게이션              |
| `ModelPicker`     | 모델 선택기 노력 수준               |
| `Select`          | 일반 선택/목록 구성 요소             |
| `Plugin`          | 플러그인 대화 상자(찾아보기, 발견, 관리)   |
| `Scroll`          | 전체 화면 모드에서 대화 스크롤 및 텍스트 선택 |
| `Doctor`          | `/doctor` 진단 화면            |

## 사용 가능한 작업

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

### 앱 작업

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

| 작업                     | 기본값       | 설명             |
| :--------------------- | :-------- | :------------- |
| `app:interrupt`        | Ctrl+C    | 현재 작업 취소       |
| `app:exit`             | Ctrl+D    | Claude Code 종료 |
| `app:redraw`           | (바인딩 해제됨) | 터미널 다시 그리기 강제  |
| `app:toggleTodos`      | Ctrl+T    | 작업 목록 표시 여부 전환 |
| `app:toggleTranscript` | Ctrl+O    | 상세 트랜스크립트 전환   |

### 기록 작업

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

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

### 채팅 작업

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

| 작업                    | 기본값                      | 설명                           |
| :-------------------- | :----------------------- | :--------------------------- |
| `chat:cancel`         | Escape                   | 현재 입력 취소                     |
| `chat:clearInput`     | Ctrl+L                   | 프롬프트 입력을 지우고 전체 화면 다시 그리기 강제 |
| `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:newline`        | Ctrl+J                   | 제출하지 않고 줄 바꿈 삽입              |
| `chat:undo`           | Ctrl+\_, Ctrl+Shift+-    | 마지막 작업 실행 취소                 |
| `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:toggle`            | Space     | 선택 전환    |
| `confirm:cycleMode`         | Shift+Tab | 권한 모드 순환 |
| `confirm:toggleExplanation` | Ctrl+E    | 권한 설명 전환 |

### 권한 작업

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

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

### 트랜스크립트 작업

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

| 작업                         | 기본값               | 설명           |
| :------------------------- | :---------------- | :----------- |
| `transcript:toggleShowAll` | Ctrl+E            | 모든 콘텐츠 표시 전환 |
| `transcript:exit`          | q, 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:up`             | Up     | 바닥글에서 위로 네비게이션(맨 위에서 선택 해제) |
| `footer:down`           | Down   | 바닥글에서 아래로 네비게이션             |
| `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     | 선택한 플러그인 설치                               |
| `plugin:favorite` | F     | 선택한 플러그인을 즐겨찾기로 설정하여 설치된 탭 상단 근처에 정렬되도록 함 |

### 설정 작업

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

| 작업                | 기본값   | 설명                                               |
| :---------------- | :---- | :----------------------------------------------- |
| `settings:search` | /     | 검색 모드 진입                                         |
| `settings:retry`  | R     | 사용량 데이터 다시 로드(오류 시)                              |
| `settings:close`  | Enter | 변경 사항을 저장하고 구성 패널을 닫습니다. Escape는 변경 사항을 버리고 닫습니다 |

### Doctor 작업

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

| 작업           | 기본값 | 설명                                                  |
| :----------- | :-- | :-------------------------------------------------- |
| `doctor:fix` | F   | 진단 보고서를 Claude에 보내 보고된 문제를 해결합니다. 문제가 발견되었을 때만 활성화됨 |

### 음성 작업

[음성 받아쓰기](/ko/voice-dictation)가 활성화되었을 때 `Chat` 컨텍스트에서 사용 가능한 작업:

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

### 스크롤 작업

[전체 화면 렌더링](/ko/fullscreen)이 활성화되었을 때 `Scroll` 컨텍스트에서 사용 가능한 작업:

| 작업                          | 기본값                  | 설명                                                                       |
| :-------------------------- | :------------------- | :----------------------------------------------------------------------- |
| `scroll:lineUp`             | (바인딩 해제됨)            | 한 줄 위로 스크롤합니다. 마우스 휠 스크롤이 이 작업을 트리거합니다                                   |
| `scroll:lineDown`           | (바인딩 해제됨)            | 한 줄 아래로 스크롤합니다. 마우스 휠 스크롤이 이 작업을 트리거합니다                                  |
| `scroll:pageUp`             | PageUp               | 뷰포트 높이의 절반만큼 위로 스크롤                                                      |
| `scroll:pageDown`           | PageDown             | 뷰포트 높이의 절반만큼 아래로 스크롤                                                     |
| `scroll:top`                | Ctrl+Home            | 대화의 시작으로 이동                                                              |
| `scroll:bottom`             | Ctrl+End             | 최신 메시지로 이동하고 자동 팔로우 다시 활성화                                               |
| `scroll:halfPageUp`         | (바인딩 해제됨)            | 뷰포트 높이의 절반만큼 위로 스크롤합니다. `scroll:pageUp`과 동일한 동작이며 vi 스타일 재바인딩을 위해 제공됨    |
| `scroll:halfPageDown`       | (바인딩 해제됨)            | 뷰포트 높이의 절반만큼 아래로 스크롤합니다. `scroll:pageDown`과 동일한 동작이며 vi 스타일 재바인딩을 위해 제공됨 |
| `scroll:fullPageUp`         | (바인딩 해제됨)            | 전체 뷰포트 높이만큼 위로 스크롤                                                       |
| `scroll:fullPageDown`       | (바인딩 해제됨)            | 전체 뷰포트 높이만큼 아래로 스크롤                                                      |
| `selection:copy`            | Ctrl+Shift+C / Cmd+C | 선택한 텍스트를 클립보드에 복사                                                        |
| `selection:clear`           | (바인딩 해제됨)            | 활성 텍스트 선택 지우기                                                            |
| `selection:extendLeft`      | Shift+Left           | 활성 선택을 한 열 왼쪽으로 확장                                                       |
| `selection:extendRight`     | Shift+Right          | 활성 선택을 한 열 오른쪽으로 확장                                                      |
| `selection:extendUp`        | Shift+Up             | 활성 선택을 한 행 위로 확장합니다. 선택이 상단 가장자리에 도달하면 뷰포트를 스크롤합니다                       |
| `selection:extendDown`      | Shift+Down           | 활성 선택을 한 행 아래로 확장합니다. 선택이 하단 가장자리에 도달하면 뷰포트를 스크롤합니다                      |
| `selection:extendLineStart` | Shift+Home           | 활성 선택을 줄의 시작으로 확장                                                        |
| `selection:extendLineEnd`   | Shift+End            | 활성 선택을 줄의 끝으로 확장                                                         |

## 키 입력 구문

### 수정자

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

* `ctrl` 또는 `control` - Control 키
* `alt`, `opt`, 또는 `option` - Alt/Option 키
* `shift` - Shift 키
* `meta`, `cmd`, 또는 `command` - Meta/Command 키

예를 들어:

```text theme={null}
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`와 동일합니다.

### 코드

코드는 공백으로 구분된 키 입력 시퀀스입니다:

```text theme={null}
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`로 설정하여 기본 단축키를 바인딩 해제합니다:

```json theme={null}
{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+s": null
      }
    }
  ]
}
```

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

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

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

## 예약된 단축키

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

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

## 터미널 충돌

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

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

## Vim 모드 상호 작용

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

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

## 유효성 검사

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

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

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