最近好多朋友私信问我同一个问题Claude Code 用着用着终端就卡住了那个转圈的 spinner 一直在原地打转等十几秒甚至一分钟都不出结果。这个现象太典型了我在自己的机器上也踩过不少次坑。Claude Code 本质上是个交互式 AI 编程代理它把“读代码、改文件、跑命令、看结果”拆成一串带状态的异步任务spinner 其实就是它在汇报“我正在干活”。但具体卡在哪一环、为什么卡大多数人根本没认真看过一眼。这篇文章不聊虚的就从 spinner 状态标识入手把卡顿根源、排查路径和可落地的配置方案一次性讲清楚。不管你是刚装好 Claude Code 不知道怎么下手的还是已经卡到想砸终端的都能按图索骥找到问题。1. 先把 Spinner 看明白它不是死机是任务状态的风向标1.1 Spinner 停在哪问题大概率就出在哪很多人一看到终端里长时间转圈第一反应是“又死了”抬手就是 CtrlC 杀掉进程。其实多数情况下 Claude Code 没死只是被某个环节拖住了。spinner 的本质是“当前任务状态的可视化”它对应一条完整的任务循环模型思考、调用工具、读取结果、继续生成、渲染输出。我建议你先别急着打断而是盯住 spinner 停住的位置。如果光标的 spinner 停在“等待模型返回”的阶段那多半是 API 响应慢或者上下文太长如果停在某个工具执行之后比如刚跑完一条 git 命令或者刚读完一个大文件那问题大概率出在工具调用本身如果是输出代码块的时候逐字符地卡那就是终端渲染在拖后腿。判断这一步比任何排查工具都管用因为后续的所有手段都建立在“你大概知道卡在哪一段”的基础上。1.2 不同环节卡住的特征与判断方法我做了个简单的对照方便你一眼定位卡住位置典型特征最可疑的环节刚输入指令后立刻转圈几乎没有输出纯等待模型 API 响应、鉴权、网络链路工具调用后反复转圈终端出现命令输出但不继续shell 命令挂起、LSP、git 操作输出大段代码时卡文字逐字出现又停顿终端渲染压力、ANSI 转义序列会话越长越卡后面每条消息都慢上下文膨胀、context 接近上限多开会话后普遍卡所有任务整体变慢本地内存不足、日志文件膨胀有了这个初步印象再往下排查就不会像无头苍蝇。我自己习惯的做法是先不打断等 30 秒到 1 分钟同时打开另一个终端窗口去看日志和进程状态如果连日志都在更新但输出迟迟不来说明是模型侧或上下文的问题如果日志完全没有新内容那就要检查是不是某个外部进程把 Claude Code 卡死了。1.3 判断“真死”还是“假死”的两个实用技巧第一个技巧是看网络流量。在 macOS 上用nettop过滤 claude 进程Windows 上打开资源监视器看网络活动如果请求还在持续发送说明只是响应慢进程是活的。第二个技巧是直接开一个最小请求去测 API——比如用 curl 单独发一次消息看模型多久能返回结果。如果 API 本身要 10 秒才回那终端里转圈 10 秒是正常现象不需要杀进程反过来API 已经返回了但终端还在转那就是下游渲染或工具调用的问题。2. 卡顿根源拆解模型、上下文、终端一个都跑不了2.1 模型侧的隐形瓶颈限流、排队与首字延迟Claude Code 背后调用的模型服务是共享资源官方 API 在高峰期出现排队和限流非常正常。你感觉到的“卡”很多时候其实是 API 返回首字的时间TTFT变高了。TTFT 受两个因素影响最大一是当前服务的负载二是你这次请求携带的上下文长度。打个比方你点外卖的时候商家页面一直显示“制作中”可能是店里单太多也可能是你这份订单配菜特别复杂。Claude Code 也一样如果你在同一个会话里积累了大量历史消息每次新请求都会把全部上下文重新发给模型做 prefill这部分的计算量是随 token 数线性增长的。上下文有 2 万 token 和 20 万 token首字响应时间差出 10 倍以上都不稀奇。所以我一直强调spinner 持续转很多时候不是你运气差而是你让模型每次都在“复习”一整本长篇小说。2.2 上下文膨胀是最大的隐性杀手很多人有个习惯一个会话从早用到晚什么东西都在里面聊。代码文件整段贴进去、报错信息复制进来、工具输出不断追加不知不觉上下文就顶到了几十万 token。这时候每一次交互模型都要把几十万 token 重新处理一遍卡顿就成了必然结果。我自己踩过一次很深的坑让 Claude Code 在一个会话里反复修改同一个大型配置文件期间我又贴了三四次完整文件内容最后每个问题都要等 40 秒才回。后来用/context一看上下文占用已经超过了模型窗口的一半等于是让模型每次回答前都先读完一本厚书。从那以后我养成了习惯超过 50% 占用就果断/compact或者/clear卡顿立刻缓解。2.3 本地环境终端渲染、插件叠加与资源消耗Claude Code 的终端交互体验依赖所在终端的渲染能力。Windows 自带的经典控制台窗口对 ANSI 转义序列的支持一般遇到大段彩色 diff 输出容易出现逐字符渲染、光标闪动、输入延迟。我强烈建议 Windows 用户换 Windows Terminal实测下来渲染压力至少减半。除此之外如果你用的是 VS Code 集成终端又装了语言服务插件、代码补全插件、Git 增强插件它们会跟你输入时的键盘事件和输出渲染抢资源。特别是某些插件会在你回车之后立即触发代码检查和格式化跟 Claude Code 的输出混在一起观感上就像“整个界面都卡了”。这种问题其实不是你网络慢而是本地多个进程在打架。2.4 外部命令挂起偷偷卡住 spinner 的“卧底”Claude Code 在执行任务时会调用终端命令来完成工具操作比如读目录、跑测试、查 git 状态。这些命令一旦挂起spinner 就会一直转。最常见的挂起点有几种在超大 Git 仓库里跑 status 或 diff、某个命令等待用户输入却没接受到输入流、脚本里的网络请求长期无响应、或者命令本身有交互式提示符。遇到这种情况你会发现 spinner 卡在一个工具调用的结果输出之后后面再也没有新动作。这时候需要去查 Claude Code 的日志它会记录到底执行了哪条命令、命令的退出状态和耗时。搞清楚是哪条命令在拖时间再针对性地优化而不是一味地重试或干脆不用这个功能。3. 排查方案从现象到根因的四步实操路径3.1 让日志开口说话打开调试模式并定位日志文件Claude Code 的日志目录一般在~/.claude/logs下macOS 的另一种常见位置是~/.local/share/claude/logsWindows 则在%USERPROFILE%\.claude\logs。不确定的话可以启动时带变量让日志输出到终端。我常用的一个办法是开一个额外终端窗口用 tail 实时跟踪日志# macOS / Linux tail -f ~/.claude/logs/*.log # Windows Terminal / PowerShell Get-Content $env:USERPROFILE\.claude\logs\* -Wait同时用调试模式启动 Claude Codeclaude --debug开启之后终端会打印更详细的请求发送记录、工具调用记录、耗时数据。不信你可以下一次卡住时切到另一个终端看日志通常都能看到某一条工具调用的时间戳明显异常或者某个 API 请求的耗时超长。3.2 用最小请求隔离 API 层的问题当你怀疑是模型 API 的问题时最快的验证办法是绕过 Claude Code 直接测一次 API。先确认你的密钥和端点配置然后用 curl 发一个尽量小的请求记录从发出到收到第一个字符的时间curl -N -X POST 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: claude-3-7-sonnet-latest, max_tokens: 64, messages: [{role: user, content: ping}] }如果这个最小请求都等了 10 秒以上说明服务侧或者你当前网络环境到 API 端点的链路本身就不稳Claude Code 卡住顺手就能解释了。反过来如果最小请求秒回但在 Claude Code 里依然卡问题就堆在你当前会话的上下文规模和本地环境上。3.3 检查上下文占用与会话体积在卡住或刚启动的时候直接在会话里输入/context它会展示当前上下文的使用比例和 token 分布。输入/status可以查看当前账户状态、模型信息和 API 连通状态。这两个命令是排查卡顿最该先用的组合。我建议把/status的输出当作“体温计”当它显示 API 连接正常但 context 占比已经 70% 以上的时候不用犹豫立刻/compact。压缩历史记录能显著减小后续每次请求的 payloadspinner 转圈时间会肉眼可见地缩短。如果你正在做一个跨多个文件的大改动索性就在完成一个阶段后/clear开新会话让模型轻装上阵。3.4 最小复现实验用二分法定位触发条件如果日志、API、上下文都查过问题依然无法解释那就做最小复现。把当前任务拆到一个全新的空会话里只给它一个极小的指令、只涉及一个文件看还会不会卡。如果小任务不卡那就是原会话的累积信息量太大如果小任务也卡再看是不是特定目录、特定命令或者特定输入触发的。我遇到过一次非常奇怪的情况只要让 Claude Code 读取某个固定目录spinner 就会卡 20 秒但其他目录完全正常。最后查出来是那个目录里挂载了一个网络磁盘每次读取目录都要等网络超时。这种问题靠“全局重装”是解决不了的必须用最小复现把它逼出来。4. 针对性解决方案与实践配置4.1 管好上下文从源头降低每次请求的耗时上下文管理是解决 Claude Code 卡顿最直接的手段。我自己当前的标准操作是任务开始前用CLAUDE.md固化项目约定避免每轮对话重复描述项目背景需要贴代码时不整段粘贴而是先用 grep 把关键行筛出来再贴任务每完成一个小里程碑就/clear一次让会话始终维持在“轻量”状态。# 查看当前上下文占用在会话中输入斜杠命令即可 /context # 压缩历史保留核心上下文 /compact # 彻底清空当前会话 /clear压缩之后模型的“记忆”会丢掉一些细节如果发现它忘了前面的约定把关键约定补进CLAUDE.md即可。这不是妥协而是提高效率的正确姿势——让模型每次只聚焦当前最重要的信息响应速度才能稳定。4.2 调整环境变量与重试策略Claude Code 支持通过环境变量控制一些运行参数。比如设置最大输出 token、超时时间、重试次数等。在 bash 或 PowerShell 里导出环境变量后再启动可以避免某些请求无限制地等下去。# 限制单次最大输出 token避免生成过长内容导致终端长时间转圈 export CLAUDE_CODE_MAX_OUTPUT_TOKENS4096 # 通过环境变量设置 API 端点第三方兼容端点时常用 export ANTHROPIC_BASE_URLhttps://your-endpoint.example.com export ANTHROPIC_API_KEYyour-api-key对于第三方模型或本地模型重点要关注并发和超时参数。有些兼容服务本身吞吐很低如果你还开了多个会话同时跑互相排队会让每个任务都显得“卡死”。我一般只在单个会话里跑重活其他窗口只读代码。4.3 给终端减负换终端、降插件、开缓冲终端渲染是最容易被忽略的卡顿源。Windows 上优先换 Windows Terminal关掉旧终端的快速编辑模式macOS 上用 iTerm2 或保持终端应用为最新版本Linux 桌面环境下实测 Ghostty 和 kitty 的渲染性能都比较好。同时把终端缓冲区加大这样大量日志输出时不会触发频繁滚动重绘。如果你在 VS Code 里用 Claude Code建议做个对比实验把那些非必要的扩展临时禁用特别是自动保存、自动格式化、GitLens 这类高频监听插件。很多时候你感觉是 Claude Code 卡其实是编辑器本身在背后疯狂做增量索引和代码检查把 CPU 占满了。4.4 接入第三方模型与本地模型时的特殊卡点热词里很多人提到用 cc-switch 接 DeepSeek、Qwen、GLM或者用 LM Studio 跑本地模型。这类方案能跑通但卡点会更隐蔽。第三方兼容端点通常吞吐和限流策略跟官方不一致请求量稍大就会被限速。本地模型则完全受显卡算力约束模型量化精度太低、上下文窗口设得太大、显存不够触发 CPU offload都会让 token 生成速度掉到每秒几条。接入后的第一件事不是干大活而是先测速。给第三方端点发一个 100 token 的小请求记录总耗时给本地模型也发同样的小请求对比官方 API。如果你算下来每秒生成速度连 20 token 都不到那后续任何复杂任务都会很卡。正确的策略是把任务拆小块减少单次 token 生成量同时把上下文窗口调小别让本地模型不断把旧内容搬进显存。5. 高频卡顿场景速查表与隐蔽坑5.1 先检索这个表再决定要不要重装下面这张对照表是我从实际运维自己环境的过程中总结出来的。遇到卡顿先花 30 秒对照一下比直接重装工具高效得多。现象最可能的原因处理办法所有请求都非常慢API 侧高峰期或网络链路差看日志、测最小请求、换时段会话越长越慢上下文膨胀/context查看/compact或/clear卡在某个工具调用后外部命令挂起在日志里找对应命令并排查输出大段代码时卡终端渲染压力大换 Windows Terminal、关插件刚启动就转圈很久配置加载或首次初始化检查 CLAUDE.md、hooks 和日志多开会话后整体变慢本地资源耗尽关掉不用的终端和编辑器插件报权限或订阅错误密钥无效或组织限制检查ANTHROPIC_API_KEY与订阅状态接本地模型后极慢推理速度太低降低量化级别、缩小上下文、减少并发5.2 几个容易被忽略的隐蔽坑我额外整理几个常规文档里不会写的坑这些我都是真金白银踩出来的。第一个是日志文件膨胀。Claude Code 跑久了日志文件可能涨到几个 GB日志写入和终端监听都会拖累整体性能。定期清空~/.claude/logs下的旧日志很多“越用越卡”的问题直接消失。第二个是输入法冲突。Windows 上使用中文输入法时终端里的键盘事件偶尔会被 IME 拦截导致你感觉“输入没反应”。如果你发现自己敲命令时明显延迟但 spinner 早就不转了留意一下系统托盘里的输入法状态。第三个是时钟不同步。API 通信依赖 TLS 证书和认证签名如果本机时间偏差过大握手阶段会反复失败重试表象就是每次请求前先卡十几秒。跑一下系统时间同步卡顿莫名消失的情况我见得太多了。第四个是残留 hook 或自动化脚本。Claude Code 支持自定义 hook会在特定事件触发时执行脚本。如果 hook 脚本写得有性能问题或者网络请求超时它会阻断主流程。检查一下配置里有没有无效或过时的 hook暂时禁用对比一下速度。5.3 最后分享一个我自己常用的“十分钟排障法”不吹不黑我用这套方法解决过至少十几次卡顿先开调试模式看日志确认卡点在哪一层再用 curl 测 API 最小请求排除服务端问题然后看/context和/status确认上下文和账户状态最后再用最小复现实验确认是不是某个特定文件或目录的问题。整套流程十分钟内做完一般都能定位到根因。说得直接一点Claude Code 卡顿这件事九成以上不是工具坏了而是上下文、环境和服务端三者之间的匹配出了问题。别急着卸载重装先花十分钟按这套流程走一遍多半能找到能立竿见影的解法。如果你也有过离奇的卡顿经历对照上面的速查表逐项试过来应该比网上那些“重启一下就好”的回复靠谱得多。