【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 的自动重试针对以下类型的瞬时故障触发条件说明5xx 服务器错误500、503 等服务端异常529 过载OverloadedAnthropic 自定义的容量满状态码请求超时请求在 API_TIMEOUT_MS 内未完成临时 429 限流服务端临时性速率限制断开的连接TCP 连接中途断开不会重试的情况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是当前是第几次 / 最多几次。指数退避的设计原理避免请求风暴如果所有客户端在服务端过载时都立刻重试会把刚恢复的服务立刻再次打垮给服务端恢复时间随着等待时间增长服务端有更多时间处理积压请求自动探测恢复一旦某次重试成功倒计时自动消失对用户透明。四、响应流停滞看门狗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属性值默认值10上限v2.1.18615影响范围所有瞬时故障的重试次数用途一脚本里快速暴露失败CI / 自动化脚本有时不希望等太久才看到失败。把重试次数调小让脚本更快认输报错方便你及时干预export CLAUDE_CODE_MAX_RETRIES3 claude -p 你的任务这样最多重试 3 次失败总耗时从默认的几分钟缩短到十几秒。用途二交互式场景默认 10 次基本够用通常不需要改。如果你希望更快看到错误比如快速判断服务是否恢复可以调到 5。用途三更顽强v2.1.186如果你处在不稳定的网络环境且任务不能中途失败可以调到 15export CLAUDE_CODE_MAX_RETRIES15变量二CLAUDE_CODE_RETRY_WATCHDOG属性值默认值未设置开启方式设置为1影响范围仅429 / 529 容量错误用途CI / 无人值守场景扛住容量波动正常情况下重试次数达到MAX_RETRIES后就放弃。对于 429速率限制和 529过载这类容量错误如果你希望任务无限期等待直到容量恢复开启这个变量export CLAUDE_CODE_RETRY_WATCHDOG1开启后对于 429/529Claude Code 会无限重试不再受 MAX_RETRIES 次数限制直到成功为止。适用场景离线批处理任务比如夜间自动化无人值守的长时间 CI 任务宁可慢不能停的场景。不适用场景交互式开发——你不会想对着无限倒计时干等任务本身有时间限制的 CI会一直等到超时。注意RETRY_WATCHDOG 只对 429/529 生效对 500 等其他错误无效500 不是容量问题无限重试服务端崩溃也没用。变量三API_TIMEOUT_MS属性值默认值60000010 分钟单位毫秒影响范围单个请求的超时时间用途一慢速网络 / 代理环境如果你的网络延迟高、代理链路慢默认 10 分钟可能不够。调大export API_TIMEOUT_MS1200000 # 20 分钟国内通过第三方中转接入的用户通常设到300000050 分钟{ env: { API_TIMEOUT_MS: 3000000 } }用途二有时间约束的任务如果你的任务必须在某时间内完成调小超时可以让超时更快暴露export API_TIMEOUT_MS60000 # 1 分钟配合MAX_RETRIES计算总等待时间最坏情况下总耗时 ≈MAX_RETRIES × API_TIMEOUT_MS每次重试都超时的情况。六、场景配置推荐场景一日常交互式开发# 全部用默认值 # CLAUDE_CODE_MAX_RETRIES10默认 # API_TIMEOUT_MS600000默认默认配置已经很合理不需要调整。场景二脚本 / CI希望快速失败export CLAUDE_CODE_MAX_RETRIES3 export API_TIMEOUT_MS60000 # 1 分钟最多重试 3 次每次超时 1 分钟总最坏等待 3 分钟。场景三批处理任务扛住容量波动export CLAUDE_CODE_RETRY_WATCHDOG1 export API_TIMEOUT_MS600000 # 保持默认超时429/529 无限重试等容量恢复再跑。场景四慢网络 / 代理环境export API_TIMEOUT_MS1800000 # 30 分钟 export CLAUDE_CODE_MAX_RETRIES5 # 减少次数但每次等更久场景五国内第三方 API 中转{ env: { ANTHROPIC_AUTH_TOKEN: 你的key, ANTHROPIC_BASE_URL: https://中转地址, API_TIMEOUT_MS: 3000000 } }七、配置生效方式临时当前 Shell 会话export CLAUDE_CODE_MAX_RETRIES5 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 } }八、总结三个变量的职责分工变量管什么何时调整MAX_RETRIES最多重试几次脚本要快速失败→调小网络差要更顽强→调大RETRY_WATCHDOG429/529 是否无限重试无人值守批处理任务→开启API_TIMEOUT_MS每次请求等多久慢网络→调大有时间约束→调小记住一句话你看到报错时Claude Code 已经重试过了。这 3 个变量让你控制已经重试了几次和重试的节奏根据你的场景选对配置就能在更快失败和更顽强坚持之间找到平衡。参考Claude Code 官方《错误参考》自动重试章节、官方环境变量文档、社区重试机制源码分析。