Claude Code SDK #25：Keybindings 全解——context × keystroke × action，把快捷键改成自己的肌肉记忆

今天这期聊一个很容易被低估的东西：Keybindings。

Claude Code 的快捷键不是一张固定表。v2.1.18 之后，你可以把按键改成一份本地 JSON；运行 /keybindings，它会创建或打开 ~/.claude/keybindings.json，改完后无需重启，Claude Code 会自动检测并应用。1

这意味着一件事：如果你每天在 Claude Code 里写代码，快捷键不再只是「顺不顺手」的问题。它开始影响你能不能快速打断任务、切换模式、打开外部编辑器、处理后台 Agent、查看 transcript，以及在 tmux、fullscreen、Vim mode 里少踩坑。

1. 先把模型想对：context × keystroke × action

Keybindings 的配置文件是一个对象，核心字段是 bindings 数组；数组里的每个 block 都声明一个 context，再把某些 keystroke 映射到 action。官方示例里，Chat context 可以把 ctrl+e 绑定到 chat:externalEditor，也可以把 ctrl+u 设置成 null 来解绑。1

Keybindings 配置映射图 — 自制示意图：Keybindings 的核心路径是 context block → keystroke map → action namespace，依据官方 Keybindings 文档整理。1

最小配置长这样：

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

这里有两个细节值得记住。

第一，context 不是装饰字段。Global 作用于整个应用，Chat 只管主输入区，Autocomplete 只在补全面板打开时生效，Confirmation 管权限和确认弹窗，Task 管后台任务，DiffDialog 管 diff 查看器，Scroll 管 fullscreen 模式下的滚动和选择。官方文档列出的 context 超过十个，所以同一个按键在不同界面可以有不同含义。1

第二，action 用 namespace:action 的形式命名。比如 chat:submit 发送消息，app:toggleTodos 显示任务列表，task:background 把当前任务转入后台。这个命名方式比「某个按键做什么」更稳定，因为你真正绑定的是 Claude Code 内部动作，而不是终端层面的字符。1

2. 哪些默认键最应该先认识

如果只想先把日常体验调顺，别从全量 action 表开始背。先看这些高频动作：

场景	默认按键	动作	为什么重要
中断当前操作	`Ctrl+C`	`app:interrupt`	它是硬编码中断键，不能重绑；长任务跑偏时第一时间用它。1
退出 Claude Code	`Ctrl+D`	`app:exit`	同样属于保留快捷键，不能改成别的 action。1
打开外部编辑器	`Ctrl+G` 或 `Ctrl+X Ctrl+E`	`chat:externalEditor`	长 prompt、复杂 diff 描述、批量指令更适合丢进编辑器写。1
插入换行	`Ctrl+J`	`chat:newline`	它是跨终端稳定方案；Shift+Enter 是否可用取决于终端配置。2
切换权限模式	`Shift+Tab`	`chat:cycleMode` / `confirm:cycleMode`	输入区和确认弹窗各有对应 action，别只改其中一个。1
后台化当前任务	`Ctrl+B` 或 `Ctrl+X Ctrl+B`	`task:background`	官方给了 `Ctrl+X Ctrl+B`，用于避开 tmux 的 `Ctrl+B` prefix 冲突。1
查看 transcript	`Ctrl+O`	`app:toggleTranscript`	fullscreen 模式下，原生 scrollback 看不到 alternate screen 里的内容，transcript 是回看入口。3

这张表的重点不是让你照抄，而是帮你分层：哪些键是系统保留，哪些键是 Claude Code action，哪些键其实要先去终端层修。混在一起改，最容易把自己绕晕。

快捷键冲突雷达 — 自制示意图：`Ctrl+C` / `Ctrl+D` 属于保留键，`Ctrl+B` 容易撞 tmux，Option / Meta 要先确认终端是否发送 modifier。1 2

3. Keystroke 语法：别把终端问题误判成 Claude 问题

官方支持的 modifier 包括 ctrl / control、shift、alt / opt / option / meta，以及 cmd / command / super / win。但 cmd 组只有在终端上报 Super modifier 时才会被检测到，比如支持 Kitty keyboard protocol 或 xterm modifyOtherKeys mode 的终端；想跨终端稳定，优先用 ctrl 或 meta。1

大写字母也有规则：单独的 K 等价于 shift+k，适合 Vim 风格区分大小写；但 ctrl+K 只是写法风格，和 ctrl+k 一样，不额外代表 Shift。1

