键盘快捷键定制
本教程共 30 篇 · 第 15 篇 · 更新于 2026-08-10 · 约 10 分钟阅读
本节目标：熟悉 pi 的默认快捷键体系，掌握
keybindings.json的配置语法，能自定义快捷键甚至切换到 Emacs 或 Vim 风格，并学会处理终端快捷键冲突。
终端应用的效率很大程度取决于键盘操作是否顺手。pi 的 TUI 界面把几乎所有常用操作都绑了快捷键——移动光标、提交输入、切换模型、展开工具输出、浏览会话树——手指不用离开键盘就能完成大部分交互。
默认设置已经够用，但万一你想把 ctrl+p 从”切换模型”改成”历史记录向上”，或者把整套方向键改成 Vim 的 hjkl 模式——pi 不但支持，而且改完 /reload 就生效，不需要重启。
本章基于 pi v0.84.1。
快捷键配置文件
文件位置只有一个：
~/.pi/agent/keybindings.json修改后不需要重启 pi，在交互模式里敲：
/reloadpi 会重新加载配置文件，新的快捷键立刻生效。想看当前所有快捷键及其绑定，用：
/hotkeys这个命令列出所有可绑定的操作名称、当前绑定键和所属功能区——排查冲突或者找某个功能对应的配置键名时特别好用。
Note如果你是从旧版 pi 升级上来的，旧配置中不带命名空间前缀的键名（比如
cursorUp、expandTools）会在启动时自动迁移为新的带命名空间的格式（tui.editor.cursorUp、app.tools.expand）。不需要手动改。
快捷键的书写格式
基本格式：修饰键+按键。修饰键可以组合，按键可以是字母、数字、功能键、方向键、符号键。
修饰键： ctrl、shift、alt、super
可用按键：
- 字母：
a-z - 数字：
0-9 - 功能键：
f1-f12 - 方向键：
up、down、left、right - 特殊键：
escape/esc、enter/return、tab、space、backspace、delete、insert、home、end、pageUp、pageDown - 符号键：
`,-,=,[,],\,;,',,,.,/等，基本覆盖键盘上所有可打印符号
组合写法：
ctrl+shift+p
alt+ctrl+x
ctrl+shift+alt+x
super+k
ctrl+super+k
ctrl+1super 键（Windows 上的 Win 键，macOS 上的 Cmd 键）需要终端支持 Kitty keyboard protocol 才能单独识别。如果你的终端不支持，super 组合键可能不生效。
默认快捷键一览
按功能区分类，方便查找。
编辑器光标移动
| 操作 | 默认快捷键 | 说明 |
|---|---|---|
| 光标上移 | up | 到最顶后进入更早的历史记录 |
| 光标下移 | down | 到最底后进入更新的历史记录 |
| 光标左移 | left、ctrl+b | 左移一个字符 |
| 光标右移 | right、ctrl+f | 右移一个字符 |
| 按词左移 | alt+left、ctrl+left、alt+b | 左移一个单词 |
| 按词右移 | alt+right、ctrl+right、alt+f | 右移一个单词 |
| 行首 | home、ctrl+home、ctrl+a | 跳到行首 |
| 行尾 | end、ctrl+end、ctrl+e | 跳到行尾 |
| 跳转到字符 | ctrl+] | 向前跳到指定字符 |
| 跳转回字符 | ctrl+alt+] | 向后跳到指定字符 |
| 向上翻页 | pageUp、ctrl+pageUp | 编辑区向上翻页 |
| 向下翻页 | pageDown、ctrl+pageDown | 编辑区向下翻页 |
编辑器删除
| 操作 | 默认快捷键 | 说明 |
|---|---|---|
| 删除前一个字符 | backspace | — |
| 删除后一个字符 | delete、ctrl+d | — |
| 删除前一个词 | ctrl+w、alt+backspace | — |
| 删除后一个词 | alt+d、alt+delete | — |
| 删至行首 | ctrl+u | 光标到行首之间的内容 |
| 删至行尾 | ctrl+k | 光标到行尾之间的内容 |
输入与提交
| 操作 | 默认快捷键 | 说明 |
|---|---|---|
| 换行 | shift+enter、ctrl+j | 插入换行符，不提交 |
| 提交输入 | enter | 发送当前内容 |
| Tab/补全 | tab | 触发路径自动补全 |
| 撤销 | ctrl+- | 撤销上一步编辑 |
| 粘贴最近删除 | ctrl+y | 粘贴 kill ring 中最新的文本 |
| 循环粘贴历史 | alt+y | 在 kill ring 中循环切换粘贴内容 |
程序操作
| 操作 | 默认快捷键 | 说明 |
|---|---|---|
| 中断/取消 | escape | 取消当前 AI 操作 |
| 清空/退出 | ctrl+c | 第一次清空编辑区，第二次退出 |
| 退出（编辑区为空时） | ctrl+d | — |
| 外部编辑器 | ctrl+g | 在外部编辑器中编辑当前输入 |
| 粘贴图片 | ctrl+v（Windows: alt+v） | 从剪贴板粘贴 |
| 复制会话 | ctrl+x | 复制最后一条 AI 消息 |
模型与推理
| 操作 | 默认快捷键 | 说明 |
|---|---|---|
| 模型选择器 | ctrl+l | 打开模型选择列表 |
| 下一个模型 | ctrl+p | 循环切换到下一个模型 |
| 上一个模型 | shift+ctrl+p | 循环切换到上一个模型 |
| 切换推理等级 | shift+tab | 循环切换推理深度 |
| 展开/折叠推理 | ctrl+t | 显示或隐藏 AI 推理过程 |
| 展开/折叠工具输出 | ctrl+o | 显示或隐藏工具调用输出 |
消息队列与会话
| 操作 | 默认快捷键 | 说明 |
|---|---|---|
| 跟进消息 | alt+enter | 将消息加入跟进队列 |
| 取回排队消息 | alt+up | 将排队消息取回编辑器 |
会话树导航
| 操作 | 默认快捷键 | 说明 |
|---|---|---|
| 折叠/上一步 | ctrl+left、alt+left | 折叠分支或跳到上一个段落 |
| 展开/下一步 | ctrl+right、alt+right | 展开分支或跳到下一个段落 |
| 编辑标签 | shift+l | 编辑树节点的标签 |
| 切换时间戳 | shift+t | 显示或隐藏标签时间戳 |
全屏模式（Fullscreen TUI）
在 --tui-mode fullscreen 下，默认的 up/down/pageUp/pageDown/home/end 控制的是对话历史滚动而不是编辑器光标。要用编辑器的话加上 ctrl 前缀。
| 操作 | 默认快捷键 | 说明 |
|---|---|---|
| 对话区上翻 | pageUp | — |
| 对话区下翻 | pageDown | — |
| 跳到上一条消息 | ctrl+shift+up | — |
| 跳到下一条消息 | ctrl+shift+down | — |
| 滚动到顶部 | home | — |
| 滚动到底部 | end | 跟随新输出 |
keybindings.json 写法
最简单的配置：一个操作绑定一个键。
{
"tui.editor.historyPrevious": "ctrl+p",
"tui.editor.historyNext": "ctrl+n"
}一个操作绑定多个键（数组）：
{
"tui.editor.deleteWordBackward": ["ctrl+w", "alt+backspace"]
}配置文件里只需要写你要改的操作。没写的操作保持默认快捷键不变。每个操作可以绑定单个快捷键（字符串）或多个快捷键（数组）。
Tip配置项会完全覆盖默认值，不是追加。如果你给某个操作指定了
["ctrl+p"]，它原来的默认快捷键就没了——只有ctrl+p有效。
Emacs 风格
习惯 Emacs 的人可以把编辑器操作改成自己熟悉的快捷键：
{
"tui.editor.historyPrevious": "ctrl+p",
"tui.editor.historyNext": "ctrl+n",
"tui.editor.cursorLeft": ["left", "ctrl+b"],
"tui.editor.cursorRight": ["right", "ctrl+f"],
"tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
"tui.editor.cursorWordRight": ["alt+right", "alt+f"],
"tui.editor.deleteCharForward": ["delete", "ctrl+d"],
"tui.editor.deleteCharBackward": ["backspace", "ctrl+h"],
"tui.input.newLine": ["shift+enter", "ctrl+j"]
}这个配置把方向键、删除、换行都加上了 Emacs 风格的备用快捷键。注意 ctrl+p 原来是”下一个模型”，改完之后在编辑器里它就变成”历史记录向上了”。模型切换你仍然可以在 /settings 或模型选择器里做。
Vim 风格
习惯 hjkl 的人可以把方向键映射到 alt+h/j/k/l：
{
"tui.editor.cursorUp": ["up", "alt+k"],
"tui.editor.cursorDown": ["down", "alt+j"],
"tui.editor.cursorLeft": ["left", "alt+h"],
"tui.editor.cursorRight": ["right", "alt+l"],
"tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
"tui.editor.cursorWordRight": ["alt+right", "alt+w"]
}因为 pi 的编辑器不是模态的（不能切 Normal/Insert 模式），纯 hjkl 绑定会和你输文字冲突——你想打 “hello”，pi 收到四个方向键操作。所以这里用 alt+hjkl，既保留了肌肉记忆，又不会在打字时误触发。
终端快捷键冲突
这是终端应用绕不开的话题。你的终端模拟器自己就占着一堆快捷键。
常见的冲突清单：
| 终端快捷键 | 终端行为 | pi 想用 | 怎么办 |
|---|---|---|---|
ctrl+l | 清屏 | 打开模型选择器 | 在终端设置里取消”清屏”快捷键，或者把 pi 这边改成别的 |
ctrl+c | 发送 SIGINT | 清空编辑区 | 这种通常不需要改——pi 区分了”编辑区有内容”和”编辑区为空”两种场景 |
ctrl+d | 发送 EOF | 退出 | 同样区分场景，编辑区为空才退出 |
ctrl+z | 挂起进程（Linux/macOS） | 挂起到后台 | 没问题，行为一致。Windows 上该快捷键无默认绑定 |
alt+enter | 全屏切换（部分终端） | 跟进消息 | 在终端设置里禁用全屏快捷键 |
super+* | 系统级快捷键 | 自定义组合键 | 需要终端支持 Kitty keyboard protocol 才能传给 pi |
解决方法就两种：要么在终端设置里把冲突的快捷键关掉，要么在 pi 的 keybindings.json 里改绑定。选哪个看你的习惯——如果某个终端快捷键你完全不用，在终端里关掉最彻底。如果你用了好多年的终端清屏习惯，就改 pi 这边的配置。
NoteWindows 终端用户注意：
ctrl+z在 Windows 上没有默认绑定（Windows 不支持 Unix job control）。如果你手动绑了它，pi 会显示状态提示而不是真的挂起。在 WSL 里则正常支持ctrl+z/fg。
全屏模式的快捷键路由
当你用 --tui-mode fullscreen 启动 pi 时，默认的导航键行为会改变：
| 按键 | 非全屏模式 | 全屏模式 |
|---|---|---|
home、end | 控制编辑器 | 控制对话区滚动 |
ctrl+home、ctrl+end | 控制编辑器 | 控制编辑器 |
pageUp、pageDown | 控制编辑器 | 控制对话区滚动 |
ctrl+pageUp、ctrl+pageDown | 控制编辑器 | 控制编辑器 |
简单记：全屏模式下，不加 ctrl 的是对话区滚动，加了 ctrl 的才是编辑器操作。如果你想反过来，在 keybindings.json 里调：
{
"tui.altScreen.pageUp": "ctrl+pageUp",
"tui.altScreen.pageDown": "ctrl+pageDown"
}这样 pageUp 控制编辑器，ctrl+pageUp 控制对话区——完全按你的偏好来。
排查与技巧
不确定某个操作的键名？ 用 /hotkeys 命令。它列出所有可绑定的操作和当前绑定，比翻文档快。
改了不生效？ 确认你运行了 /reload。确认 JSON 格式没写错（多一个逗号或少一个引号都可能导致整个文件被忽略）。
覆盖后想恢复默认？ 直接从 keybindings.json 里删掉对应的条目就行。
同一个键绑了两个操作？ 不会被阻止，但行为取决于哪个操作先被触发。尽量不要这么搞，排查起来很头疼。
fullscreen 模式下想禁用某个对话区快捷键？ 把它设成空数组：
{
"tui.altScreen.pageUp": []
}