自定义快捷键 ​

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

CodeBuddy Code 支持自定义键盘快捷键。运行 /keybindings 命令创建或打开位于 ~/.codebuddy/keybindings.json 的配置文件。

配置文件 ​

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

对 keybindings 文件的更改会自动检测并应用，无需重启 CodeBuddy Code。

字段说明
$schema可选，JSON Schema URL，用于编辑器自动补全
$docs可选，文档 URL
bindings按上下文组织的绑定块数组

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

json
{
  "$schema": "https://code.codebuddy.ai/schemas/keybindings.json",
  "$docs": "https://code.codebuddy.ai/docs/keybindings",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+u": null
      }
    }
  ]
}

上下文（Contexts） ​

每个绑定块指定一个 context，决定快捷键在何时生效：

Context说明
Global在应用的任何位置生效
Chat聊天输入框获得焦点时
InputBox文本输入框处于活跃状态时
Terminal终端视图处于活跃状态时
Autocomplete自动补全菜单显示时
Confirmation确认/权限对话框显示时
HistorySearch搜索命令历史时 (Ctrl+R)
Task任务/代理在前台运行时
Settings设置面板打开时
CommandPalette命令面板打开时
Select选择/列表组件获得焦点时
PermissionDialog工具权限对话框显示时
Help帮助页面打开时
Plugin插件对话框打开时
DiffDialogDiff 对话框打开时
MessageSelector消息选择器 (rewind) 打开时

可用动作（Actions） ​

动作遵循 namespace:action 格式，如 chat:submit 发送消息、app:toggleTodos 切换待办事项列表。每个上下文有特定的可用动作。

应用动作 ​

在 Global 上下文中可用：

动作默认按键说明
app:interruptCtrl+C中断当前操作
app:exitCtrl+D退出 CodeBuddy Code
app:redrawCtrl+L刷新终端屏幕
app:toggleTodosCtrl+T切换待办事项列表
app:toggleTranscriptCtrl+O切换详细转录
app:toggleSidebarCmd+B切换侧边栏（Web UI）
app:toggleTerminalCmd+J切换终端（Web UI）
app:commandPaletteCmd+Shift+P / Ctrl+Shift+P打开命令面板（Web UI）
app:newChatCmd+N新建对话（Web UI）
app:settingsCmd+,打开设置（Web UI）
app:focusInputCmd+L聚焦输入框（Web UI）

历史动作 ​

用于导航命令历史：

动作默认按键说明
history:searchCtrl+R打开历史搜索
history:previousUp上一条历史
history:nextDown下一条历史

聊天动作 ​

在 Chat 上下文中可用：

动作默认按键说明
chat:cancelEscape取消当前输入
chat:submitEnter发送消息
chat:killAgentsCtrl+X Ctrl+K终止所有后台代理
chat:cycleModeShift+Tab*切换权限模式
chat:modelPickerMeta+P打开模型选择器
chat:thinkingToggleMeta+T切换扩展思考
chat:undoCtrl+_, Ctrl+Shift+-撤销
chat:externalEditorCtrl+G, Ctrl+X Ctrl+E在外部编辑器中打开
chat:stashCtrl+S暂存当前输入
chat:imagePasteCtrl+V (Windows: Alt+V)粘贴图片

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

自动补全动作 ​

在 Autocomplete 上下文中可用：

动作默认按键说明
autocomplete:acceptTab接受建议
autocomplete:dismissEscape关闭菜单
autocomplete:previousUp上一项
autocomplete:nextDown下一项

确认动作 ​

在 Confirmation 上下文中可用：

动作默认按键说明
confirm:yesY, Enter确认
confirm:noN, Escape取消
confirm:previousUp上一项
confirm:nextDown下一项
confirm:toggleSpace切换选中
confirm:toggleExplanationCtrl+E切换权限说明
permission:toggleDebugCtrl+D切换权限调试信息

转录动作 ​

在 Transcript 上下文中可用：

动作默认按键说明
transcript:toggleShowAllCtrl+E切换显示全部内容
transcript:exitQ, Ctrl+C, Escape退出转录视图

历史搜索动作 ​

在 HistorySearch 上下文中可用：

