1. 从一次假死说起Claude Code 卡住的真实现场先说我自己的遭遇。有次我用 Claude Code 跑一个多文件重构任务终端里光标一直在转圈Spinner 转了差不多两分钟没停我以为是模型在思考就去泡了杯咖啡。回来一看还在转。这时候我意识到不对劲——正常思考顶多几十秒这明显是卡住了。当时的第一反应是是不是网络断了但看了下终端没有任何报错AltTab 切出去查网络也正常。后来我 CtrlC 强制中断发现任务已经跑完一半了只是 UI 层没有刷新出来。这个现象很典型Claude Code 的终端界面卡住不代表进程死了很多时候是 Spinner 状态和实际执行状态脱节。后来我陆续在 Windows、macOS、WSL 上都遇到过类似问题也看了不少社区讨论慢慢摸清了 Claude Code 卡顿的几类根源。这篇文章就把我踩过的坑和排查思路完整梳理一遍尤其是那个让人又爱又恨的 Spinner——它到底是正在思考还是卡死了怎么判断怎么处理看完你心里就有数了。如果你刚接触 Claude Code或者已经被它的界面卡顿折磨过几次这篇文章应该能帮你省下不少折腾时间。我会从状态标识怎么读开始再到真正的卡顿根源分析最后给出一套可以直接照做的排查流程。提示Claude Code 的命令行界面是基于终端渲染的它跟 VS Code 里的图形界面插件不是同一套渲染机制所以卡顿的表现和排查方式也完全不同。这一点很多人会混淆后面我会专门展开。2. Claude Code 的 Spinner 到底是什么状态标识拆解2.1 Spinner 出现的时机和它想告诉你的事Spinner 本质上是一个进程在忙的信号。Claude Code 在终端里显示 Spinner 的场景主要有三种等待 Anthropic API 响应你发送一条消息模型还没有返回完整结果这时候转圈是正常的通常持续 5 到 30 秒不等。工具调用执行中Claude 决定要读文件、写文件、执行命令这些操作需要时间尤其是Bash工具执行长任务时Spinner 会一直转。上下文窗口整理或重试机制在后台运行当对话历史过长Claude Code 可能会自动做上下文压缩这个过程你几乎看不到日志但 Spinner 会显示忙。理论上只要 Spinner 在转就代表进程内部有事件循环在跑不一定是死锁。真正需要警惕的是长时间同状态不刷新——比如 60 秒以上没有新的日志行、没有光标闪烁变化、没有 Task 更新。2.2 怎么看 Spinner 对应的底层状态Claude Code 的终端 UI 其实分几个区域输入区、输出区、状态指示区。Spinner 通常出现在状态指示区。关键点在于Claude Code 的日志输出是增量追加的如果你看到 Spinner 在转但新内容完全不再追加那大概率不是思考而是等待。我个人习惯用三步判断第一步看 Spinner 是否一直在动。如果动画都停了说明渲染进程可能已经假死。第二步看是否有新的输出行。Spinner 转但没有输出增长通常是网络请求挂起。第三步看 CPU 占用。在另一个终端跑top或任务管理器如果 Node 进程 CPU 占用极低说明它基本在干等如果 CPU 飙高那它在空转或死循环。这里有个容易忽略的点Claude Code 本身是一个 Node.js 应用它的终端交互层和底层执行层是分开的。很多时候 Spinner 卡住只是交互层的问题底层任务还在正常推进。2.3 哪些卡其实是正常的不是所有转圈都是故障。有几个场景我刚开始也误判过长文档的 stream 输出。Claude 生成大段代码时终端是逐 token 渲染的如果终端模拟器性能差渲染跟不上看起来就像卡住。大文件读入上下文。你让 Claude 读一个 5000 行的文件它要先做内容切分和 token 统计这个阶段 Spinner 转得久一点是正常的。重试机制。API 偶发超时时Claude Code 会自动重试重试期间 Spinner 会一直转但没有新输出。所以新手最容易犯的错误是一看到 Spinner 就 CtrlC结果把本来正常的操作打断了。我建议你先等 60 秒再去检查网络和进程状态。3. 卡顿根源一终端渲染性能与 UI 线程阻塞3.1 终端模拟器选型不当是隐形杀手Claude Code 的 UI 依赖终端模拟器但不同终端对 ANSI 转义序列、Unicode 字符、光标移动的渲染效率差别很大。我在 Windows 上试过默认的conhost、Windows Terminal、以及 WSL 里的各种终端模拟器体感差异非常明显。在 Windows 命令行里跑 Claude Code一旦输出内容包含大量代码块和特殊字符conhost的渲染会明显掉帧Spinner 动画甚至会出现残影给人的感觉就是卡住了。但实际上你把终端窗口拉大或者切换到 Windows Terminal同样一个会话立刻流畅很多。这个问题的根源在于conhost对现代终端特性的支持太落后它处理大流量文本刷新时采用 GDI 渲染效率远不如基于 GPU 加速的现代终端。Claude Code 的界面又偏偏是高频刷新型Spinner 动画逐帧重绘输出区逐 token 追加两相结合老终端直接扛不住。3.2 UI 线程阻塞的典型表现终端渲染卡顿的另一个表现是 UI 线程阻塞。Claude Code 的主进程是单线程的 Node.js 事件循环如果某个同步操作耗时过长比如一次性解析超大的 JSON 输出、把大量内容塞进上下文事件循环就会被占住Spinner 动画自然停摆。我实测过一个场景让 Claude 分析一份十几万行的日志文件它读完文件后做内容摘要top里能看到 Node 进程 CPU 接近 100%但终端界面完全不动Spinner 直接静止。这不是死锁是渲染线程和主线程抢占资源导致的假死。这种情况下最直接的验证方法就是等。如果 CPU 在持续干活等它处理完界面会突然刷新一大片内容——这就是典型的活卡。反过来如果 CPU 占用趋近于零那就不是 UI 阻塞而是 IO 等待。3.3 实践建议终端与界面配置参考如果你经常用 Claude Code我建议在配置阶段就做几件事Windows 用户优先用 Windows Terminal不要用默认 conhost。macOS 用户优先用 iTerm2自带的 Terminal.app 虽然能用但滚动渲染大内容时也会卡。关闭终端的光标闪烁和部分视觉效果减少渲染负担。如果跑在 VS Code 的集成终端里注意 VS Code 插件本身也会占用资源属于双重叠加。注意Claude Code 的 VS Code 插件和命令行界面是两个入口但它们在任务执行上共用同一套核心引擎。你在 VS Code 里看到界面卡顿有时候不是 Claude Code 的锅而是 VS Code 的渲染进程被其他插件拖累。4. 卡顿根源二网络层问题与 API 请求挂起4.1 网络请求挂起为什么比超时更难排查Claude Code 默认请求的 API 端点对网络质量要求比较高。如果你所在网络环境到目标服务器链路不稳定一个非常典型的现象就是Claude Code 没有报错也没有超时提示只是 Spinner 一直转任务迟迟不推进。这跟浏览器访问一个网站不一样。浏览器如果请求卡住慢慢会触发超时但 Claude Code 这类长连接流式请求TCP 层可能还保持着连接只是数据不再流动。这种情况下 Spinner 会一直存在但没有任何输出活活像个无限等待。我处理过最多的问题场景是使用代理工具这里不谈具体工具时代理节点延迟偏高Claude Code 的流式响应被中间层缓冲导致数据到达时间远超正常阈值。表面看是卡住实际是在等数据。4.2 如何区分网络卡和逻辑卡当 Spinner 持续转动且无任何输出时我建议先做一个快速网络诊断而不是盲目重启在另一个终端用curl请求 API 同域名的健康检查端点看响应是否流畅。观察本地网络流量看 Claude Code 进程是否有持续的 TCP 收发。检查 DNS 解析是否存在异常有时候 DNS 慢了也会表现为一切正常但请求迟迟不发起。4.3 一个容易忽略的隐藏开关代理环境变量很多人装完 Claude Code 直接跑不会去检查环境变量。如果系统里存在全局的代理相关环境变量比如HTTP_PROXY、HTTPS_PROXYClaude Code 会默认走代理。即使代理服务已经关了环境变量还在请求一样会挂。我遇到过最离谱的一次HTTPS_PROXY指向一个不存在的本地端口Claude Code 每次请求都先尝试连接那个端口连接失败再等待系统超时整个过程 Spinner 就这么干转了几十秒。排查了半天最后把环境变量清理掉速度立刻恢复正常。所以遇到网络层卡顿第一件事不是换节点而是检查 Claude Code 进程实际走的网络出口。可以用env | grep -i proxy看一下当前环境里有没有残留的代理配置如果有先清掉再测试。注意Claude Code 的网络配置和第三方 API 接入是两个概念。如果你用 CC Switch 这类工具切换到第三方模型接口请求的目标地址会变但代理环境变量的影响依然存在排查的时候不要把两件事混在一起。5. 卡顿根源三工具调用循环与上下文膨胀5.1 工具调用死循环Spinner 转个不停的真凶之一Claude Code 的 Agent 模式核心是思考-工具调用-观察结果-再思考的循环。正常情况下这个循环会收敛即 Claude 最终得出结论。但在某些场景下它会陷入循环不断调用某个工具得到的结果不满足预期于是继续调用。这种循环的外在表现非常迷惑Spinner 一直在转日志一直在输出看起来很忙但就是得不到最终答案。尤其是在处理文件编辑类任务时如果 Claude Code 反复读取同一个文件并进行修改可能就是工具调用的逻辑产生了重复执行。判断方法翻看输出里的工具调用记录。如果看到同一类的工具被连续调用了 5 次以上且结果都没能推进任务主体那基本可以判定为工具循环。这时候继续等也等不到结果直接 CtrlC 中断然后在提示词里明确限制工具调用次数或者拆分任务让 Claude 一步步来。5.2 上下文窗口膨胀Spinner 慢的隐性成本Claude Code 会把每次工具执行的结果、文件内容、命令输出都累积到上下文中。对话轮次越多上下文越长每次请求需要处理和发送的数据就越大响应自然变慢。如果你在一个会话里连续操作几十个文件每个文件都被完整读入上下文那么到后期即便是一个简单的问题Claude Code 也要带着巨大的上下文去请求 API。这种情况下Spinner 转的时间会越来越长最终表现就是越来越卡。这不是单次请求的网络问题而是整体资源消耗问题。我通常的做法是任务规模大的时候拆分成多个独立的会话避免一个会话里堆积太多历史记录。另一个办法是定期用/compact命令压缩上下文让它把早期的对话历史总结掉释放空间。5.3 大型 JSON 输出的渲染陷阱还有一类卡顿非常特殊Claude 返回了大量结构化数据比如 JSON、超大表格终端渲染层需要做语法高亮和格式化。这个环节如果数据量极大渲染时间会被拉长Spinner 也会保持转动。这其实可以延伸到其他工具的经验Qt 里的表格组件在大数据量刷新时如果直接用QTableWidget也会因为逐项创建控件而卡顿改成QTableView 自定义 Model之后性能就上去了。Claude Code 的终端渲染与之类似——它是逐项刷新的机制数据量一大渲染就成了瓶颈。6. 卡顿根源四系统资源与运行环境问题6.1 内存不足与 swap 风暴Claude Code 本身是一个 Electron 或者 Node 类的重进程命令行版本是 Node CLI占用相对轻但也不小。如果你的机器内存本来就紧张同时开着浏览器、VS Code、虚拟机那么 Claude Code 处理大型上下文时内存很容易被打满。内存耗尽后操作系统会启动 swap 交换。如果是 SSDswap 速度还能凑合如果机器用的是机械硬盘或者 swap 配置过小那系统整体都会变得卡顿Claude Code 的 Spinner 自然也跟着冻结。我建议跑 Claude Code 之前先确认空闲内存是否充足。Windows 用户打开任务管理器查看内存占用macOS 用户可以用活动监视器看内存压力。如果内存长期处于即将耗尽状态那不是 Claude Code 的设置问题而是机器负载问题。6.2 多平台运行差异Windows、macOS、Linux 与虚拟机Claude Code 在三个主流桌面平台上我都跑过几个平台的卡顿表现不太一样Windows受终端渲染影响最大。默认终端明显卡Windows Terminal 基本流畅。另外 Windows 的杀毒软件和实时扫描有时会拦截 Claude Code 读写临时文件导致偶发停顿。macOS整体稳定但 Apple Silicon 和 Intel 芯片的体验有明显差异Intel 版本在渲染大输出时更容易发热降频导致界面响应变慢。Linux/WSL如果在 WSL 里跑文件系统的跨系统访问是潜在性能陷阱。如果项目文件放在 Windows 的 NTFS 分区下从 WSL 侧读取会明显慢于 Linux 原生命令。还有一个经常被忽略的场景在虚拟机里跑 Claude Code。比如在 VMware 或 VirtualBox 里装 Linux然后跑 Claude Code这时候显示卡顿很可能不是 Claude Code 的问题而是虚拟机的显卡加速和 CPU 调度不给力。如果你在虚拟机里同时开着 GUI 界面效果会更明显。6.3 环境变量和系统配置对启动的影响Claude Code 启动时会读取一系列环境变量某些异常配置会导致启动后行为异常。最典型的就是前面提到的代理环境变量除此之外还有语言环境变量、Node 运行时路径等。如果你安装 Claude Code 后命令能执行但界面行为怪异我建议先跑一个诊断命令打印出当前生效的配置项确认没有异常的环境变量残留。不要急着重装很多时候重装解决不了环境变量问题。7. 五分钟排查方案从现象到根因的速查流程7.1 第一步先判断是假卡还是真卡任何卡顿问题第一步永远是判断进程是否存活。在另一个终端执行macOS/Linuxps aux | grep claudeWindowstasklist | findstr claude如果能看到进程还在运行再配合 CPU 占用判断。CPU 在持续波动说明它在干活CPU 几乎为零说明它在等待CPU 稳定高位且界面不动大概率是渲染阻塞。这一步决定了后续是等待观察还是主动干预。不要一上来就重启否则你永远不知道问题到底出在哪。7.2 第二步检查输出日志和工具调用记录Claude Code 的会话页面里有完整的工具调用记录。排查卡顿时重点看最后一次工具调用是什么时候触发的、持续了多久。如果最后一次工具调用是网络请求类那大概率是网络层问题如果是本地文件操作那可能是磁盘 IO 或文件过大。如果能打开日志功能尽量开启日志输出到文件这样即便界面崩溃日志里也能看到卡顿前的最后动作。7.3 第三步快速验证网络出口在另一个终端分别测试目标 API 端点的连通性。测试时不要只看能不能通要看延迟和响应速度。正常延迟如果在几十毫秒到一两百毫秒之间基本没问题如果延迟持续飙升到数秒甚至请求超时那网络层就是罪魁祸首。记得检查代理环境变量这一步很多人忽略但往往是最容易定位到问题的。7.4 第四步缩小交互范围如果以上都查不出问题就在小范围场景里复现。新建一个会话只发一条简单指令看是否还会卡顿简单指令没问题 → 问题与具体任务复杂度或上下文长度有关。简单指令也卡 → 问题处在环境、网络、终端或配置层面。这种二分法能快速定位问题范围省去很多无效操作。7.5 第五步记录关键操作参数做任何调试之前先记录你当前的 Claude Code 版本、运行平台、终端类型、是否开了代理。很多问题跟版本有关Claude Code 更新很频繁有时候旧版本的 Bug 在新版本已经修复了。所以排查前先确认版本不是老古董再开始后面的流程。8. 排查实践中的高频问题速查表现象最可能原因优先排查项快速处理手段Spinner 转但无任何输出网络请求挂起或代理残留网络连通性、代理环境变量清理代理配置检查 API 端点延迟Spinner 静止 CPU 低进程等待中可能连接已断日志最后活动时间点考虑 CtrlC 后重启会话Spinner 静止 CPU 100%主线程在忙渲染阻塞任务是否在读大文件或处理大输出等待自动完成不要中断输出正常但界面滚动卡顿终端渲染性能不足终端类型、系统负载换现代终端模拟器长期对话后整体变慢上下文膨胀会话长度、文件读取量使用 /compact 压缩或用新会话工具反复执行同一操作Agent 陷入工具循环工具调用记录频率中断后明确限制工具调用次数虚拟机中明显卡顿虚拟化环境性能瓶颈CPU 分配、显卡加速配置调整虚拟机资源配置同时开多个大型应用后卡顿系统资源不足内存和 CPU 占用关闭无关程序释放资源9. 几条减少卡顿的实战配置建议9.1 合理规划会话生命周期我的习惯是一个会话只做一类任务。写代码的时候不把日志分析塞进同一个会话做文件批量修改时不频繁穿插无关的闲聊问答。这样上下文保持精简既省钱又省时间卡顿概率直线下降。如果会话里已经堆积了大量内容就触发一次上下文压缩把它总结成精简摘要然后再继续提问。压缩之后Spinner 的响应速度会有明显改善。9.2 任务拆分与限制在提示词里我通常会显式交代任务的边界比如不要尝试读取其他文件只处理 src 目录下的文件最多调用三次搜索工具。这样可以在很大程度上规避工具循环带来的假卡。大文件处理时不要让 Claude 一次性读取整个文件。可以教它用命令行工具先查看文件关键部分或者用grep定位内容而不是读全文。这样既快又不占上下文。9.3 保持 Claude Code 版本更新Claude Code 迭代速度很快开发者经常会修复一些已知的界面卡顿和响应问题。隔一段时间就检查一次版本更新升级到最新版通常能解决一些莫名其妙的旧版才有的问题。不过升级之后终端配置可能会有变动有些第三方配置需要重新适配。如果你用了 CC Switch 之类的工具接入第三方模型升级后要确认配置项还能正常读取。10. 写在最后的几句大实话跟 Claude Code 打了这么久交道我最大的感受是大多数卡死不是真的死而是卡在半路。界面的 Spinner 只是一个表象背后的原因可能分布在网络、终端、上下文长度、系统资源多个层面。排查的时候不要慌先从进程状态看起再逐层排查网络和任务复杂度大多数问题都能定位到。我个人现在的工作习惯是永远开着日志输出永远保持终端模拟器是现代版本永远留意代理环境变量有没有残留。这三个习惯帮我少踩了一大半的坑。如果你刚开始用 Claude Code也希望你能从这篇文章里建立一套自己的排查思路而不是遇到卡顿就无脑重启。另外多说一句如果你用 Claude Code 频繁处理大型项目的代码可以试着把任务拆分得更细一点。与其让它一口气做十件事不如拆成十次短对话每次做一件。这样界面更流畅结果质量通常也更高。