# 终端配置

> 各终端模拟器对 Kitty 键盘协议的支持情况与按键配置方法。

---

LLMS 索引： [llms.txt](/llms.txt)

---

Pi 使用 [Kitty 键盘协议](https://sw.kovidgoyal.net/kitty/keyboard-protocol/)来可靠地检测修饰键。大多数现代终端都支持该协议，但有些需要配置。

## 能力覆盖 {#capability-overrides}

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

| 能力 | 环境变量 | JSON 设置 |
|------------|----------------------|--------------|
| OSC 8 超链接 | `PI_HYPERLINKS=1\|0\|auto` | `terminal.hyperlinks: true\|false\|"auto"` |
| 内联图片 | `PI_IMAGE_PROTOCOL=kitty\|iterm2\|none\|auto` | `terminal.images: "kitty"\|"iterm2"\|false\|"auto"` |
| 真彩色 | `PI_TRUE_COLOR=1\|0\|auto` | `terminal.trueColor: true\|false\|"auto"` |

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

## Kitty {#kitty}

开箱即用。

## iTerm2 {#iterm2}

### 常规 TUI 模式 {#regular-tui-mode}

开箱即用。

### 全屏 TUI 模式 {#fullscreen-tui-mode}

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

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

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

这是对整个 iTerm2 生效的折中方案，也可能改变原生触控板滚动。底层行为见 [iTerm2 issue 9619](https://gitlab.com/gnachman/iterm2/-/work_items/9619)。

## Apple Terminal {#apple-terminal}

可用时，Pi 会启用增强按键上报。如果 Terminal.app 仍为 `Shift+Enter` 发送普通回车，pi 会使用本地 macOS 修饰键回退，把该回车当作 `Shift+Enter` 处理。

这个回退只在 pi 与 Terminal.app 运行在同一台 Mac 上时才有效。它无法通过远程 SSH 检测本地键盘。

## Ghostty {#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 模式 {#fullscreen-tui-mode-1}

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

## WezTerm {#wezterm}

WezTerm 通常可以通过 xterm modifyOtherKeys 开箱即用地支持 `Shift+Enter`。要显式使用 Kitty 键盘协议，请创建 `~/.wezterm.lua`：

```lua
local wezterm = require 'wezterm'
local config = wezterm.config_builder()
config.enable_kitty_keyboard = true
return config
```

在 macOS 上，WezTerm 默认把 `Option+Enter` 绑定为全屏。要把 `Option+Enter` 用作 pi 的后续消息排队，请添加这个按键覆盖：

```lua
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}

Alacritty 通常可以开箱即用地支持 `Shift+Enter`。在 macOS 上，`Option+Enter` 到达时可能变成普通的 `Enter`。要把 `Option+Enter` 用作 pi 的后续消息排队，请在 `~/.config/alacritty/alacritty.toml` 中添加：

```toml
[[keyboard.bindings]]
key = "Enter"
mods = "Alt"
chars = "\u001b[13;3u"
```

修改配置后请重启 Alacritty。

## VS Code（集成终端） {#vs-code-integrated-terminal}

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` 中添加：

```json
{
  "key": "shift+enter",
  "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "\u001b[13;2u" },
  "when": "terminalFocus"
}
```

## Zed（集成终端） {#zed-integrated-terminal}

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

```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 {#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`：

```json
{
  "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 {#xfce4-terminal-terminator}

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

为获得最佳体验，请使用支持 Kitty 键盘协议的终端：
- [Kitty](https://sw.kovidgoyal.net/kitty/)
- [Ghostty](https://ghostty.org/)
- [WezTerm](https://wezfurlong.org/wezterm/)
- [iTerm2](https://iterm2.com/)
- [Alacritty](https://github.com/alacritty/alacritty)（需要编译时启用 Kitty 协议支持）

## IntelliJ IDEA（集成终端） {#intellij-idea-integrated-terminal}

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

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

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

---

反链：

- [环境变量](/book/pi/environment-variables/)
- [快捷键](/book/pi/keybindings/)
- [快速开始](/book/pi/quickstart/)
- [使用 Pi](/book/pi/usage/)