全屏渲染

全屏渲染是研究预览。你是从全屏还是经典渲染器启动，取决于你的环境（见「默认全屏」）。在当前对话里运行 /tui fullscreen 或 /tui default 来切换。行为可能根据反馈变化；下文的版本号和启动规则以官方为准。

全屏渲染是 Claude Code CLI 的另一条渲染路径：它消除闪烁，让长对话里的内存用量保持平稳，并增加鼠标支持。它在终端的备用屏幕缓冲区上绘制界面（像 vim 或 htop 那样），只渲染当前可见的消息，这减少了每次更新发给终端的数据量。

差别在渲染吞吐量是瓶颈的终端模拟器里最明显，如 VS Code 集成终端、tmux 和 iTerm2。如果 Claude 工作期间你的终端滚动位置跳到顶部，或者工具输出流入时屏幕闪烁，这个模式能解决这些问题。这里的「全屏」描述的是 Claude Code 像 vim 那样接管终端的绘制表面，与最大化终端窗口无关，在任何窗口大小下都能工作。

启用全屏渲染

在任何 Claude Code 对话里运行 /tui fullscreen。CLI 保存 tui 设置并带着完整对话重新启动进全屏，所以你可以在会话中途切换而不丢失上下文。运行 /tui default 切回经典渲染器，不带参数运行 /tui 则打印当前使用哪个渲染器。

在屏幕阅读器模式下，Claude Code 总是使用经典渲染器，只有已附加的后台会话仍以全屏渲染。如果你在任何其他会话里运行 /tui fullscreen，Claude Code 会打印说明而不是切换，也不改变已保存的 tui 设置。

Claude Code 会把这些带入重新启动的会话：

• 屏幕上呈现的对话。经过 /rewind 之后：如果你在会话早些时候回退过，Claude Code 从回退点重新启动，而不是从磁盘上保存的较长转录；比如你回退过了最后三条消息，重新启动的会话就没有它们；如果你回退到第一条消息之前，Claude Code 以空对话重新启动。
• 你的权限模式和 effort 级别。
• 你最后用 /model 选的模型。
• 你用 --allowed-tools 或 --disallowed-tools 传入的规则，以及你的 --agent、--agents、--append-system-prompt 和 --system-prompt-snapshot 标志。

如果会话有无法传给重启进程的限制，Claude Code 会拒绝重新启动。它无法传递的限制包括：--system-prompt 替换、--tools 允许列表或 --setting-sources 这样的启动标志；以及由 hook 或 SDK 权限更新只为本会话添加的拒绝或询问规则。这种情况下 Claude Code 打印 Cannot switch renderers in this session 并给出原因，它不切换也不保存任何东西。

你也可以在启动 Claude Code 之前设置 CLAUDE_CODE_NO_FLICKER 环境变量：

CLAUDE_CODE_NO_FLICKER=1 claude

tui 设置和该变量同时设置时如何组合，见该设置的条目。在全屏启动失败之后，Claude Code 仍遵循该变量但不遵循该设置。/tui 命令会从重新启动的进程里清除 CLAUDE_CODE_NO_FLICKER，使它写入的设置生效。

默认全屏

已附加的后台会话以全屏渲染，屏幕阅读器模式下的其他会话使用经典渲染器。除此之外，Claude Code 让你从下表中第一个与你的环境匹配的那一行对应的渲染器启动：

不获取功能标志的会话包括通过 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 的会话，以及关闭了遥测的会话。

如果你从经典渲染器启动且没有保存 tui 设置，Claude Code 可能在启动时打开一个对话框提供切换：

• 如果你接受，Claude Code 以与 /tui fullscreen 相同的方式重新启动、带着相同的会话状态，并在重新启动的会话成功启动后保存该设置。
• 如果你选 Not now，Claude Code 在这台机器上不再提供。
• Claude Code 在对话框显示过三次启动后停止提供，不论是否回答过。

有什么变化

全屏渲染改变 CLI 向终端绘制的方式。输入框固定在屏幕底部，而不是随输出流入而移动。如果 Claude 工作时输入框不动，说明全屏渲染已激活。渲染树里只保留可见消息，所以不论对话多长，内存都保持恒定。

