最近一周有三个朋友在群里问了同一个问题Claude Code 跑着跑着终端左下角那个 spinner 一直转转了三五分钟也没动静到底是在思考还是卡死了要不要直接 CtrlC 重来说实话我第一次遇到也慌。那会儿我也刚把 Claude Code 当日常主力工具用对它的行为模式还不熟一看到转圈超过一分钟就开始怀疑人生。后来连续排查了十几个卡顿案例才慢慢摸清楚一个道理大部分人根本不读 Claude Code 的 Spinner 状态标识把“正常慢”和“真卡死”混为一谈于是瞎按回车、反复重启最后把问题越搞越复杂。这篇文章不聊安装而是专门围绕 Spinner 状态标识、卡顿根源和排查方案展开。我会把“看到转圈之后系统内部到底在干什么”讲清楚哪些情况能等哪些情况必须动手以及我自己验证过的一套排查链路全部拿出来。你照着做至少能把一次两小时的“瞎折腾”缩短到十分钟定位。1. Spinner 不是程序在发呆读懂状态标识是排查第一步1.1 终端里那排跳动字符到底代表什么Claude Code 本质上是跑在终端里的 AI 编码助手它没有浏览器端那种花哨的进度条也没有图形界面的加载动画所以客户端选择用 ASCII 旋转字符来表达“我还活着我在干活”。你看到的那个不断轮换的字符通常长这样⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏。它一直切换形态说明程序的主进程还在正常跑请求已经被发出去了现在正卡在“等待模型响应”或者“等待工具执行结果”这个阶段。很多人一看到 spinner 就默认是“卡死了”这个直觉错得离谱。Spinner 的存在恰恰说明进程没死它只是处在一个不确定的等待期。真正危险的反而有两种一种是 spinner 完全不换形状画面像被按了暂停另一种是整个终端没有响应按键盘都没反应。这两种才是真卡死需要立刻处理。所以第一步不是重启而是先确认 spinner 的状态变化。你盯着它看五秒钟如果字符还在循环跳动哪怕响应内容迟迟不来也先不要按 CtrlC。这时候按中断等于把一个本来可能马上要完成的任务掐死在半路。1.2 Spinner 旁边的状态文字才是关键只看动画会漏掉大量信息。Claude Code 的 spinner 旁边一般会跟着一段状态文字这才是真正该读的东西。不同文字代表不同阶段有的要等有的要救。你看到的状态文本示例实际含义正常等待时长是否干预Thinking... / Working...模型正在生成回复或处理你的请求几秒到几分钟取决于任务复杂度不用管Running tool...客户端正在调用内置工具执行命令、读写文件等取决于目标命令的执行速度检查工具是否挂住Reading file...正在把项目文件读取进上下文大项目可能几十秒不用管没有状态文字spinner 也不动请求挂起、等待确认或内部错误没有正常值立即排查反复出现 Request to Claude...正在发送请求并等待响应一般数秒超过阈值要查网络我用一个表格把我在实际使用中见到最多的状态类型整理了一下你可以直接对照。有个细节值得注意状态文字和 spinner 不是绑定死的。同一个任务里你可能会看到“Reading file...”“Running tool...”“Thinking...”来回切换这是正常现象。真正的问题是状态文字在几十秒内完全不动比如一直停留在“Running tool...”但下面的文件内容没有更新那就要怀疑工具本身卡住了。1.3 三种容易被误判成卡死的“假卡”我踩过一个很典型的坑Claude Code 在处理一个比较大的仓库时突然停在某个 spinner 状态既不报错也不继续我等了五分钟以为死了冲动之下 CtrlC。结果重启后它把已经做完一半的工作丢了后来才发现那是在等一个交互确认只是确认提示因为终端渲染问题没有正常显示出来。这种事不是个例。我把常见的“假卡”分成三类第一类是等待确认但提示没渲染。Claude Code 在做危险操作前会弹出确认比如要执行可能影响系统的命令或者要删除文件。如果终端宽度不够、输出缓冲异常这个确认提示可能显示不出来看起来就像卡住了。这时候按一下回车或者输入 y往往瞬间就恢复。第二类是自动压缩上下文。Claude Code 会把当前的对话历史做一个精简和摘要这个过程需要在本地处理大量文本甚至可能触发模型重新总结耗时很长。如果你看到网络流量不太高但 CPU 占用率很高同时 spinner 一直转多半就是在压缩上下文。这时候千万不要重启等它压完就好。第三类是工具命令本身在后台卡住。比如 Claude Code 调用了某个耗时很长的 git 操作或者需要联网完成的命令可能在等待外部结果。这类“卡”其实不是客户端卡而是它依赖的外部任务没结束。区分“真卡”和“假卡”最核心的方法就一条观察进程层面的活动。只要有 CPU 波动、磁盘活动、网络请求或者状态文字还在切换就说明有活儿在干。全部静止才是真的有问题。2. 四个方向拆解卡顿根源网络、API、本地、上下文2.1 网络链路不畅通表现最像“死等”Claude Code 要把你的指令发给模型服务等生成结果返回。这条路只要有一个环节不畅就会表现为 spinner 死转。最常见的错误迹象是状态一直停留在等待响应阶段没有任何内容输出过了一阵子才吐出一个连接超时、连接重置之类的报错。有时候连报错都没有就是无限等待安静得可怕。遇到过一种很隐蔽的情况网络本身能通但 HTTPS 握手很慢。Claude Code 启动后需要先建立 TLS 连接再发送请求如果握手阶段被拖住spinner 会先转一段时间然后才收到一个看起来很随机的错误。表面上像模型问题实际就是网络对长连接不友好。判断方法很简单不要关掉 Claude Code另外开一个终端直接测一下模型服务的网络可达性。比如执行一条简单的 HTTP 探测命令curl -I -m 10 https://example-api-endpoint.com/v1/messages把地址换成你实际配置的模型服务地址-m 10意思是限制十秒内必须有响应。如果这条命令也长时间卡住或者超时那基本可以确定是网络链路的问题跟 Claude Code 本身没关系。如果你用的本地或局域网模型服务那就直接测对应 IP 和端口是否可达。2.2 API 层限流与权限表面转圈实际在重试另一类卡顿非常容易被误读请求其实已经到达了模型服务端但服务端返回了限流、鉴权、配额之类的错误。按理说客户端应该立刻报错但很多情况下客户端会退避重试也就是转一会儿、停一会儿、再转一会儿看起来像积极工作实际上是在反复撞同一个错误。这种场景的典型表现是 429 限流。模型服务对每分钟请求次数有硬限制超过之后不会直接给你结果而是要求客户端等待重试。Claude Code 遇到这类响应时会进入重试逻辑于是你看到 spinner 出现“工作—暂停—再工作”的规律性节奏。还有一种更头疼的是账户和组织策略问题。比如账号所属的组织关闭了订阅使用权限或者 API Key 没有对应资源的访问权。客户端在认证阶段就已经被拒绝但界面层不会第一时间把错误抛到眼前而是表现为请求“发不出去”。你查了半天本地配置最后发现是权限层面的问题。遇到这种情况我的建议是不要干等。直接看诊断信息确认当前用的账号、Key、配额状态有没有异常。API 层面的问题通常不会自己恢复要么等限流时间窗口过去要么换 Key要么找管理员确认权限干坐在 spinner 前面是没有意义的。2.3 本地资源与终端渲染电脑自己先累了Claude Code 是典型的 Node.js 命令行应用它对终端的渲染能力、系统资源占用其实比想象中敏感。先说终端渲染。Windows 自带的旧版终端处理 ANSI 转义序列的能力很弱Claude Code 的输出里带了不少颜色和格式控制符旧终端渲染不过来就会出现界面刷新缓慢、spinner 动画断断续续、输出内容滞后显示。你以为是卡死其实是显示层在拖后腿。这个问题在升级到 Windows Terminal 或者换到 WSL 环境后基本能消失。网上有人反馈“与 64 位版本的 Windows 不兼容”的提示很多也和终端组件或系统版本过旧有关。然后是资源占用。Claude Code 处理大项目时需要读取文件、构建上下文、执行工具命令这些都是吃 CPU 和内存的操作。如果你同时开着十几个浏览器标签、一个编辑器、几个 Docker 容器机器内存被占满之后Node 进程不得不疯狂使用交换分区表现为系统响应变慢、spinner 无规律卡顿。还有一类奇葩情况是 Node.js 版本不对。Claude Code 对运行环境的 Node 版本有要求版本过旧或过新都可能出现依赖加载失败、进程无故挂起。平时正常换了个环境就频繁卡我建议先查一下 Node 版本。2.4 上下文越来越长不是卡死是“重”得慢这个坑很多人意识不到。Claude Code 每次发起请求时都会把当前对话历史打包发给模型。你的会话越长携带的 token 越多模型服务端处理输入所花的时间就越长。在聊了二十轮、三十轮之后你感觉“怎么越用越卡”这不是错觉。每次输出的首字延迟会明显变大因为模型要先读完大量的历史内容才开始流式生成。此时 spinner 在转但它转得很“沉重”半天没有输出看起来像卡死其实是上下文已经膨胀到让每次请求都变成一次重活。更复杂的是自动压缩之后的状态。Claude Code 发现上下文太长时会先做摘要压缩这个过程本身就要消耗额外的时间和 token。压缩期间当前任务会被搁置spinner 会莫名其妙地长时间转动。如果不了解这个机制很容易把它当成故障。这部分的排查思路和真正的故障完全不同不需要改配置不需要换网络只需要清理会话或者拆分任务让每次请求的负载降下来。3. 一套可以照抄的排查链路从现象到根因我前面讲了这么多根源但真正在现场你没法按照教科书一个个猜。我一般按下面这套流程走能比较快地把范围从“整个程序”收窄到“某一个具体环节”。3.1 第一步花三分钟定性先别急着动手看到 spinner 卡住第一件事永远是观察不是干预。我给自己定的规矩是先看三分钟。把终端窗口放到足够大让状态文字完整显示出来。盯住 spinner 的切换节奏同时打开系统资源监控。Windows 上可以直接看任务管理器里的 CPU 和网络曲线macOS 用活动监视器Linux 用top或者htop。我一般会同步执行两条命令一边看日志一边看进程状态# Linux/macOS htop # Windows PowerShell 也可以看进程资源 Get-Process node | Select-Object ProcessName, CPU, WorkingSet, StartTime观察重点有三个一是 CPU 有没有周期性波动二是网络流量有没有变化三是 spinner 是否还在切换字符。如果 CPU 在跳动、网络有进出流量说明任务还在推进慢但不死。如果三项全部静止spinner 也固定成一个字符不再变化那才需要进入下一步干预。这一步看起来基础但真的能救回很多本来没问题的任务。3.2 第二步用内置诊断和日志拿到实锤Claude Code 有一套内置的斜杠命令是排查时最直接的工具。在会话里输入/doctor它会跑一遍环境检查包括配置合法性、网络连通性、认证状态等。输入/status可以查看当前账号、模型、配额信息。输入/context能看到当前会话的上下文占用情况。这三个命令的组合信息量非常大。比如/status显示配额耗尽那就别再排查网络了直接去处理额度。比如/context显示占用已经达到 90% 以上那问题多半就是上下文膨胀。再比如/doctor明确标出某个配置项不合法那就先去改配置。此外Claude Code 本身会写日志。调试模式下它会输出更详细的内容启动方式一般是在命令行里加--debug。日志文件通常在用户目录下的.claude文件夹里macOS 和 Linux 是~/.claude/Windows 是%USERPROFILE%\.claude\。不同版本路径可能略有差异以你机器上的实际输出为准。日志里有大量请求、响应、错误码信息能看到这次请求到底卡在哪个阶段。比如日志里反复出现连接重置那就是网络层出现 4xx 状态码那就是 API 层出现内存溢出或者进程异常退出那就是本地资源。3.3 第三步最小复现把变量一个个拆掉拿到日志之后进入我最喜欢的一步用最小复现来定位变量。不要看着像网络问题就直接改网络而是要控制变量。我会按下面的顺序做隔离测试先在空目录里启动 Claude Code。新建一个没有任何文件的临时目录什么都不接只发一条最简单的指令比如“你好请回复收到”。如果在空目录里正常说明问题不在程序本身而在你的项目环境。再换模型。如果你当前配置的是第三方模型服务换回官方默认模型跑同一条指令。如果换了模型就正常说明问题出在模型服务的兼容性或服务端性能上。这一步对很多人来说非常关键因为接入第三方的模型网关时卡顿概率会成倍上升。接着关掉 MCP 服务和插件。如果你配置了额外的 MCP 工具先全部断开再跑一次那条卡住的指令。很多时候 spinner 卡在“Running tool...”阶段就是某个 MCP 服务端没有响应客户端在等它返回。最后换终端。Windows 上从旧终端切到 Windows TerminalmacOS 上换 iTerm2能排除一批渲染延迟导致的问题。这一套做下来卡顿的根源基本就被锁死在某个环节了。别一上来就重装软件重装只能解决配置损坏类问题解决不了资源和权限层面的问题。3.4 第四步症状对照表快速判断重灾区我把实际排到的卡顿样本按症状归类整理成了下面这个简单对照表方便你在不同场景下做快速判断。核心症状最可能的层下一步动作Spinner 转但网络流量几乎为零网络链路或请求未发出用 curl 测目标地址检查是否可达Spinner 有规律地“转一下停一下”API 限流或退避重试查 /status、查配额、查账号权限CPU 占用高但输出迟迟不来上下文压缩或本地处理耐心等待观察日志中的压缩阶段Spinner 完全不切换界面无响应进程挂死准备重启进程并检查是否被其他任务卡住卡在 Running tool...工具长时间不返回MCP 服务或子进程关闭 MCP 后复测检查目标工具进程这个表不是严格的判决书但它能帮你把排查方向快速拉正。4. 对症下药不同卡顿情况的实际处理方案定位到根因之后剩下的就是动手修。每个层面有不同的处理策略我直接按层来写。4.1 网络层优化连接而不是干等如果你的测试确认是网络链路问题先别急着怀疑软件。我一般会按下面这个顺序处理先确认本机网络整体是否健康。开一个终端连续 ping 几个常见的公共服务看丢包和延迟。如果丢包严重大概率是你本地网络环境不稳。再换一个网络出口做交叉验证。比如从公司 WiFi 切到手机热点如果换了网络马上恢复正常那就是原网络的问题不是 Claude Code 的问题。最后才是检查软件环境的网络参数。比如你配置了自定义的模型服务地址确认端口是否开放、域名解析是否正常。如果用的是本地模型服务检查服务进程是否启动、端口是否被占用。更新 Claude Code 版本也是一个值得做的操作。命令行工具更新用npm update -g anthropic-ai/claude-code很多网络相关的兼容问题会在新版里被修复。4.2 API 层查配额、查权限、查账号状态API 层问题不需要重启电脑更不需要重装软件。我遇到最多的三种情况第一种是配额不够。如果你用的是订阅额度查一下这个月的使用量。如果你用的是 API Key查一下账户余额。一旦额度见底请求要么被直接拒绝要么在重试中反复打转。处理办法很简单充额度或者换账号。第二种是权限不足。你的账号可能被组织策略禁用或者 Key 没有开通对应模型的权限。这种情况会表现为 403 之类的鉴权错误甚至直接挂起。解决办法是找管理员确认权限或者换一个具备权限的 Key。这里多说一句不同环境变量同时配置时也会互相干扰比如同时设了多个认证相关的环境变量可能导致客户端用了错误的那一个把它清理干净再试。第三种是限流。429 限流一般是短时间的几分钟后会自动恢复。如果频繁触发限流说明你的请求频率太高。可以适当降低并发任务数不要把十几个任务一次性丢进去跑。4.3 本地资源给进程留出喘气空间本地资源问题通常好解决但容易反复犯。先说最直接的进程真卡死时不要犹豫直接杀掉卡住的 Node 进程。Linux/macOS 上可以执行pkill -f claudeWindows 上可以用任务管理器结束对应进程或者用命令行taskkill /IM node.exe /F注意taskkill /IM node.exe /F会把所有 Node 进程都杀掉如果你机器上跑着其他 Node 服务请谨慎使用手动在任务管理器里选择更稳妥。杀完之后做三件事关掉暂时用不到的大内存软件给 Claude Code 腾出空间把终端软件换成更现代的版本确认 Node 版本符合要求建议用 LTS 版本避免一些奇怪的兼容性错误。我还遇到过一种情况是磁盘空间不足。Claude Code 需要临时读写文件磁盘满了之后任务会非常诡异地在各种环节卡住。清理一下磁盘空间往往比调整一堆配置都有效。4.4 上下文管理别让会话“负重跑”上下文膨胀导致的卡顿是最容易预防的一类但很多人从来不做管理。我的习惯是按任务拆会话。做一个小功能开一个新会话做完及时清理。不要从一个上午聊到下午同一个会话里干了五件完全无关的事到后面每发一条消息都要等待很久。Claude Code 提供了几个有用的命令/compact可以压缩当前会话把历史对话做摘要释放上下文空间/clear直接清空当前会话历史回到干净状态。我个人的经验是会话超过二三十轮交互或者/context显示占用超过七成就果断使用/clear重新开一个会话。大项目里还有一个技巧配置忽略规则。比如日志目录、构建产物、打包文件这些无关内容应该通过项目配置排除掉避免 Claude Code 每次去扫描几十万行没什么意义的文件。这能显著减少上下文构建的时间。4.5 第三方模型接入时的特殊排查很多人用 Claude Code 不直接连官方模型而是通过配置网关接入 DeepSeek、Qwen、GLM 这类第三方模型或者用 CC Switch 之类的工具做模型切换。这套组合拳很好用但卡顿场景和官方客户端完全不一样。第三方接入时最典型的卡顿是spinner 转一下停了又转一下然后长时间没输出。这通常是网关转发请求时出了问题可能是一手流式响应格式不被 Claude Code 完全兼容也可能是网关服务端处理速度不够。你看半天 Claude Code 的配置找不到问题其实问题出在中间那一层。排查方法很直接打开网关侧的日志看请求有没有进来、响应有没有及时返回、流式数据是否稳定。如果网关日志显示某个请求发出后长时间没结果那就是网关或者模型服务端的问题。另一个常见问题是认证信息不匹配。切换第三方模型后需要重新配置对应的 API Key 和端点。CC Switch 这类工具管理多套配置时偶尔会出现配置没生效导致请求发到错误的地方。切换模型后务必用/status确认当前实际生效的配置。还有一个我反复遇到的坑第三方模型对工具调用的支持不一致。Claude Code 在需要执行命令时会通过工具调用模式请求模型返回特定格式的指令。如果第三方模型对工具调用格式支持不好就会陷入“请求—没下一步—再请求”的循环表现出来的也是卡顿。这种情况是模型和客户端之间的兼容性问题只能换一个支持工具调用的模型或者减少工具类指令的使用。5. 一些长期有效的小习惯和我踩过的坑排查归排查我更想说的是Claude Code 这类工具要稳定用日常习惯比应急方案重要得多。我现在的固定动作是每天开工前先开一次会话然后顺手跑一个/status确认当前模型、账号、上下文状态都正常再开始干活。每一两个小时后看一眼/context超过六成占用就直接/clear绝不恋战。这个习惯帮我避免了大量“用到后面越来越卡”的情况。MCP 服务我保持最小化。加了一个 MCP 插件就要多一层等待和出错的风险。不是真需要的能力我一般不挂。第三方模型接入时我会把调试日志打开跑几分钟确认稳定后再关免得中途出了问题毫无头绪。再分享一个非常实际的兜底方案重要的长任务我会拆成多个小步骤定期确认。不要在一条指令里塞进几十个要求让 Claude Code 一次做一堆事。任务拆得越细单次请求越短spinner 卡住的概率越低就算中间真出问题损失的范围也小。我早期吃过好几次亏一个超大任务跑了十几分钟最后卡在最后一步一重启全没了那种感觉挺糟心的。最后际使用里有一条“五分钟原则”供你参考如果 spinner 连续转了五分钟以上并且没有任何输出、日志、CPU 波动那就别再等了进入排查流程。如果中途还有流量和 CPU 活动多给它一点时间它大概率还在干活。Claude Code 是个好工具但它不会主动告诉你它卡在了哪里。把 Spinner 当成仪表盘而不是敌人学会读状态、找根源、按层处理它就能从一个“偶尔让人抓狂”的工具变成一个真正稳定的日常生产力。