我盯着终端里那个转动的圈圈已经整整三分钟了。Claude Code 又卡住了——准确地说它看起来是卡住了Spinner 一直匀速转既不报错也不出结果。这种状态想必每位用过 CLI 版 AI 编程工具的人都碰到过烦人之处在于你完全不知道它是在正常干活还是已经死在了某个隐蔽的角落。这种转圈其实有个专门的名字叫 Spinner 状态标识。它不仅是等待动画更是 CLI 工具内部执行阶段的外在映射。搞清楚它每个状态的背后逻辑再把常见的卡顿根源分类摸一遍你基本就能在三十秒内判断出该等、该杀、还是该查网络。这篇文章就是围绕这套思路写的Spinner 怎么看、卡顿根源有哪些、具体怎么一步步排查最后再附上几个真实现场和一条我自己的防卡配置清单。不管你是刚装好 Claude Code 的新手还是已经被折磨了半个月的老用户照着这套方法都能少走很多弯路。1. Spinner状态标识转圈背后到底在等什么1.1 那个转圈不是装饰它映射了每一步执行阶段Claude Code 这类终端 AI 助手本质上是一个围绕请求-响应-工具调用循环运转的 agent 程序。你扔给它一个任务它不会一次性吐完而是先解析你的指令然后根据自己的判断决定要不要调用工具读文件、跑命令、搜索代码等再根据工具返回的结果决定下一步动作。整个过程中CLI 界面必须给用户一个明确的反馈这就有了 Spinner。当你看到 Spinner 匀速转动时多数情况是程序正在等待外部响应——要么是等待 API 返回内容要么是等待某个子进程执行完。如果 Spinner 在快速闪烁、频繁变化往往意味着工具调用循环正在密集进行比如连续执行了好几个 shell 命令、反复读取文件。等等这其实才是 Claude Code 的常态工作状态看起来像卡住其实它在拼命干。我在实际使用中发现很多卡住的误判都出自这里。第一次用 Claude Code 时我给了一个重构需求它在终端里弹出任务清单后就开始转圈我又不敢打断硬生生等了五分钟。后来开了 verbose 日志才发现它那五分钟里执行了十几轮工具调用包括搜索全局文件、读取三个模块源码、执行两轮测试。转圈慢只是因为输出信息没有实时打印到终端而非死锁。1.2 不同转动状态的具体含义我把日常高频出现的 Spinner 状态整理成一个速查表按转动节奏来区分状态表现大概率含义建议动作匀速转动且偏慢等待 API 响应或模型生成先等 30-60 秒观察是否出结果快速闪烁或频繁跳动正在密集执行工具调用保持等待通常 1-2 分钟内出结果转几秒停几秒反复重试某个请求失败后触发重试机制检查网络链路和 API 配置长时间完全静止超过3-5分钟大概率进程死锁或网络请求挂死按 CtrlC 中断检查日志Spinner 消失但光标可输入伪卡死可能只是渲染层问题按回车或调整终端窗口大小需要特别提醒的是完全不转的情况不见得是坏事。我自己遇到过好几次 Spinner 消失、终端看似无响应但按下回车后下一段回复立刻刷了出来。这种多半是终端的渲染刷新出了问题不是 Claude Code 本身卡死。判断方法很简单看看终端标题栏的 CPU 占用或者直接敲几个字符看有没有回显。1.3 渲染层干扰你以为卡了其实是显示的问题前面提到的伪卡死在 Windows 上格外常见。Claude Code 在旧版 PowerShell 或未更新的 Windows Terminal 里因为 ANSI 转义序列解析不完整、字体回退、换行计算异常经常会出现界面冻结但程序仍在运行的现象。我见过一例用户在 Win11 的默认终端里跑 Claude Code屏幕卡在白底黑字的等待界面但他用 VS Code 的集成终端打开同一个会话发现所有结果都已经生成完毕——纯粹是渲染没跟上。遇到这类情况优先确认三个点终端是否支持完整 ANSI 颜色序列、Windows Terminal 是否更新到最新、系统有无自定义字体或主题干扰。只要把终端换到 Windows Terminal 或 VS Code 集成终端大部分渲染问题会直接消失。2. 卡顿根源拆解网络、终端、上下文与模型侧2.1 网络链路大多数卡顿的真正主谋Claude Code 采用典型的客户端-服务器架构你每发一句话本地 CLI 都会把当前会话的完整上下文打包成一次 HTTP 请求发给模型 API等流式响应返回再逐字渲染。这个过程里任何网络波动都会直接表现为 Spinner 长时间旋转。网络质量差、API 端点响应慢、请求体过大导致传输超时是最常见的三类问题。一个容易被忽略的细节是Claude Code 的请求体大小会随会话上下文膨胀。假设你连续处理一个大项目每轮对话都携带几万 token 的历史记录那么即使网络状况正常请求的传输耗时也会从几百毫秒涨到十几秒。这时候 Spinner 转得慢其实是内容太多导致请求变重单纯换网络解决不了。另要注意的是 Windows 平台特有的网络问题。比如报错信息里出现过internetopenurl() failed. 0x800...这类 WinINet 层错误就是系统的网络接口调用出了问题常见于系统代理配置异常或网络策略限制。遇到这种报错Claude Code 的请求压根没发出去Spinner 转一会儿就会停住。这种错误通常和 Claude Code 无关优先排查系统级的网络设置。2.2 终端与本地资源渲染瓶颈和进程占用本地环境的资源瓶颈是另一个高频卡顿来源。我见过一台配置不错的 Windows 机器跑 Claude Code 时 Spinner 频繁卡住打开任务管理器一看一个 Node.js 进程占掉了 3.5GB 内存把开发环境的其他进程挤得几乎无法响应。Claude Code 本身就是 Node.js 应用长会话、大上下文、频繁工具调用都会显著推高它的内存占用。终端渲染在低配机器上也可能成为瓶颈。当你让 Claude Code 输出一份长文档或者工具返回了大量带高亮标记的内容终端每刷新一屏都要重新计算排版和颜色。如果终端是旧版 PowerShell 或带宽受限的远程 SSH 会话这种渲染开销会放大到肉眼可见的卡顿。杀毒软件的实时扫描也可能掺一脚。尤其是 Windows Defender 对 Node.js 进程的频繁文件操作做实时监控时每次工具调用读取文件都可能被拖慢几十毫秒。几十毫秒单次看不出来但一轮 agent loop 要读几十个文件累积起来就是好几秒的额外延迟。2.3 上下文管理与 token 膨胀这个点我要单独拿出来讲因为它最隐蔽也最容易被误判为网络卡顿。Claude Code 的会话机制是每一轮请求都会携带整个对话历史包括你之前贴进去的报错信息、它读过的文件全文、执行过的命令输出。会话越长单次请求的体积越大API 的处理时间也同比增长。你想象一下你上午十点开了个会话让它帮你排查一个登录功能的问题。你贴了 20 份日志、让它读了 15 个文件、每次 grep 的输出都进了上下文。到了下午两点这个会话的上下文已经膨胀到十几万 token。此时你再随便问一个问题API 光消化这十几万 token 就要花掉大几十秒Spinner 自然转得又慢又久——这通常不是 Claude Code 的问题而是上下文把请求拖重了。Claude Code 内置的/status命令能看到当前上下文占用情况/compact可以压缩历史。我的习惯是一个会话解决一个独立任务任务完成就开新会话。这比任何网络优化都更能直接降低卡顿概率。2.4 模型侧瓶颈本地模型与第三方 API越来越多的人开始用 CC Switch 这类工具把 Claude Code 接到 DeepSeek、Qwen、GLM 等第三方模型或者反过来接 LM Studio 拉起的本地模型。这时候的卡顿来源就要重新评估了。第三方模型 API 的响应速度通常比 Claude 官方 API 慢而且各家对长上下文的支持力度不一样。实测下来某些模型在上下文超过 32k token 后响应时间会急剧上升甚至直接拒绝请求。这种情况的表现就是Spinner 转着转着突然停住等几秒后直接报错而不是正常出结果。本地模型的情况更特殊。LM Studio 接入 Claude Code 后推理速度完全取决于你的硬件。我用一张 8GB 显存的显卡跑 7B 量化模型中等长度问题大约 10-20 秒出结果但这期间如果模型还在加载权重、或者有其他程序抢占了显存等待时间会翻倍。最坑的是本地模型在推理期间 CPU 和 GPU 占用拉满Claude Code 的工具调用环节也会被拖慢导致你分不清到底是模型慢还是整个系统慢。我建议接本地模型时把请求的 max_tokens 尽量调低避免单次生成过长导致硬件长时间高负载。2.5 安装与兼容性问题Windows 用户的重灾区Claude Code 的卡顿有一部分从安装那刻就注定了。Windows 下载安装包时如果你误下了 32 位版本安装后启动就会提示由于与64位版本的Windows不兼容之类的问题后续运行会出现各种诡异卡顿。另外如果你是从第三方渠道下载的桌面版安装包务必核对官方版本号和校验值很多莫名的卡顿其实来自破损或非官方构建。还有一类典型的假卡顿启动时一切正常但发第一句话就长时间无响应最后弹出一行your organization has disabled claude subscription access for claude code。这其实是账号订阅权限的问题不是本地程序卡了。遇到这种提示检查你的账号是否具备 Claude Code 的访问权限或者是否被组织管理员在服务端禁用了订阅。权限拦截发生在 API 鉴权阶段界面上看起来就像是永久转圈。3. 排查链路从Spinner表现一步步定位根因3.1 第一步开 Verbose 日志让每一步都有据可查遇到卡住先别急着杀进程。Claude Code 支持 verbose 模式启动时加上--verbose参数或设置环境变量就能把内部执行细节打印到终端或日志文件。我试过最直观的用法claude --verbose开启后终端会输出每一轮请求的 timestamp、模型、token 数、工具调用列表、耗时等信息。如果 Spinner 卡住日志会告诉你它卡在哪个环节是等 API 响应还是等某个工具执行完毕。日志文件的位置因系统而异Windows 一般在用户目录下的.claude文件夹里macOS/Linux 则在~/.claude。查看日志时重点找两个时间点最后一次 API 请求发出时间和最后一次工具调用结束时间。两者之间的空白就是卡顿区间。3.2 第二步测试 API 连通性与响应耗时如果你怀疑问题在网络或 API 侧不要靠猜。先用命令行直接测一次 API 请求看看正常的响应耗时是多少。拿 OpenAI 兼容接口举例一个最小测试请求长这样curl -s -o /dev/null -w HTTP %{http_code} - 总耗时 %{time_total}s\n \ -X POST https://api.example.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_API_KEY \ -d {model:your-model,messages:[{role:user,content:hi}],max_tokens:10}这个请求返回的总耗时可以作为你判断的基准线。我日常使用 Claude 官方 API 的耗时大约在 2-8 秒之间第三方模型会明显更慢。如果 curl 测出来响应本身就要 20 秒以上那 Claude Code 卡在 API 等待阶段就完全不意外了。如果 curl 直接超时失败问题基本确定在网络链路或 API 配置和 Claude Code 本身无关。3.3 第三步看进程与资源占用网络没问题、日志也没异常但 Spinner 还是卡这时候要查本地资源。Windows 上打开任务管理器macOS/Linux 用htop或ps -ef重点观察三个指标Claude Code 对应的 Node.js 进程 CPU 和内存占用。内存持续上涨、CPU 长时间高占用往往是上下文膨胀或工具调用死循环。终端进程的资源占用。Windows Terminal 或 VS Code 的渲染进程偶尔会吃掉大量 CPU导致界面卡顿。磁盘 IO 和网络 IO 是否有异常波动。杀毒软件实时扫描、文件索引服务、云盘同步都可能干扰 Claude Code 的临时文件读写。日常排卡顿我把这个步骤作为是否该中断进程的依据。如果 Node.js 进程 CPU 占用居高不下且持续增长说明它可能在工具循环里打转等下去没有意义。如果 CPU 几乎为 0、内存稳定说明它在等外部响应那就再耐心等等或转去排查网络。3.4 第四步最小化复现排除干扰前面几步查完还没定位就要用最小化复现法缩小范围。具体做法是清空当前会话新建一个最简会话只发送一条几乎不消耗上下文的指令比如回复OK观察是否还卡。这个测试能帮你区分是会话上下文太重还是环境本身有问题。如果最简请求也卡继续做三个动作换个终端试试Windows Terminal 换 VS Code 集成终端、换个网络试试手机热点是无情对照实验、更新 Claude Code 到最新版本。这三个动作做完至少能筛掉环境层面的多数因素。我见过不止一个用户折腾了半天配置最后发现是旧版本里的已知 bug升级后一切正常。4. 实战复盘几个典型的卡死现场与最终解法4.1 VS Code 插件里 Spinner 转个不停一次朋友找我排查问题他的 VS Code 集成终端里Claude Code 的 Spinner 转了将近十分钟一条消息都回复不出来。日志里没有任何报错只有反复重试的 API 请求痕迹。排查发现他的环境变量中配置了一套系统级网络参数而 VS Code 插件启动 Claude Code 时继承了这套信息导致 API 请求全被拦截。单独在外部终端启动 Claude Code 则完全正常。解法很直接在 VS Code 的启动配置里显式指定一套干净的环境变量覆盖掉系统继承的设置。重新加载窗口后问题消失。这个经验后来我复制到其他类似场景都有效——凡是终端外正常、终端内卡住的奇怪现象优先怀疑环境变量差异。4.2 Windows 安装版本不兼容导致的启动即卡另一个现场同样来自 Windows。用户安装 Claude Code 后启动时立刻弹出由于与64位版本的Windows不兼容的提示强行继续后界面卡在黑屏。问题根源非常简单他下载的是 32 位安装包而系统是 64 位。重新从官方渠道下载 64 位安装包后启动和运行都恢复正常。这个案例看着简单但值得单独记录因为类似的版本不匹配问题比想象中更普遍。如果你的 Claude Code 在 Windows 上表现异常第一步就该确认安装包的位数和来源别急着深挖配置。4.3 企业订阅被禁用导致的假性卡顿这个现场最迷惑。用户在终端输入指令后Colde Code 的 Spinner 正常转动但迟迟没有输出。等待一段时间后屏幕上浮现一行提示your organization has disabled claude subscription access for claude code。整个过程平顺得像是网络慢实际上连 API 鉴权都没通过。遇到这种提示别在本地排查直接检查账号的订阅状态和组织策略。如果是个人账号确认订阅是否有效如果是团队共享账号联系管理员确认权限。卡顿界面和网络超时几乎一样所以很多人在错误的方向上浪费了大量时间。4.4 调用 LM Studio 本地模型时的等待幻觉一位网友用 CC Switch 把 Claude Code 指到 LM Studio 的本地模型。他的抱怨是每句话都要等很久完全没法用。我看了一下他的设置问题出在两个地方模型量化版本选的太高超出显卡显存后触发了 CPU 回退推理每次请求的单次生成长度设置过大模型要逐字生成上千 token自然慢。调整方案是换成更小参数量或更低量化等级、把上下文长度限制调低、把生成长度压缩到实际需要的范围。调整后单次响应的等待从两分钟降到了二十秒内。对想用本地模型的朋友这是一个非常重要的认知本地模型卡顿不是卡住而是纯粹的推理速度慢需要靠硬件配置和参数调优来解决。5. 防卡顿的日常配置与使用习惯5.1 会话管理勤开新会话勤压缩上下文防卡顿的第一招不是调配置而是养成会话洁癖。前面反复提到上下文膨胀的问题最有效的对抗方式就是缩短单个会话的生命周期。一个任务做完了就新开会话不要让它一直挂在后台累积。如果暂时无法新开会话就在对话里插入一个指令要求它对当前讨论做一个精简摘要用摘要替代完整历史继续推进。实测下来这个习惯能把长会话场景下的卡顿概率降低一半以上。我自己的经验是把一个大任务拆成调研方案实施验证四个阶段每阶段开一个新会话每个会话只保留该阶段必要的文件路径、代码片段、结论性信息。这样做不仅卡顿少了Claude Code 的输出质量也明显更稳定——原因很简单上下文里杂质少了模型决策更聚焦。5.2 终端选择与启动环境优化Windows 用户建议把默认终端换成 Windows Terminal把 PowerShell 升级到 7.x 版本。旧的 PowerShell 5.1 在渲染 ANSI 彩色输出时存在大量性能问题这在跑 Claude Code 这类依赖流式渲染的工具时会被放大成明显的卡顿感。macOS 用户优先用系统自带 Terminal 或 iTerm2 的新版本旧版本在处理超长行时同样有渲染拖慢的问题。启动环境上检查一下系统的临时目录是否被清理工具频繁重置、杀毒软件是否把 Claude Code 的工作目录加入了主动扫描清单。如果杀毒软件频繁报毒或扫描直接在信任列表里加入 Claude Code 的安装目录能显著减少工具调用阶段的间歇性卡顿。5.3 第三方 API 接入时的参数调优用 CC Switch 接 DeepSeek、Qwen、GLM 这类第三方模型时不要直接沿用 Claude 官方模型的那套参数。第三方模型对超时时间、上下文长度、生成上限的容忍度差异很大。我在配置中最常调整的三项请求超时时间第三方模型普遍比 Claude 官方慢超时时间至少设置到 120 秒以上否则长任务经常被截断。上下文长度按具体模型的上下文窗口设定宁可保守一些也不要超过模型限制导致请求失败。单次生成上限长文档生成场景里把单次生成长度分块处理避免一脚油门踩到底。5.4 定期检查版本与清理历史Claude Code 迭代速度很快旧版本经常带着新版本已经修掉的卡顿 bug。我每月至少做一次更新检查在官方仓库或 npm 上确认当前版本号和本地版本对比后决定是否升级。这个动作虽然简单但确实是防范莫名卡顿最省力的方式。另外Claude Code 会在本地缓存历史会话和日志。时间久了这些文件会积累到几百 MB 甚至几 GB。定期清理.claude目录下的旧日志和无用会话缓存既是防卡顿的手段也是保护隐私的好习惯。我会在每月初清理一次顺便把之前的项目会话导出保存。最后分享一个实用小技巧如果你经常在同一个会话里反复让 Claude Code 读取同一个大文件试试先把文件内容提炼成一份精简的说明文档再让 Claude Code 基于说明文档处理问题而不是每次都读原文件。自从我改用这个方式之后长会话里的卡顿明显改善而且 Claude Code 的输出也更稳定了。这一条是我在无数个盯着 Spinner 发呆的夜晚里总结出来的最有用的一条经验。