用 Claude Code 最让人心里发毛的时刻不是它改错代码而是你敲完一行 prompt眼睁睁看着终端里的 spinner 在那里转。转十秒还能忍转两分钟、五分钟键盘按什么都没反应就很难不开始怀疑人生。Claude Code 高频“转圈”几乎是每个用过它的人都经历过的坎但“卡顿”这个词背后往往同时混着好几层问题网络延时、上下文膨胀、本机负载、MCP 工具拖累、终端渲染甚至第三方模型接入的兼容性。这篇文章就围绕 Claude Code 的 Spinner 状态标识展开把“卡”拆成几种典型现象逐个讲清根源再给一套可以直接照做的排查路径和防卡习惯。不管你是在 VSCode 插件里用、Windows Terminal 下跑还是通过自定义 API 网关接 DeepSeek、Qwen、GLM 这类第三方模型这篇都能用得上。1. Spinner 状态标识先读懂终端里的“暗号”Claude Code 并不是一个“只会转圈”的工具。它的界面信息比普通 CLI 丰富不少有当前模式、有工具调用日志、有流式输出的文本区。所以拿到一次卡顿第一步不是拍大腿骂网络而是先看它到底“卡”在哪个环节。这个过程有点像处理 Qt 表格大数据渲染慢的问题你不会一上来就重写整个界面而是先分清是数据获取慢、模型计算慢还是绘制本身卡。把问题归类再动手效率完全不同。1.1 三种典型“转圈”形态我把实际使用中遇到的 spinning 场景分成三类每一类的处理方式都不一样。第一类是“一直在转文本区没有任何新内容”。这种情况一般发生在你刚提交 prompt 之后CLI 已经把请求发出去了正在等待模型返回第一个 token。网络延时长、请求体太大、服务端排队时这一阶段会被拖到几十秒甚至几分钟。表面看是“卡”实际请求还在路上并没有死。第二类是“转着转着停了但命令也没返回”。常见于工具调用阶段比如 Claude Code 决定执行一个 bash 命令、编辑文件或者递归读取某个大目录。如果对应的命令本身要跑很久比如 pip install、git pull、对整个仓库做 grep界面就会停在“工具执行中”的状态。这类严格说不是模型卡是工具卡。第三类是“完全没有 spinner整个界面像冻住了一样”。输入字符都有延迟光标移动也不跟手。这种情况更多是终端渲染或者本机资源问题尤其是 VSCode 内嵌终端、远程 SSH 会话或者老的 Windows 终端叠加高频 ANSI 字符输出时特别容易翻车。这三个分类是我自己长期使用中总结的不一定覆盖所有版本的新界面细节但核心逻辑是稳定的从你发出请求到开始输出文本之间的停顿归第一类工具执行到一半卡住归第二类键盘本身都变迟钝归第三类。分类对了后面的排查方向就清晰了。1.2 正常、可疑、卡死边界怎么划很多朋友问怎么判断一个转了很久的 spinner 是“正常等待”还是“已经死透”我的经验是用三个小动作确认。先看小幅变化。把终端拉近盯着 spinner 十秒。如果它还在有节奏地变化或者文本区偶尔冒出几个字符说明进程活着只是在慢速推进。再试着按一次 Esc。Claude Code 在处理过程中通常可以用 Esc 中断当前请求如果按下去之后出现类似“Interrupt / Continue / Cancel”的选择说明会话进程本身是健康的只是这次等待时间特别长。最后打开任务管理器Windows 下看“性能”面板macOS 或 Linux 下开 top、htop找到 claude 进程观察 CPU 和网络状态。CPU 和网络都在波动说明数据还在走CPU 接近 0、网络收发归零、spinner 又不转了那基本可以判定是真卡死。我自己下过一次结论真正的“死透”比例其实不高。在日常遇到的卡顿里大概只有 10% 到 20% 属于真假死其余大部分是网络等待和上下文处理造成的“慢”只是慢到让人失去耐心。所以排查的第一步永远是用事实把“假死”和“真慢”分开而不是条件反射地按 CtrlC。现象判断建议动作spinner 持续变化等待超 30 秒慢但大概率正常再等一会或按 Esc 中断后重发一个精简请求spinner 停止无输出CPU/网络有波动可能在等服务端响应抓日志或开 verbose 调试模式spinner 停止CPU/网络归零输入卡顿疑似假死记录现场状态再按流程结束进程2. 卡顿根源盘点从网络到本地逐个拆把状态读懂之后下一步是定位根源。Claude Code 卡顿的原因很少是单一因素我按自己的调试经验分成五类每一类都对应不同的解决手段。2.1 网络链路首 token 等待时间被拉长Claude Code 每次交互的核心路径是本地 CLI 把对话上下文打包成 HTTP 请求发给模型接口服务端再流式返回结果。最容易卡的第一个环节就是“发请求 - 收到第一个 token”之间的网络往返时间。如果你用的是官方 Anthropic API 端点那么网络质量和与服务端的物理距离会直接影响体感。比如我自己在家里网络高峰时段同一个 prompt 在凌晨可以两秒出字晚上却要二十多秒起步。这跟本地配置没关系纯粹是链路延迟。如果再把自定义 API 网关或者第三方模型接入加进来链路上每多一跳都可能进一步拉长首 token 时间。怎么量化这个问题最直接的办法是拿 curl 或者任意接口调试工具直接请求你的模型端点。重点看“首 token 时间”TTFT和整体往返延迟。命令行调试时可以参考这个格式time curl -sS -N -X POST https://your-api-endpoint/v1/messages \ -H Content-Type: application/json \ -H Authorization: Bearer $API_KEY \ -d {model:your-model,max_tokens:16,messages:[{role:user,content:hi}]}curl 里的地址、模型名和密钥都要替换成你自己实际在用的。看 time 输出的 real 时长如果这种最简单的最小请求都要 10 秒以上才出第一个字符那 Claude Code 卡住基本不是 CLI 的锅而是上游接口本身就慢。这时与其在本地调参数不如先去优化你的网络链路或升级服务。2.2 上下文膨胀会话越长处理越慢这是我最想强调的一个点很多人没意识到。Claude Code 在同一个会话里会累积大量上下文你发的每条 prompt、它对文件的分析、执行命令的输出、读到的代码片段都会进入模型请求。上下文里的 token 越多模型每次回答前需要“重新阅读”的内容就越多处理时间会明显上升尤其是首 token 延迟。我见过有人一个会话里连续处理十几个文件最后界面卡到输入一个字符要等半秒这就是典型的上下文膨胀。判断方法很简单。Claude Code 很多版本内置了会话信息命令常见的是 /context 或 /status可以显示当前会话的 token 占用。没有这个命令的话你也可以做个经验判断同一句话新建一个会话后立刻变快那八成就是上下文问题。处理手段三件套/compact自动把历史对话压缩成摘要。适合想保留上下文线索又不希望全文继续膨胀的情况。/clear丢掉全部历史从零开始。适合当前任务已经告一段落或者上下文已经乱到没法继续的情况。手动裁剪别让模型反复读同一个大文件。必要的信息分片传递或者让它把中间结果写进临时文件再继续读。我自己踩过最大的坑就是让 Claude Code 在一个会话里连续处理几十个文件中间还递归读目录。后期它每回一句话都要先“温习”整个仓库结构从流畅到卡顿只用了不到一小时。后来养成了“一个任务一个会话”的习惯卡顿频率立刻降下来了。2.3 本地资源与终端渲染别忽略电脑已经满载有时候问题根本不在 Claude Code而在你的电脑已经撑满了。做开发的人往往同时开着 IDE、浏览器、容器、虚拟机。我就见过有人一边在 Win11 下跑 VMware一边还开着好几个 Docker 容器编译项目这种情况下 Claude Code 的 spinner 转得慢太正常了。CLI 进程抢不到 CPU 时间片网络库被系统调度拖慢终端软件重绘界面也变卡所有因素叠加起来体验就很糟糕。终端渲染要单拎出来说。Claude Code 是典型的“大量文本 ANSI 样式”命令行界面每次输出都涉及文本重绘。你在 VSCode 内嵌终端里用输出超长 diff 或大段日志时渲染压力会明显高于系统终端。Windows Terminal、iTerm2 的新版本一般有性能优化但老版本或者某些字体渲染配置下大段输出能把界面拖到“打字都弹不出来”。排查时先看系统资源监视器。如果 CPU、内存、磁盘已经接近瓶颈先关掉一批不用的重型软件再试。也可以把终端窗口缩小一点看输入是否变快。要是 VSCode 插件里卡、原生终端不卡那基本就是渲染问题换个终端就解决了一半。2.4 工具调用与 MCP 链路的隐性等待Claude Code 能“干活”的重要原因是它不只是聊天而是会调用工具。你让它“跑一下测试”它可能先写文件、再开终端执行命令、再读结果每一步都可能成为卡点。最典型的是工具自身执行太慢比如它调用了 npm install 或者对整个仓库做全局搜索到底跑多久界面就要等多久。这种属于合理等待但如果你没意识到它还在跑命令就会以为是卡死。另一种更隐蔽的是 MCP server 拖累。Claude Code 支持通过 MCP 挂外部工具数据库、浏览器控制、各类内部系统都可以接。每多挂一个 MCP server模型做决策时就有可能去调用它。某个 server 响应慢甚至挂起整个流程就会被拖住。排查时注意界面卡住时有没有显示“正在调用某个工具”或列出工具名。如果有去确认那个工具或命令的实际执行时间。我的经验是MCP 能用但别贪多。装一堆基本用不上的 MCP server收益不高却让每次请求都多了几次工具探测把不常用的 server 停掉卡顿减少非常明显。2.5 第三方模型接入兼容层的额外开销用 Claude Code 并不一定非得接官方模型。实践中有很多人通过环境变量 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 等方式把 CLI 指向兼容 Anthropic 接口的服务然后使用 DeepSeek、Qwen、GLM 等第三方模型。也有一些社区小工具比如常见的 cc switch专门用来切换不同的模型供应商配置。这种玩法很灵活但卡顿更容易出现。兼容层转换有开销Claude Code 用的是 Anthropic Messages 风格的请求格式第三方服务往往需要做格式转换转换逻辑写得不够好就会拖慢速度。第三方模型在兼容端点下的表现也和官方差异很大除了模型本身的质量流式接口协议、限流策略也会影响体验。还有个头疼的是工具调用不兼容如果第三方模型不支持完整的 tool callingClaude Code 可能会反复重试、超时表现就是 spinner 转了又停、停了又转。排查方向是先最小化测试只发一句普通对话看请求通不通、快不快再加工具调用测试。第三方模型接入也尽量确认流式传输是否正常如果关掉流式反而更稳那大概率是网关的流式处理有问题。最后提醒一点切换供应商配置后一定要重启 Claude Code 会话很多“配置了还是卡”的问题只是旧连接还残留在进程里。3. 排查实操路径从现象到结论一条线走完前面是理论分类这一节是我自己常用的实操路径。卡顿发生时按这个顺序走通常能在五分钟内定位到问题。3.1 第一步冻结现场观察状态卡住的时候最忌讳直接杀进程。我一般先做这几件事看 spinner 是否还在动看有没有输出日志行比如工具名、正在读取的文件按一次 Esc看有没有中断菜单再用另一个终端观察系统状态。实际操作时我习惯先把 claude 进程的 PID 记下来同时看一眼负载ps aux | grep claude top -u $(whoami) -b -n 3如果 claude 进程 CPU 还在波动说明它自己的计算没停如果网络还在收发说明请求还没彻底断掉如果二者都静止再考虑强制结束。这一步看起来简单但能帮你避免一次误杀。很多时候你觉得“程序死了”其实只是输出还没刷出来而已。3.2 第二步对齐日志找关键字CLI 工具没有界面日志时靠日志文件排查。Claude Code 一般会在用户主目录下生成一个 .claude 目录配置、历史、部分日志都放里面。具体文件路径不同版本不一样先跑一句命令看看ls -la ~/.claude找到日志后重点看几个模式429限流。服务端在告诉你“请求太快或配额不够”这是用量问题不是网络故障。529、500、502服务端不稳定。多见于服务端超载或网关异常。timeout、reset、EOF连接被中途断开。对应网络链路不稳定或者网关把长连接提前关了。retry、attempt客户端在自动重试。重试多次时卡顿感会成倍增加。如果版本支持调试参数可以按claude --help输出为准临时开启更详细的日志。但我不建议长期开着调试模式写日志本身会拖慢一点只排查时开就好。3.3 第三步最小化复现拆出变量当你觉得是无头绪的“玄学卡顿”时就用控制变量法把嫌疑一个个剔除。我一般按这个顺序来新建会话只发一句“hello”看是否还卡。如果新会话也不快问题大概率在更底层跟上下文无关。换一个更小的模型。官方场景下可以试试 Haiku 这类轻量模型第三方接入则换一个轻量模型看是否变快。模型越重单次推理时间自然越长。临时禁用所有 MCP server 或插件重试。明显变快就是工具链拖累。换终端。从 VSCode 内嵌终端切到系统终端反过来也行用来判断渲染因素。如果用了第三方网关条件允许时测一下非流式模式对比流式与非流式的速度差异。这个过程中你可能会发现每个变量单独看都不严重合在一起却卡得不行。没关系只要能找到压垮体验的那根稻草剩下的就是想办法绕开它。3.4 第四步对症下药给出具体动作把问题与动作对应起来是这样的问题根源处理动作上下文膨胀按 /compact 或 /clear日常一个任务一个会话网络链路慢错峰重试对自定义网关做最小请求测试评估往返延迟服务端限流降低请求频率避免让模型连续执行大量小工具调用本机资源满载关闭重型软件给 CLI 留出 CPU 和 IO终端渲染卡换新版终端引导模型分多次输出避免一次超长 diffMCP 工具拖累禁用不常用 server只留项目必需的第三方模型兼容差换回官方端点对比切换另一个模型对比流式开关重启会话不要小看“重启会话”这个动作。CLI 长时间跑着切换模型或供应商后旧连接和旧配置可能还留在内存里。开一个新会话往往比调任何参数都更快解决问题。4. 常见问题速查与防卡实战技巧最后这部分是给日常使用准备的。把常见现象和动作列成一个速查表卡的时候照着走能省下大量“凭感觉乱试”的时间。4.1 高频卡顿场景速查表现象最可能原因优先动作输入 prompt 后 spinner 一直转迟迟不出字网络/API 首 token 慢请求体过大看日志curl 测端点必要时 /compact 后再试输出到一半突然停住流式连接中断、服务端异常等自动重试按 Esc 中断后重发看日志有无 timeout 或 5xx执行命令后界面长时间无响应命令自身耗时或挂起单独手动跑同一命令确认执行时间整体界面卡输入字符都有延迟终端渲染、本地资源换终端关重型软件观察系统负载接入第三方模型后频繁卡顿兼容层转换、工具调用不兼容最小对话测试对比流式开关重启会话长会话后期明显变慢上下文 token 膨胀用 /compact 或 /clear 开新会话我刚接触 Claude Code 时卡顿总是随手 CtrlC后来发现这样反而容易丢上下文还会让进程残留一堆临时状态。现在养成的习惯是先按 Esc 中断再确认是否需要保留现场最后才考虑结束进程。中断一次请求并不会丢失整个会话重新发一个更精简的请求往往就够了。4.2 防卡习惯让 Claude Code 长时间保持顺滑经验积累下来几条防卡习惯比任何修复手段都管用。任务尽量分拆一件事一个会话。一个阶段性任务做完了就 /clear别让历史无限堆积。担心进度丢失的话可以让 Claude Code 把关键进展写进项目里的说明文件新会话启动时再读这样既保留进度上下文又干净。别让模型反复读同一个大文件。如果你需要长期基于某个大文件工作先把它切成小块或者先让模型把关键结论整理成单独的备忘文件。反复把上千行代码塞进上下文慢是必然的。MCP 工具尽量精简。只留当前项目真正会用的其它全部停用。不要因为“万一以后用得上”就挂一排 server每一个都是潜在的卡顿源头。终端也值得花时间调一下。关闭不必要的自动补全和高亮插件降低渲染压力。Windows 下尽量用新版 Windows Terminal别用老旧的控制台窗口。macOS 下把 iTerm2 更新到最新版老版本渲染大段输出确实吃力。最后一个建议是定期重启 CLI。长时间跑着内存里堆积的连接状态、历史缓存、权限缓存都会影响性能。我一般每完成一个大任务就退出重开一次体感上比一直挂机流畅很多。4.3 我踩过的坑两条值得记住的教训第一个教训是“别把服务端问题当成本地问题”。有一次我花了几十分钟折腾本地终端设置最后发现是第三方网关在高峰期排队普通请求都要八秒才返回。如果你在某段时间大量遇到 spinner 长转先花一分钟测一下上游接口很可能直接省下半小时。第二个教训是“别迷信 killall”。之前遇到卡死就直接把 claude 进程杀掉结果经常丢会话记录还要重新初始化权限。后来改成优先按 Esc 中断再不行才结束进程发现很多“卡死”其实只是等待时间特别长中断一下重新发个精简请求完全能继续。记住强制结束进程是最后的兜底不是第一反应。另外还有个小技巧当你怀疑某个操作会触发超长任务时提前在 prompt 里跟它说清楚“只执行不要输出大段结果结果写到文件里就行”。这一下能避免大量终端渲染减少卡顿的效果立竿见影。我自己日常使用 Claude Code 的体感是卡顿无法完全消灭但绝大多数都能在五分钟内定位并避开。Spinner 其实是它留给你的信号区别只在于你有没有耐心去读。先用状态分类法判断问题类型再按日志、最小化复现、对症下药这个流程走一遍你会发现自己担心的“工具坏了”往往只是某个配置、某段会话或者某次网络波动在作怪。最后再分享一个我最近养成的习惯每个阶段性任务完成后把关键信息沉淀到项目文档然后开新会话继续。这个简单的动作让我的 Claude Code 卡顿发生率肉眼可见地降下来了。也希望你共同实践后能找到自己的防卡心法。