Agent 转圈卡住不动：先分清网络、索引、工具调用还是在等你确认

2026-07-28

数据截至 2026-07，各产品的额度与报错口径以官方最新说明为准。

**Agent 转圈不动，最常被归错的因是网络，而实际上更高频的两个原因是：它在等一次没人点的确认，或者它发起的某个工具调用没有返回。**这两种情况下重装插件、清缓存、换模型全是白费功夫，因为进程根本没在等网络。所以正确的第一步不是动手修，而是判断它停在哪一层——这是把十分钟干等变成三十秒判断的唯一办法。

站内已有三篇邻居各管一段：索引本身报错、进度条不走完看 Cursor 代码库索引卡住、失败怎么解决，光标处不弹灰字建议看补全不工作，你自己用框架写的 Agent 跑不通看 Agent 框架调试；这篇只管一件事——IDE 内置的 Agent 在一次对话中途停住、不出字也不报错时，怎么最快定位到四类成因之一并处置。

一、先看它停在哪一层

一次 Agent 执行拆开看就四层，卡住必然发生在其中一层，而每层留下的痕迹不一样。

传输层。请求已经发出，正在等服务端。典型痕迹是界面上有明确的”正在生成”状态但一个字都没吐出来，且这个状态持续时间远超你平时的首字延迟。判断关键在于首字：只要已经吐出了几十个字然后停住，问题基本不在传输层，因为流式响应一旦建立，中断通常会报错而不是静默挂着。

**上下文构建层。**Agent 动手前要先找料：检索代码库、读文件、拉取你 @ 进来的引用。痕迹是它停在准备或检索阶段，还没产生任何计划与工具调用。大仓库首次建索引、刚切完大分支导致索引大面积失效、把 node_modules 之类目录喂进去了，都会让这一步变得很久。

**工具执行层。**Agent 已经决定动手，发起了读文件、跑终端命令、调外部工具的请求，然后就没有下一步。痕迹很明确：界面停在某个具体动作上，比如某条终端命令旁边一直是运行中。这一层最容易被误判成”AI 又抽了”，实际上多半是那条命令自己没退出。

**交互等待层。**Agent 在等你。它可能在等一次写文件或执行命令的批准，可能弹出了确认但被折叠、被滚动出可视区域、或者在另一个面板里。人机确认本身是好设计，代价就是漏点一次确认，整条流程就静静地停在那儿。

一个粗判顺序：**先看有没有已经吐出的字 → 再看有没有停在某个具体工具调用 → 再看有没有待确认 → 最后才怀疑网络。**这个顺序和大多数人的直觉正好相反，但它按的是”验证成本从低到高”排的。

二、判别表：现象 → 成因 → 验证 → 处置

现象	大概率成因	怎么验证	处置动作
完全没出字，状态一直是生成中	传输层：网关、代理、区域限制或服务端排队	用命令行对同一服务发一个最小请求，看能不能拿到响应头	见第三节网络自证；确认是链路问题再动代理配置
没出字，且提示额度或速率相关信息	用量类限制，不是故障	去账号的用量/计费页看当前周期余量；再换一个不同的模型问同一句，还是同类提示就基本坐实	换轻量模型或等配额周期重置（重置口径以官方说明为准），别反复重试加剧限流
吐了一段后停住，不再继续	大概率是工具调用没返回，或响应被中断	看它最后一步在做什么，有没有停在某个动作上	中断本次执行，手动跑那条动作看是否自己卡住
停在”检索/读取代码库”阶段	上下文构建层：索引未就绪或仓库过大	新开一个对话，不 @ 任何文件问一句纯文本问题：立刻出字就说明卡在检索而不是链路	排除超大目录后重建索引，参考索引专篇
停在某条终端命令上	命令进入交互态或前台阻塞	在系统里看这个进程还在不在、有没有在等输入	强制结束该命令，改用非交互写法重跑
停在文件改写上，改动以待处理形式挂着没落盘	交互等待层：等你批准	把对话面板滚到底，检查是否有折叠的待确认项	点掉确认；长期方案是给高频安全操作放行
反复在同一步失败又重试	同一个动作反复失败、模型在原地重试（路径不存在、权限不足、参数不合法都会这样）	看它是不是每轮都在调同一个工具、参数几乎一样	直接停掉，先手动把那个动作跑通，再换更小的任务交回去
整个 IDE 都卡，不止 Agent	本地资源问题（内存、磁盘、语言服务）	看系统资源占用与 IDE 自身的进程数	先救 IDE，别在这时候排查 AI