因为对话存在备用屏幕缓冲区而不是你终端的回滚缓冲区里，有几件事的做法不同了：

如果鼠标捕获干扰了你的工作流，可以在保留无闪烁渲染的同时关闭它（见「保留原生文本选择」）。

使用鼠标

全屏渲染捕获鼠标事件并在 Claude Code 内部处理它们：

• 点击提示输入框，把光标定位到你正在输入的文本里的任意位置。
• 点击 / 命令或 @ 文件列表里的建议来接受它；悬停会高亮光标下的行。
• 点击选择菜单里的选项来选中它。这涵盖权限提示、/model、/config 和其他显示选项列表的对话框；悬停在光标下的行上显示指针。
• 点击多选菜单里的选项来切换它，点击提交按钮确认你的选择。点击自由文本行（如多选问题里的 Other 行）会聚焦它的输入字段，让你输入答案（需要 Claude Code v2.1.208 或更高）。
• 点击 /config 面板里设置的值来更改它，并用鼠标滚轮滚动设置列表（需要 v2.1.271 或更高）。
• 选项比一次显示的更多时，用鼠标滚轮滚动选择或多选菜单，例如在矮终端窗口里的 /model 列表；指针在选项上方时滚轮滚动列表（需要 v2.1.280 或更高）。
• 用滚动条滚动溢出的列表。 在 /skills、/mcp 和 /plugin 已安装列表这样的列表面板里，指针悬停在行数超出可显示范围的列表上时，旁边出现滚动条；点击滑轨跳到该位置，或拖动滑块（需要 v2.1.281 或更高）。
• 点击折叠的工具结果来展开它查看完整输出，再点击折叠；工具调用及其结果一起展开。只有还有更多内容可显示的消息才可点击。点击还会展开 ! shell 命令的输出，不论是较早被截断的结果还是命令运行时的实时进度行（需要 v2.1.257 或更高）；当发送者是队友或在你会话中运行的另一个智能体时，点击也会展开暗色的 Message from @<sender> 行。来自你其他会话之一的消息所在行还会显示消息的第一行且不可点击，所以按 Ctrl+o 阅读那一条。
• 在 macOS 上按住 Cmd、在 Linux 和 Windows 上按住 Ctrl 并点击 URL 或文件路径来打开它。普通的 http:// 和 https:// URL 在你的浏览器里打开，工具输出里的文件路径（如 Edit 或 Write 之后打印的那些）在你的默认应用里打开；不带修饰键的普通点击不会打开链接，这与原生终端行为一致。Claude Code 把网络（UNC）路径（如 \\server\share\file.ts）渲染为没有链接的纯文本，因为打开网络路径可能把你的 Windows 凭据发给它指向的主机。有些 macOS 终端把 Cmd+点击转发给运行中的应用而不是自己打开链接，而终端鼠标协议没法编码 Cmd 键，所以 Claude Code 收到的是普通点击；在 Ghostty 和 macOS 上的 Warp 里，Claude Code 检测到这一点并让对链接的普通点击打开它，按住 Cmd 仍然有效。在 VS Code 集成终端和类似的基于 xterm.js 的终端里，Claude Code 听从终端自己的链接处理器，它用的是同样的手势。
• 点击并拖动，在对话中的任何位置选择文本。双击选择一个词，遵循 iTerm2 的词边界，所以文件路径会作为一个整体被选中；双击 URL 选择整个 URL（含协议部分）；三击选择整行。
• 用鼠标滚轮滚动，在对话中移动。

选中的文本在鼠标松开时自动复制到你的剪贴板。要关闭它，在 /config 里切换 Copy on select。关闭 Copy on select 后，按 Ctrl+Shift+c 手动复制；在支持 kitty 键盘协议的终端（如 kitty、WezTerm、Ghostty 和 iTerm2）里，Cmd+c 也有效。如果你有一个活动的选择，Ctrl+c 会复制而不是取消。