动作默认按键说明
historySearch:nextCtrl+R下一条匹配
historySearch:acceptEscape, Tab接受选择
historySearch:cancelCtrl+C取消搜索
historySearch:executeEnter执行选中命令

任务动作 ​

在 Task 上下文中可用：

动作默认按键说明
task:backgroundCtrl+B将当前任务转入后台

帮助动作 ​

在 Help 上下文中可用：

动作默认按键说明
help:dismissEscape关闭帮助菜单

设置动作 ​

在 Settings 上下文中可用：

动作默认按键说明
settings:search/进入搜索模式
settings:closeEnter保存并关闭配置面板

选择列表动作 ​

在 Select 上下文中可用：

动作默认按键说明
select:nextDown, J, Ctrl+N下一项
select:previousUp, K, Ctrl+P上一项
select:acceptEnter确认选择
select:cancelEscape取消选择

命令面板动作 ​

在 CommandPalette 上下文中可用：

动作默认按键说明
commandPalette:previousUp上一项
commandPalette:nextDown下一项
commandPalette:executeEnter执行命令
commandPalette:closeEscape关闭面板

Diff 动作 ​

在 DiffDialog 上下文中可用：

动作默认按键说明
diff:dismissEscape关闭 Diff 查看器
diff:previousFileUp上一个文件
diff:nextFileDown下一个文件
diff:viewDetailsEnter查看详情

消息选择器动作 ​

在 MessageSelector 上下文中可用：

动作默认按键说明
messageSelector:upUp, K, Ctrl+P向上移动
messageSelector:downDown, J, Ctrl+N向下移动
messageSelector:topShift+Up跳到顶部
messageSelector:bottomShift+Down跳到底部
messageSelector:selectEnter选择消息

插件动作 ​

在 Plugin 上下文中可用：

动作默认按键说明
plugin:toggleSpace切换插件选中
plugin:installI安装选中插件

按键语法 ​

修饰键 ​

使用 + 分隔符组合修饰键：

  • ctrl 或 control — Control 键
  • alt、opt 或 option — Alt/Option 键
  • shift — Shift 键
  • meta、cmd 或 command — Meta/Command 键

示例：

ctrl+k          单个修饰键 + 按键
shift+tab       Shift + Tab
meta+p          Command/Meta + P
ctrl+shift+c    多个修饰键

弦序列（Chords） ​

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

ctrl+x ctrl+k   先按 Ctrl+X，松开，再按 Ctrl+K
ctrl+x ctrl+e   先按 Ctrl+X，松开，再按 Ctrl+E

弦序列有 1000ms 超时。如果超时未完成第二步，弦序列将被取消。

特殊按键 ​

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

解绑默认快捷键 ​

将动作设为 null 以解绑默认快捷键：

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

解绑弦序列的所有组合后，可以将前缀键用作单键绑定：

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

如果只解绑了部分弦序列，按下前缀键仍会进入弦等待模式。

保留快捷键 ​

以下快捷键不可重新绑定：

快捷键原因
Ctrl+C硬编码的中断/取消
Ctrl+D硬编码的退出
Ctrl+M在终端中等同于 Enter（两者都发送 CR）

终端冲突 ​

某些快捷键可能与终端复用器冲突：

快捷键冲突
Ctrl+Btmux 前缀键（按两次发送）
Ctrl+AGNU screen 前缀键
Ctrl+ZUnix 进程挂起 (SIGTSTP)

Web UI 可视化配置 ​

除了编辑 JSON 文件，你还可以在 Web UI 中通过可视化界面管理快捷键：

  1. 在侧边栏点击 快捷键 导航项，或使用 URL #/keybindings
  2. 使用搜索框按名称、按键或上下文筛选快捷键
  3. 点击编辑按钮（铅笔图标）录制新的快捷键组合
  4. 录制对话框会实时显示冲突检测
  5. 用户自定义的绑定以左侧高亮边框标记
  6. 点击重置按钮可恢复单个绑定为默认值

REST API ​

Web UI 通过 REST API 管理快捷键：

端点方法说明
/api/v1/keybindingsGET获取所有快捷键（默认 + 用户 + 合并）
/api/v1/keybindingsPUT保存用户快捷键配置
/api/v1/keybindings/resetPOST重置为默认值（删除用户配置）
/api/v1/keybindings/validatePOST验证配置（不保存）

验证 ​

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

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