这页专门排查 Claude Code 在终端里“不按预期工作”的情况：多行输入、Option 快捷键、通知、tmux 透传、全屏渲染和 Vim 模式。按你的终端类型选择对应设置，必要时运行 /terminal-setup，或检查 preferredNotifChannel、CLAUDE_CODE_NO_FLICKER 与 ~/.tmux.conf。

Claude Code 终端配置怎么排查

Claude Code 在任何终端都能直接用；如果某个键位、通知或显示效果不对，再看这一页。这里的重点是让终端把正确的信号传给 Claude Code，而不是修改 Claude Code 自己的快捷键；要改 Claude Code 响应哪些按键，去看 keybindings。

Shift+Enter 变成提交而不是换行
macOS 上 Option 快捷键没有反应
Claude 完成后没有声音或提醒
你在 tmux 里运行 Claude Code
显示闪烁或滚动位置跳动
想在提示输入框里用 Vim 键位

Enter multiline prompts

按 Enter 会提交消息。要在不提交的情况下换行，可以按 Ctrl+J，或者输入 \ 后再按 Enter。这两种方式在所有终端都能直接用，不需要任何配置。

大多数终端也支持 Shift+Enter，但不同终端的支持情况不一样：

Terminal	Shift+Enter for newline
Ghostty, Kitty, iTerm2, WezTerm, Warp, Apple Terminal, Windows Terminal	Works without setup
VS Code, Cursor, Windsurf, Alacritty, Zed	Run `/terminal-setup` once
gnome-terminal, JetBrains IDEs such as PyCharm and Android Studio	Not available; use Ctrl+J or `\` then Enter

对 VS Code、Cursor、Windsurf、Alacritty 和 Zed 来说，运行一次 /terminal-setup 会把 Shift+Enter 以及其他按键绑定写入终端的配置文件。对 VS Code、Cursor 和 Windsurf，它还会在编辑器设置里写入 terminal.integrated.mouseWheelScrollSensitivity，让 fullscreen mode 下滚动更顺一些。已有的绑定和设置会保留不动；如果看到 VSCode terminal Shift+Enter key binding already configured 之类的提示，说明这次没有改动任何内容。/terminal-setup 必须在宿主终端里直接运行，不能在 tmux 或 screen 里运行，因为它需要写宿主终端的配置文件。

如果你是在 tmux 里运行，即使外层终端本身支持 Shift+Enter，也还需要下面的 tmux 配置。

如果你想把换行绑定到别的键，或者把行为反过来，让 Enter 插入换行、Shift+Enter 提交，可以在 keybindings file 里映射 chat:newline 和 chat:submit。

Enable Option key shortcuts on macOS

有些 Claude Code 快捷键会用到 Option 键，比如 Option+Enter 换行、Option+P 切换模型。macOS 上，大多数终端默认不会把 Option 当作修饰键发送，所以这些快捷键不会生效，直到你手动打开这个选项。终端里通常叫 “Use Option as Meta Key”；Meta 是 Unix 里对现在这个 Option/Alt 键的历史叫法。

Apple Terminal

打开 Settings → Profiles → Keyboard
勾选 “Use Option as Meta Key”

如果你接受过 Claude Code 首次运行时弹出的提示，里面写着 “Option+Enter for newlines and visual bell”，这一步已经替你做过了。那个提示会自动运行 /terminal-setup，把 Option 设为 Meta，并把 Apple Terminal 配置成视觉闪烁而不是声音铃声。

iTerm2

打开 Settings → Profiles → Keys → General
将 Left Option key 和 Right Option key 设为 “Esc+”

在 iTerm2 里运行 /terminal-setup，还会在 Settings → General → Selection 里打开 “Applications in terminal may access clipboard”，这样 /copy 命令就能写入系统剪贴板。这个命令即使在 tmux 里运行也能识别出 iTerm2。改完后要重启 iTerm2 才会生效。

VS Code

在 VS Code 设置里加入：

"terminal.integrated.macOptionIsMeta": true

其他终端

Ghostty、Kitty 和其他终端，请在终端自己的配置文件里找 Option-as-Alt 或 Option-as-Meta 相关设置。

Get a terminal bell or notification

当 Claude 完成任务，或者停下来等待权限确认时，它会发出一个通知事件。把这个事件表现成终端铃声或桌面通知后，你就可以让长任务继续跑，自己去处理别的事。

默认情况下，Claude Code 只在 Ghostty、Kitty 和 iTerm2 里发送桌面通知。其他终端里，可以把 preferredNotifChannel 设为 "terminal_bell" 来改用终端铃声，或者配置 Notification hook 自定义声音或命令。

桌面通知会通过 SSH 送回本地机器，所以远程会话也能提醒你。Ghostty 和 Kitty 不需要额外配置就会把通知转到系统通知中心。iTerm2 需要手动打开转发：

打开 Settings → Profiles → Terminal
勾选 “Notification Center Alerts”
点击 “Filter Alerts”，启用 “Send escape sequence-generated alerts”

如果还是看不到通知，先确认终端应用在操作系统里有通知权限；如果你在 tmux 里运行，还要启用 passthrough。

Play a sound with a Notification hook

任何终端都可以配置 Notification hook，在 Claude 需要你介入时播放声音或执行自定义命令。Hook 会和内置通知同时运行，不会互相替代；所以像 Warp 或 VS Code 集成终端这类收不到桌面通知的环境，可以改用 hook，或者把 preferredNotifChannel 设为 "terminal_bell"。

下面的示例会在 macOS 上播放系统声音。链接里的指南还提供了 macOS、Linux 和 Windows 的桌面通知命令。

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

Configure tmux

当 Claude Code 跑在 tmux 里时，默认有两个问题：Shift+Enter 会变成提交而不是换行，桌面通知和 progress bar 也传不到外层终端。把下面这些行加到 ~/.tmux.conf，然后执行 tmux source-file ~/.tmux.conf，把配置加载到当前运行中的 server：

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

allow-passthrough 这一行会让通知和进度更新穿过 tmux，到达外层终端，而不是被 tmux 吃掉。extended-keys 这几行会让 tmux 区分 Shift+Enter 和普通 Enter，这样换行快捷键才能正常工作。

Match the color theme

用 /theme 命令，或者在 /config 里打开主题选择器，挑一个和终端匹配的 Claude Code 主题。选择 auto 选项后，Claude Code 会识别终端的浅色或深色背景；只要终端跟着系统外观切换，主题也会跟着变。Claude Code 不控制终端自己的配色方案，那个是由终端应用自己管理的。

如果你想自定义界面底部显示的内容，可以配置 custom status line，显示当前模型、工作目录、git 分支或其他上下文。

Create a custom theme

自定义主题需要 Claude Code v2.1.118 或更高版本。

除了内置预设，/theme 还会列出你自己定义的自定义主题，以及已安装 plugins 提供的主题。列表末尾选择 New custom theme… 就能交互式创建：先给主题命名，再逐个选择要覆盖的颜色 token。把光标放在某个自定义主题上时按 Ctrl+E，可以直接编辑它。

每个自定义主题都是 ~/.claude/themes/ 里的一个 JSON 文件。去掉 .json 扩展名后的文件名就是主题的 slug；选择这个主题后，Claude Code 会把 custom:<slug> 存成主题偏好。文件里有三个可选字段：

Field	Type	Description
`name`	string	显示在 `/theme` 里的名称，默认使用文件名 slug
`base`	string	主题起始使用的内置预设：`dark`、`light`、`dark-daltonized`、`light-daltonized`、`dark-ansi` 或 `light-ansi`，默认是 `dark`
`overrides`	object	颜色 token 到颜色值的映射；这里没列出的 token 会继续沿用 base 预设

颜色值支持 #rrggbb、#rgb、rgb(r,g,b)、ansi256(n) 或 ansi:<name>，其中 <name> 是 16 个标准 ANSI 颜色名之一，比如 red 或 cyanBright。未知 token 和无效颜色值会被忽略，所以拼写错误不会把渲染弄坏。

下面这个例子定义了一个保留 dark 预设，但重新着色提示高亮、错误文本和成功文本的主题：

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

Claude Code 会监视 ~/.claude/themes/，文件变化后自动重新加载，所以你在编辑器里改完，当前会话不需要重启就会生效。

下面的参考表列出 overrides 里可设置的 token。/theme 里的交互编辑器会显示同样的 token，并提供实时预览；另外还有少量这里没列出的单用途强调色，比如 onboarding 屏幕颜色。

Color token reference

下面的示例组合了下方几个分组里的 token：品牌强调色、plan 模式边框、diff 背景和 fullscreen 消息背景。

{
  "name": "Midnight",
  "base": "dark",
  "overrides": {
    "claude": "#a78bfa",
    "planMode": "#38bdf8",
    "diffAdded": "#14532d",
    "diffRemoved": "#7f1d1d",
    "userMessageBackground": "#1e1b4b"
  }
}

Text and accent colors

控制界面里主要品牌强调色，以及各处使用的前景文字颜色。

Token	Controls
`claude`	Primary brand accent, used for the spinner and assistant label
`text`	Default foreground text
`inverseText`	Text drawn on top of a colored background, such as status badges
`inactive`	Secondary text such as hints, timestamps, and disabled items
`subtle`	Faint borders and de-emphasized secondary text
`suggestion`	Autocomplete suggestions and selection highlight in pickers
`permission`	Dialog borders, including permission prompts and pickers
`remember`	Memory and `CLAUDE.md` indicators

Status colors

用于消息和状态指示，表示成功、失败和警告。

Token	Controls
`success`	Success messages and passing checks
`error`	Error messages and failures
`warning`	Warnings, caution messages, and the auto mode border
`merged`	Merged pull request status

Input box and mode indicators

设置输入框边框颜色，以及权限模式或指示器激活时显示的强调色。

Token	Controls
`promptBorder`	Input box border in the default permission mode
`planMode`	Plan mode accent and border
`autoAccept`	Accept-edits mode accent and border
`bashBorder`	Input box border when entering a `!` shell command
`ide`	IDE connection indicator
`fastMode`	Fast mode indicator

Diff rendering

给文件编辑和代码审查里的新增、删除内容上色。

Token	Controls
`diffAdded`	Background of added lines
`diffRemoved`	Background of removed lines
`diffAddedDimmed`	Background of unchanged context near added lines
`diffRemovedDimmed`	Background of unchanged context near removed lines
`diffAddedWord`	Word-level highlight within an added line
`diffRemovedWord`	Word-level highlight within a removed line

Fullscreen mode

只在 fullscreen rendering mode 里生效，这时消息会有背景填充。

Token	Controls
`userMessageBackground`	Background behind your messages in the transcript
`userMessageBackgroundHover`	Background behind a message while hovered or expanded
`messageActionsBackground`	Background behind the selected message when the action bar is open
`bashMessageBackgroundColor`	Background behind `!` shell command entries in the transcript
`memoryBackgroundColor`	Background behind `#` memory entries in the transcript
`selectionBg`	Background of text selected with the mouse