有活动选择时，按住 Shift 并按方向键可用键盘扩展它：选择到达顶部或底部边缘时，Shift+↑ 和 Shift+↓ 会滚动视口；Shift+Home 和 Shift+End 扩展到当前行的开头或结尾。

在普通提示视图里，活动选择会发生什么取决于你按的键：

• Esc：Claude Code 执行该键通常的动作，如中断运行中的响应或关闭打开的对话框，选择保持高亮。
• PgUp、PgDn、Ctrl+Home、Ctrl+End，或带 Shift、Alt/Option、Cmd/Win/Super 的方向键、Home 或 End：选择保留。
• 其他任何键，包括普通方向键、Enter 和输入的字符：Claude Code 清除选择。
• 绑定到 selection:clear 的键：Claude Code 清除选择，即使该键是 Esc 或本来会保留选择的其他键；该动作没有默认绑定。

在转录模式下，那里列出的导航和搜索键同样保留选择。

滚动对话

全屏渲染在应用内部处理滚动。用这些快捷键导航：

即使经过压缩之后，你也可以滚动回会话开头：Claude 从压缩摘要继续工作，但 Claude Code 在多次压缩之间，在全屏回滚里保留每一条较早的消息。

在没有专用 PgUp、PgDn、Home 或 End 键的键盘（如 MacBook 键盘）上，按住 Fn 配合方向键：Fn+↑ 发送 PgUp，Fn+↓ 发送 PgDn，Fn+← 发送 Home，Fn+→ 发送 End。Ctrl+Fn+→ 在 macOS 上到不了 Claude Code，所以 MacBook 键盘默认没有可用的跳到底部和弦。可以改用这几种办法：点击跳到底部按钮；用鼠标滚轮滚到底部以恢复跟随；把 scroll:bottom 重绑定为你的键盘能发送的和弦。这些动作都可重绑定，完整的动作名（包括没有默认绑定的半页和整页变体）见键位配置页的滚动动作。

向上滚动期间，对话顶部有一行暗色的标题行，显示已滚出视野上方的最近一条提示；点击该行跳到那条提示。

自动跟随

向上滚动会暂停自动跟随，使新输出不会把你拉回底部。向上滚动期间，一个 Jump to bottom 按钮浮在转录底部边缘上，新输出到达时会显示 3 new messages 这样的计数；点击它、按 Ctrl+End 或滚到底部来恢复跟随。自动跟随暂停期间，响应流式输出完成时视图也停留在你滚动到的位置。

按钮的键盘提示反映你的键盘能发送什么：在 macOS 上它建议点击，或用 Fn+↓ 滚动，因为 Ctrl+End 从 Mac 键盘到不了 Claude Code。重绑定 scroll:bottom 后，按钮在每个平台上都显示你的和弦。在窄到放不下完整标签的终端上，按钮会缩短提示而不是换行到下面的转录行上。

要彻底关闭自动跟随，使视图停留在你离开的位置，打开 /config 把 Auto-scroll 设为关。关闭自动滚动后，视图永远不会自己跳到底部；需要响应的权限提示和其他对话框无论该设置如何仍会滚动到视野中。

鼠标滚轮滚动

鼠标滚轮滚动要求你的终端把鼠标事件转发给 Claude Code。大多数终端在应用请求时都会这么做。iTerm2 把它做成按配置文件的设置：如果滚轮没反应但 PgUp 和 PgDn 有效，打开 Settings → Profiles → Terminal 并打开 Enable mouse reporting；点击展开和文本选择要工作，也需要同一个设置。

如果鼠标滚轮滚动感觉慢，你的终端可能每个物理刻度只发一个滚动事件而没有倍数。有些终端（如 Ghostty 和开启了更快滚动的 iTerm2）已经放大了滚轮事件，其他的（包括 VS Code 集成终端）每刻度恰好发一个事件，Claude Code 无法检测是哪种。设置 CLAUDE_CODE_SCROLL_SPEED 来乘以基础滚动距离：

export CLAUDE_CODE_SCROLL_SPEED=3

值 3 与 vim 和类似应用里的默认值一致。该设置接受不超过 20 的任何正值，包括小于 1 的小数（如 0.25），用来在已经放大滚轮事件的终端里减慢加速的触控板和滚轮滚动。

