自定义键位绑定

通过 ~/.claude/keybindings.json 自定义 Claude Code 的键盘快捷键。

是什么

Claude Code 支持通过配置文件自定义键盘快捷键。运行 /keybindings 即可创建或打开位于 ~/.claude/keybindings.json 的配置文件。该功能需要 Claude Code v2.1.18 或更高版本（可用 claude --version 查看版本）。

配置文件以 context（上下文）为单位组织，把按键映射到具体的 action（动作）。修改配置文件后会被自动检测并应用，无需重启 Claude Code。

怎么工作

配置文件是一个对象，包含 bindings 数组；每个块指定一个 context，以及一个从按键到 action 的映射表。
顶层可选字段：$schema（用于编辑器自动补全的 JSON Schema URL）、$docs（文档 URL）、bindings（按 context 分组的绑定块数组）。
每个绑定块通过 context 字段指定生效范围，例如 Global（全局）、Chat（主聊天输入区）、Autocomplete、Confirmation、Transcript、HistorySearch、Task、Select、Scroll 等共约 20 个上下文。
action 采用 namespace:action 格式，如 chat:submit（发送消息）、app:toggleTodos（显示任务列表）；不同 context 提供不同的可用动作。
把某个按键映射到 null 即可解绑默认快捷键；这对 chord 绑定同样有效。
Claude Code 会校验绑定并对解析错误、无效 context 名、保留键冲突、终端复用器冲突、同一 context 重复绑定发出警告；运行 /doctor 可查看键位警告。

怎么配置 / 用法

配置文件位于 ~/.claude/keybindings.json。下例把 Ctrl+E 绑定为在 Chat 上下文中打开外部编辑器，并解绑 Ctrl+U：

json

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

按键语法：修饰键用 + 连接（ctrl/control、shift、alt/opt/option/meta、cmd/command/super/win）；chord 为用空格分隔的按键序列，如 ctrl+k ctrl+s；独立大写字母隐含 Shift（K 等价于 shift+k），但带修饰键的大写字母不隐含 Shift（ctrl+K 等同 ctrl+k）。

什么时候用

想把默认快捷键改成自己习惯的键位（如把外部编辑器绑到 Ctrl+E）。
需要解绑与终端复用器（tmux Ctrl+B、screen Ctrl+A）或自身习惯冲突的默认键。
想配置 vim 风格的大写/小写区分键位或 chord 组合键。
想腾出某个按键前缀，将其从 chord 改为单键绑定使用。

限制 / 坑

保留快捷键不可重绑：Ctrl+C（中断）、Ctrl+D（退出）、Ctrl+M（终端中与 Enter 相同）、Caps Lock（不会传给终端应用）。
cmd 这组修饰键仅在上报 Super 修饰键的终端（如支持 Kitty 键盘协议或 xterm modifyOtherKeys 的终端）中可被识别，多数终端不发送；想通用请用 ctrl 或 meta。
部分快捷键可能与终端复用器冲突：Ctrl+B（tmux 前缀）、Ctrl+A（GNU screen 前缀）、Ctrl+Z（Unix 进程挂起 SIGTSTP）。
若只解绑某前缀下的部分 chord 而非全部，按下该前缀仍会进入 chord 等待模式。
vim 模式下 Escape 仅在 INSERT 与 NORMAL 间切换，不触发 chat:cancel。

硬事实速查（12 条）

需要 Claude Code v2.1.18 或更高版本。
配置文件路径为 ~/.claude/keybindings.json，用 /keybindings 创建或打开。
配置修改自动生效，无需重启。
共约 20 个 context：Global、Chat、Autocomplete、Settings、Confirmation、Tabs、Help、Transcript、HistorySearch、Task、ThemePicker、Attachments、Footer、MessageSelector、DiffDialog、ModelPicker、Select、Plugin、Scroll、Doctor。
Chat 上下文默认键示例：chat:submit=Enter、chat:newline=Ctrl+J、chat:cancel=Escape、chat:stash=Ctrl+S、chat:externalEditor=Ctrl+G 或 Ctrl+X Ctrl+E。
Global/App 默认键：app:interrupt=Ctrl+C、app:exit=Ctrl+D、app:toggleTodos=Ctrl+T、app:toggleTranscript=Ctrl+O。
history:search 默认 Ctrl+R，historySearch:cycleScope（session/project/everywhere）默认 Ctrl+S。
permission:toggleDebug 现为未绑定，其原默认 Ctrl+D 已在 v2.1.146 移除（因与 app:exit 冲突）。
modifier 别名：alt=opt=option=meta；cmd=command=super=win。
把 action 设为 null 即可解绑默认快捷键，对 chord 同样适用。
fullscreen rendering 下 Chat 中 chat:clearInput（Ctrl+L）两秒内按两次执行 /clear。
校验涵盖 JSON 解析错误、无效 context、保留键冲突、复用器冲突、重复绑定；用 /doctor 查看警告。

官方出处：https://code.claude.com/docs/en/keybindings

自定义键位绑定 ​

是什么 ​

怎么工作 ​

怎么配置 / 用法 ​

什么时候用 ​

限制 / 坑 ​