Usage meter and speaker labels

调整 /usage 视图里的用量条，以及区分你和 Claude 消息的标签颜色。

Token	Controls
`rate_limit_fill`	Filled portion of the usage meter
`rate_limit_empty`	Unfilled portion of the usage meter
`briefLabelYou`	Color of the `You` label on your messages
`briefLabelClaude`	Color of the `Claude` label on assistant messages

Shimmer variants and subagent colors

有些 token 还有配套的 shimmer 版本，用来提供 spinner 动画渐变里更亮的颜色。如果动画看起来不协调，就把 shimmer 和基础 token 一起覆盖。

claude and claudeShimmer
warning and warningShimmer
permission and permissionShimmer
promptBorder and promptBorderShimmer
inactive and inactiveShimmer
fastMode and fastModeShimmer

每个 subagent 和并行任务都会用八种命名颜色之一显示，方便你在 transcript 里区分它们。token 名称遵循 <color>_FOR_SUBAGENTS_ONLY 这种模式，其中 <color> 可以是 red、blue、green、yellow、purple、orange、pink 或 cyan。你可以覆盖这些值来改变对应命名颜色的显示效果。比如，定义里写了 color: blue 的 subagent，会使用 blue_FOR_SUBAGENTS_ONLY 的值来渲染。

提示输入框里的 ultrathink 和 ultraplan 关键字，会显示为七色彩虹渐变。token 名称遵循 rainbow_<color> 和 rainbow_<color>_shimmer 的模式，其中 <color> 是 red、orange、yellow、green、blue、indigo 或 violet。