这张表的用法是从上往下扫现象，而不是从下往上找解法。你只需要一条命中，就能把动作范围从”所有可能”缩到”一两步”。

三、按成本从低到高动手

**第 0 步：先停，别叠加。**卡住时最常见的错误动作是再发一次。多发的请求会把待处理队列拉长，本身已经触发限流的话，重试只会让你更快撞墙。先按停止。

**第 1 步：换一次最小提问。**新开一个对话，问一句不需要读任何文件的话，比如让它解释一小段你贴进去的代码。这一步能一刀切开传输层和其它三层：能正常出字，说明链路和账号都活着，问题在上下文或工具；还是不出字，直接进第 2 步。

**第 2 步：60 秒证明不是链路。**在终端里对目标服务发一个最小请求，看 HTTP 状态码：

# 只要响应头，不拉正文
curl -sS -o /dev/null -D - --max-time 15 https://api.example.com/v1/models

拿到状态码就能对号入座：401 是凭据不对或过期，403 常见于地区/权限维度被拒，429 是限流，5xx 是对端的问题不是你的。如果连状态码都拿不到，看报错名——ETIMEDOUT 指向出口链路不通或代理没生效，ECONNRESET 指向连接被中途切断（企业网关和某些安全设备会这么干）。如果报的是证书链校验失败，通常是路上有一层做 TLS 拦截的设备用自己签发的证书替换了服务端证书，处置是按公司 IT 的规范把该设备的根证书装进系统信任库，而不是关掉证书校验——关校验能让报错消失，但同时也让你分不清后面还有没有别的链路问题。各家 API 的报错语义细节差别不小，逐条对照可以看 OpenAI API 报错排查。

代理相关的一个高频坑：终端里的 HTTPS_PROXY 生效，但 IDE 是从桌面环境启动的，读不到你在 shell 配置文件里写的变量，于是终端能连、IDE 连不上。验证办法是从终端里启动 IDE，看行为是否改变。

关于区域：这类工具的服务商都会划定自己的可用地区范围，中国大陆在不在支持名单里、以什么形式接入，各家不同而且会调整，具体以官方的可用地区说明与服务条款为准，别照搬别人半年前的经验。落到排查上你只需要认一件事：如果你这一侧的网络到目标服务本身就不可达，症状就是发不出去、连不上、或者连上又被切断，而不是”AI 变笨了”，往模型和提示词上找原因是白费。市面上存在第三方中转，我不背书也不给渠道——只提醒一点：中转链路上的超时和连接重置会以完全一样的方式表现为”Agent 转圈”，而你在自己这一侧永远查不出原因。用了中转就要接受这类不可观测的卡顿。

**第 3 步：把工具调用单独拎出来跑。**如果它停在某条终端命令上，别在 Agent 里等，自己开个终端把那条命令原样跑一遍。跑得通说明是 Agent 侧的进程管理问题，跑不通说明命令本身有问题。同理，如果它停在调用外部工具上，先确认那个工具进程还活着——外部工具挂掉之后，调用方往往只能干等到超时。

**第 4 步：缩小上下文再试。**把一次让它”改整个模块”的任务，换成”只改这一个函数，文件我贴给你”。如果缩小之后立刻正常，成因就落在上下文构建层，往下按索引与检索的路子走。

**第 5 步：才轮到重启和清缓存。**这一步能修的问题真实存在（进程僵死、本地状态错乱），但它把现场毁了，所以放最后。重启前如果还想留证据，先把当前对话或报错截下来。

四、它在等你确认，而你在等它出字

这一层单独讲，因为它占比高、代价低、却最容易被漏。

**待确认被折叠。**长对话里 Agent 生成了一堆动作，确认项在中间某处，你的视线在底部。习惯动作：卡住先按一次滚到底，再往上扫一屏。

**终端命令进入交互态。**最典型的伪故障。Agent 让终端跑一条命令，命令弹出了分页器、进度确认或者等你输 y，而 Agent 看不见这个交互，只能等到超时。常见触发者是默认走分页器的命令、需要确认的安装类命令、交互式 rebase。规避写法是把非交互显式打开：

git --no-pager log --oneline -n 20
export GIT_PAGER=cat
export PAGER=cat

包管理和脚手架同理，能带上非交互参数就带上；git rebase -i 这类必须人工介入的命令不要交给 Agent。

**Git 状态本身在阻塞。**仓库处在冲突未解决、rebase 未完成的中间态时，Agent 的很多动作会失败或挂住。卡住时顺手来一句：

