自定义快捷键¶

通过 keybindings 配置文件自定义 Claude Code 的键盘快捷键。

自定义快捷键需要 Claude Code v2.1.18 或更高版本。 用 claude --version 查看当前版本。

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

配置文件¶

keybindings 配置文件是一个包含 bindings 数组的 JSON 对象。 每个 block 指定一个上下文和按键到动作的映射。

修改 keybindings 文件后会自动检测并生效，无需重启 Claude Code。

下面的示例将 Ctrl+E 绑定到在 Chat 上下文中打开外部编辑器，并解除 Ctrl+U 的绑定：

{
  "$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+u": null
      }
    }
  ]
}

上下文¶

每个绑定 block 指定一个上下文（context），表示绑定在哪些场景下生效：

可用动作¶

动作遵循 namespace:action 格式。 例如 chat:submit 发送消息，app:toggleTodos 显示任务列表。每个上下文有各自可用的动作。

App 动作¶

Global 上下文中可用的动作：

历史动作¶

命令历史导航相关的动作：

Chat 动作¶

Chat 上下文中可用的动作：

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

自动补全动作¶

Autocomplete 上下文中可用的动作：

确认动作¶

Confirmation 上下文中可用的动作：

权限动作¶

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

对话记录动作¶

Transcript 上下文中可用的动作：

历史搜索动作¶

HistorySearch 上下文中可用的动作：

任务动作¶

Task 上下文中可用的动作：

主题动作¶

ThemePicker 上下文中可用的动作：

帮助动作¶

Help 上下文中可用的动作：

Tab 动作¶

Tabs 上下文中可用的动作：

附件动作¶

Attachments 上下文中可用的动作：

Footer 动作¶

Footer 上下文中可用的动作：

消息选择动作¶

MessageSelector 上下文中可用的动作：

Diff 动作¶

DiffDialog 上下文中可用的动作：

Diff 详情视图还将类似 pager 的按键绑定到标准滚动动作。这些绑定属于 DiffDialog 上下文，仅在详情视图中生效：

模型选择器动作¶

ModelPicker 上下文中可用的动作：

Select 动作¶

Select 上下文中可用的动作：

Plugin 动作¶

Plugin 上下文中可用的动作：

Settings 动作¶

Settings 上下文中可用的动作。select:accept 和 confirm:no 动作复用自 Select 和 确认动作 上下文，但行为适配了 Settings 场景：每个设置修改即生效，所以 Escape 关闭面板时修改已经保存。

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 上的 Win 键，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    多修饰键组合

大写字母¶

单独的大写字母隐含 Shift。 例如 K 等同于 shift+k。这对 vim 风格绑定很有用。

带修饰键的大写字母（如 ctrl+K）仅作风格处理，不隐含 Shift：ctrl+K 与 ctrl+k 相同。

组合键（Chords）¶

组合键是用空格分隔的按键序列：

ctrl+k ctrl+s   先按 Ctrl+K，释放，再按 Ctrl+S

特殊键¶

• escape 或 esc — Escape 键
• enter 或 return — Enter 键
• tab — Tab 键
• space — 空格键
• up、down、left、right — 方向键
• backspace、delete — 删除键

解除默认快捷键¶

将动作设为 null 即可解除默认快捷键绑定：

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

这也适用于组合键绑定。解除共享同一前缀的所有组合键后，该前缀就可以作为单键绑定使用。任何活动上下文中的组合键都会保留其前缀，所以必须在定义它的上下文中逐个解除。

默认的 Ctrl+X 系列跨两个上下文：Chat 中的 ctrl+x ctrl+k 和 ctrl+x ctrl+e，以及 Task 中的 ctrl+x ctrl+b。要释放 ctrl+x 本身作为单键绑定，需要解除所有这些：

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

如果只解除了部分组合键，按下前缀仍会进入组合键等待模式。

保留快捷键¶

以下快捷键无法重新绑定：

终端冲突¶

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

Vim 模式交互¶

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

• Vim 模式 在文本输入层处理输入（光标移动、模式切换、动作）
• 快捷键绑定 在组件层处理操作（切换待办、提交等）
• Vim 模式中的 Escape 切换 INSERT 到 NORMAL 模式，不触发 chat:cancel
• 大多数 Ctrl+key 快捷键穿透 vim 模式到达快捷键绑定系统
• Vim NORMAL 模式中，? 显示帮助菜单（vim 行为）
• Vim NORMAL 模式中，/ 打开历史搜索，等同于标准模式的 Ctrl+R

验证¶

Claude Code 会验证你的快捷键配置，对以下情况显示警告：

• 解析错误（无效的 JSON 或结构）
• 无效的上下文名称
• 保留快捷键冲突
• 终端多路复用器冲突
• 同一上下文中的重复绑定

运行 /doctor 可查看快捷键相关警告。