晚上十一点我正打算让 Claude Code 把手里最后一段代码重构完。Spinner 转了两圈然后整个世界安静了。光标还在闪界面没报错任务管理器里的 CPU 曲线也平平淡淡——它就像一台看起来正常运转、其实早已停摆的机器。这种“卡住”在 Claude Code 里实在太常见了不是崩溃没有红色报错只是无穷无尽的等待。这个现象被讨论了很多次但大多数人的第一反应是“是不是网络问题”“是不是模型负载高”然后一通乱试。我排查过不少这样的案例最后发现真正的原因往往藏在一些你想不到的角落终端渲染、工具调用子进程、上下文窗口膨胀、第三方 API 接入后的限流策略、甚至虚拟机里的资源抢占。这篇文章就围绕 Spinner 状态标识、卡顿根源和排查方案展开把那些容易混淆、容易误判的点逐个讲清楚。无论你是在 Windows、macOS 还是 Linux 上跑 Claude Code也不管你是直接连接官方服务还是通过 LM Studio、CC Switch 这类工具接入本地模型或第三方模型这套排查方法都能用。1. 先分清“假卡”和“真卡”Spinner 状态标识是第一步很多人一看到 Spinner 在转就默认“它还在思考”结果等了五分钟才发现根本不正常。Spinner 转不转、转得快慢、旁边有没有文字提示其实是在给你发信号。只是这些信号大多数时候被忽略了。1.1 Claude Code 的几种等待状态我按自己平时观察到的表现把 Claude Code 在终端里的等待状态大致分成四类状态Spinner 表现伴随现象正常耐心时间对应阶段思考/推理中匀速转动偶尔停一下又转终端文字不定期刷新偶尔出现省略号几秒到几十秒LLM 正在生成回复工具调用阻塞停住不动或者转得极慢界面下方出现工具名、文件路径、命令片段通常 3~10 秒内应该返回等待子进程 / 外部命令执行完流式输出Spinner 消失或变成闪烁光标文字正逐字往外蹦持续几秒到几十秒Token 流式返回中完全挂起Spinner 消失界面僵住键盘输入无响应回车没反应超过 30 秒基本不正常客户端、渲染线程或进程级阻塞其中最容易卡出问题的是第二种工具调用阻塞。Claude Code 在干活的时候会频繁调用终端命令、读写文件、执行 lint 或测试脚本每次调用都会有一个子进程在后台跑。子进程不退出Spinner 就一直挂着。很多你觉得“卡死”的场景其实是某个命令在你的机器上迟迟跑不完。1.2 用 Spinner 状态快速定位问题层我用的一个笨但有效的办法Spinner 卡住的时候先按一下回车或者按 Esc 试试界面能不能响应。如果按了没反应那是客户端层面挂死了问题出在本地进程、终端渲染、系统资源这些地方。如果按了有反应说明界面还活着那就是后台在等某个东西返回问题大概率出在网络请求、API 响应、子进程执行这些链路。有一次我非常确定 Claude Code 已经卡死结果按了两下 Esc 之后它居然弹出了中断工具调用的提示。原来它在等一个git pull命令返回而那个仓库连接的远端服务器早就超时了。这种“假死”如果不看 Spinner 状态很容易误判成客户端崩溃。2. 网络链路与 API 层请求发出后迟迟没有回应排除了客户端挂死之后第二个要查的就是网络请求链路。Claude Code 对网络异常其实很能“扛”它会一直等等到超时为止。这也意味着一段轻轻的网络波动在你屏幕上就是一段很长的卡顿。2.1 请求生命周期里的三段瓶颈一次请求发出到显示文字可以拆成三个时间段建立连接DNS 解析 TCP/TLS 握手正常情况下最多一两秒。服务端接收并开始生成从请求发到收到第一个字节TTFB正常情况下几秒到十几秒取决于上下文长度和模型负载。流式传输阶段Token 逐字返回如果断断续续可能是网络丢包也可能是服务端生成速度波动。排查第一步是分清卡在哪一段。如果整个请求连服务端都没到你会发现 Claude Code 界面里的 Spinner 一直在转但终端没有任何输出流量。我自己会开一个系统监控面板或者直接看任务管理器里的网络曲线——如果请求发出后网络曲线几乎为零说明连接根本没建立起来。基础连通性测试可以这样打# 检查 DNS 解析是否正常 nslookup api.anthropic.com # 测量到服务端的往返延迟只做连通性参考 ping api.anthropic.com注意ping 顺畅不代表 HTTPS 请求一定顺畅。真正影响 Claude Code 的是 TCP 443 端口的数据通路。我遇到过 ping 延迟正常但请求就是发不出去的场景后来发现是本机防火墙规则把某些程序的外连请求拦了。如果网络曲线有流量但 Spinner 转了很久不出文字那问题更可能在服务端处理阶段也就是你发的请求上下文过长、模型本身负载高、或者你接入的第三方 API 在排队。这个时候要看下一个层面了。2.2 第三方 API 接入DeepSeek/Qwen/GLM/LM Studio的专项排查用 CC Switch 这类工具把 Claude Code 接到 DeepSeek、Qwen、GLM 上的人越来越多这类接入的卡顿特性和官方直连完全不一样。最常见的几个卡点限流Rate Limit。第三方 API 对每分钟请求数、每分钟 Token 数都有限制。一旦触发限流接口不会立刻断掉而是会返回 429 或者直接让请求排队。Claude Code 的表现就是 Spinner 转很长时间然后突然吐出一段错误甚至什么都不吐过一会儿又继续。上下文过长导致 Prefill 等待。很多第三方模型并不是专门为 Claude Code 的调用方式设计的。当你把一大段上下文塞过去时服务端要在生成第一个 Token 之前先把整段上下文处理一遍。上下文越大等待越久。这跟你本地电脑性能没关系是服务端在算。工具调用模式回退。Claude Code 重度依赖工具调用协议。有些第三方模型对工具调用的支持比较弱可能会降级成纯文本回答也可能会导致请求中间断掉然后重试重试期间你看到的就是一轮又一轮的等待。排查这类问题我建议直接看请求返回内容。把调试模式打开看 HTTP 响应码和耗时# 打开调试日志 CLAUDE_CODE_DEBUG1 claude日志里会记录每一条请求的耗时和返回状态。如果绝大多数时间都耗在 429 或者限流相关错误上那答案很清楚把请求频率降下来或者换一个额度更高的模型服务。接入本地模型的场景又不一样。比如 LM Studio它的接口是 OpenAI 兼容的Claude Code 通常通过一处接口地址把它包一层。本地模型的卡顿表现在另外几个地方首次推理慢。模型要加载到显存大模型动不动占用十几个 G冷启动要等很久。KV Cache 换入换出。当上下文很长、显存不够时每生成一个 Token 都可能涉及缓存操作越到后面越慢。生成速度上限。取决于你的显卡算力Llama 级别的大模型在消费级显卡上也就是每秒几十个 Token。本地模型接入的配置通常长这样# 指向本地模型的 OpenAI 兼容接口 export ANTHROPIC_BASE_URLhttp://127.0.0.1:1234 export ANTHROPIC_AUTH_TOKENlm-studio如果你的显卡是普通消费级的建议把上下文长度限制调小一些别让 Claude Code 每次都把完整仓库历史塞给本地模型。我的一个实测经验是本地模型跑短任务很流畅但一旦涉及多文件、长上下文的改动等待时间会指数级上升。这不是 Claude Code 的锅是本地推理算力的天花板。2.3 组织级策略与账号边界导致的“假卡顿”还有一种情况请求发出后很快有响应但响应内容只有一个错误提示比如订阅不可用、或组织策略限制了 Claude Code 的访问。这时候 Spinner 可能会转一小会儿然后停下屏幕上出现一行说明文字。我遇到过一种很迷惑的现象终端提示请求被拒但 Claude Code 不退出也不继续干活就那么干等着。如果你发现 Spinner 短暂转动后停了、界面还能输入但后续没有任何进展可以先检查是不是账号、订阅或组织层面的限制。另外如果你在启动 Claude Code 时看到提示说“当前环境或账号范围不受支持”这也不是卡顿问题而是准入条件不满足。不要浪费时间排查网络先确认账号状态和订阅状态是否在官方支持范围内再考虑下一步。3. 本地环境与终端渲染Windows 用户的重灾区我见过太多 Windows 用户被 Claude Code 卡到崩溃最后发现根因根本不在网络上而是出在本地终端这一层。Claude Code 是个面向终端交互的程序它对终端环境的依赖比普通 GUI 应用重得多。3.1 Windows 64 位兼容性问题与终端选择Claude Code 安装包的某些原生模块在 Windows 上表现不太稳定尤其是一些需要调用本地编译产物的依赖。如果你安装时用的是 32 位工具链或者 Node.js 版本过老运行中可能会出现莫名奇妙的卡顿、命令执行异常甚至提示与 64 位版本不兼容。我的建议按顺序做安装 Node.js 的 20 以上 LTS 版本并且确认是 64 位安装包。用 Windows Terminal不要用旧版 cmd 或 PowerShell 5.1。Windows Terminal 对 Unicode、ANSI 转义序列的渲染效率高很多Claude Code 大量使用颜色、光标控制、局部刷新旧终端在渲染这些内容时会消耗大量 CPU。安装完成后如果出现原生模块相关的报错重装一遍依赖让本机编译器重新编译原生模块。有一个很容易被忽视的点Claude Code 在 Windows 上会调用系统命令完成工具操作。如果你的系统 PATH 环境变量里残留着各种乱七八糟的路径或者某个命令真正执行时间异常长Claude Code 的每个工具调用都会被拖住。清理 PATH 之后很多“卡顿”会神秘消失。3.2 Win11 VMware 下的虚拟化拖累在虚拟机里跑 Claude Code 是一个高风险操作。尤其是 Win11 宿主机上再跑 VMware然后虚拟机里又开一个 Windows 环境来跑 Claude Code——我试过不行不是不能跑是体验极其分裂。问题在三个地方资源分配有限。Claude Code 本身不重但它启动的子进程、终端渲染、以及你可能同时开启的本地模型服务都需要 CPU、内存、GPU 资源。虚拟机里分配的内存不足或者 CPU 核心数不够Claude Code 会频繁进入等待状态。磁盘 I/O 延迟。虚拟机的虚拟磁盘性能远不如宿主机物理 SSD尤其当 Windows 虚拟内存、终端日志、模型缓存都挤在同一块虚拟磁盘上时读写延迟会让你感觉每一步都“卡一下”。显卡资源分配。Claude Code 终端渲染虽然不需要强力 GPU但如果虚拟机没开启 3D 加速终端画面刷新会变得很迟钝Spinner 动画看起来一顿一顿的给人一种卡死的错觉。如果你必须在这种环境里跑我的建议是虚拟机至少分配 4 核 CPU 和 8 GB 内存系统盘和模型缓存目录放到独立的虚拟磁盘上并且关闭宿主机的后台内存压缩和磁盘索引。另外把虚拟机的网络适配器类型设为 VMXNET3虚拟网卡的性能比默认的 e1000 好很多。3.3 桌面端与 IDE 插件的渲染瓶颈Claude Code 桌面版和 VS Code 插件的卡顿逻辑不完全一样但有一个共同的敌人渲染负担过重。我在写代码的时候喜欢让它跑一条很长的测试命令测试输出瞬间刷屏几百行。这时候终端界面要处理大量字符绘制和滚动刷新如果渲染线程忙不过来整个界面会进入“假死”状态。这跟很多年前 WinForm 里控件过多导致界面卡死的道理一模一样——不是代码逻辑卡住是 UI 渲染线程被海量刷新拖垮了。解决办法有三个方向减少输出量。在 system prompt 或者参数里让 Claude Code 精简输出不要每次打印完整的文件内容只输出改动摘要。关闭自动滚动。终端长时间自动滚动会让你感觉界面卡顿改为手动滚动。分页输出。某些终端支持分页模式输出超过一定行数自动折叠可以大幅降低渲染压力。VS Code 插件的卡顿还要额外检查插件本身设置。如果你同时装了多个 AI 辅助插件它们都挂在集成终端里监听输出每个插件都会争抢渲染资源。把不用的扩展禁用掉再测试往往立竿见影。至于在 Ubuntu 等 Linux 系统上跑 Claude Code 卡顿的情况最常见的是终端字体渲染和 GPU 加速问题。某些 Linux 终端对中文字体的渲染效率很低改成使用西文字体或等宽字体后界面流畅度会明显提升。4. 一套可复现的排查清单顺着日志逐层锁凶讲了这么多原因必须有一套能落地的排查动作。我自己排查卡顿问题时的顺序是固定的先看状态再看日志然后用变量对照法锁定根源。下面这张清单你可以直接抄过去。4.1 开启 Debug 日志盯住时间戳Claude Code 的调试日志是排查卡顿的最重要工具。启动时加上--debug参数或者在环境变量里设置调试开关。# Linux / macOS export CLAUDE_CODE_DEBUG1 claude --debug # Windows PowerShell $env:CLAUDE_CODE_DEBUG 1 claude --debug日志会记录详细的请求、响应和子进程执行情况。打开日志后我首先会全局搜索耗时异常的记录重点关注网络请求的开始时间和结束时间看耗时是均匀分布还是集中在某一次。工具调用的命令内容和返回值看有没有命令执行超时。错误和重试次数看有没有反复重试但始终失败的操作。有一次我发现日志里同一个请求重试了四次前三次都在几秒后中断第四次才成功。单看界面你会觉得它就是“偶尔慢了一下”但日志揭示了真正的根因。顺着重试的规律去查最终定位到是本地一个安全软件在拦截特定类型的请求。关掉拦截规则后卡顿彻底消失。4.2 四组变量二分法很多卡顿问题看日志也迷雾重重因为多个变量同时起作用。这个时候我会用二分法一次只改变一个变量观察卡顿是否消除。建议按这个顺序测试换终端。Windows 用户从 PowerShell 换成 Windows Terminal 或者 Git BashmacOS 用户从默认 Terminal 切换到 iTerm2。终端层面优化成本最低先排掉渲染问题。换网络路径。临时关闭自定义的网关或转发层恢复最基础直连状态测试。如果你的网络环境本身比较特殊这一步能快速区分是外部链路问题还是 Claude Code 自身问题。换接入方式。官方直连卡就换第三方 API第三方 API 卡就换回官方直连有条件的话再试试本地模型。这个方法能锁定是不是特定服务端的问题。换任务复杂度。让 Claude Code 做一个一句话改动然后再让它重构成百上千行的文件。如果短任务流畅、长任务卡死问题多半出在上下文管理和工具调用队列上。每一轮只动一个变量记录结果。两三轮之后导致卡顿的因素基本会被圈在一个很小的范围内。4.3 典型案例完整复盘拿我之前遇到的一个真实案例完整走一遍流程。现象是 Claude Code 在改动一个较大的 Python 项目时频繁卡住Spinner 状态是“停住不动”界面能响应但后台迟迟不返回。第一步看日志发现卡住的时间点全部集中在同一个工具调用上一条静态检查命令。这条命令在项目根目录下执行正常耗时应在一秒以内但日志显示它跑了三十五秒还没结束。第二步直接手动在终端里跑这条命令结果显示它扫描了整个项目目录而项目里有个vendor文件夹里面有大量第三方库源码。这条命令本身没有问题但扫描范围过大导致执行时间爆炸。第三步解决方式很简单在 Claude Code 的配置里把这个检查命令排除掉或者在工具层让它跳过vendor目录。改完之后所有卡顿点瞬间消失。这个案例给我最大的提醒是很多卡顿的根因是非常本地化的。它在你的机器上是个大问题换一台电脑可能根本复现不了。这也是为什么排查时必须依赖日志而不是凭感觉猜。4.4 几个值得改的配置项最后分享几个我常用、也确实有效果的配置调整方向。控制单次请求的上下文规模。Claude Code 会把你当前打开的目录结构、文件内容和历史消息都带进上下文。项目越大预处理越慢。可以用配置来限制它扫描的目录范围排除掉 node_modules、dist、.git 这些无关目录。让 Claude Code 分步执行而不是一次性搞定所有事情。把它当作一个需要明确指令的执行者每次让它完成一个小目标然后再推进下一步。这能显著减少工具调用的并发数和上下文膨胀程度。及时清理会话历史。长会话会让上下文越滚越庞大处理耗时越来越长。定期开一个新会话把关键背景和要求重新描述一遍比一直续着旧会话要快得多。调整终端的字符编码和换行符设置。Windows 下命令输出常因编码问题导致解析异常个别命令可能长时间等待。统一设置为 UTF-8 能避开不少奇怪的问题。无论你是什么系统、什么接入方式这套“看状态、读日志、控变量、调配置”的思路都通用。排查卡顿问题我最大的体会是大部分时候 Claude Code 自己没有卡卡的是它和你电脑之间的某个环节——终端、子进程、网络链路或者是上下文本身。找准环节问题就解决了一大半。