Claude Code SDK #23：Terminal Configuration 全解——Shift+Enter、tmux、通知、主题与 fullscreen，一次把终端手感调顺

如果你在 Claude Code 里遇到这几类怪问题：Shift+Enter 直接提交、Option+P 没反应、tmux 里没有通知、VS Code 终端闪屏、大段日志粘贴后界面卡住。先别急着怪模型。

很多时候，问题不在 Claude，也不在 SDK，而在终端没有把「正确的信号」送到 Claude Code。官方 Terminal configuration 页开场就说得很直白：Claude Code 默认能在任何终端里运行，这页只在「某件具体事情不符合预期」时才需要看。1

这期 #23 拆的就是这个隐藏层：终端配置不是美化项，而是 Claude Code 交互体验的信号层。

1/ 先分清：Terminal configuration 管「信号」，Keybindings 管「动作」

Claude Code 的终端问题最容易被误判成快捷键问题。

官方文档把边界切得很清楚：Terminal configuration 关注的是终端是否把正确按键、通知、渲染信号传给 Claude Code；如果你想改 Claude Code 收到信号后要执行什么动作，才去看 keybindings。1

你看到的现象	先查哪一层	原因
Shift+Enter 不能换行	终端配置	终端可能根本没把 Shift+Enter 和 Enter 区分开。1
想把 Enter 改成换行、Shift+Enter 改成提交	Keybindings	这是把 `chat:newline` 和 `chat:submit` 重新映射。2
Option+P 打不开模型选择器	终端配置	macOS 终端通常默认不把 Option 当 modifier 发送。1
tmux 里通知、进度条消失	tmux passthrough	tmux 默认可能吞掉外层终端需要的 escape sequence。1

一个实用判断：如果 Claude Code 没收到信号，改 keybindings 没用；如果信号已经收到，但你想改行为，才改 keybindings。

Terminal signal path — 自制示意图：终端先发出按键信号，Claude Code CLI 再把信号交给 keybindings 动作；边界依据官方 Terminal configuration 与 Keybindings 文档整理。1

2/ 换行：Ctrl+J 是保底方案，Shift+Enter 看终端

在 Claude Code 的 chat 输入框里，Enter 默认提交消息。要插入换行，官方给了两个所有终端都可用的保底方案：按 Ctrl+J，或者输入 \ 后再按 Enter。1

Shift+Enter 能不能直接换行，取决于终端：