Chord 用空格分隔，例如：

ctrl+k ctrl+s

它表示先按 Ctrl+K，松开，再按 Ctrl+S。如果你喜欢 Emacs / tmux 那种前缀键思路，chord 会比堆一堆单键快捷键更干净。1

终端层要单独看。Claude Code 的 Terminal Configuration 文档说得很清楚：那一页解决的是「终端是否把正确的按键信号发给 Claude Code」，而 Keybindings 解决的是「Claude Code 收到按键后响应哪个动作」。2 比如 macOS 的 Option 键默认经常不作为 modifier 发送，需要在终端里开启「Use Option as Meta Key」或类似设置；否则你在 keybindings.json 里写 meta+p，Claude Code 可能根本收不到这个信号。2

4. `null` 不是删除字段，是主动解绑

解绑默认快捷键的写法是把 action 设为 null：

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

这个行为也适用于 chord。更细的点在 prefix：如果你解绑了某个 prefix 下的所有 chord，就可以把这个 prefix 本身拿来当单键绑定；如果只解绑一部分，按下 prefix 后仍会进入等待下一个键的 chord-wait 状态。官方示例是先解绑 ctrl+x ctrl+k 和 ctrl+x ctrl+e，再把 ctrl+x 绑定成 chat:newline。1

我建议你把 null 当成「冲突管理工具」，而不是随手清空默认键。尤其是 tmux 用户：Ctrl+B 和 tmux prefix 冲突，Claude Code 文档也把它列为 terminal multiplexer conflict；但 task:background 还有 Ctrl+X Ctrl+B 这个默认 chord，可用它绕开冲突。1

一个更稳的 Task 配置可以这样写：

{
  "bindings": [
    {
      "context": "Task",
      "bindings": {
        "ctrl+b": null,
        "ctrl+x ctrl+b": "task:background"
      }
    }
  ]
}

5. Vim mode、fullscreen 和 `/doctor`：三个边界条件

第一，Vim mode 和 Keybindings 是两套层级。Vim mode 处理输入框里的光标移动、模式和 motion；Keybindings 处理组件级动作，比如提交、切换 todos、打开 model picker。官方特别说明，Vim mode 里的 Escape 会从 INSERT 切到 NORMAL，不会触发 chat:cancel。1

第二，fullscreen 会让滚动和选择变成应用内动作。比如 scroll:pageUp、scroll:pageDown、selection:copy、selection:extendDown 都归到 Scroll context；Fullscreen 文档也提示，在 alternate screen buffer 中，原生命令行 scrollback 和搜索会变，回看通常要通过 Ctrl+O 进入 transcript。1 3

第三，别靠肉眼排错。Claude Code 会校验 keybindings，并对 invalid JSON、无效 context、保留键冲突、terminal multiplexer 冲突、同一 context 内重复绑定给出 warning；运行 /doctor 可以查看这些 keybinding warnings。1

6. 今天可以直接照做的一套顺序

先运行 claude --version，确认版本不低于 v2.1.18。自定义快捷键从这个版本开始可用。1
运行 /keybindings，让 Claude Code 创建或打开 ~/.claude/keybindings.json。不要一开始就从别人的配置里复制几十行。1
只改三个你每天高频用的动作：外部编辑器、换行、后台任务。先验证它们在 Chat、Task、Confirmation 这些不同 context 里的行为。
如果你在 tmux、VS Code、iTerm2、JetBrains 终端里用 Claude Code，先读 Terminal Configuration。Shift+Enter、Option-as-Meta、tmux passthrough 这些问题不是 keybindings.json 一份文件能解决的。2
改完跑 /doctor。如果它提示 reserved shortcut、duplicate binding 或 multiplexer conflict，先修这些基础问题，再去调更细的肌肉记忆。1

Keybindings 安全上线清单 — 自制示意图：先确认版本，再打开配置文件，小步改 1-3 个高频动作，最后用 `/doctor` 看 warning。1

Keybindings 的价值不在于把每个按键都改掉。真正有效的配置通常很短：少数几个高频动作，避开终端冲突，保留系统保留键，再把不同 context 的边界想清楚。

先从一个痛点开始改。比如把长 prompt 送进外部编辑器，或者把 tmux 下的后台任务改成 chord。能少一次手忙脚乱，就已经值回这份配置文件。