git status --short --branch

看到 UU 之类的冲突标记，或者文件里还留着 <<<<<<<、=======、>>>>>>>，先把冲突处理干净再谈 AI。

**批准策略太紧或太松。**每一步都要点，长任务必然在某处停住等你；全放开则可能执行到你不想执行的命令。可行的中间态是按操作类型分级：读取和格式化类放行，写文件和跑命令保留确认，删除和网络请求永远手动。这套取舍的完整讨论在人在环中的取舍那篇。

五、什么时候别再折腾：止损点与回滚点

排查也是有成本的，而且这个成本很容易超过任务本身。给自己划三条线。

**时间止损。**同一个”卡住”你已经排到第三种假设还没定位，停手，改成手动完成任务，把排查留到手上没活的时候。理由很实际：排查的收益不确定，任务的截止时间确定。

**回滚止损。**Agent 卡住的现场往往是脏的——改了一半的文件、写了一半的新文件、跑了一半的迁移。动手排查之前先做一次存档，最省事的是把当前改动整体收起来：

git stash push -u -m "agent-stuck-$(date +%m%d-%H%M)"

带 -u 是因为 Agent 新建的文件还没被跟踪，不带就会被漏掉。这样你既保住了现场，又拿到了一个干净的工作区去复现。确认不需要了再 git stash drop。

**换路止损。**下面任一条成立，就别在这条路上继续了：

你已经确认是区域限制或中转链路问题，本地无论怎么调都不影响对端；
同一个任务连续两次在同一步卡死，说明这是稳定复现的能力边界，不是偶发；
仓库体积决定了每次上下文构建都很久，那么单次排查解决不了根本问题；
任务本身需要多轮交互式确认，天然不适合让 Agent 端到端跑。

换路不等于放弃 AI：把大任务切成几个只碰一两个文件的小任务，改用补全式协作而不是 Agent 式协作，或者把同一件事挪到命令行工具里做，都是有效的绕行。

六、避坑清单

**卡住就无脑重试。**为什么会踩：重试是最省脑子的动作，而且偶尔真的会好。怎么避：给自己定一个”最多重试一次”的硬规矩，第二次卡住就转入判断流程。如果症状里有额度或限流的迹象，重试反而会延长你被限的时间。

**先重装插件、先清缓存。**为什么会踩：这是通用故障的肌肉记忆，且不需要理解问题。怎么避：把它放在动作序列最后。重装销毁的是现场，之后你连”到底是哪一层”都无从判断了。

**一上来就换模型。**为什么会踩：换模型看起来像变量控制，实际上一次换掉了模型、路由、可能还有服务端队列。怎么避：换模型只用来验证一个假设——“是不是这个模型当前不可用”，验证完就换回来，别把它当修复手段。

**把交互式命令交给 Agent。**为什么会踩：你自己在终端里跑习惯了，那些确认提示对你是透明的，你不觉得它算”交互”。怎么避：交给 Agent 的命令一律加非交互参数，或者预先设好环境变量；必须人工介入的命令自己跑。

**在脏工作区里排查。**为什么会踩：卡住那一刻你只想让它继续，没心情整理现场。怎么避：养成”卡住先 stash 再排查”的顺序。否则你后面很难分清哪个报错是原始故障，哪个是半成品代码引起的。

**把整个仓库当默认上下文。**为什么会踩：让它读全库最省描述成本，一句话就能提问。怎么避：默认给最小上下文，需要更多再加。上下文越大，构建越慢、卡住的概率越高、答案还更容易被无关代码带偏。

**看到界面有动静就认为它在干活。**为什么会踩：转圈动画是个纯前端效果，它不证明任何后端进展。怎么避：判断依据只认三个——有没有新字吐出、有没有新的工具调用、有没有文件被改动。三个都没有，超过一分钟就当它停了。

收束

Agent 卡住不是一种故障，是四种故障共用了一个症状。你要做的不是记住一堆修复动作，而是在动手前花三十秒判断层次，因为不同层的修复动作互不相通——用网络的办法修确认等待，永远修不好。

下次转圈时按这五条自检，多数情况能在一分钟内定性：

有没有已经吐出的字？有 → 不是传输层。
有没有停在某个具体工具调用或终端命令上？有 → 先去看那条命令。
把对话滚到底，有没有待确认项？有 → 点掉就结束了。
git status --short --branch 干净吗？不干净 → 先处理仓库状态。
新开一个不需要读文件的最小提问，能出字吗？不能 → 才去查链路和账号。