终端	Shift+Enter 换行状态
Ghostty、Kitty、iTerm2、WezTerm、Warp、Apple Terminal、Windows Terminal	无需配置即可工作。1
VS Code、Cursor、Devin Desktop、Alacritty、Zed	运行一次 `/terminal-setup`。1
gnome-terminal、JetBrains IDE 终端	不支持；用 `Ctrl+J` 或 `\` + Enter。1

这里有个坑：/terminal-setup 要在宿主终端里跑，不要在 tmux 或 screen 里面跑。它需要写宿主终端的配置文件，套一层 multiplexer 后，Claude Code 可能摸不到真正要改的配置。1

如果你只是想换键位，不是修终端信号，可以直接写 ~/.claude/keybindings.json。例如把 ctrl+x 绑成换行，需要在 Chat context 里把对应 keystroke 映射到 chat:newline；keybindings 文档同时说明，chat:submit 的默认键是 Enter，chat:newline 的默认键是 Ctrl+J。2

3/ macOS 的 Option 键：它默认不一定是 Meta

Claude Code 里有一批 Meta / Option 快捷键，比如 Option+Enter 换行、Option+P 切模型。macOS 上的麻烦是：很多终端默认不把 Option 当 modifier 发送，所以你按了，Claude Code 收不到。1

对应配置很具体：

终端	设置入口
Apple Terminal	Settings → Profiles → Keyboard，勾选「Use Option as Meta Key」。1
iTerm2	Settings → Profiles → Keys → General，把 Left / Right Option key 设成 `Esc+`。1
VS Code	在设置里加 `"terminal.integrated.macOptionIsMeta": true`。1

如果你第一次启动 Claude Code 时接受了「Option+Enter for newlines and visual bell」提示，Apple Terminal 这部分已经由 /terminal-setup 处理过：它会启用 Option as Meta，并把 audio bell 改成 visual screen flash。1

4/ 通知：长任务结束后，你需要一个能穿透终端的提醒

Claude Code 在任务结束或等待权限确认时会触发 notification event。默认情况下，桌面通知只在 Ghostty、Kitty 和 iTerm2 里发送；其他终端可以把 preferredNotifChannel 设成 "terminal_bell"，或者用 Notification hook 播放声音、执行命令。1

最小可用的 macOS 声音 hook 长这样，写在 ~/.claude/settings.json：1

{
  "hooks": {
    "Notification": [
      {
        "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
      }
    ]
  }
}

iTerm2 还要额外开通知转发：Settings → Profiles → Terminal，勾选「Notification Center Alerts」，再进「Filter Alerts」启用「Send escape sequence-generated alerts」。如果你在 tmux 里跑 Claude Code，还要配 tmux passthrough。1

这不是花活。长时间跑代码审查、批量改文件、后台 Agent 时，通知决定你能不能把 Claude Code 当成异步 worker 用，而不是盯着终端等它停下来。

5/ tmux：三行配置解决两类问题

Claude Code 跑在 tmux 里时，官方点名了两个默认会坏的地方：Shift+Enter 会变成提交，桌面通知和 progress bar 也传不到外层终端。解决办法是在 ~/.tmux.conf 加三行，然后执行 tmux source-file ~/.tmux.conf。1

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

这三行分别对应两个能力：allow-passthrough 让通知和进度更新穿过 tmux；extended-keys 让 tmux 区分 Shift+Enter 和普通 Enter。1

tmux passthrough and extended keys — 自制示意图：tmux 夹在外层终端与 Claude Code 之间，passthrough 负责通知与进度，extended-keys 负责区分组合键。1

如果你还开了 fullscreen rendering，tmux 还有一个独立注意点：鼠标滚轮需要 set -g mouse on，否则滚轮事件会被 tmux 自己处理。Fullscreen 文档也提醒，iTerm2 的 tmux -CC integration mode 不适合开启 fullscreen rendering。3

6/ 主题：`/theme` 管 Claude Code 的配色，不管你的终端主题

Terminal configuration 里还有一段容易被忽略：Claude Code 的 /theme 只改变 Claude Code 界面里的颜色；终端应用自己的配色，仍然在终端应用里设置。1

自定义主题要求 Claude Code v2.1.118 或更高版本。主题文件放在 ~/.claude/themes/，文件名去掉 .json 后就是 slug；文件里有三个可选字段：name、base、overrides。1

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

我建议把主题当成「状态可读性」来调，而不是当皮肤来调。比如 error、warning、success、permission、planMode、diffAdded、diffRemoved 这些 token，直接影响你在终端里扫失败、权限、计划模式和 diff 的速度。官方的 token reference 也按 text/accent、status、input box、diff、fullscreen 等组划分。1

7/ Fullscreen rendering：它不是全屏窗口，是另一条渲染路径

如果你在 VS Code integrated terminal、tmux 或 iTerm2 里看到屏幕闪、滚动位置跳、长会话越来越卡，优先试 /tui fullscreen。官方 fullscreen 文档说明，这个模式把界面画到终端的 alternate screen buffer，只渲染当前可见消息，所以长会话里的内存使用更稳定。3

Classic scrollback vs fullscreen rendering — 自制示意图：classic renderer 依赖原生 scrollback，fullscreen renderer 使用 alternate screen，只渲染可见消息。3

当前会话里切换：1

/tui fullscreen

启动前默认开启：1

CLAUDE_CODE_NO_FLICKER=1 claude

注意它改变的是滚动模型：对话不再存在于终端原生 scrollback 里。要搜索和回看，进入 transcript mode，用 Ctrl+o，再用 / 搜索；如果需要把内容写回终端原生 scrollback，可以在 transcript mode 里按 [。3

VS Code、Cursor、Devin Desktop 还有一个联动：/terminal-setup 会把 terminal.integrated.gpuAcceleration 设成 "off"，避免 integrated terminal 乱码；同时会调整 terminal.integrated.mouseWheelScrollSensitivity，让 fullscreen mode 里滚动更顺。1

8/ 大段粘贴：超过 10,000 字符会折叠显示，但最好改走文件

Claude Code 对大粘贴做了一个保护：当你一次粘贴超过 10,000 字符时，输入框会显示成 [Pasted text] 占位符，避免输入框失控；提交时，完整内容仍会发送给 Claude。1

但这不代表你应该把日志、源码、长 JSON 都粘进去。官方特别提醒，VS Code integrated terminal 在超大粘贴时可能丢字符；更稳的方式是把内容写进文件，让 Claude 读取文件路径。1

这条建议可以直接变成团队规范：

小片段：直接粘贴。
中等片段：确认 [Pasted text] 后再提交。
大文件、长日志、CI 输出：保存成文件，让 Claude 读路径。
需要反复引用的上下文：不要粘贴，放进 repo 或 .claude/ 约定文件。

9/ Vim mode：改的是输入编辑器，不是整个 Claude Code

如果你想在 prompt input 里用 Vim 风格编辑，可以在 /config → Editor mode 开启，或者把 editorMode 设成 "vim"。这个字段属于 settings.json 的可用配置项。1 4

但它不是一个完整 Vim。官方说它支持 NORMAL / VISUAL 模式的一部分 motions 和 operators；Vim motions 也不能通过 keybindings 文件重映射。INSERT 模式下按 Enter 仍然提交 prompt，要换行用 NORMAL 模式的 o / O，或 Ctrl+J。1

这点对重度 Vim 用户很重要：Vim mode 解决的是「我怎么编辑这一条 prompt」，不是「我怎么重写 Claude Code 的全局交互」。全局动作仍然由 keybindings 系统处理，Vim mode 和 keybindings 是两层。2

10/ 我的推荐配置顺序

如果你今天只想把 Claude Code 终端手感调顺，按这个顺序来：

先修换行。 在你的主力终端确认 Shift+Enter 是否可用；不行就跑 /terminal-setup，再把 Ctrl+J 当保底肌肉记忆。1
macOS 用户打开 Option-as-Meta。 否则一堆 Meta 快捷键看起来像坏了，其实只是终端没把 Option 发出去。1
tmux 用户先加三行 passthrough / extended-keys。 不然通知、进度、Shift+Enter 都可能被 tmux 截断。1
长任务用户配通知。 Ghostty、Kitty、iTerm2 走桌面通知；其他终端用 preferredNotifChannel: "terminal_bell" 或 Notification hook。1
闪屏、跳滚动、长会话卡顿，再上 /tui fullscreen。 这是渲染路径切换，不是普通外观设置；切过去后要适应 transcript mode 的搜索和复制方式。3

Terminal configuration 这章看似边角，实战里却很关键。模型能力越强，你越会把 Claude Code 当成长时间运行的开发进程，而不是一次问答窗口。到了这个阶段，终端能不能正确传按键、传通知、稳住渲染，直接决定你的工作流能不能跑起来。