Switch to fullscreen rendering

如果 Claude 工作时出现显示闪烁，或者滚动位置跳来跳去，可以切换到 fullscreen rendering mode。这种模式会在终端保留给全屏应用的独立屏幕上渲染，而不是不断追加到普通 scrollback 里，所以内存占用更稳定，也额外支持鼠标滚动和选择。在这个模式下，你要在 Claude Code 内部用鼠标或 PageUp 滚动，而不是用终端原生的 scrollback；搜索和复制方法见 fullscreen page。

在当前会话里保留对话内容并切换，可以运行 /tui fullscreen。如果要把它设为默认，在启动 Claude Code 之前设置 CLAUDE_CODE_NO_FLICKER 环境变量：

CLAUDE_CODE_NO_FLICKER=1 claude

$env:CLAUDE_CODE_NO_FLICKER = "1"; claude

{
  "env": {
    "CLAUDE_CODE_NO_FLICKER": "1"
  }
}

Paste large content

当你往提示框里粘贴超过 10,000 个字符时，Claude Code 会把输入折叠成一个 [Pasted text] 占位符，这样输入框还能继续正常使用。完整内容在你提交后仍然会发送给 Claude。

VS Code 集成终端在非常大的粘贴场景下，可能会在内容到达 Claude Code 之前就丢掉一些字符，所以那里更适合用基于文件的工作流。对于整个文件或很长日志这类超大输入，建议先把内容写入文件，再让 Claude 读取，而不是直接粘贴。这样对话记录更清晰，后续轮次里 Claude 也能直接按文件路径引用它。

