说实话用Claude Code最让人血压上升的画面就是那个spinner一直在转转十秒、转三十秒、转一分钟屏幕上一行字都没多。不管你是刚装好claude code的新手还是已经在VSCode里配好插件的老手遇到这种转圈卡住都容易心态爆炸。更麻烦的是很多人一看到spinner就不管三七二十一按CtrlC结果白白打断了一个已经运行到一半的完整任务。我在Mac、Ubuntu、Windows上都跑过Claude Code也把DeepSeek、Qwen、GLM这些第三方模型通过cc switch接进去用过。踩了足够多的坑之后我总结出一个核心结论大部分卡住其实并不是程序死掉而是它正在等待某个东西——等模型回复、等命令执行完、等你按一下确认键、等网络重试。这篇文章我干脆把spinner状态标识是什么、真实卡顿根源有哪些、以及一套从日志到复现的完整排查方案一次讲清楚希望能帮你少走我这几个月的弯路。1. 先分清Spinner在转可能是在等它而不是等死1.1 Spinner背后到底在等什么四类最常见状态Claude Code是一个TUI程序它没有图形界面那种明晃晃的加载条只有一个活动指示器就是大家说的spinner加上当前状态文字。不同版本样式可能有差异但逻辑是一样的这个转圈图标只表示有一个事件在等待中至于是什么事件在等才是问题的关键。我平时把它归纳成四类最常见状态状态类型表象一般时长需要你干预吗等待LLM响应spinner Working之类的状态文字没有新增输出几秒到几十秒长任务可能更久不需要等首token出现执行工具调用spinner一直在转但界面可能滚动出命令/文件操作信息取决于命令本身如果bash命令跑很久要看命令是否正常权限确认看似卡住其实光标停在提示处等y/Enter或选择直到你操作需要回复y、n或者提供路径网络重试转一会儿报错然后自己再转循环每次退避几秒到几十秒观察状态码决定是否终止先说等LLM响应。每次对话Claude Code都会把上下文编码之后发到模型端点然后等待流式返回。模型进入长思考模式或者输出长代码块时第一块内容可能来得比较慢这段时间spinner会一直转。我见过最夸张的一次是让Claude Code重写一个模块它思考了差不多一分半钟才吐出第一行字。如果你在这时候CtrlC等于把一次完整的规划过程打断了重来之后它又要从头想反而更慢。第二种是工具调用。Claude Code会实际执行bash命令、读写文件。比如让它跑npm install或者在一个几百MB的仓库里执行git status命令本身就要几十秒spinner自然会转着等命令返回。这种状态下界面往往不是完全静止的你可能会看到命令输出、文件路径在滚动那就证明它没死只是活干得慢。第三种特别容易被误判。Claude Code在执行有副作用的操作前会询问你比如允许运行命令吗的确认。在正常的终端里提示会直接显示出来但在某些终端环境比如VSCode集成终端和系统终端混用或者用了特殊shell配置里提示可能没有正常渲染看起来就是spinner停在那里不动。这时候你只要试着按一下回车、输入y多半就恢复了。第四种是网络重试。Claude Code在拿到429、529、503这类状态码时不会立刻放弃而是会退避重试。转一下、报个错、再转一下节奏感很强。如果你看到这种周期性转圈报错的形态那基本可以锁定是网络或模型端点的问题而不是本地进程卡死。1.2 假卡顿与真卡顿的边界判断假卡顿和真卡顿我最常用的一个笨办法是看spinner的动画本身。spinner还在匀速转动说明主进程的渲染循环还活着程序大概率在等待某个外部事件要是spinner的动画都停了、光标也没了整个界面完全凝固那才是真的死掉或者进入死循环。接下来的判断要看输出节奏。观察十到三十秒如果过程中出现过任何新的一行输出、状态文字变化、或者错误提示那它只是在慢速工作不是卡死。如果三十秒内什么变化都没有也没日志再考虑中断。还有一个小技巧是看日志尾部。Claude Code的日志文件路径在~/.claude/logs下卡住的时候开另一个终端执行tail -f ~/.claude/logs/latest.jsonl如果日志还在不断追加内容说明内部流程还在推进如果最后一条日志是几十秒前的就说明流程真的卡在了某一环。这一步直接把猜变成了看是我排查时最先用的手段。2. 卡顿根源分三层网络、模型端点、本地进程2.1 网络层API端点可达性与响应超时Claude Code本身不跑大模型推理它本质上是一个把所有操作包装成API请求的客户端。换句话说spinner每转一圈背后可能都对应着一个HTTPS请求在途中。网络层出问题是最常见的卡顿来源。常见的网络层问题有这么几类一是成本最低的端点可达性。你配的API服务不管官方还是第三方网关在当前网络下连都连不上TCP握手就卡住spinner会一直等到超时。判断方法就是用curl打个请求试试如果连接超时那什么都别说了网络不通。二是延迟过高。连接能通但每次请求要好几秒才建立连接传输再慢一点整个请求下来十几秒体感上就是转圈转得让人抓狂。这种一般是链路问题也可能是你终端里配置了出口代理造成的。这里特别提醒一句如果你的终端环境变量里有HTTP_PROXY和HTTPS_PROXYClaude Code是会读的。公司网络里的出口代理、本地调试用的代理只要不稳定所有API请求都会被拖慢表现就是spinner空转很长时间然后超时。三是请求被静默丢弃。有些网络环境会断开长时间空闲的TCP连接Claude Code如果长时间没有对话再发起请求连接可能已经失效需要重新握手这时候卡顿几秒甚至十几秒都很正常。网络层的验证方式很简单后面第3章会给完整的curl命令模板这里先说结论如果curl直连一条消息请求能在1到3秒内返回网络层基本没问题要是连接就花超过1秒那就先从网络环境开始排查。2.2 模型端点层官方账号、第三方API与限流排队模型端点层的问题是Claude Code卡顿里最有迷惑性的。因为表面上看网络是好的、进程是活的但请求打过去之后模型服务端就是不吐数据。先说官方直连的情况。用Anthropic官方账号登录后默认走api.anthropic.com模型是账号对应的订阅模型。官方端点一般很稳定但订阅账号有配额和并发限制一旦触发限流你会看到429或者529。Claude Code遇到这些状态码会退避重试表现为转圈、报错、再转圈的循环。如果你在多个终端同时开好几个会话很容易撞上并发限制。再说第三方接入这是现在多数人在用的场景。通过cc switch这类工具接入DeepSeek、Qwen、GLM本质上只是改了三个东西ANTHROPIC_BASE_URL请求发到哪里、ANTHROPIC_AUTH_TOKEN用什么凭据、ANTHROPIC_MODEL请求什么模型。这三件套只要有一个不对请求就可能挂起。这里有个大坑DeepSeek和很多国产模型服务本身是OpenAI兼容协议而Claude Code用的是Anthropic原生协议。中间必须有一个网关或者转换层把两种协议互相翻译。如果这个转换层对SSE流式支持不完整请求发过去之后服务端迟迟不返回完整的流结束标记Claude Code就会永远等下去spinner转到天荒地老最后超时。我在接入第三方模型时遇到过好多次请求打了服务端也在处理但就是没输出的情况最后都是协议转换层流式响应不完整导致的。还有一种非常隐蔽的情况模型本身的行为差异。像DeepSeek的reasoner模式、Qwen的思考模式推理阶段可能很长而且流式返回时前半段都是思考内容或者干脆不发数据。Claude Code这边看到的是已发出请求、还没有有效token返回只能转圈。这不是故障是模型特性但体感上就是卡。最后是限流排队。第三方API通常限制了并发数有的套餐只允许1到5个并发请求。你开着多个会话或者一个会话里Claude Code同时发起多个工具调用超出部分就会排队。排队期间服务端不返回任何内容spinner就一直转着。这时候如果你能登录网关或服务商控制台看请求队列基本一目了然。2.3 本地层Node、终端、插件与权限进程网络和模型端点都正常的话就要看看本地这一层。Claude Code本地进程的依赖和运行环境出问题同样会卡。Node版本是第一关。Claude Code是基于Node.js的CLI工具官方要求Node 18以上。如果Node版本过老某些请求处理流程会异常表现可能是启动后一切正常但一发起请求就卡住甚至进程直接退出。升级Node版本后问题经常自动消失。终端环境是第二关。同样的Claude Code在系统终端比如macOS的Terminal、Linux的GNOME Terminal和VSCode集成终端里表现可能完全不同。集成终端里跑着插件扩展宿主进程如果你的插件版本和CLI版本不一致两边通信就可能出问题。我之前遇到过VSCode插件里spinner疯狂转圈、但系统终端里同样的指令秒回的情况后来把插件和CLI都升到同一版本才解决。权限确认是第三关。前面说过了Claude Code执行bash命令或修改文件之前默认要征求你的同意。在PTY环境不完整时这个确认提示可能不会正常显示出来结果就是它一直在等你输入你以为它在运算。处理方式很简单点一下终端窗口按回车或输入y试一次。还有一个很容易忽略的本地问题大目录扫描。Claude Code在启动会话时会对当前工作目录做上下文感知扫描文件、读取Git状态。如果你的项目里有巨大的node_modules、.git、dist目录扫描过程会让CPU和磁盘IO瞬间飙到很高界面看起来像冻住了spinner也不动。这时候它不是卡死是在疯狂干活等扫描完就会恢复。关于这类情况的根治方案我在第4章会展开。3. 一套标准的排查链路从Debug日志到最小复现3.1 第一步开Debug日志让Claude Code自己说话很多卡顿排查一开始就靠猜这是我踩过的最大坑。正确做法是先打开Debug日志让程序把每一件事记下来。启动时加上debug参数claude --debug --verbose然后它会开始记录会话级别的日志。日志文件默认在~/.claude/logs下按日期存放比如latest.jsonl。卡住的时候另开一个终端执行tail -f ~/.claude/logs/latest.jsonl看日志尾部到底在干什么。我常看的几个关键信息请求是否发出、HTTP状态码是什么、错误类型是connectivity_error还是rate_limit_error、以及最后一条日志停在哪一步。日志里如果有Request timed out那方向就是网络或端点如果是429、529那就是限流或服务过载如果日志停在等待用户输入那就回到权限确认那一类问题。这一步做完基本能定位到网络层、模型端点层、本地层中的某一层后面的排查就不用广撒网了。3.2 第二步curl直连验证端点健康日志里如果看到请求状态异常下一步用curl直连端点做探针测试。这种方式绕开Claude Code的封装直接看一条请求从发出到返回的真实耗时和状态码。官方端点的探针命令大概长这样curl -sS -o /dev/null -w connect:%{time_connect}s total:%{time_total}s code:%{http_code}\n \ https://api.anthropic.com/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:你的模型ID,max_tokens:64,messages:[{role:user,content:hi}]}如果你用的是第三方网关或兼容端点把URL换成你cc switch里配置的ANTHROPIC_BASE_URL对应的地址即可认证头按网关要求调整。怎么解读结果connect时间表示TCP握手的耗时如果超过1秒说明到端点的网络链路有问题total时间表示完整请求的耗时如果一条极简请求就回个hi都要超过10秒那问题大概率出在端点本身响应慢。code是HTTP状态码200是健康429、529、503都是服务端在说我忙/我限流了。这一步尤其适用于第三方API场景。我排查DeepSeek、Qwen接入卡顿时几乎每次都是curl一发就发现端点响应要几十秒或者干脆返回一个奇怪的网关错误码问题马上清晰了。3.3 第三步环境变量与配置核对curl发现端点本身有问题之前先确认Claude Code实际用的是不是你以为的那个端点。这个步骤看起来基础但却是翻车率最高的地方。需要重点核对的几个环境变量环境变量作用排查要点ANTHROPIC_BASE_URL请求发往的API地址确认是否被cc switch等工具改过ANTHROPIC_AUTH_TOKENBearer鉴权凭据和ANTHROPIC_API_KEY同时存在时优先级要注意ANTHROPIC_API_KEY账号api key检查是否有过期、带空格、换行符ANTHROPIC_MODEL请求的模型ID确认模型ID确实是服务端支持的名称HTTP_PROXY/HTTPS_PROXY出去的代理确认代理是否可达、是否拖慢请求NO_PROXY不走代理的地址白名单确认API域名是否需要加白名单查看当前生效的环境变量env | grep -i anthropic env | grep -i proxy这里有个真实场景值得说我用cc switch切换过多个模型服务之后偶尔会忘记某个profile里残留了旧的环境变量。你以为自己在请求GLM实际ANTHROPIC_BASE_URL还指向另一个网关那头的服务可能已经不在了或者模型名不匹配表现在界面上就是spinner转很久然后超时。所以每次切换之后先确认环境变量再开任务能省掉一大半莫名其妙的卡顿。另外还要看一眼项目的settings.json在.claude/settings.json和~/.claude/settings.json这里可能配置了默认模型、权限策略。如果权限策略把所有bash命令都配置成必须确认那每次执行命令都会等你按键配合第2.3节说的PTY显示问题很容易伪装成卡死。3.4 第四步最小化复现与对照实验前三步都没查出问题时最后用最小化复现来二分定位。原理很简单先把变量减到最少再逐步加回看哪一步开始卡。我通常这样操作建一个空目录里面什么都没有。启动Claude Code发一句hi看是否卡。如果不卡把任务换成让它读当前目录文件再看。逐级加上真实业务prompt、项目上下文、多个文件、多轮对话。每次变化都记录此刻spinner是否正常、日志尾部在做什么。这一步能把问题范围压缩得很小。如果空目录里一条消息都卡那就是基础配置或网络问题如果空目录不卡、一进真实项目就卡那就是上下文加载/权限/大目录扫描的问题如果单次对话不卡、并行开多个会话才卡那就是并发限流的问题。对照实验也很有用。保持同一段prompt不变依次切换不同模型端点记录各自耗时。我做过一次比较同一个要求分析这个项目的目录结构官方路径秒级响应某个第三方网关要等30秒才返回另一个网关请求直接挂起。结果一目了然——问题在端点侧不在Claude Code本身。4. 典型场景的针对性处理方案4.1 VSCode插件里疯狂转圈先回系统终端做对照VSCode插件是卡顿重灾区因为插件跑在扩展宿主进程里和终端渲染、插件版本、CLI版本都有关系。处理套路很简单先在系统终端里启动claude复现同样的操作。如果系统终端不卡、只有VSCode插件卡那就是插件侧的问题。我会按顺序做三件事检查CLI版本和插件版本claude --version看和VSCode市场里插件版本新旧是否差得很远。版本差太远时两边通信用的API可能不兼容。重置或重装插件这一步能清掉插件缓存里可能残留的旧端点和旧配置。在VSCode里检查是否有多个Claude Code进程在后台运行ps aux | grep claude。有一次我同时开了三个会话进程彼此争抢同一个第三方API的并发额度插件里每个会话都在转圈。另外一个我自己的经验VSCode集成终端和系统终端的PTY处理有差异权限确认提示在集成终端里偶尔不渲染导致假卡顿。如果你在插件里看到spinner停住不动先按一下回车、输个y确认一下是不是在等你批准命令再决定要不要重启。4.2 第三方模型接入时的转圈DeepSeek、Qwen、GLM场景把第三方模型接入Claude Code是很多人卡顿的主要场景。结合我实际接入DeepSeek、Qwen、GLM的经验最需要盯住三个环节。第一协议要选对。前面说了Claude Code是Anthropic原生协议DeepSeek多数接口是OpenAI兼容协议。如果中间网关只做了简单转发、没有把SSE流完整转换成Anthropic格式请求就会有去无回。建议选用明确支持Anthropic原生协议或做过协议转换的服务而不是随便拿一个OpenAI兼容地址填进去。第二模型ID要精确。cc switch切换时model字段要和服务端完全一致。比如某个网关把模型叫qwen-plus你就不能写成qwen-max叫deepseek-chat就不要写成deepseek-v3。很多卡顿不是网络问题是模型名不匹配服务端直接不响应或缓慢兜底。第三注意思考模式带来的长等待。DeepSeek R系列、Qwen带思考的版本会在推理阶段消耗大量时间流式响应里可能先出现一大段思考内容或者长时间无有效输出。Claude Code和它们交互时spinner转得久一点是正常的。想快一点可以切换到非思考模式的版本比如deepseek-chat、qwen-flash这类速度优先的模型。限流排队也别忘了。第三方套餐并发低多个会话同时跑后发的请求会排队。现象是每个会话都在转圈转着转着偶尔有一个突然出结果然后又继续卡。这种要么错峰使用要么升级并发额度要么减少同时开的会话数量。4.3 大仓库、长上下文场景下的假死在大型项目里用Claude Code启动时的目录扫描很容易造成假死。spinner一动不动、CPU占用100%、磁盘IO拉满你以为是程序挂了其实它在疯狂扫描。根治方式是建.claudeignore文件告诉它哪些目录不用管。比如node_modules .git dist build .coverage这个文件的语法类似.gitignore把大目录排除掉之后启动扫描会快很多卡顿感会明显下降。我接手一个大型前端项目时第一次没建这个文件启动会话光扫描就花了快一分钟建完ignore之后基本秒进。另一个长上下文问题是塞太多东西。如果你在会话里读了好几个大文件、多次调/memory、或者让它自己翻了很多文件上下文窗口会迅速膨胀。Claude Code每次回复都要把所有上下文重新编码发送内容越多中转时间越长spinner转得就越久。这时候解决方案是减少上下文用/compact压缩会话、裁剪不必要的文件而不是一边嫌慢一边继续往会话里塞文件。如果已经卡在了一次工具执行上比如一个bash命令跑太久可以先按一下CtrlC中断当前工具调用让进程回到对话状态再用/compact整理会话内容继续。不要直接关掉整个终端那样会丢掉当前会话的上下文。4.4 升级版本与首次安装后容易踩的卡顿Claude Code的升级是claude update在线拉新版本。升级本身一般很顺但升级完第一次启动会做依赖检查和组件更新后台可能还在跑npm安装。这时候你看到spinner转个半分钟到一分钟多半是它在准备环境不是死机。我给个建议升级后第一次启动耐心等看~/.claude/logs里有没有更新记录再决定要不要干预。首次安装时也有个常见坑。如果你是behind网络或公司内部环境npm镜像源可能慢安装anthropic-ai/claude-code包装半天没反应。可以先检查npm registry配置npm config get registry如果指向了内部或镜像源确认它是可用的。这个和卡顿排查关系不大但很多人的Claude Code一开始就卡其实是安装阶段就埋了雷。热词里有句提示很多人遇到过note: claude code might not be available in your country. check supported co...。这个提示是客户端在检查官方API可达性/支持范围时输出的一行信息。遇到它说明你当前环境不适合直接连官方端点。这时候与其反复重试官方地址不如走你本地/区域网络可以稳定访问的第三方兼容端点通过配置ANTHROPIC_BASE_URL等方式让Claude Code跑起来。需要说明的是我不打算在这里展开任何网络工具使用因为这超出技术排查的范畴但换一个可达的模型端点本身就是常规的API配置思路也是这类提示出现时最务实的处理方向。5. 排查Claude Code卡顿这几年的个人体会写到最后分享几个我实际踩坑后沉淀下来的习惯。第一个习惯是不要在卡顿瞬间急着CtrlC。按下CtrlC之前先花十秒记录现场spinner还转不转、界面有没有报错、日志最后一条是什么、当前工具是bash还是文件操作。没有现场信息后面排查全靠猜往往查了半天发现是误杀——本来再等十秒就出结果了。第二个习惯是五分钟排查法。第一分钟看状态标识判断是等待类还是死锁类第二分钟看日志尾部第三分钟用curl探针测端点第四分钟做一次最小化复现第五分钟整理排查结论。这五步做完大多数问题都能落到网络层、模型端点层、本地层中的某一层。第三个习惯是接受慢和卡的差别。Claude Code在模型端点处理慢、上下文大、第三方限流时它本来就会慢。慢不是故障卡才是。如果每次都是转圈几分钟然后出结果那优化方向是换快一点的模型端点、精简上下文如果转圈到最后直接超时或报错那才是真正需要排查的卡顿。现在我自己遇到spinner转圈第一反应已经不再是焦虑而是按上面这套流程走一遍。多数时候五分钟定位十分钟解决。希望这篇文章也能让你在下次看到spinner时心里有底手上有方案。
说实话用Claude Code最让人血压上升的画面就是那个spinner一直在转转十秒、转三十秒、转一分钟屏幕上一行字都没多。不管你是刚装好claude code的新手还是已经在VSCode里配好插件的老手遇到这种转圈卡住都容易心态爆炸。更麻烦的是很多人一看到spinner就不管三七二十一按CtrlC结果白白打断了一个已经运行到一半的完整任务。我在Mac、Ubuntu、Windows上都跑过Claude Code也把DeepSeek、Qwen、GLM这些第三方模型通过cc switch接进去用过。踩了足够多的坑之后我总结出一个核心结论大部分卡住其实并不是程序死掉而是它正在等待某个东西——等模型回复、等命令执行完、等你按一下确认键、等网络重试。这篇文章我干脆把spinner状态标识是什么、真实卡顿根源有哪些、以及一套从日志到复现的完整排查方案一次讲清楚希望能帮你少走我这几个月的弯路。1. 先分清Spinner在转可能是在等它而不是等死1.1 Spinner背后到底在等什么四类最常见状态Claude Code是一个TUI程序它没有图形界面那种明晃晃的加载条只有一个活动指示器就是大家说的spinner加上当前状态文字。不同版本样式可能有差异但逻辑是一样的这个转圈图标只表示有一个事件在等待中至于是什么事件在等才是问题的关键。我平时把它归纳成四类最常见状态状态类型表象一般时长需要你干预吗等待LLM响应spinner Working之类的状态文字没有新增输出几秒到几十秒长任务可能更久不需要等首token出现执行工具调用spinner一直在转但界面可能滚动出命令/文件操作信息取决于命令本身如果bash命令跑很久要看命令是否正常权限确认看似卡住其实光标停在提示处等y/Enter或选择直到你操作需要回复y、n或者提供路径网络重试转一会儿报错然后自己再转循环每次退避几秒到几十秒观察状态码决定是否终止先说等LLM响应。每次对话Claude Code都会把上下文编码之后发到模型端点然后等待流式返回。模型进入长思考模式或者输出长代码块时第一块内容可能来得比较慢这段时间spinner会一直转。我见过最夸张的一次是让Claude Code重写一个模块它思考了差不多一分半钟才吐出第一行字。如果你在这时候CtrlC等于把一次完整的规划过程打断了重来之后它又要从头想反而更慢。第二种是工具调用。Claude Code会实际执行bash命令、读写文件。比如让它跑npm install或者在一个几百MB的仓库里执行git status命令本身就要几十秒spinner自然会转着等命令返回。这种状态下界面往往不是完全静止的你可能会看到命令输出、文件路径在滚动那就证明它没死只是活干得慢。第三种特别容易被误判。Claude Code在执行有副作用的操作前会询问你比如允许运行命令吗的确认。在正常的终端里提示会直接显示出来但在某些终端环境比如VSCode集成终端和系统终端混用或者用了特殊shell配置里提示可能没有正常渲染看起来就是spinner停在那里不动。这时候你只要试着按一下回车、输入y多半就恢复了。第四种是网络重试。Claude Code在拿到429、529、503这类状态码时不会立刻放弃而是会退避重试。转一下、报个错、再转一下节奏感很强。如果你看到这种周期性转圈报错的形态那基本可以锁定是网络或模型端点的问题而不是本地进程卡死。1.2 假卡顿与真卡顿的边界判断假卡顿和真卡顿我最常用的一个笨办法是看spinner的动画本身。spinner还在匀速转动说明主进程的渲染循环还活着程序大概率在等待某个外部事件要是spinner的动画都停了、光标也没了整个界面完全凝固那才是真的死掉或者进入死循环。接下来的判断要看输出节奏。观察十到三十秒如果过程中出现过任何新的一行输出、状态文字变化、或者错误提示那它只是在慢速工作不是卡死。如果三十秒内什么变化都没有也没日志再考虑中断。还有一个小技巧是看日志尾部。Claude Code的日志文件路径在~/.claude/logs下卡住的时候开另一个终端执行tail -f ~/.claude/logs/latest.jsonl如果日志还在不断追加内容说明内部流程还在推进如果最后一条日志是几十秒前的就说明流程真的卡在了某一环。这一步直接把猜变成了看是我排查时最先用的手段。2. 卡顿根源分三层网络、模型端点、本地进程2.1 网络层API端点可达性与响应超时Claude Code本身不跑大模型推理它本质上是一个把所有操作包装成API请求的客户端。换句话说spinner每转一圈背后可能都对应着一个HTTPS请求在途中。网络层出问题是最常见的卡顿来源。常见的网络层问题有这么几类一是成本最低的端点可达性。你配的API服务不管官方还是第三方网关在当前网络下连都连不上TCP握手就卡住spinner会一直等到超时。判断方法就是用curl打个请求试试如果连接超时那什么都别说了网络不通。二是延迟过高。连接能通但每次请求要好几秒才建立连接传输再慢一点整个请求下来十几秒体感上就是转圈转得让人抓狂。这种一般是链路问题也可能是你终端里配置了出口代理造成的。这里特别提醒一句如果你的终端环境变量里有HTTP_PROXY和HTTPS_PROXYClaude Code是会读的。公司网络里的出口代理、本地调试用的代理只要不稳定所有API请求都会被拖慢表现就是spinner空转很长时间然后超时。三是请求被静默丢弃。有些网络环境会断开长时间空闲的TCP连接Claude Code如果长时间没有对话再发起请求连接可能已经失效需要重新握手这时候卡顿几秒甚至十几秒都很正常。网络层的验证方式很简单后面第3章会给完整的curl命令模板这里先说结论如果curl直连一条消息请求能在1到3秒内返回网络层基本没问题要是连接就花超过1秒那就先从网络环境开始排查。2.2 模型端点层官方账号、第三方API与限流排队模型端点层的问题是Claude Code卡顿里最有迷惑性的。因为表面上看网络是好的、进程是活的但请求打过去之后模型服务端就是不吐数据。先说官方直连的情况。用Anthropic官方账号登录后默认走api.anthropic.com模型是账号对应的订阅模型。官方端点一般很稳定但订阅账号有配额和并发限制一旦触发限流你会看到429或者529。Claude Code遇到这些状态码会退避重试表现为转圈、报错、再转圈的循环。如果你在多个终端同时开好几个会话很容易撞上并发限制。再说第三方接入这是现在多数人在用的场景。通过cc switch这类工具接入DeepSeek、Qwen、GLM本质上只是改了三个东西ANTHROPIC_BASE_URL请求发到哪里、ANTHROPIC_AUTH_TOKEN用什么凭据、ANTHROPIC_MODEL请求什么模型。这三件套只要有一个不对请求就可能挂起。这里有个大坑DeepSeek和很多国产模型服务本身是OpenAI兼容协议而Claude Code用的是Anthropic原生协议。中间必须有一个网关或者转换层把两种协议互相翻译。如果这个转换层对SSE流式支持不完整请求发过去之后服务端迟迟不返回完整的流结束标记Claude Code就会永远等下去spinner转到天荒地老最后超时。我在接入第三方模型时遇到过好多次请求打了服务端也在处理但就是没输出的情况最后都是协议转换层流式响应不完整导致的。还有一种非常隐蔽的情况模型本身的行为差异。像DeepSeek的reasoner模式、Qwen的思考模式推理阶段可能很长而且流式返回时前半段都是思考内容或者干脆不发数据。Claude Code这边看到的是已发出请求、还没有有效token返回只能转圈。这不是故障是模型特性但体感上就是卡。最后是限流排队。第三方API通常限制了并发数有的套餐只允许1到5个并发请求。你开着多个会话或者一个会话里Claude Code同时发起多个工具调用超出部分就会排队。排队期间服务端不返回任何内容spinner就一直转着。这时候如果你能登录网关或服务商控制台看请求队列基本一目了然。2.3 本地层Node、终端、插件与权限进程网络和模型端点都正常的话就要看看本地这一层。Claude Code本地进程的依赖和运行环境出问题同样会卡。Node版本是第一关。Claude Code是基于Node.js的CLI工具官方要求Node 18以上。如果Node版本过老某些请求处理流程会异常表现可能是启动后一切正常但一发起请求就卡住甚至进程直接退出。升级Node版本后问题经常自动消失。终端环境是第二关。同样的Claude Code在系统终端比如macOS的Terminal、Linux的GNOME Terminal和VSCode集成终端里表现可能完全不同。集成终端里跑着插件扩展宿主进程如果你的插件版本和CLI版本不一致两边通信就可能出问题。我之前遇到过VSCode插件里spinner疯狂转圈、但系统终端里同样的指令秒回的情况后来把插件和CLI都升到同一版本才解决。权限确认是第三关。前面说过了Claude Code执行bash命令或修改文件之前默认要征求你的同意。在PTY环境不完整时这个确认提示可能不会正常显示出来结果就是它一直在等你输入你以为它在运算。处理方式很简单点一下终端窗口按回车或输入y试一次。还有一个很容易忽略的本地问题大目录扫描。Claude Code在启动会话时会对当前工作目录做上下文感知扫描文件、读取Git状态。如果你的项目里有巨大的node_modules、.git、dist目录扫描过程会让CPU和磁盘IO瞬间飙到很高界面看起来像冻住了spinner也不动。这时候它不是卡死是在疯狂干活等扫描完就会恢复。关于这类情况的根治方案我在第4章会展开。3. 一套标准的排查链路从Debug日志到最小复现3.1 第一步开Debug日志让Claude Code自己说话很多卡顿排查一开始就靠猜这是我踩过的最大坑。正确做法是先打开Debug日志让程序把每一件事记下来。启动时加上debug参数claude --debug --verbose然后它会开始记录会话级别的日志。日志文件默认在~/.claude/logs下按日期存放比如latest.jsonl。卡住的时候另开一个终端执行tail -f ~/.claude/logs/latest.jsonl看日志尾部到底在干什么。我常看的几个关键信息请求是否发出、HTTP状态码是什么、错误类型是connectivity_error还是rate_limit_error、以及最后一条日志停在哪一步。日志里如果有Request timed out那方向就是网络或端点如果是429、529那就是限流或服务过载如果日志停在等待用户输入那就回到权限确认那一类问题。这一步做完基本能定位到网络层、模型端点层、本地层中的某一层后面的排查就不用广撒网了。3.2 第二步curl直连验证端点健康日志里如果看到请求状态异常下一步用curl直连端点做探针测试。这种方式绕开Claude Code的封装直接看一条请求从发出到返回的真实耗时和状态码。官方端点的探针命令大概长这样curl -sS -o /dev/null -w connect:%{time_connect}s total:%{time_total}s code:%{http_code}\n \ https://api.anthropic.com/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:你的模型ID,max_tokens:64,messages:[{role:user,content:hi}]}如果你用的是第三方网关或兼容端点把URL换成你cc switch里配置的ANTHROPIC_BASE_URL对应的地址即可认证头按网关要求调整。怎么解读结果connect时间表示TCP握手的耗时如果超过1秒说明到端点的网络链路有问题total时间表示完整请求的耗时如果一条极简请求就回个hi都要超过10秒那问题大概率出在端点本身响应慢。code是HTTP状态码200是健康429、529、503都是服务端在说我忙/我限流了。这一步尤其适用于第三方API场景。我排查DeepSeek、Qwen接入卡顿时几乎每次都是curl一发就发现端点响应要几十秒或者干脆返回一个奇怪的网关错误码问题马上清晰了。3.3 第三步环境变量与配置核对curl发现端点本身有问题之前先确认Claude Code实际用的是不是你以为的那个端点。这个步骤看起来基础但却是翻车率最高的地方。需要重点核对的几个环境变量环境变量作用排查要点ANTHROPIC_BASE_URL请求发往的API地址确认是否被cc switch等工具改过ANTHROPIC_AUTH_TOKENBearer鉴权凭据和ANTHROPIC_API_KEY同时存在时优先级要注意ANTHROPIC_API_KEY账号api key检查是否有过期、带空格、换行符ANTHROPIC_MODEL请求的模型ID确认模型ID确实是服务端支持的名称HTTP_PROXY/HTTPS_PROXY出去的代理确认代理是否可达、是否拖慢请求NO_PROXY不走代理的地址白名单确认API域名是否需要加白名单查看当前生效的环境变量env | grep -i anthropic env | grep -i proxy这里有个真实场景值得说我用cc switch切换过多个模型服务之后偶尔会忘记某个profile里残留了旧的环境变量。你以为自己在请求GLM实际ANTHROPIC_BASE_URL还指向另一个网关那头的服务可能已经不在了或者模型名不匹配表现在界面上就是spinner转很久然后超时。所以每次切换之后先确认环境变量再开任务能省掉一大半莫名其妙的卡顿。另外还要看一眼项目的settings.json在.claude/settings.json和~/.claude/settings.json这里可能配置了默认模型、权限策略。如果权限策略把所有bash命令都配置成必须确认那每次执行命令都会等你按键配合第2.3节说的PTY显示问题很容易伪装成卡死。3.4 第四步最小化复现与对照实验前三步都没查出问题时最后用最小化复现来二分定位。原理很简单先把变量减到最少再逐步加回看哪一步开始卡。我通常这样操作建一个空目录里面什么都没有。启动Claude Code发一句hi看是否卡。如果不卡把任务换成让它读当前目录文件再看。逐级加上真实业务prompt、项目上下文、多个文件、多轮对话。每次变化都记录此刻spinner是否正常、日志尾部在做什么。这一步能把问题范围压缩得很小。如果空目录里一条消息都卡那就是基础配置或网络问题如果空目录不卡、一进真实项目就卡那就是上下文加载/权限/大目录扫描的问题如果单次对话不卡、并行开多个会话才卡那就是并发限流的问题。对照实验也很有用。保持同一段prompt不变依次切换不同模型端点记录各自耗时。我做过一次比较同一个要求分析这个项目的目录结构官方路径秒级响应某个第三方网关要等30秒才返回另一个网关请求直接挂起。结果一目了然——问题在端点侧不在Claude Code本身。4. 典型场景的针对性处理方案4.1 VSCode插件里疯狂转圈先回系统终端做对照VSCode插件是卡顿重灾区因为插件跑在扩展宿主进程里和终端渲染、插件版本、CLI版本都有关系。处理套路很简单先在系统终端里启动claude复现同样的操作。如果系统终端不卡、只有VSCode插件卡那就是插件侧的问题。我会按顺序做三件事检查CLI版本和插件版本claude --version看和VSCode市场里插件版本新旧是否差得很远。版本差太远时两边通信用的API可能不兼容。重置或重装插件这一步能清掉插件缓存里可能残留的旧端点和旧配置。在VSCode里检查是否有多个Claude Code进程在后台运行ps aux | grep claude。有一次我同时开了三个会话进程彼此争抢同一个第三方API的并发额度插件里每个会话都在转圈。另外一个我自己的经验VSCode集成终端和系统终端的PTY处理有差异权限确认提示在集成终端里偶尔不渲染导致假卡顿。如果你在插件里看到spinner停住不动先按一下回车、输个y确认一下是不是在等你批准命令再决定要不要重启。4.2 第三方模型接入时的转圈DeepSeek、Qwen、GLM场景把第三方模型接入Claude Code是很多人卡顿的主要场景。结合我实际接入DeepSeek、Qwen、GLM的经验最需要盯住三个环节。第一协议要选对。前面说了Claude Code是Anthropic原生协议DeepSeek多数接口是OpenAI兼容协议。如果中间网关只做了简单转发、没有把SSE流完整转换成Anthropic格式请求就会有去无回。建议选用明确支持Anthropic原生协议或做过协议转换的服务而不是随便拿一个OpenAI兼容地址填进去。第二模型ID要精确。cc switch切换时model字段要和服务端完全一致。比如某个网关把模型叫qwen-plus你就不能写成qwen-max叫deepseek-chat就不要写成deepseek-v3。很多卡顿不是网络问题是模型名不匹配服务端直接不响应或缓慢兜底。第三注意思考模式带来的长等待。DeepSeek R系列、Qwen带思考的版本会在推理阶段消耗大量时间流式响应里可能先出现一大段思考内容或者长时间无有效输出。Claude Code和它们交互时spinner转得久一点是正常的。想快一点可以切换到非思考模式的版本比如deepseek-chat、qwen-flash这类速度优先的模型。限流排队也别忘了。第三方套餐并发低多个会话同时跑后发的请求会排队。现象是每个会话都在转圈转着转着偶尔有一个突然出结果然后又继续卡。这种要么错峰使用要么升级并发额度要么减少同时开的会话数量。4.3 大仓库、长上下文场景下的假死在大型项目里用Claude Code启动时的目录扫描很容易造成假死。spinner一动不动、CPU占用100%、磁盘IO拉满你以为是程序挂了其实它在疯狂扫描。根治方式是建.claudeignore文件告诉它哪些目录不用管。比如node_modules .git dist build .coverage这个文件的语法类似.gitignore把大目录排除掉之后启动扫描会快很多卡顿感会明显下降。我接手一个大型前端项目时第一次没建这个文件启动会话光扫描就花了快一分钟建完ignore之后基本秒进。另一个长上下文问题是塞太多东西。如果你在会话里读了好几个大文件、多次调/memory、或者让它自己翻了很多文件上下文窗口会迅速膨胀。Claude Code每次回复都要把所有上下文重新编码发送内容越多中转时间越长spinner转得就越久。这时候解决方案是减少上下文用/compact压缩会话、裁剪不必要的文件而不是一边嫌慢一边继续往会话里塞文件。如果已经卡在了一次工具执行上比如一个bash命令跑太久可以先按一下CtrlC中断当前工具调用让进程回到对话状态再用/compact整理会话内容继续。不要直接关掉整个终端那样会丢掉当前会话的上下文。4.4 升级版本与首次安装后容易踩的卡顿Claude Code的升级是claude update在线拉新版本。升级本身一般很顺但升级完第一次启动会做依赖检查和组件更新后台可能还在跑npm安装。这时候你看到spinner转个半分钟到一分钟多半是它在准备环境不是死机。我给个建议升级后第一次启动耐心等看~/.claude/logs里有没有更新记录再决定要不要干预。首次安装时也有个常见坑。如果你是behind网络或公司内部环境npm镜像源可能慢安装anthropic-ai/claude-code包装半天没反应。可以先检查npm registry配置npm config get registry如果指向了内部或镜像源确认它是可用的。这个和卡顿排查关系不大但很多人的Claude Code一开始就卡其实是安装阶段就埋了雷。热词里有句提示很多人遇到过note: claude code might not be available in your country. check supported co...。这个提示是客户端在检查官方API可达性/支持范围时输出的一行信息。遇到它说明你当前环境不适合直接连官方端点。这时候与其反复重试官方地址不如走你本地/区域网络可以稳定访问的第三方兼容端点通过配置ANTHROPIC_BASE_URL等方式让Claude Code跑起来。需要说明的是我不打算在这里展开任何网络工具使用因为这超出技术排查的范畴但换一个可达的模型端点本身就是常规的API配置思路也是这类提示出现时最务实的处理方向。5. 排查Claude Code卡顿这几年的个人体会写到最后分享几个我实际踩坑后沉淀下来的习惯。第一个习惯是不要在卡顿瞬间急着CtrlC。按下CtrlC之前先花十秒记录现场spinner还转不转、界面有没有报错、日志最后一条是什么、当前工具是bash还是文件操作。没有现场信息后面排查全靠猜往往查了半天发现是误杀——本来再等十秒就出结果了。第二个习惯是五分钟排查法。第一分钟看状态标识判断是等待类还是死锁类第二分钟看日志尾部第三分钟用curl探针测端点第四分钟做一次最小化复现第五分钟整理排查结论。这五步做完大多数问题都能落到网络层、模型端点层、本地层中的某一层。第三个习惯是接受慢和卡的差别。Claude Code在模型端点处理慢、上下文大、第三方限流时它本来就会慢。慢不是故障卡才是。如果每次都是转圈几分钟然后出结果那优化方向是换快一点的模型端点、精简上下文如果转圈到最后直接超时或报错那才是真正需要排查的卡顿。现在我自己遇到spinner转圈第一反应已经不再是焦虑而是按上面这套流程走一遍。多数时候五分钟定位十分钟解决。希望这篇文章也能让你在下次看到spinner时心里有底手上有方案。
