1. 先搞清楚 Spinner 到底在告诉你什么1.1 卡住的第一反应最近这几个月Claude Code 群里出现频率最高的问题不是怎么安装也不是怎么配 MCP而是“又卡住了”。你能看到终端里的 Spinner 一直在转转得很有节奏但就是没有任何输出等十分钟、半小时都是这个样子。很多人第一反应是网络问题第二反应是 Claude Code 坏了然后直接 CtrlC 杀掉进程重来。我一开始也这样但后来发现大多数“卡住”根本不是死机而是你不知道当前这个转圈到底代表什么状态。Spinner 转不转其实只说明一件事这个进程还活着事件循环还在跑。它并不代表模型正在思考也不代表请求正在被处理更不代表下一秒一定会出结果。我见过最夸张的一次一个 spinner 在终端里转了一晚上第二天早上看还在转实际上那条命令在等待输入从最开始就不可能有输出。所以搞明白状态标识和卡顿根源之间的关系比学会各种排查命令更重要。这篇文章我就用实战的角度把 Claude Code 的 Spinner 状态标识、常见卡顿根源和完整排查方案一次性说清楚适合那些已经被“转圈”折磨到没脾气的开发者。1.2 状态标识的几种真实含义Claude Code 在终端里的状态显示不同版本会有点差异但逻辑是通用的。我按自己实际观察到的现象整理了一下大概有这么几种你看到的状态背后是什么常见触发场景纯 spinner 在转没有任何文字请求已发出正在等待模型返回第一个数据块模型服务端首字延迟高或者网络链路不稳定spinner 在转旁边有工具名正在执行工具调用等待工具返回结果bash 命令、文件读写、MCP 工具调用spinner 在转有 token 数量在涨模型正在生成内容服务端在正常返回长回答生成、代码补全、大段重构spinner 停了界面没有任何动静请求可能已经结束也可能链路断了且没收到错误事件网络流中断、进程等待用户输入、终端渲染异常spinner 在转但光标还能正常输入终端输入队列还活着可能是子进程阻塞等待确认的权限弹窗被遮挡或子命令挂起这里最关键的一点是Claude Code 并没有把“等待模型返回”和“流已经断开”分开显示。也就是说只要客户端没收到明确的错误事件它就会继续等spinner 就一直转。这点特别容易误导人。我排查过的很多案例里用户盯着 spinner 看了十分钟以为是模型在思考实际请求早就断了。想准确判断到底死没死不能只看 spinner要看日志、看 token 变化、看网络状态这些在第 3 章我会详细展开。1.3 怎么判断是思考还是死循环我个人的经验是看到 spinner 不要急着干预先做三个观察。第一看 spinner 旁边是否出现新的文字比如工具名切换或者正在处理的子任务描述这说明请求还在推进。第二观察 30 秒内终端的日志有没有新增内容有新增说明链路还通着。第三按一下方向键或者在输入框里敲一个回车看终端本身有没有响应。如果终端完全不理你了那是终端进程本身卡了不是模型的问题。判断标准可以这样定如果 30 秒内没有任何新的输出、没有日志变化、没有 token 计数变化那先等 90 秒再说。超过 3 分钟还是死水一潭基本可以判定为假死这时候才需要启动排查流程。另外有个反直觉的经验有时候 spinner 一直在转但模型端其实早就输出完了只是终端渲染卡住没刷新。你输个回车或者调整一下窗口大小输出就全蹦出来了。这种“伪卡顿”比我预想的要常见尤其是用 VSCode 集成终端时输出缓冲区一旦被塞满很容易出现这种假象。所以判断死没死永远不要只看肉眼。2. 卡顿根源从网络到工具的一整条链路2.1 网络层流式响应中断是最大元凶Claude Code 和模型服务端的通信走的是流式传输数据会一个块一个块地推给客户端。这个机制本身没问题但它对网络的稳定性要求很高。你想象一根水管水正流着中间被人踩了一脚但踩的位置刚好没完全堵死这时候水龙头还开着你就是等不到水出来。网络层卡顿就是这个感觉请求发出去之后服务端可能已经生成了一部分内容但某个节点断了客户端没收到完整的结束事件于是它只能继续等spinner 只能继续转。我遇到过的情况包括DNS 解析偶尔变慢请求发出去半天找不到入口网络波动让长连接中断但中断信号没有正确传给进程还有网关设备对长时间空闲的连接做了回收导致流式响应被静默掐掉。这类问题有个共同特征spinner 转得很均匀很稳定没有任何报错但就是没有任何输出。排查的时候可以先看一眼有没有收到任何 token如果连第一段内容都没回来大概率是连接建立阶段就出了问题。连第一个字节都等不到基本可以排除“模型在长思考”这种解释。2.2 模型服务端长输出与限流因素的叠加模型服务端本身也会成为卡顿的根源。最常见的是首字延迟太高。你发了请求服务端可能在排队或者在做复杂的推理或者在做路由调度总之第一个 token 迟迟回不来。Claude Code 的 spinner 看不出这种区别它打分不了“服务端繁忙”和“服务端宕机”于是你就只能干等。另一个常见因素是限流。高峰期请求量大了服务端开始对新请求做排队或降速处理这时候体验就是整体变慢尤其长 prompt 会更明显。怎么判断是不是服务端的问题一个很简单的办法是换个非高峰时段跑同一个任务如果秒出结果那说明之前的卡顿大概率是服务端繁忙。另一个办法是看其他工具是否也慢。如果你同时挂了好几个 AI 编程工具它们都在转圈那就不是 Claude Code 本身的问题而是上游服务整体变慢了。这个判断虽然朴素但很有效能帮你快速缩小责任范围不用在自己终端里瞎折腾。2.3 工具执行层卡住的往往不是 Claude而是它手里的工具这一层是最容易被新手忽略的。Claude Code 不只是对话它还要执行工具调用。比如它调用 bash 命令、读写文件、操作 MCP 工具。工具调用一旦挂起外面的 spinner 会一直转看起来像是模型卡住了实际上模型早就把任务交给了工具工具自己卡住了。我踩过最深的一个坑是这样的Claude 在执行一个脚本脚本里有一行 read 命令等待输入。在普通终端里运行没问题但在 Claude Code 的 bash 工具里这个 read 会一直等没有人给它输入于是整个任务就停在那里spinner 转得飞起。这种问题从界面上看就是单纯的“卡住”不查工具调用记录完全看不出问题。还有 MCP 工具如果你接了一些外部 API 的 MCP Server它内部调用了其他接口接口超时了那工具调用就会一直卡到超时上限才返回这个等待时间可能长达几分钟。判断这类问题的方法很简单去看日志里最后一条记录是不是某个工具调用开始执行如果是那责任基本在工具侧。2.4 本地环境终端、资源与 Windows 的奇怪问题还有一部分卡顿锅在本地环境。终端渲染就是一个容易被忽略的点。Claude Code 在终端里输出的内容包含大量特殊字符和控制序列如果终端字体不支持某些 Unicode 字符或者本地终端的渲染程序处理不过来就会出现界面假死。这种假死的典型特征是spinner 可能还在转但整个终端窗口不刷新输入也没反应甚至窗口标题都变灰了。资源占用也不可忽视。Claude Code 本身就是 Node.js 进程当上下文变得很长终端里积累了大量内容时内存占用会明显上涨。如果机器本身内存不大加上 VSCode、浏览器、多个终端页签同时开着系统进入内存交换整个操作都会卡顿。Windows 下还有一个容易遇到的问题就是实时扫描程序对 Node.js 进程的读写做了过度检查导致命令执行明显变慢甚至出现看起来像卡死的情况。这些问题看着五花八门但排查思路是一样的先确认是不是本地资源瓶颈再往上追网络和服务端。3. 实操排查一套可以照着做的流程3.1 先看状态再动工具我总结了一套排查顺序核心原则就一句话先看状态再动工具。不要一上来就杀进程杀进程是最后手段因为它会把当前会话的临时状态一并丢掉有时候反而更麻烦。正确顺序是先确认进程活不活再确认请求走没走到远端最后确认工具调用是否在正常推进。第一步确认进程还活着。按一下方向键或者随便敲个字符看终端有没有响应。如果完全没响应可能是终端本身挂了需要重启终端。第二步观察 spinner 旁边和日志里有没有新内容。有内容说明还在推进只是慢那就不要动它。第三步如果确认没有新内容再进入日志分析阶段。这三步可以帮你筛掉一半以上的“伪卡顿”至少你不会把终端渲染问题当成模型问题去折腾。3.2 日志和调试模式怎么用Claude Code 的日志信息非常关键。默认情况下日志写在用户目录下的.claude文件夹里具体路径根据系统不同略有差异。你可以用claude --debug --verbose启动这样终端会直接显示内部请求日志包括发送了什么请求、收到的响应块大小、错误类型等等。我排查问题的时候基本都会先开这个模式因为它能直接告诉我请求到底走没走通。日志里值得关注的信息包括请求是否成功发出、是否收到了响应块、是否有重试日志、是否有工具调用记录。比如你看到日志里只有一条请求记录之后什么都没有那说明服务端没有返回或者在网络传输中丢了。你看到日志里一直在打印重试说明请求被拒绝了但客户端在自动重试这时候 spinner 也会转但转得很“徒劳”。另一个实用小技巧如果不想每次用命令行启动可以直接开两个终端一个跑 Claude Code一个用tail -f实时看日志文件。这样排查效率会高很多也方便对比输出和时间戳。3.3 端到端链路验证如果日志显示请求发出去之后没有任何响应接下来就要做链路验证。最直接的方法是用 curl 直接请求模型 API 端点看能不能正常拿到流式响应。代码大概是这样的curl -N https://api.anthropic.com/v1/messages \ -H x-api-key: YOUR_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: ping}] }这个命令会直接打印流式响应。如果能很快看到内容说明模型端、API 端和网络都没问题卡顿就要往 Claude Code 的本地配置和工具调用方向看。如果 curl 也一直挂着没输出那就是更底层的链路问题了你需要再检查网络连通性、DNS 解析、防火墙规则这些基础项。这一步能帮你把问题一分为二避免在错误的方向上浪费时间。3.4 排查顺序速查表我整理了一张速查表实际操作时可以按顺序对照执行步骤做什么判断依据1观察 spinner 旁边是否有文字变化有变化说明在推进继续等2按方向键或输入字符确认终端响应终端无响应优先处理终端3开启 debug 模式观察日志输出有响应块则链路通无响应块则断链4用 curl 直连 API 端点能返回则问题在本地不能返回则问题在链路5查看工具调用记录卡在工具调用则排查工具脚本本身6换模型或换网络环境做 A/B 测试换环境正常则问题出在原环境7再看本地资源占用内存或 CPU 打满则优化本地环境这套流程我用了很久基本能定位 90% 以上的卡顿问题。关键是每一步都要有明确的判断依据不要凭感觉。如果到了第 6 步问题还在那就要考虑是不是模型本身对当前任务的处理能力不够或者你的请求方式有问题。4. 接入第三方模型时的卡顿特殊性deepseek/qwen/glm4.1 第三方 API 常见的卡死点很多人觉得官方服务卡顿和自己搭的第三方模型接入是两回事其实卡顿形态大同小异但第三方接入多了几个特殊的坑。最典型的是协议兼容问题。Claude Code 默认和 Anthropic API 的格式通信而大多数第三方模型用的是 OpenAI 兼容格式或者自己的格式中间要做一个转换。这个转换一旦没做好会出现一种很奇怪的假死状态spinner 一样在转但服务端根本没在处理你的请求。我见过一个真实案例配置好之后跑任何任务都卡在 spinner 上等了十分钟才报错。后来一查发现是 base URL 配错了请求发到了一个不存在的路径上服务端返回 404但客户端因为流式处理的逻辑问题没有立即把 404 当错误处理而是继续等直到超时。这种情况在官方接入里几乎不会出现但在第三方接入里很常见。还有一个问题是流式输出格式不标准。有些服务端声称支持流式输出但实际返回的数据不是标准 SSE 格式Claude Code 解析不了就会一直等后续数据块表现同样是 spinner 无限转。4.2 cc switch 配置时容易被忽略的几个细节如果你用 cc switch 或者其他方式接入了 deepseek、qwen、glm 这些模型有几个细节特别值得注意。第一base URL 一定要确认到具体的服务版本路径不要只写到域名就结束有些服务商要求带/v1有些要求带具体的 API 版本配错了就是请求黑洞。第二模型名称一定要和服务商的模型 ID 完全一致大小写、日期后缀都不能错。模型名不存在的直接 404但有人会遇到模型名存在但权限不足的情况这时候服务端可能会返回一个慢超时而不是立刻拒绝。第三环境变量的生效范围。有些配置写到 shell 配置文件里但你在图形界面启动的 VSCode 继承不到这些变量导致 Claude Code 实际还是用了默认配置。这个问题排查起来特别容易忽略因为你在终端里检查环境变量是正常的但 IDE 里完全不是那回事。我建议在 Claude Code 里执行命令查看实际生效的配置或者直接在启动命令里带上环境变量这样最不容易出错。另外第三方接入时如果开了调试模式一定要看请求日志里实际用的 base URL 是什么肉眼看到的配置文件和进程实际生效的配置经常是两码事。4.3 模型能力差异怎么影响 Spinner不同模型的工具调用能力差异巨大这直接影响 spinner 的“表演”。有些模型对 Claude Code 发出的 tool use 格式支持得不好比如工具参数嵌套太深就理解不了或者响应里的工具调用格式不标准Claude Code 解析不出来只能继续等待。这种情况下模型端早就返回了但客户端不知道spinner 就一直转。我的建议是接入第三方模型之前先用最简单的任务测一下三件事纯文本对话是否正常、流式输出是否正常、工具调用是否正常。三者都通过再上线正式任务。不要拿一个复杂重构任务去测试出了问题你根本分不清是模型能力不行还是配置问题。另外不同模型对长代码生成的处理差异很大有的模型生成几百行代码时中途会停顿很久看起来和卡死一模一样但实际上它在一个一个 token 地慢慢挤。这种时候没有更好的办法只能靠日志确认 token 是否在增长然后耐心等。5. 修复手段与日常预防5.1 紧急止损会话恢复与任务拆分如果确认是真卡住第一步止损要讲究策略。直接杀掉进程确实简单但会丢失当前会话的上下文再开一个窗户就冷了Claude 忘了刚才讨论到哪了。正确操作是先 CtrlC 中断当前请求然后看会话能不能继续如果能继续就接着输入/compact压缩上下文再继续压缩不了就用--continue或恢复会话的方式拉回来。更好的做法是从一开始就不要让任务跑到卡死那么久。Claude Code 适合把一个大的需求拆成多个小回合来推进每轮只让它做一件事比如先写功能设计再写代码实现最后单独做测试。长上下文加多工具连发是触发各种卡顿的高发组合。我见过太多人是攒了一个超长需求一次性丢进去Claude 需要读取大量文件、连续调用十几次工具任何一个环节卡住就连锁反应。拆任务不是降低效率反而是在规避不必要的风险。5.2 配置级优化上下文、工具与权限日常使用中合理控制上下文是减少卡顿的最有效手段之一。/clear会清空当前上下文但不会退出进程简单任务之间可以多用。/compact则会把长上下文压缩成摘要保留关键信息但减少 token 占用上下文刷新之后请求速度会明显变快spinner 转圈的时间也会缩短。工具数量也要精简。很多人的 MCP 配置里挂了一堆 Server但常用的可能就一两个。每次对话模型都要把可用工具列表带上工具越多请求体越大推理时间越长。你可以把不常用的 MCP Server 暂时禁用掉需要的时候再开。权限确认也存在类似的“假卡”问题自动审批没开启时工具调用会等待你按确认键。如果你切了窗口或者在别处忙没注意到终端提示session 就会一直卡在等待确认的状态spinner 也一直转。这种情况也很常见所以我会建议你在终端里保持可见留意权限提示。如果觉得工具调用频繁可以配置允许列表让特定工具自动执行但要注意权限边界不要无脑全开。5.3 版本与运行环境维护Claude Code 的更新频率不算低新版本往往会在请求超时、流式响应、工具调度这些环节做修复。如果你长期不更新遇到某些卡顿问题其实早就被修掉了你还在那儿手动排查。保持更新的命令很简单执行claude update或者直接用对应包管理器的升级命令。升级之后最好重启会话让新版本完全生效。Node.js 版本也需要关注。Claude Code 依赖 Node.js 运行版本过旧可能导致某些依赖库行为异常。我个人踩过的坑是 Node 版本太老导致某些网络请求的 keep-alive 逻辑出问题出现“过一段时间就断连”的奇怪现象升级 Node 之后就好了。Windows 上还要特别注意终端执行策略和编码设置PowerShell 的默认编码在某些场景下会和 Claude Code 的输出冲突表现为乱码、卡顿、不刷新。把终端编码切到 UTF-8很多奇怪问题会自然消失。5.4 长期使用习惯我自己的一个习惯是网络环境不太稳定的时候先跑一个小任务做链路测试比如让它读一下当前目录的文件列表如果这个操作秒回再让它跑长任务。不要一上来就扔一个需要连续调用十几轮工具的重任务一旦中间网络抖动整条任务链就要从头再来。定期清理会话也是好习惯。Claude Code 的会话文件会保留很多历史记录积累多了之后启动和切换会话都会变慢。我会定期把不再需要的会话目录清掉同时保持.claude目录整洁。最后一条建议当一个问题反复出现时不要只解决一次而是把排查结论记下来。比如我后来发现只要是某个特定操作触发的卡顿基本都和某一个 MCP 工具的超时设置有关于是直接把超时时间调短问题就再也没出现过。6. 常见问题速查表可直接收藏6.1 现象与处置对照我把实际遇到的高频问题整理成一张表遇到卡顿先对着找找比自己瞎试快得多现象最可能的原因优先排查动作spinner 一直转但没有任何输出网络流中断或服务端首字延迟高看日志确认是否有响应块spinner 停在一个工具名旁边工具调用挂起可能是子命令等待输入查工具调用日志检查脚本里的交互命令等了几分钟之后突然报错请求超时被客户端终止调整超时配置或检查服务端限流终端界面完全无响应终端渲染问题或本地资源耗尽先按回车/方向键测试终端本身输出时断时续频繁卡顿网络不稳定流式传输频繁中断检查网络质量避免换网络环境只有特定任务会卡其他正常模型能力不足或工具调用格式不兼容换简单模型验证逐层拆解任务接第三方模型后必现卡顿协议不兼容或 base URL/模型名配置错误用 curl 直连验证检查实际生效配置这张表覆盖了我遇到过的大多数情况。如果你遇到的问题不在表里大概率是环境特有的问题按第 3 章的链路排查法走一遍通常能定位。6.2 几个容易混淆的场景最后说几个我经常在网上看到有人搞混的场景。第一个是“spinner 在转但 VSCode 输出面板还在滚动”这说明请求在正常推进只是终端窗口可能没跟上渲染。第二个是“spinner 停了但终端光标还能输入”进程没死但当前请求可能已经结束或者正在等待权限确认注意看终端底部有没有提示。第三个是“spinner 不转了你以为好了但敲命令没反应”这种情况多半是子进程被阻塞整个终端等待子进程退出不是 Claude Code 崩溃了。我做过的另一个有意思的观察是很多人把“等确认权限”当成卡顿处理。Claude Code 执行到某个敏感操作时会停下来等用户确认这个状态下没有明显的提示框spinner 可能会停住或继续转。如果你的操作设计到文件写入、命令执行、网络访问卡住的时候先看看终端是不是有等待确认的提示按一下 y 或者回车可能就恢复了。这种问题不是故障就是交互流程没走完。我个人在实际排查中体会最深的还是那条简单原则看日志永远比看 spinner 有价值。优化好链路、控制好上下文、养成确认状态的好习惯你才能真正把精力花在写代码上而不是和转圈较劲。