用Claude Code写代码写得好好的突然终端里那个小转圈Spinner一直转个不停敲什么命令都没反应。这种经历我相信不只我一个人遇过。Claude Code在终端里工作时除了文字输出屏幕上那个旋转指示符其实是整个工具状态机最直观的仪表盘——它转了不代表一定卡死但一直不停又没有任何产出就基本可以断定哪里出了问题。这篇文章从一个每天都在终端里敲Claude Code的人的角度把Spinner各种状态标识的含义、卡顿产生的根源、以及一套我自己实测下来的排查方案完整梳理一遍。无论你是刚装好Claude Code的小白还是已经接入了DeepSeek、Qwen、GLM等第三方模型的老手遇到转圈不停都能按图索骥。1. 读懂SpinnerClaude Code界面里的转圈到底在表达什么很多教程只教你怎么装、怎么用却没人告诉你终端里那些旋转符号分别代表什么。结果就是一看到Spinner就慌以为程序挂了。其实Claude Code的TUI界面设计得相当克制每一个旋转动画背后都对应一个明确的阶段。1.1 两种基础Spinner等待模型回复还是等待工具执行我平时实际使用下来Claude Code的Spinner基本可以归成两大类型。第一类是在等模型的Spinner。你按下回车发出指令Claude Code把请求交出去之后界面会进入一个等待模型返回的状态。这时候屏幕上通常会有一个旋转动画日志区会停在你最后发出的那条消息上。这种Spinner的本质是请求已发出但还没拿到第一个token。它转多久取决于网络往返时间、服务端排队时间和模型首token生成速度。你发了一个需要写几千行代码的大需求它转个二三十秒都很正常。第二类是在执行工具的Spinner。Claude Code的特色就是它能在终端里直接跑命令、读写文件、调用MCP工具。当模型决定调用某个工具时界面会切到工具执行状态日志区会显示正在执行的工具名比如RunTool、ReadFile、MultiEdit这种。这时候Spinner转动代表着模型已经把活儿派下去了正在等工具把结果拿回来。如果工具执行顺利Spinner转两下就会回来继续生成如果工具本身卡住这个Spinner就一直转。区分这两种Spinner特别重要因为排查方向完全不同。前者是网络和模型问题后者是本地环境、命令参数、脚本逻辑问题。你用排查工具问题的思路去排查网络问题大概率白忙一场。1.2 几种常见的Spinner变体怎么判断它卡在哪个阶段实际用的时候Spinner不是孤零零一个圈它通常会伴随一些其他界面信号。我把常见的组合总结成一张表界面表现真实含义判断结论Spinner转动日志持续增长模型边想边输出工作正常耐心等待别打断Spinner转动日志停在某个工具名上工具调用未返回大概率命令/脚本卡住Spinner转动日志区长时间无任何新增请求发出后首token迟迟未到网络或服务端问题Spinner静止但界面能输入空闲状态等你下指令不是卡顿正常待机Spinner静止键盘无响铃响应进程挂起或渲染层崩溃需要强制恢复或重启同一位置反复出现短促Spinner请求重试/退避中大概率遇到限流或临时故障这里有个容易被忽略的点Claude Code在接收到流式响应的过程中日志区会一行一行往外冒字Spinner一直转。很多人误以为它一直在转就是卡死其实这是流式输出在正常推进。判断卡不卡关键是看日志有没有新进展而不是看Spinner停不停。还有一种特殊情况Claude Code执行长任务时会进入静默思考状态界面可能看起来什么都没有但进程其实在后台认真做事情。我接第三方模型比如Qwen、GLM时尤其容易遇到这种状态因为不同模型的思考节奏差异很大。这时候别急着CtrlC先给它一点时间通常等个一两分钟就会有反应。1.3 一个容易误判的场景等待用户确认与权限弹窗Claude Code在调用某些需要许可的工具时会停下来等待用户确认。这种状态下它不会一直转而是像一句话说了一半那样停住比如显示Do you want to proceed?。但如果你在非交互模式比如某些脚本或自动化调用里运行这个待确认信号可能永远不会被处理看起来就像卡死。我遇到过几次在CI环境里调用Claude Code它执行到需要确认的地方直接停摆Spinner也不转了界面也不响应了。排查这种问题最直接的办法就是看终端最后一行文字是什么。如果是提问句说明它在等你确认而不是卡住。在无交互模式中要么提前用参数把权限都放开对应的是--dangerously-skip-permissions这一类许可参数具体看官方CLI帮助要么确保所有调用都以交互方式运行。这个判断在后续排查中会反复用到。2. 转圈不动的两类根源模型在想还是工具在堵搞懂了Spinner的含义接下来要回答核心问题为什么它老是不停。我自己把Claude Code卡顿的根源归结为两类一类发生在模型侧请求发出去了但响应迟迟回不来另一类发生在工具侧模型已经决定要做某件事但动作本身卡住了。这两类的表现相似底层逻辑完全不同。2.1 模型侧的等待网络不稳、服务端限流、上下文积压模型侧卡顿最常见的原因是网络并没有真正断掉而是处于一种看着通了但很不稳定的状态。TCP连接建立没问题但数据包延迟忽高忽低流式响应隔几秒才吐一个字符。这种情况下Spinner会一直转日志区偶尔冒出几个字又停住。它的本质是请求发出去了响应通道却像水管被捏住了一样只滴答水不流水。第二个容易踩的坑是服务端限流。你连续在多个会话窗口里高频提问或者单条消息里塞了特别长的上下文服务端会启动限流机制直接表现为请求排队时间变长。这种限流通常不是报错而是让你干等。Spinner一直在转但等很久才有反应甚至最终只是返回一个错误提示。第三个是上下文积压。Claude Code默认会把当前会话的历史消息都带进每次请求。当对话轮次多了、文件内容大了之后单次请求要传输的token数暴涨服务端处理时间自然跟着涨。我试过在同一个会话里连续让Claude Code读多个大文件、改多个模块到后面每回一次消息Spinner都要转一分多钟。这不是工具坏了是你把这个会话喂得太肥了。模型侧还有一个不算罕见的现象流式输出中断。客户端在等一个结束标记但服务端因为网络抖动没把最后的标记传过来连接其实已经断了界面却还挂着Spinner。这种情况比较隐蔽因为后台看连接可能已经关闭但TUI界面没有及时感知。2.2 工具侧的阻塞Bash命令失控、MCP工具失联、文件读写过久工具侧的卡顿我把它形容为模型已经把球传出去了但接球的人站在原地不动。最常见的是Bash命令没有自动结束。Claude Code执行一个命令比如跑测试、启动服务、执行脚本如果这个命令本身是长驻型的——像npm run dev、python server.py、tail -f这种——它永远不会返回。模型在等命令的输出结果命令却一直挂在那边Spinner就跟着一直转。这种卡顿特别容易发生在你让Claude Code帮我启动项目帮我监控日志的场景。文件读取和写入也可能变成卡顿源头。当一个大文件有几百兆时Claude Code读取后要把内容作为上下文发送给模型这个过程既要读盘又要传输、编码、拼接每一步都在消耗时间。更麻烦的是遇到二进制文件、超大压缩包这类Claude Code没法直接处理的内容工具端可能会反复尝试解析表现为长时间没有输出。MCP工具的失联是另一个大头。现在很多人会通过MCP服务器给Claude Code接各种外部服务比如数据库查询、浏览器工具、内部API。一旦某个MCP服务器没有正常启动、认证过期、或者端口被占用工具调用就会一直挂起。我遇到过最极端的情况是某个MCP服务器进程崩溃了但客户端没有收到明确错误Claude Code以为工具还在执行Spinner整整转了好几分钟。2.3 终端侧的隐形拖累渲染压力、滚动缓冲、键盘事件丢失除了模型和工具还有一个很少人关注的卡顿源头终端本身。Claude Code是一个TUI程序它有大量字符动画、颜色渲染、滚动输出。当你运行的终端性能偏弱或者让它渲染超大段的输出时渲染层可能先卡住。具体表现是Spinner还转但整个界面刷新变得一帧一帧地跳输入延迟明显。滚动缓冲也是一个因素。在macOS的默认终端、Ubuntu的一些轻量终端里如果缓冲区里堆积了过多历史输出Claude Code每次刷新界面都要重新重绘大量内容CPU占用率直线飙升。开一个top看看经常能看到终端进程占了几百的CPU。这种卡顿其实跟Claude Code关系不大纯粹是终端在拖后腿。键盘事件丢失则更玄学界面看起来还活着Spinner也在转但你怎么按Esc、怎么敲命令都没反应。这种情况我碰到过两回最后发现是终端进入了某种异常状态比如之前按了某个快捷键触发了终端的暂停输出功能常见的组合键像CtrlS会让终端输出暂停再按CtrlQ才恢复。这类问题排查起来最冤枉因为压根不是Claude Code的锅。2.4 一张流程图式的判断标准什么时候该等什么时候该动手根据我自己的经验遇到Spinner长时间转先别急着做任何操作花十秒钟做三个判断第一日志区最后一行是什么时候更新的。如果几秒前还在更新说明链路还是活的只是慢可以再等等。如果一分钟以上没动静进入下一步判断。第二最后一行内容是在等模型的一句话还是在等工具的一个结果。如果是后者立刻打开另一个终端窗口用ps看一下是不是有可疑的命令挂在那里。我之前定位过一次卡顿就是发现Claude Code派出去的pip install命令因为网络源问题卡在连接阶段半个多小时没反应。第三看整个终端还能不能流畅操作。如果能流畅输入、能呼出菜单说明进程没死只是某个环节慢如果连输入都迟滞问题可能出在渲染层。这三个判断做完基本能确定该继续等还是动手查。3. 现场定位四步走不开第二个终端很难确认卡点很多人遇到卡顿就只会CtrlC重来其实Claude Code卡住的时候大量线索就摆在眼前。我的习惯是开一个新终端窗口从进程、网络、日志三个维度同时盯把卡点范围一步步缩到最小。3.1 第一步先看当前会话的入出日志别急着打断进程Claude Code在运行时会对每个关键动作打日志。虽然默认界面上不会全部展开但你至少能看到最近发生了什么。进入排查前先把当前会话里面能看到的输出完整翻一遍。重点看几个信息最近一次工具调用的工具名是什么最近一次模型回复是在什么时候有没有已经输出的错误提示被淹没在滚屏里。很多时候卡顿的原因早就在界面里提示过了只是滚动太快你没看到。我有一次排查了半天最后发现Claude Code早就打印了一个MCP server disconnected的提示只是被后面一大段工具输出顶到上面去了。如果界面上没有足够信息可以考虑从Claude Code的工作目录里找日志文件。Claude Code会把一些运行日志写在本地目录中具体位置和文件名在不同版本上会有差异但通常能通过find ~ -name *.log -newermt 10 minutes ago这类命令快速捞到最近修改的日志文件。翻日志的时候注意找error、retry、timeout、reconnect这几个关键词它们基本能直接告诉你问题出在哪个环节。3.2 第二步开一个新终端同时看进程状态和网络连接这一步是整个排查链路里最有含金量的动作。卡住的时候Claude Code进程到底是在跑还是挂起看一眼就知道。进程方面执行ps aux | grep claude看进程状态列。正常工作的进程一般处于S可中断睡眠或R运行中状态如果你看到的是D不可中断睡眠说明进程卡在内核IO上通常是磁盘读写或网络阻塞导致某些系统调用一直没返回。如果进程消失了那问题另说——说明它根本没在跑只是终端界面残留。网络方面执行lsof -nP -iTCP -sTCP:ESTABLISHED | grep claude如果能看到Claude Code和API服务器之间有大量长连接挂着且状态是ESTABLISHED说明链路没断那问题大概率出在服务端响应慢或者客户端在等流式数据。如果连接状态是SYN_SENT说明TCP握手都还没完成基本可以断定是网络连通性问题。再顺手ping一下API服务器或者用curl直接测一下调用接口的延迟。这种外部探测能帮你快速区分是网络到不了还是到了但服务端不给活。我实测下来Claude Code卡住时大概率是连接存在但数据流停滞纯断网型反而不多。3.3 第三步用一次最小复现锁定到底是模型慢还是工具堵看完了进程和网络接下来做一个干净利落的实验把卡顿场景放到一个全新、极简的会话里复现。新建一个会话先不发任何复杂指令只发一句你好请回复OK这种最基础的消息。如果这个简单请求都转圈半天说明问题在模型侧或网络侧跟你的具体任务无关。接下来发一条涉及工具调用的指令比如帮我列出当前目录下有哪些文件。如果这一步也卡住那问题大概率在Claude Code本地执行层或终端环境。用这个最小复现法我能很快把故障域劈成两半。有一次用户在社区问我说Claude Code执行任何涉及文件操作的请求都会卡死但纯聊天没问题。我让他用最小复现试了一下发现卡住的都是ls -la这类系统命令。最后查出来是终端环境的PATH被改了Claude Code调用ls时找不到可执行文件但错误提示又没有在界面里显示只能一直等。这个方法比直接看日志更高效因为它用实验代替了猜测。3.4 第四步配合调试日志抓取请求链路找到卡在哪个环节如果前几步都没定位到就需要开更细粒度的调试输出。Claude Code在不同版本里提供的调试手段有差异有些版本支持--debug之类的启动参数有些版本需要设置环境变量开启详细日志。具体参数以官方文档为准我这里讲思路。打开调试日志的意义在于你能看到一次完整请求的链路时间轴请求发出是什么时候收到第一个token是什么时候工具请求发出去是什么时候工具结果回来是什么时候。只要把每个环节的时间戳列出来卡在哪个区间就一目了然。我通常这样操作先停掉卡住的会话然后带着调试参数重新启动Claude Code复现刚才的操作再把日志里各个阶段的时间差算出来。比如请求发出到首token返回花了90秒那问题就在模型侧工具发起调用的时间戳和工具结果的落点时间戳之间隔了五分钟那问题肯定在工具执行这一侧。这一步做完还没有结论的情况我基本没遇到过。所谓排查方案本质上就是把一个模糊的卡住拆成一个有时间、有对象、有阶段的具体事件然后一个问题一个问题地排除。4. 接入方式不同卡顿的脾气也不同Claude Code不是只有官方API一条路可走。现在很多人会通过各种配置工具把它接到第三方模型上也有人主要在VSCode插件里使用还有人跑在Ubuntu服务器上。这些接入方式各有各的卡顿脾气需要单独说清楚。4.1 官方API连接卡顿集中在网络层与服务端限流用官方API时Claude Code的网络路径相对固定模型服务端质量也稳定剩下会出问题的就是两个地方你的本机网络质量以及你是不是撞上了限流。本机网络这块我遇到过诡异的时通时不通。明明浏览网页正常Claude Code就是慢得要命后来用mtr一类的工具测才发现是到API服务器的某一个中间节点在丢包数据时不时重传流式响应自然断断续续。这种情况下的Spinner特征是转一会儿日志吐半行又停过一会又吐半行。你看着它像在干活实际上一分钟也完成不了几句话。限流的识别则稍微容易一点。如果你在短时间内反复发请求或者有一条消息使用了超长上下文服务端会进入限流保护。这种限流通常不会立刻拒掉请求而是让请求排着队慢慢处理。Spinner表现就是长时间空转然后突然一次性返回大量内容。应对思路也简单错峰使用降低请求频度短会话快问快答。别在高峰期硬扛。4.2 接第三方模型DeepSeek、Qwen、GLM兼容性、超时与上下文窗口问题这是我近期被问得最多的一块。很多人通过cc switch这类工具把Claude Code接到DeepSeek V4、Qwen、GLM等模型上图的是便宜和方便。但第三方模型接入场景里的卡顿跟官方API完全不是一回事。第一是协议兼容性。Claude Code原生走的是Anthropic的接口协议而第三方模型大多是OpenAI兼容格式。中间那层转换工具要做协议翻译、参数映射、流式数据格式转换。只要某一段流式输出格式不合规范转换层就可能一直在缓冲迟迟不把数据交给Claude Code。表现就是Spinner转了很久界面一句都没有吐出来然后突然一次性全部出现。这不是模型慢是格式转换慢。遇到这个情况优先检查你用的转换工具是不是最新版第三方模型的Anthropic兼容端点是否存在一些已知的流式输出问题。第二是超时配置不匹配。官方API的超时参数在Claude Code里是按官方服务特征标配的但第三方模型的响应速度波动大有的模型首token就要等上一分多钟。如果客户端配置了一个比较短的超时时间请求会被提前掐断然后走重试逻辑。重试本身又会重新发起一次完整请求周而复始。一个请求卡了半天实际上是在做无限的超时重试循环。第三是上下文窗口差异。Claude Code默认会按官方模型的上下文能力去塞会话历史。当你换成上下文窗口小得多的第三方模型时会话一长就会超出模型能力。有的转换层会硬把超出的部分截掉有的会直接报错还有的会拖着整个超长请求反复重试。这几种情况都可能让你看到转圈很久然后报错或一直转圈没结果。接第三方模型的时候我的建议是开短会话、勤清空、不要把大文件塞进上下文、遇到诡异卡顿先升级转换工具并核对两端的超时参数。4.3 VSCode插件与桌面版插件桥接、终端复用、渲染层的额外开销VSCode插件、桌面版与纯命令行版本还有一个区别中间多了一层插件进程或UI进程的桥接。这个桥接层一旦出问题卡顿就会以各种奇怪的形式出现。在VSCode里用Claude Code最常见的是集成终端和插件面板的联动延迟。你可以把Claude Code当成一个在VSCode集成终端里运行的程序但插件会额外监听它的输出、状态变化再渲染到侧边栏面板里。如果项目文件特别多文件监视器频繁触发事件插件层可能要处理大量文件变更导致Claude Code在终端里的整体交互变卡。桌面版或GUI封装还有一个渲染开销问题。这类客户端通常要吃更多内存如果你的机器配置不高系统内存被吃满后Claude Code进程会频繁触发垃圾回收或交换分区Spinner照样转但明显感觉到整个系统都在拖。在VSCode场景里遇到卡顿我建议先试试把插件面板收起或禁用改用纯集成终端使用Claude Code。如果变流畅了说明卡顿在插件桥接层如果还卡再回到前面说的排查链路。4.4 Ubuntu和macOS终端环境的细节差异开发和运维场景里Ubuntu和macOS是两个大头。两者跑Claude Code卡顿表现也有微妙差别。Ubuntu这边最常见的是终端环境变量问题。Claude Code对locale环境敏感如果系统的LANG、LC_ALL没有设置成UTF-8的locale某些输出处理会出现异常表现为字体显示乱码、界面刷新延迟、甚至部分字符渲染时CPU占用飙升。我在Ubuntu Server上遇到过Claude Code输出中文内容时奇慢的情况排查到最后就是把en_US.UTF-8加上问题立刻消失。另一个常见问题是终端字体和fallback字体缺失导致每个字符都要做字体降级渲染拖慢整个TUI刷新。macOS这边问题更多出在终端的GPU加速和滚轮回滚上。默认终端在渲染大量彩色字符时性能一般反而是iTerm2在某些版本上也有自己的渲染问题。如果你在macOS上用了某个第三方终端卡顿先换个终端试试成本最低。还有一个操作系统层面的坑系统级的代理设置或安全软件。如果你的系统配了全局代理、网络过滤工具Claude Code的流量也会经过这层代理一旦不稳定表现就是网络侧卡顿。这个属于环境问题不在代码层面排查时如果前面几步都正常可以检查一下系统网络偏好设置里有没有额外的东西在接管流量。5. 让Claude Code少转圈的实战策略排查问题只是一半更多时候我们是希望它压根别卡。这部分是我在日常使用中逐步攒出来的防卡套路每一条都落在实际动作上。5.1 管理上下文长度别把会话喂成一头大象几乎所有越来越慢的反馈背后都有一个共同推手会话太长了。Claude Code每次请求都要把整个会话历史发给模型。当你的会话积累了五六十条消息包括读取过的文件内容、工具执行记录、日志片断单次请求的token数量会非常惊人。在官方API上这意味着更长的排队和生成时间在第三方模型上可能直接顶到上下文上限。我自己的习惯是每完成一个独立子任务就开一个新会话每讨论完一个文件模块就明确告诉Claude Code把上面这些内容做一个总结然后我们换个会话继续。这比让它无限带着记忆工作可靠得多。也可以用/clear这类内置命令清空会话历史只保留当前工作上下文。这个话题在所有Claude Code教程里都值得被反复强调——控制上下文就是控制延迟。还有一个同样重要的点不要直接让Claude Code读取超大的文件。如果你需要它分析一个大日志或大代码库先自己用grep、head、awk把这些文件切到几百行以内再作为上下文提供。这能让请求体量瞬间小一个量级卡顿概率也随之大降。5.2 给危险命令加timeout别让Bash工具没完没了工具调用卡顿的一个重要来源就是Claude Code执行的命令本身无止境。它可能执行了npm run dev可能启动了tail -f甚至可能因为网络问题导致git clone长时间无响应。我的做法是提前用系统的timeout命令给可能卡住的命令上一道保险。例如在提示词里明确要求它执行长驻命令时使用timeout 30 npm run build这样即使命令卡住30秒后也会被强杀并返回一个超时错误Claude Code拿到错误后会自己决定下一步行动而不是无限等下去。这条经验我在生产环境里验证过很多次效果立竿见影。比起让Claude Code等一个永远不会返回的结果让它迅速拿到一个超时错误要好得多。另外如果某个命令本身是长驻服务比如python server.py你要让Claude Code做的是后台启动加日志重定向而不是前台阻塞执行。前台执行长驻服务基本必然卡住Spinner。5.3 常态化检查MCP服务和日志状态把异常消灭在暴露前如果你接了MCP服务器建议每次启动Claude Code之前或之后花十秒钟确认这些依赖服务都健康。我自己遇到了太多次Claude Code转圈然后报MCP超时的情况最后定位到的都是某个数据库MCP服务的连接池满了或者某个鉴权token过期了。你可以用MCP服务自己提供的健康检查接口或ps命令快速确认服务进程在不在、端口通不通。养成这种习惯之后其实很多卡顿根本不会到你面前。日志检查也是如此。我不建议等到卡了才翻日志平时就可以隔一段时间瞄一眼Claude Code的工作日志。如果在日志里看到大量的重试记录、超时记录哪怕当前界面看起来流畅也说明链路已经处在不稳定的边缘最好提前介入处理。5.4 安装与升级环节的假卡顿下载卡住、版本不匹配最后要提一个很让人抓狂的假卡顿Claude Code在安装或在线升级的时候也会表现出卡住的样子。尤其在不同平台安装Claude Code、下载新版、VSCode插件更新时安装脚本长时间停留在一个进度上界面没有任何输出。这种卡跟使用时的卡不是一个机制它通常是网络下载慢、安装脚本等待交互确认、或者系统权限弹窗没有弹出来导致的。遇到安装或升级时长时间无响应先看看终端最后一行有没有Do you want to continue?这类交互提示再检查系统是否有隐藏的权限确认框在等待点击。如果下载过程本身慢那只能耐心等或者更换网络环境后重试。这里有一点需要特别提醒如果启动时看到官方关于当前区域不支持的使用提示那就意味着你这个环境不属于官方支持范围后续各种连接异常和超时都属于环境本身的问题不在正常的排查路径内请以官方支持范围为准不要试图用非常规手段绕过。版本方面也容易踩坑。命令行版本、VSCode插件版本、配置的模型版本三者如果不一致可能产生奇怪的行为包括但不限于Spinner长时间转动、某些参数不生效、工具调用异常。每次升级后最好确认一下各个端都处于一致版本。这不是理论上的猜测我在一次升级到新版命令行后、插件还停留在旧版本时就遇到了对话卡顿和输出格式错乱的问题把插件同步升级后一切恢复。最后分享一个小习惯我现在只要发现Claude Code有卡顿苗头第一反应不再是猛按Esc而是先开一个top看CPU再开一个lsof看连接。这个职业习惯帮我省掉了无数盲目重启的冤枉时间。Claude Code是一个工具转圈是它在工作的信号也是它向你反馈状态的窗口。与其烦它总卡不如把它当成一个需要维护的环境——该清理会话就清理会话该检查进程就检查进程该升级就升级。这套组合拳打下来你会发现大多数卡死其实都是可以预防和快速解决的。