企业官网建设流程全解析

【Claude】Claude Code 自动重试机制详解：3 个环境变量调优指南

关键词：Claude Code、自动重试、指数退避、CLAUDE_CODE_MAX_RETRIES、CLAUDE_CODE_RETRY_WATCHDOG、API_TIMEOUT_MS、Retrying in Ns、Waiting for API response

一、为什么需要理解重试机制

很多人对 Claude Code 的重试机制有一个根本性的误解："我看到报错说明刚才失败了一次。"

实际上：你在终端看到任何报错时，Claude Code 已经替你重试过了最多 10 次。

这一点至关重要，因为它决定了你如何解读报错的严重程度：

• 看到Retrying in Ns · attempt 3/10：还在重试中，不是最终失败；
• 看到最终报错（如API Error: 500或Repeated 529）：已经重试 10 次全部失败，是持续性问题；
• Waiting for API response：响应流停滞 20 秒，预警阶段，还没失败。

理解这个机制，就能正确判断"要不要干预"以及"怎么干预"。

二、重试的触发条件

Claude Code 的自动重试针对以下类型的瞬时故障：

不会重试的情况：

• 4xx 客户端错误（401 认证失败、400 请求格式错误、403 禁止访问）——重试没有意义，需要你修复请求本身；
• 配额耗尽（session limit、weekly limit）——重试只会浪费时间；
• 内容拒绝（Usage Policy）——同上。

三、退避算法：指数退避

重试不是"立刻再试"。每次重试之间，Claude Code 使用**指数退避（Exponential Backoff）**策略，等待时间随重试次数指数增长：

第 1 次重试：等 ~1 秒 第 2 次重试：等 ~2 秒 第 3 次重试：等 ~4 秒 第 4 次重试：等 ~8 秒 ...（每次翻倍，有最大值上限） 第 10 次重试：等 ~几十秒

重试期间，终端微调器显示倒计时：

Retrying in 8s · attempt 4/10

其中8s是本次等待时间，4/10是当前是第几次 / 最多几次。

指数退避的设计原理：

1. 避免"请求风暴"：如果所有客户端在服务端过载时都立刻重试，会把刚恢复的服务立刻再次打垮；
2. 给服务端恢复时间：随着等待时间增长，服务端有更多时间处理积压请求；
3. 自动探测恢复：一旦某次重试成功，倒计时自动消失，对用户透明。

四、响应流停滞看门狗（Waiting for API response）

这是重试机制的一个特殊子系统，专门处理"连接已建立，但响应流停滞"的情况。

工作原理

当请求已经发出、连接已经建立，但响应流上连续 20 秒没有新数据到达时，看门狗触发：

Waiting for API response · will retry in … · check your network

此时：

• 请求还没失败，只是响应流暂时停滞；
• 倒计时走完后，Claude Code 会主动中止这个停滞的连接并发起新的重试；
• 一旦数据恢复流动或重试成功，横幅自动消失。

版本注意

• v2.1.185+：停滞阈值20 秒；
• 早期版本：10 秒后显示横幅，措辞略不同。

诊断信号

如果Waiting for API response每次重试都反复出现，把它当网络问题处理。

偶发一次后恢复 = 正常的流式波动；每次都出现 = 代理/VPN/防火墙有稳定的拦截。

五、三个关键环境变量

这是本文的核心部分——根据你的使用场景，选择合适的配置组合。

变量一：CLAUDE_CODE_MAX_RETRIES

用途一：脚本里快速暴露失败

CI / 自动化脚本有时不希望等太久才看到失败。把重试次数调小，让脚本更快"认输"报错，方便你及时干预：

export CLAUDE_CODE_MAX_RETRIES=3 claude -p "你的任务"

这样最多重试 3 次，失败总耗时从默认的几分钟缩短到十几秒。

用途二：交互式场景

默认 10 次基本够用，通常不需要改。如果你希望更快看到错误（比如快速判断服务是否恢复），可以调到 5。

