作为Claude Code的日常用户最让人上火的画面就是命令发出去之后终端里那个转圈图标一直转转足十分钟就是不吐一个字。我见过太多人在群里问“是不是死了”“要不要重开”其实这事儿远没那么玄。Spinner状态标识、卡顿根源、排查方案这三件事是连在一起的只要能看懂转圈的状态在提示什么再结合日志和上下文占用去定位大部分卡顿都能在三五分钟内找到方向而不是靠运气乱试。这篇文章就把我自己的排查路子完整写出来。核心思路很简单先看Spinner状态标识属于哪种“转”再顺着工具调用、上下文膨胀、网络开销这几个常见根源去定位最后给出一套可以直接照做的排查流程和优化配置。适合刚接触Claude Code没几天的新手也适合已经在用但被“转圈卡住”折磨过几次的中度用户。1. 动手之前先看懂Spinner状态标识很多人一看到转圈图标就慌其实Spinner状态标识本身就能透露不少信息。Claude Code界面很简单没有复杂的仪表盘唯一的“运行状态灯”就是那个Spinner以及旁边不断刷新的文本输出流。所以要排查卡顿第一步不是查代码、不是改配置而是学会读这个状态灯。1.1 四种肉眼可辨的Spinner状态我观察下来Claude Code的Spinner状态大致可以分成四种。第一种是“快速空转”就是转圈图标转得很快但面板上没有多少新输出。这个状态通常出现在输入框等待、流式输出间歇、或者是短小的工具调用间隙几秒到十几秒之内就会过去。如果你看到这个状态超过三十秒那就不是正常间隙了得往下查。第二种是“匀速常转”图标转得不算快但在稳定输出文字、不断打印日志或工具调用信息。这种状态多半是模型正在一个较长的推理过程里或者在做连续多次的工具调用。它确实在干活只是慢这种“慢”往往和上下文体积有关系。第三种是“慢转卡顿”转圈图标明显变慢甚至一顿一顿的终端里半天蹦出一个字。这种状态常见于网络请求挂起、API长时间未返回、或者工具执行结果迟迟不回填。遇到这个状态基本上可以锁定在网络层或命令执行层。第四种最麻烦叫“假死空转”Spinner状态标识还在转圈也在动但终端完全没有任何输出CtrlC要按好几下才有反应。这种通常是某个外部进程把命令行工具阻塞住了比如插件等待确认、命令执行进入交互状态、或者是API请求连上了但数据流卡死。千万别在这种状态下傻等直接查日志、中断重来更实在。1.2 状态标识背后一个完整的工作循环要理解Spinner状态为什么会有这些差异得先明白Claude Code运行时的完整循环。每次你输入一条指令工具会做这么一件事把当前会话的历史对话、已读文件的摘要、CLAUDE.md里的项目规则全部打包成一个上下文窗口发送给模型处理模型返回的不是单纯的最终答案而往往是一串结构化的“行为序列”包含文本输出、工具调用请求比如读文件、执行终端命令、改代码CLI再把工具调用结果回填给模型继续下一轮推理直到模型给出终止标记、或者达到某个极限条件。每一次“回话”背后可能是好几轮“模型推理—工具执行—结果回填”的小循环。Spinner在转说明至少有一个小循环正在跑。所以Spinner状态标识真正的价值是它暗示着当前正处于哪一类循环里。快速空转多半是流式响应间隙匀速常转一般在模型长推理或连续工具调用慢转卡顿常见于网络等待或工具挂起假死空转往往是阻塞性死锁。这个分类不是官方文档里的标准而是我在实操中总结的经验用它来当排查的第一层过滤器很管用。1.3 从状态标识判断“该等还是该动手”看见Spinner转起来第一反应不应该是“完了”而是“先看日志再决定”。我自己的判断标准是这样的如果转圈的同时日志文件里还有新的请求记录在增加输出流里还有零星文字在蹦那就说明链路是通的只是慢这时候耐心等一等顺便去查上下文占用如果Spinner转着但日志已经三分钟没新增记录了那基本可以判断链路断了这时候不要浪费生命在等待上中断重开一次或者先查网络。这个判断姿势很重要因为很多人一碰到卡顿就想重开会话但如果你连卡在哪个环节都不知道重开之后很可能再次踩进同一个坑。学会先用Spinner状态标识做初步分类是后面所有排查方案的第一块基石。2. 卡顿根源拆解转圈到底在等什么Spinner只是现象真正的“卡顿根源”其实就藏在那几类循环里。我拆了这么多次Claude Code的卡顿90%以上都逃不出下面四个大类上下文膨胀、工具调用循环、网络层开销、以及模型推理本身。把这四个根源搞清楚排查方案才有依据。2.1 上下文膨胀最大的隐形杀手Claude Code的模型上下文是有限的而且“读进上下文的文本量”和“每次推理的耗时”基本是正相关的。你让它读一个两千行的源码文件表面上看它“读”完了实际上那整个文件内容会被塞进上下文窗口里后面的每一次工具调用模型都要带着这一大坨历史来回处理。上下文体积从几千token涨到几万甚至十几万token之后单次推理耗时会成倍上升费用也跟着涨但界面上唯一的变化就是Spinner转得更慢了。我拿自己一个真实项目举例。当时让它重构一个旧模块我图省事直接让它读整个src目录结果上下文瞬间被四五万token撑满。一开始还好改到第三个文件时每次让它改动一行代码Spinner都要转一分多钟才响应。我用/status一看上下文占用已经接近窗口上限。后来我把那个大仓库拆成多个独立任务每次只让它读相关的几个文件同样的改动几乎秒回。所以遇到“越用越慢”的卡顿第一个怀疑对象就应该是上下文膨胀。2.2 工具调用循环反复尝试的“死循环”Claude Code的一大卖点是能直接执行终端命令但这同时也埋下一个坑它会尝试自己排除命令行错误。比如你让它构建项目它执行了一个npm命令失败后返回了一个报错它不会就此放弃而是会基于报错再推理一次、再执行一次。如果报错信息很模糊它可能就会陷入“执行—失败—再执行—再失败”的小循环里表现就是Spinner一直转日志里反复出现同一个命令调用。这类情况我在用Claude Code做构建脚本、跑测试和做批量文件重命名时遇到过很多次。它在那边转圈并不代表“挂了”而是真的在反复尝试只是尝试方向可能不对。这时候最好的办法就是中断它自己看一眼报错在指令里把更明确的约束写进去或者直接把容易出问题的命令改成手动执行完再让它接手后续。2.3 网络层与API配置的隐性开销模型推理最终是发生在远端服务器上的CLI和API之间的网络请求质量直接决定了Spinner的节奏。如果你用的是默认的官方接口正常网络情况下每个请求的响应时间在几秒到一分钟之间都有可能如果你用了第三方兼容API、自己搭了网关、或者机器上挂着各类代理环境变量那请求链路又长了一层任何一个环节抖动都会表现为Spinner状态长时间的慢转或假死。这边有一个我自己踩过的坑用第三方API接入DeepSeek、Qwen这些模型时如果API配置里没设好超时时间或请求并发限制平台一旦限流CLI就会一直挂在等待响应的状态里终端既不报错也不输出。后来我养成了一个习惯排查卡顿的时候第一件事就是用/status看当前连接的是哪个API端点确认网络环境里没有多余代理干扰再继续往下查。2.4 模型推理本身不是所有卡顿都是问题最后要说的这个根源最容易被误判。复杂任务里模型规划时间长一点、思考的链条长一点从几秒钟到一两分钟都是非常正常的。你要它跨十几个文件做一个架构级重构还带着一堆约束条件它内部要先想明白整个方案这个阶段Spinner状态标识就是匀速常转。我最早接触Claude Code时就犯过这个错看它转圈转了一分钟以为是卡死了直接CtrlC结果重新执行之后它又花了同样的时间思考来回折腾了三次才反应过来——人家是在认真思考不是卡住。怎么区分“认真思考”和“真卡死”我的办法是看日志和输出流如果日志里能频繁看到模型生成内容或工具调用的记录它就还活着如果日志完全静止那才是真有问题。另外同一个任务如果重开几回每次都花类似的时间思考和输出那基本可以判定是模型推理的正常耗时不是故障。3. 排查方案五步定位从“玄学”到“科学”前面把Spinner状态标识和卡顿根源讲清楚了这节直接进入实操。我把自己的排查流程固定成了五步每一步都有明确的动作和判断标准。按这个顺序走一般不需要乱试就能锁住问题点。3.1 第一步观察现象分清“慢”和“死”观察现象不是傻等而是带着问题去看。具体来说有这么几个观察点Spinner状态标识转得快还是慢终端有没有新输出日志文件是否有新增记录距离上一次输出已经过去多久这三个问题问完基本能得出第一步结论如果还在持续输出属于“慢”往上下文膨胀和模型推理方向排查如果完全静止属于“死”往网络挂起和工具阻塞方向排查。这一步最大的价值是避免“无差别重开”。我自己最开始的排查习惯很差一卡就CtrlC、重开、从零再来结果每次都在同一个位置卡住。后来我学会先观察三分钟确认是真死锁之后再干预很多虚假的卡顿其实自己就恢复了。3.2 第二步打开日志让Claude Code开口说话Claude Code的日志是排查卡顿最直接的证据。操作上很简单在以日志模式启动Claude Code之前先设置一下环境变量常见的方式是export CLAUDE_CODE_LOGGING1然后带日志模式运行日志文件一般会写到~/.claude/logs目录下。如果你不想重新启动也可以在运行的会话里直接开日志开关。日志打开后再复现一次卡顿然后去看最后几百行记录。你会看到每一次API请求是什么时候发出的、响应是什么时候收到的、工具调用是什么时候启动的、执行结果是什么时候返回的。如果你发现某次API请求发出之后日志里再也没有后续记录那问题就出在“请求发出后没收到响应”这个环节直接去查网络和API配置。如果你发现日志里同一个命令反复出现那问题就出在工具调用循环和网络没关系。日志就是定位卡顿根源的裁判没有它你只能瞎猜。3.3 第三步用/status和/context查看上下文账本日志告诉你“卡在哪个环节”/status和/context则帮你回答“为什么这个环节会卡”。在Claude Code会话里输入 /status能看到当前会话用的模型标识、上下文占用百分比、API端点类型这些关键信息。再输入 /context 或相关命令能列出当前上下文里占空间大户大概率就是那几个被读进去的大文件或者是积累了很久的历史对话。这一步的排查逻辑很清晰如果上下文占用已经在80%以上那卡顿根源大概率是上下文膨胀直接按第4章的“会话瘦身”方案处理如果占用很低说明问题不在上下文继续往下走。每次做耗时较长的任务之前我也会先看一眼 /status记录一个基线等到卡顿的时候再对比一次上下文涨了多少一目了然。3.4 第四步检查网络与API接入点走到这一步基本上锁定的是链路问题。先用 /status 确认当前会话连的是哪个API端点再看系统环境变量或配置文件里有没有设置 ANTHROPIC_BASE_URL、ANTHROPIC_MODEL、ANTHROPIC_API_KEY 这些项。很多人用第三方API时改过这些配置但改完可能根本没意识到旧配置还在生效结果请求一直打到错误端点Spinner自然一直转圈。实操建议是在排查期内尽量保持接入点干净没特殊情况就走直连的官方API或者单一明确的第三方接入点不要在机器上同时留着多层转发配置。我见过一个案例某台机器上同时配置了多个环境变量和代理链结果Claude Code发出的API请求绕过了预期端点走了个奇怪的链路既不报错也不返回最后把所有环境变量清掉、只保留一份API配置之后才恢复正常。3.5 第五步剔除工具循环与错误重试最后一步专门对付工具调用循环。打开日志后如果看到同一类命令被反复执行而且每次都以失败收场那就别再让它自己折腾了。直接中断人工看一眼报错原因然后在新的指令里给你自己人工修正后的做法。我的习惯是把三件事同时做掉在命令行里把出问题的命令手动执行一遍确认能跑通在指令里明确告诉Claude Code“不要再重试某类操作”用系统参数限制单次会话可执行的最大操作数量。这一套下来工具循环基本能被摁住。4. 快速优化配置与第三方接口接入排查完下一步就是给环境做“提速优化”。这一节重点讲四件事会话瘦身、控制工具调用、用cc switch接第三方模型、以及登录账号和纯API Key的区别。每一件都是我实测过有效的事。4.1 会话瘦身比想象中更有效的/compact和会话隔离如果 /status 显示上下文占用很高最直接的解法是见什么拆什么。我会优先用 /compact 命令压缩当前会话的上下文它会用一段摘要替代之前的冗长对话实测下来上下文占用能掉一大截后续响应速度立竿见影。如果任务还能重来我往往会用 /clear 直接清空当前会话开一个全新的干净会话接着干效果更彻底。除了压缩会话隔离也非常关键。Claude Code每个会话的上下文是各自独立的如果你把“修A模块”和“改B模块”放进同一个会话里改到后面整个上下文里塞满了A模块的代码处理B模块时就全是干扰。我现在的习惯是同一个仓库、同一个任务目标就开一个新会话绝不混用。最关键的一点是不要随意让它读整个仓库目录而是精确到一个文件或一个函数上下文体积能控制得非常小。4.2 控制工具调用超时、输出上限与授权范围Claude Code会自动执行一部分终端命令但这不是没有限制的。为了不让它无限重试或一次干太多事我建议手动做三个限制。第一个是设置输出token上限通过环境变量比如 CLAUDE_CODE_MAX_OUTPUT_TOKENS限制单次输出的量避免模型在长输出上耗时过久。第二个是给命令执行设一个超时心理线如果一个命令执行超过几分钟还没完就直接中断虽然CLI没有特别直观的“全局超时”选项但你可以在指令里写明“如果执行超过XX秒就停止”。第三个是缩小授权范围在项目根目录的CLAUDE.md里明确告诉它哪些命令可以直接执行、哪些必须提前确认能有效规避“它自己乱跑命令然后卡在奇怪环节”的场面。安全方面还是得多说一句让Claude Code执行终端命令时默认保持先确认再执行的模式会更稳妥特别是rm、git push、重命名这类有副作用的操作出了事也不好撤销。4.3 用cc switch接入DeepSeek、Qwen、GLM等第三方模型“用Claude Code接入第三方模型”这件事本质上不是修改Claude Code本身而是换掉它背后的API接入点。Claude Code通过环境变量 ANTHROPIC_BASE_URL、ANTHROPIC_MODEL、ANTHROPIC_API_KEY 来决定“请求发到哪里、调用哪个模型”第三方模型只要提供兼容的API端点就能接进来。在模型间切换最顺手的工具是 cc switch这个工具专门用来管理Claude Code的多供应商配置。使用逻辑不复杂安装之后先进行初始化它会列出支持的供应商DeepSeek、Qwen、GLM等你选择目标供应商填上对应的API Key它自动帮你切换好 base url 和模型名。之后正常启动Claude Code让/status看一眼确认当前连的供应商正确就可以正常对话了。实际用下来DeepSeek V3/R1系列、Qwen系列、GLM系列都能在Claude Code里跑基本的对话、读文件和改代码。但要注意两点第三方模型和官方模型在“工具调用格式遵循度”上会有差异有些模型适合复杂工具链有些不适合得实际试第三方API的响应速度、并发限制也各不相同遇到Spinner状态慢转时优先怀疑供应商限流。4.4 登录账号与仅用API Key的差异关于登录和不登录的区别我经常被人问到。不登录Claude Code账号直接用API Key方式运行是完全可以的尤其当你接第三方模型时走的就是这套模式。这种情况更像“裸用命令行工具”基本对话、读写文件、执行命令都没问题但一些依赖云端账号体系的功能比如跨设备会话同步、用量仪表盘、官方订阅流量包等用不上。登录官方账号则走的是订阅体系按套餐包含流量使用AI能力上限和上下文设计也以官方模型为准。如果你有官方订阅日常主力用官方模型、需要省钱或实验时用cc switch切第三方是最舒服的组合。我自己就是这么配的默认接官方模型写复杂架构批量修小问题或跑实验时切到第三方模型两边互补。5. 高频问题与避坑实录最后一部分把我在实操中遇到的典型问题整理成一张速查表再分享几条长期摸索出来的习惯。希望帮你少走一些弯路。5.1 常见的卡顿问题速查表现象高概率根源建议处理方式Spinner快速空转超过30秒网络请求挂起或API未返回看日志确认请求是否发出检查API端点和网络配置必要时中断重试匀速常转但输出很慢上下文膨胀或模型长推理用/status查占用用/compact压缩上下文或拆分会话日志里同一命令反复出现工具调用循环中断人工执行命令看报错并在指令里禁止盲目重试任务中途完全无输出工具执行卡死或假死空转CtrlC中断重开后先开日志再复现换第三方模型后频繁慢转供应商限流或模型兼容性差用cc switch换模型或调整单次请求频率、改用轻量模型越用越慢上下文积累过多用/clear开新会话任务拆细再继续这张表我反复用了好几个月基本能覆盖九成以上的卡顿现象。每次遇到问题先对号入座再动手比漫无目的地重开会话高效太多。5.2 实测下来最顺手的几个小习惯第一个习惯所有耗时任务都开日志模式跑。你可能觉得开日志会拖慢速度实际上影响很小但排查价值极大。卡住的时候直接看日志最后几行三分钟定位问题没有日志就只能瞎猜。第二个习惯大任务开工前先看一眼 /status 的上下文占用和API端点记个基线。任务跑到一半卡住时再对比一次立刻能判断是上下文膨胀还是接入点异常。整个过程不过几秒钟但能省下半小时的排查时间。第三个习惯善用“新会话”而非“续旧会话”。很多人习惯在一个会话里把活全干完但这种用法在Claude Code里非常吃亏。每个会话的上下文都是包袱背着几十万token的包袱处理新任务慢是必然的。我现在每切换一个子任务就开新会话快得不是一点半点。5.3 千万别踩的“重开主义”陷阱最后想专门说一个心态问题不要逢卡必重开。重开看似干脆但你会丢掉当前会话里所有的中间状态和上下文重新来过之后还是可能卡在同一个地方而且更气人的是你根本不知道为什么会卡。正确心态应该是先用Spinner状态标识分类再配合日志定位最后针对根源处理。把“重开”当成所有方案都失败后的兜底措施而不是默认操作。我自己就做过一次特别蠢的事。一个大型重构任务进行到快收尾时模型开始思考一个复杂约束Spinner匀速转了好一会儿我当时手贱按下CtrlC重开了结果第二次跑又是同样的节奏第三次我才反应过来这不是卡顿是模型确实在规划。后来我学会了一件事看到Spinner状态标识在转先喝茶看日志确认它真的死了再动手。慢一点点没关系瞎折腾才最浪费时间。如果你现在正被某个转圈图标折磨到心烦不妨照着这条流程走一遍观察状态、开日志、查上下文、查接入点、切除工具循环。大部分卡顿都能在这三步之内现出原形。剩下的那些疑难杂症只要你手上有日志去社区提问时也能给出别人看得懂的上下文问题解决起来快得多。