自定义快捷键

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

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

配置文件

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

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

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "$docs": "/tutorials/cc-interface/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 上下文中可用的操作：

权限操作

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

记录操作

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

历史搜索操作

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

任务操作

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

主题操作

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

帮助操作

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

Tabs 操作

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

附件操作

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

页脚操作

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

消息选择器操作

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

Diff 操作

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

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

模型选择器操作

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

选择操作

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

Plugin 操作

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

设置操作

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

语音操作

在启用语音听写时，在 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    多个修饰符

大写字母

独立的大写字母意味着 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 - 删除键

取消绑定默认快捷键

将操作设置为 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 模式交互

启用 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 或结构）
• 无效的上下文名称
• 保留快捷键冲突
• 终端多路复用器冲突
• 同一上下文中的重复绑定

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