用途三：更顽强（v2.1.186+）

如果你处在不稳定的网络环境，且任务不能中途失败，可以调到 15：

export CLAUDE_CODE_MAX_RETRIES=15

变量二：CLAUDE_CODE_RETRY_WATCHDOG

用途：CI / 无人值守场景扛住容量波动

正常情况下，重试次数达到MAX_RETRIES后就放弃。对于 429（速率限制）和 529（过载）这类容量错误，如果你希望任务无限期等待直到容量恢复，开启这个变量：

export CLAUDE_CODE_RETRY_WATCHDOG=1

开启后，对于 429/529，Claude Code 会无限重试，不再受 MAX_RETRIES 次数限制，直到成功为止。

适用场景：

• 离线批处理任务（比如夜间自动化）；
• 无人值守的长时间 CI 任务；
• "宁可慢，不能停"的场景。

不适用场景：

• 交互式开发——你不会想对着无限倒计时干等；
• 任务本身有时间限制的 CI（会一直等到超时）。

注意：RETRY_WATCHDOG 只对 429/529 生效，对 500 等其他错误无效（500 不是容量问题，无限重试服务端崩溃也没用）。

变量三：API_TIMEOUT_MS

用途一：慢速网络 / 代理环境

如果你的网络延迟高、代理链路慢，默认 10 分钟可能不够。调大：

export API_TIMEOUT_MS=1200000 # 20 分钟

国内通过第三方中转接入的用户，通常设到3000000（50 分钟）：

{ "env": { "API_TIMEOUT_MS": "3000000" } }

用途二：有时间约束的任务

如果你的任务必须在某时间内完成，调小超时可以让超时更快暴露：

export API_TIMEOUT_MS=60000 # 1 分钟

配合MAX_RETRIES计算总等待时间：最坏情况下，总耗时 ≈MAX_RETRIES × API_TIMEOUT_MS（每次重试都超时的情况）。

六、场景配置推荐

场景一：日常交互式开发

# 全部用默认值 # CLAUDE_CODE_MAX_RETRIES=10（默认） # API_TIMEOUT_MS=600000（默认）

默认配置已经很合理，不需要调整。

场景二：脚本 / CI，希望快速失败

export CLAUDE_CODE_MAX_RETRIES=3 export API_TIMEOUT_MS=60000 # 1 分钟

最多重试 3 次，每次超时 1 分钟，总最坏等待 3 分钟。

场景三：批处理任务，扛住容量波动

export CLAUDE_CODE_RETRY_WATCHDOG=1 export API_TIMEOUT_MS=600000 # 保持默认超时

429/529 无限重试，等容量恢复再跑。

场景四：慢网络 / 代理环境

export API_TIMEOUT_MS=1800000 # 30 分钟 export CLAUDE_CODE_MAX_RETRIES=5 # 减少次数，但每次等更久

场景五：国内第三方 API 中转

{ "env": { "ANTHROPIC_AUTH_TOKEN": "你的key", "ANTHROPIC_BASE_URL": "https://中转地址", "API_TIMEOUT_MS": "3000000" } }

七、配置生效方式

临时（当前 Shell 会话）：

export CLAUDE_CODE_MAX_RETRIES=5 claude # 这次启动生效

永久（写入 settings.json）：

// ~/.claude/settings.json { "env": { "CLAUDE_CODE_MAX_RETRIES": "5", "API_TIMEOUT_MS": "1200000" } }

项目级别（只对该项目生效）：

// 项目/.claude/settings.json（项目目录） { "env": { "CLAUDE_CODE_MAX_RETRIES": "3" } }

八、总结：三个变量的职责分工

记住一句话：你看到报错时，Claude Code 已经重试过了。这 3 个变量让你控制"已经重试了几次"和"重试的节奏"，根据你的场景选对配置，就能在"更快失败"和"更顽强坚持"之间找到平衡。

参考：Claude Code 官方《错误参考》自动重试章节、官方环境变量文档、社区重试机制源码分析。