自定义键盘快捷键

Claude Code 支持自定义键盘快捷键。运行 /keybindings 创建或打开你的配置文件 ~/.claude/keybindings.json。注意：下面表里的默认键和「需要 vX.Y.Z 或更高」之类的版本说明来自官方文档核实时的状态，会随版本变化，以官方为准。

配置文件

快捷键配置文件是一个带 bindings 数组的对象，每个块指定一个上下文和一张从按键到动作的映射。对键位文件的改动会被自动检测并应用，无需重启 Claude Code。

下面的例子在聊天上下文里把 Ctrl+E 绑定为打开外部编辑器，并解绑 Ctrl+S：

{
  "$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+s": 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 上下文）

v2.1.257 之前，有一个默认绑定 Ctrl+E 的 confirm:toggleExplanation 动作，在 Bash 和 PowerShell 权限提示上显示模型生成的命令解释。

对话框用 confirm:yes 和 confirm:no 来接受和取消，即使它们问的不是是/否问题。如果你在这个上下文里绑定了单个字母如 y 或 n，这个字母也会作用于从不把它显示为按键的对话框；把 y 和 n 显示为按键的对话框自己读取这些字母，不需要绑定。大多数对话框里，连按两次 Ctrl+C 或 Ctrl+D 会关闭对话框而不是退出 Claude Code，第一次按键后的提示会说明第二次是关闭对话框还是退出；这两个键是保留的，不能重绑定。

下面的例子把 y 绑定到 confirm:yes，把 n 绑定到 confirm:no：

{
  "bindings": [
    {
      "context": "Confirmation",
      "bindings": {
        "y": "confirm:yes",
        "n": "confirm:no"
      }
    }
  ]
}

有了这些绑定，当文本字段有焦点时，y 和 n 仍然作为字母输入。v2.1.280 之前，y 默认也绑定到 confirm:yes、n 绑定到 confirm:no；如果你在 v2.1.280 之前用 /keybindings 创建了 keybindings.json，文件里会列出这两个绑定，在你删掉这两行之前它们一直有效。

权限动作

转录动作（Transcript 上下文）

transcript:toggleShowAll 只适用于经典渲染器；在全屏渲染里，转录查看器不提供显示全部的开关。

历史搜索动作（HistorySearch 上下文）

historySearch:next、accept、cancel 和 execute 的默认键适用于经典渲染器里的内联历史搜索，它总是搜索所有项目的提示。historySearch:cycleScope 只在全屏渲染里生效：那里 Ctrl+R 打开的是搜索对话框，Ctrl+S 循环它的范围。对话框的其他键是固定的、不能重绑定：Enter 或 Tab 把高亮的匹配放进提示输入框，Esc 取消。

任务动作（Task 上下文）

主题动作（ThemePicker 上下文）

帮助动作（Help 上下文）

标签页动作（Tabs 上下文）

在带标签页的对话框里，标签行有焦点时，tabs:next 和 tabs:previous 切换标签页；在 /help 和 /sandbox 这样的一些对话框里，切换标签页的键在标签内容内部也有效。Up 和 Down 在标签行和标签内容之间移动焦点，内容里的列表只在有焦点时才响应按键。

附件动作（Attachments 上下文）

页脚动作（Footer 上下文）

选中某个页脚项（如提示下方智能体面板里的一行）时，即使你把 Chat 上下文里的 Enter 重绑定为 chat:queueSubmit 或 chat:newline，Enter 也会打开它。Chat 里绑定在 Footer 上下文没有绑定的键上的绑定（如 Shift+Tab 的 chat:cycleMode），在选中某项时仍然有效。

消息选择器动作（MessageSelector 上下文）

在回退菜单的消息列表里，你用 Select 动作及其默认键在消息间移动并选择一条，你对这些动作的 Select 绑定在这里也适用。MessageSelector 上下文自己没有动作或默认绑定，用它来只改变这个列表的某个键，方法是在 MessageSelector 块里绑定一个 Select 动作，如 select:accept。下面的例子把 o 绑定为在回退菜单里选择高亮的消息，而不改变任何其他列表：

{
  "bindings": [
    {
      "context": "MessageSelector",
      "bindings": {
        "o": "select:accept"
      }
    }
  ]
}

v2.1.283 之前，这个列表忽略 Select 绑定，并有自己的动作：messageSelector:up、down、top、bottom 和 select。如果你的 keybindings.json 绑定了这些名字之一，该绑定在此列表里作为做同样事情的 Select 动作继续生效。Home 和 End 跳到列表两端（v2.1.283 之前，Shift+K 和 Shift+J 这样的键默认做这件事）。

diff 动作（DiffDialog 上下文）

文件列表也响应 Select 动作，通过它们的默认键和你的 Select 绑定：select:previous 和 select:next 移到上一个和下一个文件，Enter 通过 select:accept 打开选中文件的 diff。要只为文件列表改变其中某个键，在 DiffDialog 块里绑定该 Select 动作。v2.1.283 之前，文件列表忽略 Select 绑定，Enter 通过单独的 diff:viewDetails 动作打开选中文件的 diff；如果你的 keybindings.json 绑定了 diff:viewDetails，该绑定在文件列表里作为 select:accept 继续生效。

diff 详情视图还把类似分页器的键绑定到标准的滚动动作。这些绑定属于 DiffDialog 上下文，只适用于详情视图；Scroll 上下文的默认值不变：

diff 面板动作

/diff 在全屏渲染里打开的 diff 面板的动作。app:cycleDiffBase 在面板打开期间生效的 DiffPanel 上下文里，其余在 Global 里。面板需要 Claude Code v2.1.260 或更高。

模型选择器动作（ModelPicker 上下文）

effort 滑块动作（EffortSlider 上下文）

不带参数运行 /effort 时打开的滑块。滑块的 Enter 和 Escape 键不能重绑定。

Select 动作（Select 上下文）

在 /skills、/mcp 和 /tasks 这样的列表面板里，Claude Code 应用你的 select:pageUp、pageDown、first 和 last 绑定；在大多数其他列表（如 /model 选择器）里，你的 select:first 和 select:last 绑定生效，PageUp 和 PageDown 不论你的绑定如何都按页翻动选项。v2.1.280 之前，那些其他列表忽略 Home、End 以及你的 select:first 和 select:last 绑定；v2.1.283 之前，/mcp 工具列表不论你的绑定如何都用固定的 PageUp 和 PageDown 翻页。

插件动作（Plugin 上下文）

设置动作（Settings 上下文）

select:accept 和 confirm:no 动作复用自 Select 和 Confirmation 上下文，带有设置特定的行为：每个设置在你改动时立即应用，所以 Escape 关闭面板并保存你的改动，而不是拒绝。

智能体动作（Agents 上下文）

适用于用 claude agents 打开的智能体视图（需要 v2.1.257 或更高）。

智能体视图打开期间，对 Agents 上下文绑定的任何键，Claude Code 使用 Agents 绑定，并忽略同一个键上的 Chat 或 Global 绑定：例如在智能体视图里按 Ctrl+S 会切换会话分组，而不是触发默认的 chat:stash。dispatch 输入的外部编辑器快捷键不是 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。

和弦

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

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 ctrl+s 和 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 ctrl+s 需要 v2.1.275 或更高。要把 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 ctrl+s": null,
        "ctrl+x tab": null,
        "ctrl+x": "chat:newline"
      }
    }
  ]
}

