Claude Code 只执行第一步就卡住：原因排查与恢复建议
Claude Code 出现输入指令后只执行第一步、随后无响应的现象，集中反馈一度指向服务端故障。文章区分服务中断、客户端版本回归、网络代理与地区限制等情形，给出排查顺序、版本回退的取舍和恢复后的检查清单。
Claude Code 这类终端里的 AI 编程工具，最怕的不是直接报错，而是“看起来还在，实际已经不动了”。有用户遇到的情况是：输入任何指令后，工具只执行第一步——比如读一个文件、列一下目录——随后就没有下文，既不继续调用工具，也不返回明确错误。重启、换项目、回退版本，有人有效，有人无效；同一时间段还有多人在反馈类似问题，这就不能只从本地配置找原因。
从集中反馈看，问题一度指向服务端：官方状态页出现重大故障标记，自检请求出现 504，随后又逐步恢复。与此同时，也有人回退到旧版本后恢复正常，于是“服务端挂了”和“新版本有问题”两种判断混在一起。下面按排查顺序拆开讲。
先分清：大面积故障还是单机问题
判断顺序很重要。先看范围，再看版本，最后才动配置。
- 同一时间多人中招：如果多个项目、多个账号都出现同样症状，且公开反馈里有集中讨论，优先怀疑服务端或上游模型服务。
- 只有一台机器或一个项目异常：更可能是本地配置、MCP 工具、hooks、代理、登录态或项目文件问题。
- 只在新版本出现：升级后开始、回退后恢复，才更像客户端版本回归。
- 出现明确报错：如 504、鉴权失败、地区限制，按报错方向查，不要盲目重装。
常见原因与对应表现
| 现象 | 更可能的原因 | 处理方向 |
|---|---|---|
| 所有指令只执行第一步，多个用户同时发生，官方状态异常 | 服务端或上游故障 | 等待恢复，减少连续重试 |
| 升级后开始，回退旧版后恢复 | 客户端版本回归 | 锁定已知可用版本，向官方反馈 |
| 偶发 504、超时，切换网络后表现不同 | 网络、代理、DNS 或 TLS 链路问题 | 检查代理变量，换网络对照 |
| 出现“This model provider doesn't serve your region” | 账号或服务商地区限制 | 查官方支持范围，合规使用 |
| 长会话后卡住，短指令正常 | 上下文过长、本地资源或扩展干扰 | 新建会话，逐个关闭扩展排查 |
排查步骤：从最省事到最彻底
1. 先确认服务状态
打开官方状态页，看是否处于故障或降级状态；同时用最小指令复测，不要连续重试几十次。若状态页已标记重大故障，最稳妥的做法是等待恢复，并保留错误截图和时间点。服务端故障期间，重装客户端、反复登录通常没有意义。
2. 用最小环境复现
新建一个空目录，启动新会话，只发一条简单指令，例如“列出当前目录文件并总结”。然后临时关闭 MCP servers、hooks、自定义命令和项目级配置，再测一次。如果最小环境正常，问题更可能在某个工具或项目配置；如果仍然只执行第一步，再往版本和网络方向查。
3. 检查版本并谨慎回退
先记录当前版本和安装方式：
claude --version
# 若使用 npm 全局安装，可安装上一个确认正常的版本：
npm install -g @anthropic-ai/claude-code@<上一个正常版本>
回退只建议在“升级后出现、旧版可复现正常”的情况下做。讨论中出现过回退到 1.0.52 后恢复的反馈，但也有人回退无效，因此不能把它当成通用修复方案。版本号是否适合你的环境，应以官方发布记录和实际复现为准，不建议直接照抄。
4. 检查网络与代理
- 确认
HTTP_PROXY、HTTPS_PROXY、NO_PROXY没有把请求导向不可用代理。 - 换一个网络做对照，例如从公司网络切到手机热点，观察 504 或卡住是否变化。
- 用
curl检查到官方服务域名的连通性和 TLS 握手，具体域名以官方文档为准。 - 如果只有某个网络环境异常，优先排查公司网关、DNS 和代理规则。
5. 处理地区限制报错
如果错误信息是“This model provider doesn't serve your region”，这不是普通网络抖动，也不是回退版本能解决的。应查看服务商的地区支持说明，使用所在地区支持的账号和服务商；不要用伪造地区、共享账号等方式绕过限制，这类做法可能导致账号封禁或数据风险。
版本回退到底有没有用
回退版本是否有效，取决于问题根因。服务端大面积故障时，回退客户端不能修复上游；有些人回退后“好了”，可能只是恰好赶上服务恢复。反过来，如果问题稳定地随新版本出现、旧版本稳定复现正常，那就值得按版本回归处理。
比较稳妥的做法是：保留一个已知可用的版本，升级前记录版本号；出现问题时先用最小环境验证；确认是版本问题后再回退，并关注后续修复版本。长期停留在旧版可能错过安全修复和功能改进，不建议无限期不回退。
恢复后的检查清单
- 确认官方状态页已恢复正常，而不是只恢复了个别请求。
- 重新登录或刷新凭证，排除鉴权态过期。
- 查看当前版本，决定升级到最新稳定版还是暂时保留已知可用版。
- 跑一条最小指令，确认工具调用链完整。
- 逐个启用 MCP、hooks 和自定义命令，找出可能的干扰项。
- 长任务拆成阶段，及时提交代码或保存进度，避免一次会话中断后全部重来。
- 保留错误码、时间点和版本号，便于后续排查或向官方反馈。
长任务与运行环境
如果排查后确认是本地网络切换、笔记本休眠导致长任务频繁中断，可以把运行环境放到长期在线的远程 Mac 上，例如新加坡机房的独享远程 Mac，按月租用、远程连接，适合持续运行 Claude Code 这类工具。但它只解决运行环境稳定性问题，不能修复服务端故障，也不能用于规避地区限制或账号规则。
小结
遇到“只执行第一步就卡住”，先看是不是同一时间段的大面积故障，再看最小环境能否复现，最后才考虑版本回退和网络配置。服务端故障优先等待恢复；版本问题再用旧版对照；地区限制按官方支持范围合规处理。把版本、网络、扩展和日志分开验证，比反复重装更有效。
