跳至内容
Pi Agent
中文文档
平台设置
终端设置

终端设置

创建于 2025-07-16·更新于 2026-07-16

Pi 使用 Kitty 键盘协议 来实现可靠的修饰键检测。大多数现代终端都支持该协议，但部分终端需要进行配置。

Kitty、iTerm2

开箱即用，无需额外配置。

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 配置。

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 可能需要可见硬件光标来定位 IME 候选窗口。如果 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 应可开箱即用。

VS Code 1.109.5 之前的版本需要为 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+, 或通过设置 → 打开 JSON 文件）中添加以下配置，以转发 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 键盘协议的终端：

IntelliJ IDEA（集成终端）

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

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

建议使用专用终端模拟器以获得最佳体验。

tmuxShell 别名