Pi 官方文档
终端设置
终端设置
Pi 使用 Kitty keyboard protocol 来可靠识别修饰键。大多数现代终端都支持这个协议，但有些需要额外配置。
Kitty, iTerm2
开箱即用。
Apple Terminal
Pi 会在可用时启用增强按键报告。如果 Terminal.app 仍然把 Shift+Enter 发送成普通的 Return，pi 会使用本地 macOS 修饰键回退，把这个 Return 当作 Shift+Enter 处理。
这个回退只在 pi 与 Terminal.app 运行在同一台 Mac 上时有效。通过远程 SSH 时，它无法识别本地键盘。
Ghostty
把下面内容添加到你的 Ghostty 配置中（macOS 上是 ~/Library/Application Support/com.mitchellh.ghostty/config，Linux 上是 ~/.config/ghostty/config）：
keybind = alt+backspace=text:\x1b\x7f
较旧版本的 Claude Code 可能添加过这个 Ghostty 映射：
keybind = shift+enter=text:\n
那个映射会发送原始的 linefeed byte。在 pi 内部，它和 Ctrl+J 没有区别，所以 tmux 和 pi 都不再能看到真正的 shift+enter 按键事件。
如果你添加这个映射只是因为 Claude Code 2.x 或更新版本，你可以删掉它；不过如果你还想在 tmux 里使用 Claude Code，就先保留，因为在那里它仍然需要这个 Ghostty 映射。
如果你希望 Shift+Enter 通过这个重映射在 tmux 中继续生效，请把 ctrl+j 加到 ~/.pi/agent/keybindings.json 里的 pi newLine keybinding 中：
{
"newLine": ["shift+enter", "ctrl+j"]
}
WezTerm
WezTerm 通常会通过 xterm modifyOtherKeys 让 Shift+Enter 开箱即用。若要显式使用 Kitty keyboard protocol，请创建 ~/.wezterm.lua：
local wezterm = require 'wezterm'
local config = wezterm.config_builder()
config.enable_kitty_keyboard = true
return config
在 macOS 上，WezTerm 默认把 Option+Enter 绑定为全屏。若要把 Option+Enter 用于 pi 的后续排队，请添加这个按键覆盖配置：
local wezterm = require 'wezterm'
local config = wezterm.config_builder()
config.keys = {
{
key = 'Enter',
mods = 'ALT',
action = wezterm.action.SendString('\x1b[13;3u'),
},
}
return config
如果你已经有 config.keys 表，就把这条项加进去。
在 WSL 上，WezTerm 可能需要显示硬件光标，才能正确定位 IME 候选窗口。如果 CJK IME 候选没有跟随文本光标，请在运行 pi 之前设置 PI_HARDWARE_CURSOR=1，或者在设置中把 showHardwareCursor 设为 true。
Alacritty
Alacritty 通常会让 Shift+Enter 开箱即用。在 macOS 上，Option+Enter 可能会被识别成普通的 Enter。若要把 Option+Enter 用于 pi 的后续排队，请添加到 ~/.config/alacritty/alacritty.toml：
[[keyboard.bindings]]
key = "Enter"
mods = "Alt"
chars = "\u001b[13;3u"
修改配置后，重启 Alacritty。
VS Code (Integrated Terminal)
VS Code 1.109.5 及更新版本会在集成终端中默认启用 Kitty keyboard protocol，所以 Shift+Enter 应该可以开箱即用。
早于 1.109.5 的 VS Code 需要为 Shift+Enter 显式配置终端按键绑定。
keybindings.json 位置：
- macOS:
~/Library/Application Support/Code/User/keybindings.json - Linux:
~/.config/Code/User/keybindings.json - Windows:
%APPDATA%\\Code\\User\\keybindings.json
把下面内容添加到 keybindings.json：
{
"key": "shift+enter",
"command": "workbench.action.terminal.sendSequence",
"args": { "text": "\u001b[13;2u" },
"when": "terminalFocus"
}
Windows Terminal
把下面内容添加到 settings.json（Ctrl+Shift+, 或 Settings → Open JSON file），以转发 pi 使用的带修饰键 Enter：
{
"actions": [
{
"command": { "action": "sendInput", "input": "\u001b[13;2u" },
"keys": "shift+enter"
},
{
"command": { "action": "sendInput", "input": "\u001b[13;3u" },
"keys": "alt+enter"
}
]
}
Shift+Enter会插入新行。- Windows Terminal 默认把
Alt+Enter绑定为全屏。这会导致 pi 收不到用于后续排队的Alt+Enter。 - 把
Alt+Enter重映射到sendInput，就能把真实的按键组合转发给 pi。
如果你已经有 actions 数组，就把这些对象加进去。如果旧的全屏行为仍然存在，请彻底关闭并重新打开 Windows Terminal。
xfce4-terminal, terminator
这些终端对转义序列的支持有限。像 Ctrl+Enter 和 Shift+Enter 这样的带修饰键 Enter，无法与普通 Enter 区分，因此 submit: ["ctrl+enter"] 这类自定义按键绑定无法工作。
为了获得最佳体验，请使用支持 Kitty keyboard protocol 的终端：
IntelliJ IDEA (Integrated Terminal)
内置终端对转义序列的支持有限。在 IntelliJ 的终端里，Shift+Enter 无法与 Enter 区分。
如果你希望显示硬件光标，请在运行 pi 前设置 PI_HARDWARE_CURSOR=1（默认关闭，以保证兼容性）。
为了获得最佳体验，建议使用专门的终端模拟器。