自定义快捷键

使用快捷键配置文件在 Claude Code 中自定义快捷键。

Claude Code 支持可自定义的快捷键。运行 /keybindings 来创建或打开位于 ~/.claude/keybindings.json 的配置文件。

配置文件

快捷键配置文件是一个包含 bindings 数组的对象。每个块指定一个上下文和一个按键映射到操作的映射。

此示例将 Ctrl+E 绑定到在聊天上下文中打开外部编辑器，并取消绑定 Ctrl+U：

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

上下文

每个绑定块指定一个上下文，其中绑定适用：

在 v2.1.205 之前，/doctor 诊断屏幕存在 Doctor 上下文和 doctor:fix 操作。

可用操作

操作遵循 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 上下文中可用的操作：

*在没有 VT 模式的 Windows 上（Node <24.2.0/<22.17.0，Bun <1.2.23），默认为 Meta+M。

在 v2.1.257 之前，confirm:toggleExplanation 操作（默认绑定到 Ctrl+E）在 Bash 和 PowerShell 权限提示上显示模型生成的命令说明。

权限操作

在 Confirmation 上下文中可用的权限对话框操作：

记录操作

在 Transcript 上下文中可用的操作：

transcript:toggleShowAll 仅在经典渲染器中应用；在全屏渲染中，记录查看器不提供显示全部切换。

历史搜索操作

在 HistorySearch 上下文中可用的操作：

historySearch:next、historySearch:accept、historySearch:cancel 和 historySearch:execute 默认值适用于经典渲染器中的内联历史搜索，它始终搜索来自所有项目的提示。historySearch:cycleScope 仅在全屏渲染中生效，其中 Ctrl+R 打开搜索对话框，Ctrl+S 循环其范围。对话框的其他键是固定的，无法重新绑定：Enter 或 Tab 将突出显示的匹配项放在提示输入中，Esc 取消。

任务操作

在 Task 上下文中可用的操作：

主题操作

在 ThemePicker 上下文中可用的操作：

帮助操作

在 Help 上下文中可用的操作：

Tabs 操作

在 Tabs 上下文中可用的操作：

附件操作

在 Attachments 上下文中可用的操作：

页脚操作

在 Footer 上下文中可用的操作：

消息选择器操作

在 MessageSelector 上下文中可用的操作：

Diff 操作

在 DiffDialog 上下文中可用的操作：

差异详情视图还将寻呼机风格的快捷键绑定到标准滚动操作。这些绑定是 DiffDialog 上下文的一部分，仅在详情视图中应用；滚动操作下列出的 Scroll 上下文默认值保持不变。

Diff 面板操作

用于 /diff 在全屏渲染中打开的 diff 面板的操作。app:cycleDiffBase 在 DiffPanel 上下文中，在面板打开时处于活动状态；其他的在 Global 中。面板需要 Claude Code v2.1.260 或更高版本。

模型选择器操作

在 ModelPicker 上下文中可用的操作：

工作量滑块操作

在 EffortSlider 上下文中可用的操作，这是运行不带参数的 /effort 时打开的滑块。滑块的 Left、Right、Enter 和 Escape 键无法重新绑定。

选择操作

在 Select 上下文中可用的操作：

Claude Code 在 /skills 菜单中应用您的 select:pageUp、select:pageDown、select:first 和 select:last 绑定。在大多数其他列表中，例如 /model 选择器，Claude Code 使用 PageUp 和 PageDown 进行分页，无论您的绑定如何，并忽略 Home 和 End。

Plugin 操作

在 Plugin 上下文中可用的操作：

设置操作

在 Settings 上下文中可用的操作。select:accept 和 confirm:no 操作从选择和确认上下文中重用，具有特定于设置的行为：更改会在您更改时立即应用于每个设置，因此 Escape 关闭面板并保存您的更改，而不是拒绝。

代理操作

在 Agents 上下文中可用的操作，该上下文适用于代理视图，使用 claude agents 打开。需要 v2.1.257 或更高版本。

当代理视图打开时，Claude Code 对 Agents 上下文绑定的任何键使用 Agents 绑定，并忽略同一键上的 Chat 或 Global 绑定。例如，在代理视图中按 Ctrl+S 会切换会话分组，而不是触发默认的 chat:stash。

调度输入的外部编辑器快捷键不是 Agents 操作。代理视图遵循 Chat 上下文的 chat:externalEditor 绑定，默认为 Ctrl+G。

绑定在代理视图中的单个按键上触发，因此绑定到 chat:externalEditor 的 Ctrl+X Ctrl+E 组合键不会在那里打开编辑器。

语音操作

在启用语音听写时，在 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 组仅在报告 Super 修饰符的终端中被检测到，例如支持 Kitty 键盘协议或 xterm 的 modifyOtherKeys 模式的终端。大多数终端不会发送它，因此对于希望在任何地方都能工作的绑定，请使用 ctrl 或 meta。

