它到底是什么

/keybindings 是 Claude Code 的会话内 slash 命令,执行后会打开或创建位于 ~/.claude/keybindings.json 的快捷键配置文件,让你自定义终端内所有可绑定的快捷键。

版本要求: 需要 Claude Code v2.1.18 或更高版本(可用 claude --version 确认)。

配置文件的改动会被自动检测并立即生效,无需重启 Claude Code。

怎么触发 / 怎么使用

1. 打开配置文件

在会话输入框中直接输入:

/keybindings

若 ~/.claude/keybindings.json 不存在则自动创建并打开;已存在则直接打开编辑。

2. 配置文件结构

文件是一个包含 bindings 数组的 JSON 对象,每个元素指定一个 context 及其键位映射:

{
  "$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
      }
    }
  ]
}

3. Action 格式

所有 action 采用 namespace:action 格式,例如 chat:submit、app:toggleTodos。将某个键位的值设为 null 表示解绑该默认快捷键:

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

4. 键位语法

修饰键用 + 分隔:

ctrl+k          Ctrl + K
shift+tab       Shift + Tab
meta+p          macOS 上为 Option+P,其他平台为 Alt+P
ctrl+shift+c    多修饰键组合

可用修饰符关键字:

Chord(和弦) — 两段按键序列用空格分隔:

ctrl+k ctrl+s   先按 Ctrl+K,松开,再按 Ctrl+S

大写字母 — 单独大写字母隐含 Shift(如 K 等同 shift+k),适合 vim 风格绑定。带修饰符时(如 ctrl+K)大写仅为书写风格,不额外附加 Shift。

特殊键名: escape/esc、enter/return、tab、space、up/down/left/right、backspace/delete。

5. 解绑 Chord 前缀

若要将某个 chord 前缀释放为单键,需先解绑该前缀下的所有 chord:

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

若只解绑部分 chord,按下前缀后仍会进入和弦等待模式。

保存 / 配置 / 集成

配置文件固定路径为 ~/.claude/keybindings.json(用户级,全局生效)。

$schema 字段指向 SchemaStore 托管的 JSON Schema,可为 VS Code、JetBrains 等编辑器提供自动补全与校验,非必填。

运行约束 / 限制

保留快捷键(不可重绑)

终端冲突(可能被拦截)

Cmd 修饰符限制

cmd/command/super/win 修饰符仅在支持 Kitty 键盘协议或 xterm modifyOtherKeys 模式的终端中生效;大多数终端无法发送该修饰符,建议用 ctrl 或 meta 代替以确保跨终端兼容。

跟同类原语对比

两者独立运行,不互相覆盖。Vim mode 下的 Escape 切换输入模式,不触发 chat:cancel;大多数 Ctrl 组合键在 vim NORMAL 模式下仍透传到 keybindings 系统。

全部可用 Context 与核心 Action

Context 列表

Global context 核心 Action

Chat context 核心 Action

WSL 上的图片粘贴:官方原文为 'Ctrl+V (Alt+V on Windows and WSL). On WSL, both shortcuts are bound by default'。即在 WSL 上 Ctrl+V 与 Alt+V 默认同时绑定到 chat:imagePaste,并非用 Alt+V 互斥替换 Ctrl+V。

经典使用场景

• 将提交键改为 Ctrl+Enter:将 chat:submit 绑定到 ctrl+enter,避免意外发送多行输入。
• vim 风格 J/K 导航:在 Select、MessageSelector 等 context 下将 J/K 绑定为上下移动,无需离开键盘主区。
• 解绑与 shell 冲突的键:若某个终端快捷键与 Claude Code 默认键位打架(如 Ctrl+S 被终端用于流控制),将其设为 null 解绑。
• 释放 chord 前缀:解绑 ctrl+x ctrl+k 和 ctrl+x ctrl+e 后,可将 ctrl+x 单独绑定为换行键,兼顾 Emacs 用户习惯。

常见坑

1. cmd 修饰符在大多数终端无效 — 绝大多数终端不发送 Super/Command 修饰符,写了 cmd+k 但实际上从不触发。统一改用 ctrl 或 meta。

2. 保留键写入配置会触发校验警告 — Ctrl+C/Ctrl+D/Ctrl+M/Caps Lock 无法重绑,写入后 Claude Code 会针对保留键冲突给出校验警告(官方原文 'shows warnings for … Reserved shortcut conflicts')。用 /doctor 可查看所有 keybinding 警告。

3. Chord 前缀未完全解绑导致单键失效 — 若 ctrl+x ctrl+k 还存在绑定而只设置了 ctrl+x 的映射,按下 Ctrl+X 后仍进入 chord 等待模式而非立即触发新动作。必须把同一前缀下的所有 chord 全部设为 null 再绑定单键。

4. Ctrl+B 被 tmux 截获 — tmux 默认 prefix 是 Ctrl+B,Claude Code 中的 task:background 默认绑定了该键。官方在 v2.1.169 起新增 Ctrl+X Ctrl+B 的 chord 备选,tmux 用户建议改用 chord 版本或更改 tmux prefix。

来源

• Customize keyboard shortcuts — Claude Code 官方文档
• Commands — Claude Code 官方文档