无人值守遇到用量上限：CLAUDE_CODE_RETRY_WATCHDOG 的两个新变量
CLAUDE_CODE_RETRY_WATCHDOG 是 Claude Code 的无人值守重试模式：夜间批处理、CI 任务这类没人盯着的场景里，遇到 429、529 之类的错误不会直接失败，而是自己等、自己重试。之前我们介绍过给 429/529 等待封顶的 CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS。
不过「撞上用量上限」是另一种情况：它有明确的重置时间，可能是几十分钟，也可能是好几个小时。最近两个版本围绕它补了两个变量，一个管「别等太久」，一个管「别白等」。
2.1.305：额度提前恢复，能及时发现
新增的 CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS 让无人值守重试模式能察觉到在重置时间之前就已经解除的用量上限。
为什么会提前解除？比如管理员临时给组织调高了额度、团队成员帮你申请到了额外用量，或者你在别处处理了额度问题。以前 watchdog 拿到重置时间后就只认那个时间点，额度明明已经可以用了，任务还在原地睡觉。
有了这个变量，watchdog 在等待期间会按你设定的间隔（单位从变量名看是毫秒）回头再确认一次，额度一恢复就能接着跑。
# 示例：等待用量上限期间，每 10 分钟复查一次
export CLAUDE_CODE_RETRY_WATCHDOG=1
export CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS=600000
claude -p "跑完整套迁移脚本并汇总结果"间隔不必设得太短：额度提前恢复本来就不是高频事件，十分钟级别通常就够用。
2.1.301：重置太远，干脆结束
另一个变量是 2.1.301 加的 CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS：当用量上限的重置时间离现在太远、超过你设定的值时，watchdog 不再等待，而是直接结束这个请求。
这对有时间窗口的任务很重要。比如一个 CI job 本身有一小时超时，额度要四小时后才重置，与其让它一直挂着占住 runner、最后被超时杀掉，不如尽早失败、让流水线按失败处理或换别的方式重跑。
# 示例：重置时间超过 30 分钟就不等了
export CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS=1800000三个变量怎么分工
| 变量 | 管什么 | 版本 |
|---|---|---|
CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS | 等待 429、529 的时间上限 | 2.1.295 |
CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS | 用量上限重置太远时直接结束请求 | 2.1.301 |
CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS | 等用量上限期间定期复查，提前解除就继续 | 2.1.305 |
它们都只在打开 CLAUDE_CODE_RETRY_WATCHDOG 时有意义。一个比较实用的组合是：用 MAX_USAGE_LIMIT_WAIT_MS 决定「最多愿意等多久」，在这个窗口内再用 USAGE_LIMIT_RECHECK_MS 定期看看能不能提前开工。
另外别忘了之前已有的行为：遇到组织支出上限、余额耗尽这类错误，重试模式会直接失败，而不是无限期等待重置——这类问题靠等是等不好的。
小结
- 2.1.305 的
CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS：等待用量上限时定期复查，额度提前恢复就继续； - 2.1.301 的
CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS：重置时间太远时直接结束，不占着资源干等； - 再加上管 429/529 的
MAX_WAIT_MS，无人值守任务在「等不等、等多久、要不要提前醒」三件事上都能自己掌控了。