要交互式调整滚动速度，运行 /scroll-speed。对话框显示一个在打开期间可以滚动的标尺，让你立即感受到变化；按 ← 和 → 调整速度，r 重置为自动检测的默认值，Enter 保存。对话框以整数步进到 10，在支持更精细控制的终端上还提供四分之一步进，下到 0.25。该命令写入与 CLAUDE_CODE_SCROLL_SPEED 环境变量设置相同的值，持久化到 ~/.claude/settings.json；对话框的最大值是 10：如果你通过环境变量设置了更高的值，对话框显示 10，从对话框保存会持久化 10。该命令在 JetBrains IDE 终端里不可用。

除了基础速度，当你快速转动滚轮时 Claude Code 还会加速滚动速率，所以快速转动比同样数量的慢速刻度覆盖更长的距离。要关闭加速并保持每刻度恒定速率，在 settings.json 里把 wheelScrollAccelerationEnabled 设为 false（需要 Claude Code v2.1.174 或更高）。

在 JetBrains IDE 终端里滚动

在 JetBrains IDE 终端里，Claude Code 应用自己的滚动处理并忽略 CLAUDE_CODE_SCROLL_SPEED：该终端发送滚动事件的速率比其他模拟器高得多，在别处调好的倍数在这里会过头。在 2025.2 版本里，该终端还有会产生多余方向键和方向错误事件的滚轮缺陷；Claude Code 在运行时检测到这些并自动缓解，所以触控板和鼠标滚轮滚动无需配置就能工作。要获得最佳滚动体验，升级到 2025.3 或更高；如果检测到该缺陷，Claude Code 会在你第一次滚动时显示提示。

搜索与回顾对话

Ctrl+o 在普通提示和转录模式之间切换。要获得只显示你最后一条提示、带编辑 diffstat 的工具调用一行摘要和最终响应的更安静的视图，运行 /focus；该设置跨会话保持，再次运行 /focus 关闭它。

转录模式获得 less 风格的导航和搜索：

你终端的 Cmd+f 和 tmux 搜索看不到对话，因为它在备用屏幕缓冲区里而不是原生回滚里。要把内容交还给你的终端，先按 Ctrl+o 进入转录模式，然后：

