claude-swap自动切换深度解析：2个配置让Claude Code撞上限自动轮换不中断-平芜编程栈

claude-swap自动切换深度解析：2个配置让Claude Code撞上限自动轮换不中断

【免费下载链接】claude-swapSwitch between multiple Claude Code accounts, with automatic rate-limit rotation, usage dashboard, and parallel sessions项目地址: https://gitcode.com/gh_mirrors/cl/claude-swap

claude-swap 是一款面向 Claude Code 的多账号切换工具，内置自动切换引擎：持续监控每个账号的 5 小时/7 天额度用量，在触达限流之前自动轮换到额度最充裕的账号，让长时间运行的任务永不断档。本文带你用 2 个配置项，把这套限流自动轮换机制完整跑起来。

为什么需要自动切换账号

Claude Code 的订阅账号受两层限流约束：5 小时窗口和7 天窗口。重度使用下一两个小时就可能撞上限，报错、干等、手动换号一气呵成。

cswap auto的解法很直接：前台循环默认每 60 秒轮询一次用量，当当前账号的"约束窗口"（5h/7d 中占用率更高的那个）触及阈值时，主动切换到额度剩余最多的账号。关键在于它是前置切换——切换发生时旧账号依然有效，正在运行的 Claude Code 会在下次调用时自然拾取新凭证，全程无需重启、不干扰任务。引擎在写入时持有 Claude Code 自己的凭证锁（实现见 autoswitch.py），所以切换永远不会和 token 刷新打架。

快速上手：3 步开启自动轮换

# 1. 安装 uv tool install claude-swap # 或 pipx install claude-swap # 2. 录入账号：先登录第 1 个账号，执行 cswap add； # 再登录第 2 个账号（不要先 /logout），再次执行 cswap add # 3. 启动自动切换 cswap auto

启动后会看到一行提示，例如Auto-switch running: threshold 90%, every 60s，按 Ctrl-C 停止。想先观察它的决策而不实际动手，加--dry-run即可。

配置一：切换阈值（何时切）

autoswitch.threshold决定"用掉多少时开始找下家"，取值 50–99.9，默认90%。

cswap config set autoswitch.threshold 80 # 更早切换，留足缓冲

为什么默认不是 100%？90% 给 macOS 钥匙串约 30 秒的缓存滞后、以及一个重型子代理轮次烧过临界点都留了余量（见 settings.py 中的注释）。
命令行参数cswap auto --threshold 80可临时覆盖，适合单次实验。
候选账号必须低于阈值且比当前账号好出一个迟滞幅度（默认 10 个百分点），这样两个都贴着线的账号绝不会来回乒乓，而严格更优的账号一定会被选中。

配置二：轮换策略（切到谁）

autoswitch.strategy决定目标账号怎么选，只有两种取值：

cswap config set autoswitch.strategy best # 默认 cswap config set autoswitch.strategy consume-first # 用满优先

best（默认）：稳坐当前账号直到接近限额，然后跳到额度剩余最多的账号。适合"谁余粮多睡谁"的日常使用。
consume-first（用满优先）：主动停留在周窗口重置时间最近的账号上，专烧快过期的周额度，用完了再走人。适合多账号都接近周限额、担心周额度作废的场景。

两种策略的行为差异都实现在 autoswitch.py 的tick()决策循环中。

进阶：把单模型限额也纳入决策（可选第三配置）

如果你主要用某一个模型、先撞它的每周单模型限额，可以让引擎一并盯着：

cswap config set autoswitch.model Fable # 或 "Fable,Opus"，甚至 all

模型名取cswap list里每行的名称（大小写不敏感）。配置后，即使账号的 5h/7d 窗口还有余量，该模型周额度烧光时也会触发切换。

安全机制：它为什么不会乱切

冷却时间：默认两次主动切换之间至少间隔 5 分钟（autoswitch.cooldownSeconds）。
令牌保鲜：激活目标账号前会先刷新其 token；刷新令牌已死的账号会被隔离并明确报告，而不是带病上阵。
自适应轮询：正在燃烧的账号查得密、闲置账号查得稀，API 流量始终平稳，账号再多也不撞 Anthropic 的接口限额（节奏常量集中在 poll_policy.py）。
状态持久化：冷却与隔离记录写入autoswitch_state.json，所以 cron 驱动的--once跨进程也能衔接。

后台运行：让 cron 替你值班

--once模式只做一次"检查-切换"就退出，退出码即结果（0已切换 /1出错 /2无需动作 /3无可切换目标），非常适合定时任务：

*/5 * * * * cswap auto --once --json >> ~/.cswap-auto.log 2>&1

加--json时每次 tick 输出一行 JSON 事件（poll、switch、no-switch、all-exhausted等），方便写脚本追踪。

实时监控：watch 面板

自动切换开着时，另开一个终端跑cswap watch，即可看到每个账号 5h/7d 进度条、重置倒计时和当前活跃账号（active标记），切换发生在哪个窗口上一目了然：

图中账号 3 的 5h 窗口已达 96%（红色告警），而当前活跃的账号 2 还有 24% 余量——引擎会在账号 2 触及阈值前完成轮换。

小结：2 个配置速查

配置	命令	默认值	作用
切换阈值	`cswap config set autoswitch.threshold 80`	90%	约束窗口用到多少时开始找下家
轮换策略	`cswap config set autoswitch.strategy consume-first`	best	切到"余量最多"还是"先烧快过期的"

配好这两项，Claude Code 撞上限之前账号已经悄悄换好——你只需要继续写代码。更多细节（隔离恢复、账号禁用、导出导入）可参考 README.md 的 Automatic switching 章节。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考