27 终端配置

Pi 使用 Kitty 键盘协议来可靠地检测修饰键。大多数现代终端都支持该协议，但有些需要配置。

能力覆盖

Pi 会自动检测 OSC 8 超链接、内联图片协议和真彩色。如果在终端代理或多路复用器背后检测失败，可以使用这些高级覆盖项：

设置的优先级高于环境变量；不设置或设为 auto 则保持自动检测。只强制启用完整终端链路都支持的能力，因为不支持的转义序列可能破坏渲染。

Kitty

开箱即用。

iTerm2

常规 TUI 模式

开箱即用。

全屏 TUI 模式

Pi 接管整个视口，因此 iTerm2 会发送鼠标滚轮报告，而不是滚动它原生的回滚缓冲区。在 iTerm2 默认的快速触控板行为下，这些报告可能丢失大部分加速滚轮增量，使全屏滚动比常规滚动慢得多。

如果在全屏模式下，快速的滚轮手势每次只能移动大约一行：

1. 打开 iTerm2 → Settings → Advanced。
2. 搜索 Trackpad scrolls fast? 并把它设为 No。

这是对整个 iTerm2 生效的折中方案，也可能改变原生触控板滚动。底层行为见 iTerm2 issue 9619。

Apple Terminal

可用时，Pi 会启用增强按键上报。如果 Terminal.app 仍为 Shift+Enter 发送普通回车，pi 会使用本地 macOS 修饰键回退，把该回车当作 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

该映射会发送原始换行字节。在 pi 内部，它与 Ctrl+J 无法区分，因此 tmux 和 pi 都看不到真正的 shift+enter 键事件。

如果你添加这条映射仅仅是为了 Claude Code 2.x 或更新版本，可以把它删除；除非你想在 tmux 中使用 Claude Code——那种情况下仍然需要这条 Ghostty 映射。

Pi 已将 Ctrl+J 绑定为默认的换行别名，因此 Shift+Enter 在 tmux 中可以经由该重映射继续工作，无需额外的 pi 配置。

全屏 TUI 模式

在全屏模式下，链接仍然可以点击，但当 pi 捕获鼠标输入时，Ghostty 不会显示悬停下划线，也不会显示左下角的 URL 预览。在 macOS 上按住 Shift+Command、在 Linux 上按住 Shift+Ctrl，可以使用 Ghostty 的原生链接处理。

WezTerm

WezTerm 通常可以通过 xterm modifyOtherKeys 开箱即用地支持 Shift+Enter。要显式使用 Kitty 键盘协议，请创建 ~/.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 可能需要可见的硬件光标来定位输入法候选窗口。如果 CJK 输入法候选没有跟随文本光标，请在运行 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（集成终端）

VS Code 1.109.5 及更新版本默认在集成终端中启用 Kitty 键盘协议，因此 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"
}

Zed（集成终端）

把这些按键绑定添加到你的 Zed keymap.json：

{
  "context": "Terminal",
  "bindings": {
    "shift-enter": ["terminal::SendText", "\u001b[13;2u"],
    "ctrl--": ["terminal::SendText", "\u001b[45;5u"],
    "ctrl-alt-]": ["terminal::SendText", "\u001b[93;7u"]
  }
}

Windows Terminal

Pi 在原生 Windows 或 WSL 上运行时使用 Windows 风格的快捷键：

• Alt+V 粘贴图片或剪贴板文本。
• Ctrl+F 在全屏模式下搜索会话记录，Ctrl+Up/Ctrl+Down 在标记的消息之间跳转。
• Alt+P 切换到上一个模型。
• Ctrl+Z 在原生 Windows 上撤销编辑；WSL 使用 Alt+Z，以便 Ctrl+Z 可以挂起 pi。
• Ctrl+Q 排队一条后续消息，Alt+Q 恢复排队的消息。

在 settings.json 中添加（Ctrl+Shift+, 或 Settings → Open JSON file），以转发用于插入新行的 Shift+Enter：

{
  "actions": [
    {
      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
      "keys": "shift+enter"
    }
  ]
}

Windows Terminal 默认把 Alt+Enter 绑定为全屏。如果想用它代替 pi 默认的 Ctrl+Q 来排队后续消息，请配置 Windows Terminal 发送该键，并在 pi 中把 app.message.followUp 绑定到 alt+enter。

如果你已经有 actions 数组，把这个对象加进去即可。修改设置后，请完全关闭并重新打开 Windows Terminal。

xfce4-terminal、terminator

这些终端对转义序列的支持有限。Ctrl+Enter 和 Shift+Enter 这类带修饰的回车键无法与普通 Enter 区分，导致 submit: ["ctrl+enter"] 这类自定义快捷键无法工作。

为获得最佳体验，请使用支持 Kitty 键盘协议的终端：

• Kitty
• Ghostty
• WezTerm
• iTerm2
• Alacritty（需要编译时启用 Kitty 协议支持）

IntelliJ IDEA（集成终端）

内置终端对转义序列的支持有限。在 IntelliJ 的终端中，Shift+Enter 无法与 Enter 区分。

如果你希望显示硬件光标，请在运行 pi 前设置 PI_HARDWARE_CURSOR=1（默认关闭以保持兼容）。

为获得最佳体验，建议使用专门的终端模拟器。