• [：把完整对话写入你终端的原生回滚缓冲区，所有工具输出都展开。对话现在是你终端里的普通文本，所以 Cmd+f、tmux 复制模式和任何其他原生工具都能搜索或选择它。长会话在此期间可能暂停片刻。这会持续到你用 Esc 或 q 退出转录模式、回到全屏渲染；下一次 Ctrl+o 从头开始。
• v：把对话写入临时文件并在 $VISUAL 或 $EDITOR 里打开它。

在 diff 面板里观察你的改动

在全屏渲染里，/diff 在对话旁打开一个面板，而不是一个你必须关闭的查看器，所以你可以在 Claude 工作时观察改动累积。在宽终端里，Claude 开始编辑文件后，面板也可以自己打开。面板显示什么、如何让它保持关闭以及如何更改它比较的对象，见交互模式页的 diff 面板。

清除对话

运行 /clear 开始新对话。如果显示看起来乱码或部分空白，按 Ctrl+L 重绘屏幕，重绘会保留对话和你的输入。当你的终端把 Cmd+K 传给 Claude Code 时，它与 Ctrl+L 作用相同；iTerm2 和 Terminal.app 自己处理 Cmd+K 并清除它们自己的屏幕，Claude Code 检测到被清除的屏幕并重绘对话。（v2.1.280 之前，从 v2.1.260 起，在全屏渲染里按 Ctrl+L，或在 Cmd+K 到达 Claude Code 时，会清除屏幕；v2.1.238 之前，两秒内按两次 Ctrl+L 会运行 /clear。）

配合 tmux 使用

全屏渲染在 tmux 里能用，有三点注意。

鼠标滚轮滚动需要 tmux 的鼠标模式。如果你的 ~/.tmux.conf 还没启用它，添加这一行并重新加载配置：

set -g mouse on

没有鼠标模式时，滚轮事件去了 tmux 而不是 Claude Code；用 PgUp 和 PgDn 的键盘滚动两种情况下都有效。Claude Code 检测到 tmux 且鼠标模式关闭时，会在启动时打印一次性提示。

全屏渲染与 iTerm2 的 tmux 集成模式（用 tmux -CC 进入的模式）不兼容：在集成模式下，iTerm2 把每个 tmux 窗格渲染为原生分屏，而不是让 tmux 向终端绘制，备用屏幕缓冲区和鼠标跟踪在那里不能正常工作：鼠标滚轮没有反应，双击可能破坏终端状态。不要在 tmux -CC 会话里启用全屏渲染；iTerm2 里不带 -CC 的普通 tmux 没问题。

直到 3.6 系列的 tmux 版本没有实现同步输出，所以在这些版本下，重绘期间可能比直接在终端里运行 Claude Code 时看到更多闪烁。Claude Code 在启动时探测终端对同步输出的支持，并在终端报告支持时使用它。如果你在 tmux 下看到闪烁，升级到最新的 tmux，或在 tmux 之外的独立终端标签页里运行 Claude Code。

保留原生文本选择

鼠标捕获是最常见的摩擦点，尤其是在 SSH 上或 tmux 里。Claude Code 捕获鼠标事件时，终端原生的选中即复制就不再起作用：你用点击拖动做的选择存在于 Claude Code 内部而不是终端的选择缓冲区里，所以 tmux 复制模式、Kitty hints 和类似工具看不到它。

Claude Code 把选择写入系统剪贴板，使用的路径取决于你的环境。在本地会话里它运行原生剪贴板工具：

• macOS：pbcopy
• Linux：Wayland 上用 wl-copy，X11 上用 xclip 或 xsel（装了哪个用哪个）；Claude Code 同时写入剪贴板和 PRIMARY 选择，所以中键粘贴也有效
• Windows 和 WSL：PowerShell 的 Set-Clipboard

在 tmux 里它还写入 tmux 粘贴缓冲区；在 SSH 上回退到 OSC 52 转义序列；在 GNU screen 里，Claude Code 也会把长选择复制到剪贴板（v2.1.219 之前，如果你复制了长于约 570 个字符的选择，GNU screen 会把 base64 文本打印到窗口里）。每次复制之后，Claude Code 会打印一条提示，告诉你它用了哪条路径。有些终端默认阻止 OSC 52：iTerm2 在你打开 Settings → General → Selection → Applications in terminal may access clipboard 之前一直阻止它；在 iTerm2 里运行 /terminal-setup 会替你启用它。

对一次性的原生选择，要用的键取决于你的终端：

• Terminal.app：Fn
• iTerm2：Option
• VS Code、Cursor 和 Devin Desktop：Shift，或在 macOS 上启用了 terminal.integrated.macOptionClickForcesSelection 设置时用 Option
• 大多数其他终端：Shift

在点击拖动时按住该键。你的终端自己处理选择而不是把它传给 Claude Code，所以 Cmd+C 这样的复制快捷键对你选中的内容有效；Claude Code 也在屏幕提示里显示正确的键。在 SSH 上或 tmux 里，Claude Code 不一定能检测到你从哪个终端连接，所以提示改为列出候选键。

如果你总是依赖原生选择，设置 CLAUDE_CODE_DISABLE_MOUSE=1 退出鼠标捕获，同时保留无闪烁渲染和平稳的内存：

CLAUDE_CODE_NO_FLICKER=1 CLAUDE_CODE_DISABLE_MOUSE=1 claude

禁用鼠标捕获后，用 PgUp、PgDn、Ctrl+Home 和 Ctrl+End 的键盘滚动仍然有效，你的终端原生处理选择；你会失去 Claude Code 里的点击定位光标、点击展开、URL 点击和滚轮滚动。

要保留滚轮滚动但关闭点击、拖动和悬停处理，改设 CLAUDE_CODE_DISABLE_MOUSE_CLICKS=1；两个变量都设置时，CLAUDE_CODE_DISABLE_MOUSE 优先。禁用点击后，Claude Code 仍然捕获鼠标，所以滚轮和触控板滚动对话，但左键点击在 Claude Code 里什么也不做；你仍需按住终端的那个键做原生点击拖动选择，右键和中键粘贴在支持它们的终端上继续有效。

排障

屏幕上有过时或错位的文字

全屏渲染只发送帧之间发生变化的单元格。有些终端（最常见的是 Windows Terminal 和其他基于 ConPTY 的宿主）错误地合并这些定位写入，把早先输出的碎片留在屏幕上，直到你调整窗口大小。设置 CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT=1，让它在每一帧重绘每个单元格，而不是发送增量更新。

在 Windows PowerShell 上：

$env:CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT = "1"
claude

在 macOS 或 Linux 上：

CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT=1 claude

在 Windows 上，Claude Code 已经为后台会话和智能体视图自动启用完整重绘，所以只有对你直接启动的交互式全屏会话才需要设置这个变量。

启动时出现「Claude Code's fullscreen renderer didn't finish starting last time」

如果这台机器上的某个全屏会话在成功启动前崩溃，Claude Code 会让你的下一个会话以经典渲染器启动，并打印两行之一。会话在绘制出第一帧、并且要么持续运行了 10 秒、要么你用 /exit、Ctrl+C 或 Ctrl+D 结束它之后，才算成功启动。你看到的那一行告诉你这个会话之后 Claude Code 会怎么做：

• 一次启动失败之后，你看到 Claude Code's fullscreen renderer didn't finish starting last time on this machine；Claude Code 在你启动的下一个会话里再次尝试全屏渲染。
• 两次启动失败之后，你看到 Claude Code's fullscreen renderer has repeatedly failed to start on this machine；Claude Code 持续使用经典渲染器，直到你更新 Claude Code 或运行 /tui fullscreen，在之后的会话里不打印任何东西。

要确认你处于经典渲染器是因为启动失败，不带参数运行 /tui；当失败的启动是原因时，Current renderer 一行会这么说。要保持经典渲染器，运行 /tui default，它保存 tui 设置而不重新启动；要再次尝试全屏渲染，运行 /tui fullscreen；如果那个会话也没能完成启动，就报告问题。（v2.1.236 之前，Claude Code 在启动失败后仍继续以全屏渲染启动会话。）

Claude Code 如何统计失败的启动：

• 计数的会话：只有因为你的 tui 设置这么说、因为你接受了启动对话框、或因为 Claude Code 默认让你全屏而以全屏渲染启动的会话。
• CLAUDE_CODE_NO_FLICKER=1：如果你设置了它，Claude Code 即使在启动失败后也以全屏渲染该会话，并且不计数。
• 计数重置：Claude Code 按 Claude Code 版本统计失败的启动，成功的全屏启动会重置计数。
• 启动对话框：如果你接受了对话框而重新启动的会话崩溃了，Claude Code 两行都不打印，并且在这个 Claude Code 版本上不再显示对话框。

研究预览

全屏渲染是研究预览功能。它在常见的终端模拟器上测试过，但在不常见的终端或不寻常的配置上你可能遇到渲染问题。如果遇到问题，在 Claude Code 里运行 /feedback 报告，或在 claude-code 的 GitHub 仓库开一个 issue，并附上你的终端模拟器名称和版本。

要关闭全屏渲染，运行 /tui default，或者如果你是通过环境变量启用的就取消设置 CLAUDE_CODE_NO_FLICKER。用 /tui default 切回时，Claude Code 可能先显示一个可选的反馈提示，问你为什么切换；输入原因并按 Enter 发送，或按 Esc 跳过，不论哪种 CLI 都会重新启动进经典渲染器。要不论已保存的 tui 设置如何都强制使用经典渲染器，设置 CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1；经典渲染器把对话保留在你终端的原生回滚里，所以 Cmd+f 和 tmux 复制模式照常工作。

从智能体视图或 claude attach 打开的后台会话总是使用全屏渲染：附加的终端进入备用屏幕缓冲区来显示会话，而经典渲染器在那里没有回滚或鼠标处理，所以 tui 设置和 CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN 对它们不适用。