你在终端里用 Claude Code 的时候十有八九撞见过这个画面前几秒还跟打了鸡血一样哗哗输出突然光标旁边的小圆点Spinner开始原地转圈转啊转一分钟、两分钟……你心里开始发毛是它还在思考还是已经死掉了要不要按 CtrlC 打断我自己的经验是大多数人在这个瞬间都会做一个错误决定要么过早打断正常推理要么对着一个早已卡死的会话干等十分钟。折腾过几轮之后我决定把 Spinner 状态标识、卡顿根源和排查方案彻底捋一遍这篇文章就是那段时间的沉淀希望能帮你省下大量重复踩坑的时间。这篇文章适合谁主要是重度使用终端的 Claude Code 用户包括在 VS Code 集成终端里用插件的朋友以及那些通过第三方 API 接入 DeepSeek、Qwen、GLM 等模型、时不时就得跟假死搏斗的人。我会先讲清楚 Spinner 背后的状态语义再把卡顿拆成几条独立的根源回路逐一分析最后给出一条从观察到定位、从止损到预防的完整排查链路。1. Spinner 不是装饰品先读懂它的状态语言1.1 Spinner 到底在传达什么Claude Code 的终端界面和 ChatGPT 网页版不一样它没有那种打字机式的逐token冒泡效果而是用一个圆点动画告诉你你的请求还活着。每次你发出去一条消息终端会进入一个等待响应的状态那个小圆点就开始转。它的转动本身就是一个心跳信号意思是进程没有被挂起我还在等上游返回数据。这里有个很多人没意识到的基础事实Claude Code 请求后端模型时不是等整个回答生成完才一次性打印而是等第一个 token 到达之后就开始边收边渲染。所以你在界面上看到的是输出了一部分、然后停住、然后继续、又停住这种间歇性停顿恰恰说明网络链路和模型推理都在正常跑只是上游生成速度有波动。真正需要警惕的是另一种情况连第一个 token 都迟迟不来Spinner 从开始转就那么一直转这时候问题大概率出在请求发出之前或者请求途中的某个环节。1.2 三种典型状态下的 Spinner 行为根据我实际观察Claude Code 的 Spinner 大致有三种状态面孔你可以把它当成一种终端二进制心跳状态特征界面表现底层含义大概率原因匀速旋转圆点在稳定地转没有忽快忽慢请求已发出等待模型首字节或持续接收正常推理中或工具调用执行中转但输出零进展圆点转着但屏幕很长时间没有新内容模型在思考或工具命令在等待或网络长时间无数据extended thinking 模式、上游响应慢、工具命令阻塞完全静止圆点定格输入框都无响应进程可能被阻塞在某个系统调用或死锁终端渲染卡死、bash 工具挂起、磁盘/内存故障我遇到过很多次转但零进展最后发现是在等待一个我自己发出去的df -h这类命令——它其实早就执行完了但是输出被某个less分页器拦截了Claude Code 的 tool 结果层面却迟迟得不到命令已结束的信号。这种被工具执行卡脖子的情况往往被误认为模型坏了。实际上模型早就给出了工具调用计划后台的 bash 进程却吊着不释放。1.3 边输出边卡与真死锁的识别诀窍最容易让新手困惑的是边输出边卡——它看起来像是卡住了但隔几秒又蹦出来一小段文字。我的经验是跟着它的输出节奏走不用打断。Claude Code 在处理大段代码重构或多文件修改时由于要流式接收大量内容终端渲染和 token 解析都吃紧屏幕更新会产生一顿一顿的效果。真实用户往往以为这是卡死了其实把屏幕拉到最底部看输出是在走的只是慢。真正的死锁也很容易认Spinner 彻底不动命令输入区没有任何响应你按什么键都没反馈连 CtrlC 都要等好几秒才生效。这种状态我总结过一个快速判别法用另一个终端开一个tail -f ~/.claude/logs/最新日志文件如果日志在持续追加说明进程活着但可能在等待某个资源如果日志也停了那基本可以断定是进程层面的瘫痪该打断打断别心疼。2. 卡顿根源拆解网络、终端渲染与工具执行三条回路我排查过的卡顿案例多了之后发现一个规律Claude Code 卡住从来不是某一个环节的问题而是三条回路里的某一条或者某几条出了问题。你搞清楚是哪条回路排查方向立刻清晰。2.1 网络回路请求发没发出去响应回没回来网络是卡顿的头号来源但网络慢和网络断是完全不同的两回事。我在连接第三方 API 时踩过一个大坑服务商给的ANTHROPIC_BASE_URL地址本身没问题但他那边的网关会对长时间思考的请求做 60 秒超时切断。结果就是 Claude Code 这边 Spinner 一直转好像模型在认真思考其实上游早就把连接掐了Claude Code 在等待超时重试。检验网络回路的办法非常朴素开着 Spinner 卡住的时候另开一个终端看看本机到目标 API 域名到底通不通、延迟多大。用curl -I或者curl --max-time 15 -v直接请求一下接口。如果 curl 也卡住那必然是网络链路问题如果 curl 秒回但 Claude Code 还是不动那问题就在应用层或上游服务的业务逻辑上不是链路断了。另一个容易被忽略的点是连接复用失效。某些代理类软件我这里说的是通用HTTP代理配置不是特定工具只处理初始连接连接存活一段时间后握手过期长连接断开但 TCP 层没感知Claude Code 这边就成了看着在线、实际上请求扔进黑洞。这种情况我在接入非官方渠道API时遇过很多次后来加了一层自定义的网络健康检查脚本定时探测目标接口卡顿概率骤降。2.2 终端渲染回路模型在正常吐字但屏幕反映不过来很多卡死其实是假卡死真凶是终端渲染跟不上。Claude Code 是流式输出每次输出半个或一个 token 就往终端写。如果一次代码生成让你在几秒内灌进来几百行文本终端软件的文本缓冲、语法高亮、滚动重绘都会开始抢 CPU。我实测过在同样的 Windows 机器上用旧版 PowerShell 窗口跑 Claude Code大输出时 UI 会冻结 2 到 3 秒换成 Windows Terminal 后渲染流畅度有肉眼可见的提升。终端软件对大量输出的处理能力差异极大。Windows 上还有特殊的 GPU 加速坑。Windows Terminal 默认开启基于 GPU 的图形渲染听起来很美但在某些核显型号和过旧显卡驱动的组合下反而会导致滚动卡顿。我在排查一台老笔记本时发现把 Windows Terminal 的GPU 加速关掉之后Claude Code 的大输出滚动从掉帧式卡顿变成了能接受的慢。另外终端里配置的等宽字体如果某个字符在你的字体里缺失终端会自动做字体回退查找也会造成瞬时停顿。判断终端渲染回路问题有个可靠的标志卡住的瞬间看系统监视器CPU 占用被终端进程拉满而 Claude Code 进程的 CPU 占用反而不高。同时你看~/.claude/logs/的最新日志还在持续写入 token 数据。那就是典型的模型在干活屏幕在挣扎。2.3 工具执行回路bash 挂起、权限审批、大文件读写Claude Code 的杀手级功能是能直接执行终端命令但这也是最容易卡死的地方。它发出一个工具调用tool_use比如让你去跑某个构建脚本然后它就在等这个 bash 进程返回 result。如果你让它跑了一条没有超时控制的sleep类命令或者去 grep 一个巨大的文件夹这个工具调用就可能长时间挂起。权限审批也是隐藏卡点。我配置了/permissions限定之后每次工具调用都可能弹出一个是否需要允许执行的确认流程。在纯命令行会话里这个确认是等待用户输入的如果你切走窗口或者忘了注意提示区就会造成Claude Code 在等我我在等它的尴尬死锁。日志里表现为 tool_use 已发出tool_result 迟迟不来进程既不崩溃也不继续。大文件读写也踩过雷。有次我让它分析一个几百 MB 的日志文件它决定用 awk 做逐行统计那个 awk 跑了快十分钟。期间 Spinner 一直转我一度以为是死机了。后来习惯成自然只要涉及大文件、递归目录、正则扫全盘的操作我一定会提前在指令里加只处理前多少行或者用并行管道限制执行时间这类约束。2.4 模型推理与上下文膨胀首字延迟才是慢性杀手除了外部回路模型自身也会卡。Claude Code 默认会携带完整的对话历史去请求模型当你的会话上下文接近模型窗口上限时无论端到端网络多快上游处理请求的时间都会指数级增长。这表现在 Spinner 上就是从一开始就转得比平时慢很多转了很久才打出第一个字。我在跑一个几百轮的长会话时明显感受到回答速度下降到原来的十分之一。用/context一看上下文占用已经 90% 以上。这不是网络问题是模型在庞大的上下文里做注意力计算每个 token 的生成都慢得离谱。遇到这种情况正确的操作不是等待而是主动做/compact压缩上下文或--resume新开一个更精简的会话。3. 自底向上的排查链路五分钟定位卡在哪一段前两部分是理论框架接下来是实际能落地的排查流程。我给自己定了一个四级排查的口诀判活、看日志、做二分、止损复现。每一步都只花几十秒但基本能锁定问题归属。3.1 第一步判活——先确认进程是死是活遇到卡顿第一件事不是关窗口是判断进程活没活。我常用的几个实操动作观察 Spinner 还在不在转。如果还在转起码说明事件循环没崩。另开终端执行ls -t ~/.claude/logs/ | head -3看最近的日志文件有没有新内容。再执行tail -n 5 ~/.claude/logs/最新日志如果时间戳是最近一分钟之内说明进程活跃。用系统监视器看 CPU 和网络流量。Claude Code 的 node 进程如果有 CPU 占用说明它在算如果网络有持续流量说明在上传/下载。试一下敲Esc或者直接输入一个新字符看看输入框有没有反应。如果四招下来全都没反应再考虑 CtrlC 暴力中断。这里有个小技巧先按一下 Esc 取消当前响应如果 3 秒内没反应再上 CtrlC最后才考虑关闭终端。因为有些卡顿只是 UI 渲染线程被占满主逻辑线程还活着直接杀掉会丢掉上下文。3.2 第二步看日志——日志不会撒谎Claude Code 的日志是排查故障的照妖镜。默认位置在~/.claude/logs/文件名是一串日期加时间。打开最新日志你能看到每次请求的类型、耗时、模型名称、token 数量、错误信息。我用 jq 过滤日志里的关键字段能快速看出卡顿发生在哪一层# 查看最近日志里所有 assistant 消息的时间戳 jq select(.typeassistant) | {timestamp: .timestamp, message: .message.content[0].text} ~/.claude/logs/$(ls -t ~/.claude/logs | head -1) | tail -20如果日志里最后一条 assistant 消息时间戳停在你发消息之前说明请求压根没进入模型响应阶段问题在网络或 API 配置如果时间戳在持续更新说明模型在返回内容问题在渲染如果日志里出现了 timeout、connection reset、rate limit 之类字样那原因不言自明。启动阶段也可以用 debug 模式拿到更细的信息claude --debugdebug 模式会把更多请求链路细节打到日志里我排查第三方 API 问题时基本都是开 debug 跑一次等复现卡顿后再去看日志里的 HTTP 层耗时。3.3 第三步做二分——把问题切成小块验证同时有太多变量时我习惯做二分定位一次只动一个变量判断哪一步导致卡顿。常用的验证序列换一个极简请求比如说你好如果立即响应说明链路基本健康问题大概率出在会话上下文的大小或复杂度上。清空当前会话重新开一个再跑同样复杂的任务。如果新会话正常八成是旧会话上下文过大或内容里存在某种让模型陷入循环的指令。临时改用一个更小/更快的模型通过ANTHROPIC_SMALL_FAST_MODEL等环境变量切换如果变快说明是主模型推理耗时。把输出目标从终端改成文件重定向例如claude -p 生成一个xxx output.txt如果改文件后不再卡 UI说明是终端渲染问题。关掉部分权限避免触发工具调用的等待。如果关掉后明显顺畅说明是工具执行审批流程卡住了一把。这套二分法特别管用因为它能快速把模型慢网络差渲染卡工具阻塞这四类原因拆开。我实测最多三轮就能锁定原因。3.4 第四步止损与复现——救回数据比追究原因更重要定位问题的同时也要知道怎么在保住会话的前提下止损。如果你用的是/resume或者claude --continue延续之前会话卡顿后重开时--resume通常能恢复最近的对话上下文。如果上下文已经很大先别急着恢复一次跑到底进去后立刻/compact把历史压缩成摘要再继续任务。记录复现步骤也很关键。我每次遇到卡顿都会在日志目录里把当时的环境信息一起存下来包括 Node 版本、Claude Code 版本、终端类型、当时上下文 token 量、目标 API 类型。下次再卡时先对照历史如果特征是相似的直接跳到之前的解决方案省掉重新排查的时间。3.5 完整案例一次第三方 API 接入的高仿死锁拿我一个实际案例来演示整套流程。当时我用一个兼容接口接入了第三方模型做到一半 Spinner 持续旋转但零输出。我先判活日志在写入网络有下行流量但非常小进程没死。接着看日志发现最后一条 assistant 消息时间戳只更新到请求发出的前十秒后面一直是 pending。我用 curl 直接测目标接口的延迟发现单轮请求响应在 2 秒内但发两个连续请求之间如果有 5 秒的思考间隙第二个请求就经常卡住 100 秒以上。这个现象强烈指向服务商的连接复用或带宽策略问题。于是我改了接入方式用 CC Switch 之类的配置管理工具切换到一个超时设置更宽松的供应商通道再在环境变量里加了更长的超时上限问题消失。这个过程里二分法帮我排除了模型本身慢和终端渲染的问题最后剩下的就是网络链路。4. 高频卡顿场景复盘安装、升级、插件与第三方API4.1 安装与升级阶段卡在下载不动和首次初始化很多人的卡顿从安装就开始了。Claude Code 通常通过 npm 全局安装npm install -g anthropic-ai/claude-code的时候如果 Node 版本过低或者 npm 配置了不合适的 registry下载阶段会长时间挂起。判断方法很简单看终端里有没有网络流量如果在走但极慢大概率是下载源限速如果完全没有流量检查 npm registry 配置。升级到新版时也偶尔会遇到装完但版本没变的情况。我遇到过一次缓存污染npm 缓存里有损坏的包导致claude --version显示的还是旧版但命令行行为已经开始异常。重装命令是通用的三板斧清 npm 缓存、强制重装、确认全局 bin 路径没有多个版本打架。具体命令各系统大同小异核心是先删除再重装。首次启动时卡很久也常发生。Claude Code 第一次运行会做授权流程、目录初始化、配置文件写入某些系统上还会等待你完成登录确认。如果你开了代理但环境变量没配对这些初始化请求可能卡在网络等待上。我建议首次启动时保持终端前台盯着输出如果出现登录/授权相关提示按提示操作完再开始干活。4.2 VS Code 插件场景CLI 与插件版本不匹配在 VS Code 里通过插件方式用 Claude Code是一种很顺手的模式但插件与 CLI 的版本差距经常引发看似卡死的问题。尤其是插件在 Output 面板里报一堆找不到模块、端口被占用之类错误时实际表现就是界面没反应。排查时先看两件事第一Output 面板里选择 Claude Code 相关通道看有没有明确的报错信息第二终端里claude --version对比插件要求的版本。如果版本不一致优先更新 CLI 到与插件匹配的版本再重载 VS Code 窗口。VS Code 集成终端里的渲染卡顿问题可以用 2.2 节的思路处理必要时把集成终端切到外部终端跑 Claude CodeUI 冻结的影响面会小很多。4.3 第三方 API 接入的场景base URL、模型名与响应等待热词社区里经常出现用 cc switch 接入 DeepSeek、Qwen、GLM 等模型。这本质上是通过环境变量比如ANTHROPIC_BASE_URL、ANTHROPIC_MODEL等把 Claude Code 的请求导向兼容接口。用这样的方式接入时卡顿概率会比官方通道高一个量级原因有三。第一第三方通用接口往往按更严格的超时策略切断长请求Claude Code 这边还在等首字节上游却已经杀连接。第二不同模型对工具调用的返回格式可能不完全兼容模型返回的工具调用在 Claude Code 解析端表现为响应在读但一直不结束。第三某些第三方服务商有并发限制当你同时开了多窗口会话时后面的请求会被排队表现为 Spinner 长时间旋转。我建议通道切换之后先别急着跑复杂任务用最简单的对话把链路走通再用一个中等复杂度的代码任务压测超时表现。同时记住用harness方式免登录接入其他模型时Claude Code 的一些内置能力比如跨设备同步、更强的工具权限管理可能不能用稳定性和功能支持也会有差异遇到卡顿时优先怀疑兼容层本身。4.4 看起来像卡顿实则与 Claude Code 无关的系统干扰这里面有个特别容易误伤的场景Claude Code 本身没卡是操作系统层面卡了Spinner 只是跟着遭殃。我排查过一个 Windows 用户的案例他的终端里 Claude Code 频繁冻结但日志一直正常。后来发现是蓝牙鼠标驱动异常导致系统中断风暴整个 UI 都时不时冻结几秒——和 Claude Code 一点关系都没有。类似的还有输入法冲突、杀毒软件扫描正在写入的日志文件、内存被其他程序占满导致终端分不到 CPU 时间。排查这类干扰的关键是跳出应用看系统打开任务管理器/活动监视器观察整体 CPU、内存、磁盘占用。如果整个系统都已高负载那 Claude Code 卡只是结果不是原因。另外终端里跑一些 GUI 程序的输出比如某些脚本弹出的窗口也可能阻塞终端输入别忽略了这类周围环境因素。5. 把卡顿发生概率降下来的配置和使用习惯排查得再熟练不如让卡顿少发生几次。下面这些配置和操作习惯是我用真金白银的时间换来的按性价比从高到低排列。5.1 控制会话上下文的体积别把长会话当储物间上下文膨胀是最隐蔽的卡顿放大器。一个会话跑几百轮之后每次请求携带的历史都像背着一座大山。除了主动/compact还要养成任务分段的习惯一个大目标拆成几个小会话执行中间用文件或者--resume传递关键结论别让单个会话无限变长。我自己的习惯是一个会话持续对话超过 50 轮或者/context显示占用超过 60%就主动/compact一次。如果任务已经完成了阶段目标直接结束会话新开一个接着干这样历史包袱最小。claude --continue虽然方便但如果上一个会话已经巨大继续之后反而更慢。5.2 合理使用权限系统避免工具调用无声等待权限审批是那种平时没感觉卡起来要命的环节。如果不想每次工具调用都被弹窗打断就把/permissions配置得更细只允许高频安全命令自动执行其他命令走审批。这样既能减少一刀切带来的审批阻塞也不至于放开全部权限导致误操作。如果某些命令注定要跑很长时间比如构建、测试、数据导入尽量在请求时明确要求以非交互方式执行或者干脆在外部终端自己先跑完再让 Claude Code 读取结果文件。这样你既能看到进度也不让 Claude Code 傻等一个长任务。5.3 给外部命令加超时防止 bash 工具吊死日常使用中我会在指令里反复让 Claude Code 不要执行可能无限挂起的命令同时用系统工具给那些有风险的命令套上超时壳子。比如timeout 30 ./build.sh如果构建脚本超过 30 秒timeout 会主动杀掉进程并返回超时错误Claude Code 立刻能拿到 tool_result而不是在那里傻等。这个思路同样适用于任何可能长时间运行的命令。另外一个相关技巧是尽量让 Claude Code 用管道和head限制大文件处理范围而不是直接全量读入。5.4 终端侧的健康体检清单终端环境对卡顿体验的影响经常被低估。我建议定期做这些检查确认用的是现代终端Windows 上用 Windows TerminalmacOS 上确认 iTerm2 或原生终端版本较新老旧终端是渲染卡顿的重灾区。检查终端字体设置确认没有使用缺失字形过多的花哨字体等宽字体选择中规中矩的JetBrains Mono、Cascadia Code 这类。保持终端缓冲区设置合理不是越小越好也不是越大越好我一般设置为 10000 行左右。留意磁盘剩余空间日志文件如果无限膨胀把磁盘占满Claude Code 的写入会阻塞进而拖垮整个会话。5.5 做一个极简健康巡检脚本最后给有动手能力的朋友一个思路把前面说的判活、看日志、探网络三步合成一个极简脚本卡顿发生时先跑它自动输出一段摘要比如最近日志更新时间、目标 API 连通性和延迟、当前 node 进程 CPU 占用、终端进程 CPU 占用。我自己的巡检脚本会把这些结果打印在一屏之内这样我不用手动开三个窗口来回看。脚本本身没什么高深的无非是用curl、tail、ps这些命令拼装判断逻辑但它能让你在焦虑时刻快速冷静下来判断是该等还是该砍。最后再分享一个我个人的操作体会和 Claude Code 相处别把它当成一个必须每次都秒回的工具。它偶尔的沉思是模型在做 extended thinking这个阶段硬打断反而会毁掉一次高质量推理。我现在的习惯是遇到 Spinner 转个不停先跑我的巡检脚本十秒钟之内确定等还是杀。如果是上下文太大就/compact之后续跑如果是第三方 API 超时就切换通道如果只是渲染卡把输出重定向到文件里继续看。把心态从急着重启调成先诊断再决定你和这个终端助手之间的配合会顺畅得多。