Edit prompts with Vim keybindings

Claude Code 在提示输入框里内置了 Vim 风格编辑模式。可以通过 /config → Editor mode 打开，或者在 ~/.claude/settings.json 里把 editorMode 设成 "vim"。把 Editor mode 设回 normal 就会关闭。

Vim mode 支持 NORMAL 和 VISUAL 模式的一部分移动和操作，比如 hjkl 导航、v/V 选择，以及配合文本对象使用的 d/c/y。完整按键表见 Vim editor mode reference。Vim 移动键不能通过 keybindings file 重新映射。

在 INSERT 模式下，按 Enter 仍然会提交提示词，不像标准 Vim。要插入换行，请在 NORMAL 模式下用 o 或 O，或者按 Ctrl+J。

Interactive mode: full keyboard shortcut reference and the Vim key table
Keybindings: remap any Claude Code shortcut, including Enter and Shift+Enter
Fullscreen rendering: details on scrolling, search, and copy in fullscreen mode
Hooks guide: more Notification hook examples for Linux and Windows
Troubleshooting: fixes for issues outside terminal configuration

常见问题

Shift+Enter 还是不能换行，为什么？

先确认你的终端是否本来就支持 Shift+Enter。Ghostty、Kitty、iTerm2、WezTerm、Warp、Apple Terminal 和 Windows Terminal 无需额外配置；VS Code、Cursor、Windsurf、Alacritty、Zed 需要运行一次 /terminal-setup；gnome-terminal 和 JetBrains IDE 自带终端不支持，只能用 Ctrl+J 或 \ 再按 Enter。

为什么我在 tmux 里看不到通知？

tmux 默认会拦截通知和进度条。把 set -g allow-passthrough on、set -s extended-keys on 和 set -as terminal-features 'xterm*:extkeys' 加到 ~/.tmux.conf，再执行 tmux source-file ~/.tmux.conf。如果外层终端本身也不支持通知，还要检查 preferredNotifChannel 或 Notification hook。

Claude Code 能直接把大段文本完整粘贴进去吗？

超过 10,000 个字符时，输入会在界面里折叠成 [Pasted text] 占位符，但提交后仍会发送完整内容。VS Code 集成终端更容易在超大粘贴时丢字符，所以长日志、整文件这类内容更适合先写入文件，再让 Claude 按路径读取。

Claude Code 终端配置怎么排查 #

Enter multiline prompts #

Enable Option key shortcuts on macOS #

Apple Terminal #

iTerm2 #

VS Code #

其他终端 #

Get a terminal bell or notification #

Play a sound with a Notification hook #

Configure tmux #

Match the color theme #

Create a custom theme #

Color token reference #

Text and accent colors #

Status colors #

Input box and mode indicators #

Diff rendering #

Fullscreen mode #

Usage meter and speaker labels #

Shimmer variants and subagent colors #

Switch to fullscreen rendering #

Paste large content #

Edit prompts with Vim keybindings #

Related resources #

常见问题 #

Shift+Enter 还是不能换行，为什么？ #

为什么我在 tmux 里看不到通知？ #

Claude Code 能直接把大段文本完整粘贴进去吗？ #