如果你解绑了某个前缀上的一部分而非全部和弦，按下该前缀仍会为剩余的绑定进入和弦等待模式。

保留的快捷键

这些快捷键不能重绑定：

终端冲突

有些快捷键可能与终端复用器冲突：

文本字段

如果你绑定了单个字母、数字或 Space，仍然可以在对话框或面板内的文本字段里输入该字符；一个这样的字段是对 Claude 所提问题的 Other 回答。字段有焦点期间，你不带 Ctrl、Alt 或 Cmd 按下的可打印键会进入字段，Claude Code 不会拿它去匹配你的绑定。

字段有焦点期间，这些键仍会运行它们的绑定：不输入字符的键（如 Enter、Escape、Tab 和方向键）；任何带 Ctrl、Alt 或 Cmd 按下的键；以及已在进行中的和弦的第二个按键。在主提示处，Claude Code 把每个键与活动上下文（如 Chat）匹配，只有没有绑定接管它时才输入该键。

与 vim 模式的交互

通过 /config → Editor mode 启用 vim 模式后，键绑定和 vim 模式独立运作：

• Vim 模式在文本输入层面处理输入（光标移动、模式、动作）。
• 键绑定在组件层面处理动作（切换待办、提交等）。
• vim 模式里的 Escape 键把 INSERT 切换到 NORMAL 模式，它不会触发 chat:cancel。
• 大多数 Ctrl+键快捷键会穿过 vim 模式到达键绑定系统。
• vim 键不能通过键位文件重映射；要把 jj 这样的两键 INSERT 模式序列映射为 Escape，用 vimInsertModeRemaps 设置。
• 在 vim NORMAL 模式下，? 显示帮助菜单（vim 行为）。
• 在 vim NORMAL 模式下，/ 打开历史搜索，与标准模式里的 Ctrl+R 相同。

校验

Claude Code 校验你的键绑定，并对以下情况向调试日志写警告：

• 解析错误（无效的 JSON 或结构）
• 拼错的修饰键，如 ctl+k：Claude Code 丢弃它不认识的部分，并把绑定应用到剩下的按键（这个例子里是 k）
• 无效的上下文名称
• 无效的动作值，例如既不是字符串也不是 null 的动作
• 未知的动作名称，例如拼错的已注册动作：Claude Code 跳过该绑定，并保留该键上任何默认绑定的效力
• 保留快捷键冲突
• 同一上下文里的重复绑定

用 --debug 启动 Claude Code 查看详情。