例如：

ctrl+k          Ctrl + K
shift+tab       Shift + Tab
meta+p          macOS 上的 Option + P，其他地方的 Alt + P
ctrl+shift+c    多个修饰符

大写字母

Claude Code 不区分大小写地解析按键名称，因此 K 与 k 的绑定相同，ctrl+K 与 ctrl+k 相同。要绑定 Shift 和一个字母，请写 shift+k。

非美国键盘布局

即使您的活动键盘布局输入其他字符，也要将 Ctrl 快捷键的按键名称写成拉丁字符。

Claude Code 如何将您按下的按键与绑定匹配取决于布局的类型：

• 在非拉丁布局（如西里尔字母）下，当终端使用 Kitty 键盘协议并报告该位置时，Claude Code 通过按键的美国布局位置来匹配 Ctrl 快捷键。在这样的终端中，使用俄语布局时，按下 Ctrl 和物理 W 键会触发 ctrl+w。在不报告位置的终端中，Claude Code 匹配终端为按键发送的任何内容：ASCII 控制代码触发拉丁快捷键，作为西里尔字符到达的按键不匹配任何绑定
• 在重新排列拉丁字母的布局（如 AZERTY）下，Claude Code 匹配按键输入的字母，因此按下 Ctrl 和标记为 A 的按键会触发 ctrl+a

在 v2.1.247 之前，在使用 Kitty 键盘协议的终端（如 Ghostty、Kitty、WezTerm 和 iTerm2）中，在非拉丁布局下按下 Ctrl 快捷键不会触发其绑定。

和弦

和弦是由空格分隔的按键序列：

ctrl+k ctrl+s   按 Ctrl+K，释放，然后按 Ctrl+S

在前一个按键的 3 秒内按下每个按键。如果您等待更长时间，Claude Code 会取消和弦并显示一条简短通知。

特殊键

• escape 或 esc - Escape 键
• enter 或 return - Enter 键
• tab - Tab 键
• space - 空格键
• up、down、left、right - 箭头键
• pageup、pagedown - Page Up 和 Page Down 键
• home、end - Home 和 End 键
• backspace、delete - 删除键
• wheelup、wheeldown - 鼠标滚轮滚动事件

取消绑定默认快捷键

将操作设置为 null 以取消绑定默认快捷键：

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

这也适用于和弦绑定。取消绑定共享前缀的每个和弦会释放该前缀以用作单键绑定。任何活跃上下文中的和弦都会保留其前缀，因此您必须在定义该和弦的上下文中取消绑定每个和弦。

Claude Code 在 ctrl+x 前缀上绑定这些默认和弦：Chat 中的 ctrl+x ctrl+k、ctrl+x ctrl+e、ctrl+x enter、ctrl+x ctrl+a 和 ctrl+x tab，Task 中的 ctrl+x ctrl+b，以及 DiffPanel 中的 ctrl+x b。ctrl+x enter 和弦需要 v2.1.247 或更高版本，ctrl+x b、ctrl+x ctrl+a 和 ctrl+x tab 需要 v2.1.260 或更高版本。要将 ctrl+x 本身回收为单键绑定，请取消绑定所有这些：

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

如果您取消绑定前缀上的某些但不是全部和弦，按下前缀仍会进入和弦等待模式以处理剩余的绑定。

保留的快捷键

这些快捷键无法重新绑定：

终端冲突

某些快捷键可能与终端多路复用器冲突：

Vim 模式交互

启用 vim 模式（通过 /config → 编辑器模式）时，快捷键和 vim 模式独立运行：

• Vim 模式在文本输入级别处理输入（光标移动、模式、动作）
• 快捷键在组件级别处理操作（切换待办事项、提交等）
• vim 模式中的 Escape 键从 INSERT 切换到 NORMAL 模式；它不触发 chat:cancel
• 大多数 Ctrl+key 快捷键通过 vim 模式传递到快捷键系统
• Vim 键不能通过快捷键文件重新映射。要映射两键 INSERT 模式序列（如 jj）到 Escape，请使用 vimInsertModeRemaps 设置
• 在 vim NORMAL 模式中，? 显示帮助菜单（vim 行为）
• 在 vim NORMAL 模式中，/ 打开历史搜索，与标准模式中的 Ctrl+R 相同

验证

Claude Code 验证您的快捷键并显示以下警告：

• 解析错误（无效的 JSON 或结构）
• 无效的上下文名称
• 无效的操作值，例如不是字符串或 null 的操作
• 未知的操作名称，例如注册操作的拼写错误。Claude Code 跳过该绑定并保持该键的任何默认绑定有效。在 v2.1.246 之前，具有未知操作名称的绑定会静默禁用该键
• 保留快捷键冲突
• 同一上下文中的重复绑定

Claude Code 在文件加载时报告警告，并将每个警告写入调试日志。使用 --debug 启动 Claude Code 以查看详细信息。