claude-swap：Claude Code 多账号管理的高效方案

claude-swap 是一款专为 Claude Code 用户打造的多账号切换工具，支持多账号自动轮换、速率限制智能规避、用量仪表盘、并行会话，以及交互式 TUI 界面。

---

痛点场景：为什么 Claude Code 用户需要这个工具？

Claude Code 是 Anthropic 官方推出的 AI 编程助手，在开发者社区中口碑极佳。但它有一个设计限制：同一时刻只能登录一个账号。

这在以下场景会造成实际困扰：

场景一：个人 + 工作账号分离 开发者小张白天用公司账号在 Claude Code 上处理工作代码，晚上想用个人账号学习新技术。每次切换都要登出、登录，还可能丢失当前会话。

场景二：批量开发者工具 团队 leader 李总需要管理 5 个 Claude Code 账号（公司购买了企业套餐），轮换给不同项目组使用。手动切换繁琐且容易出错。

场景三：速率限制管理 Claude Code 有 5 小时窗口和 7 天窗口的用量限制。重度用户常常在关键时刻遇到 "rate limit exceeded"，被迫中断工作。

claude-swap 正是为解决这些问题而生的。

---

核心功能：能做哪些事？

账号管理

cswap add          # 添加当前登录的账号
cswap list         # 查看所有账号及用量
cswap switch 2     # 切换到第2个账号
cswap disable 2    # 临时禁用第2个账号

自动轮换（核心亮点）

cswap auto                     # 自动监控 + 切换
cswap auto --threshold 80      # 用量达到 80% 就切换（默认 90%）
cswap auto --strategy best     # 切换到剩余配额最多的账号
cswap auto --strategy consume-first  # 优先消耗即将重置的配额（用完即弃策略）
cswap auto --model Fable       # 同时监控 per-model 限制

自动切换逻辑非常细致：

• 冷却机制：切换后默认 5 分钟冷却，防止在阈值附近反复横跳；
• 隔离保护：对正在 Claude Code 中运行的账号切换会加锁，不与 token 刷新冲突；
• 自适应轮询：繁忙的账号被更频繁地检查，耗尽的账号约 10 分钟检查一次；
• 容错设计：API 出错时保留上次已知数据，指数退避重试。

交互式 TUI 仪表盘

cswap           # 直接启动 TUI 全屏仪表盘
cswap watch     # 直接打开 live 监控视图

TUI 实时展示：每个账号的 5h/7d 用量、重置时间、auto-switch 状态，支持键盘操作完成所有管理任务（添加/禁用/启用/删除账号）。

macOS 菜单栏小部件（可选）

需要安装 claude-swap[menubar]（macOS 专属）：

• 菜单栏实时显示所有账号的 5h/7d/spend 用量；
• 点击切换指定账号或轮换；
• 一键开启/关闭自动切换。

并行会话模式（session mode）

允许同时运行多个 Claude Code 实例，每个使用不同账号。适合同时处理多个项目、多个客户代码库的开发者。

---

技术实现：如何安全地切换账号？

凭证存储策略

claude-swap 不存储密码，只存储 OAuth tokens 和 refresh tokens：

• Linux / Windows：凭证存储在本地文件；
• macOS：凭证存储在系统 Keychain（安全区域）。

切换时，claude-swap 会持有 Claude Code 自己的凭证锁（credential locks），确保切换操作与 token 刷新不会互相干扰。

用量获取机制

通过调用 Anthropic 账户 API 获取实时用量数据：

# 自适应轮询逻辑
if account.is_busy:
    poll_interval = 30s  # 繁忙账号更频繁检查
elif account.is_exhausted:
    poll_interval = 600s  # 耗尽账号降低频率

账户隔离设计

切换账号时，保留账号无关的 OAuth 状态（如 MCP server 登录信息），只覆盖账号专属的登录状态，避免 MCP server 需要重新配置。

---

安装与使用

推荐安装方式（uv）

uv tool install claude-swap

之后在终端中直接使用 cswap 命令。

从源码安装

git clone https://github.com/realiti4/claude-swap.git
cd claude-swap
uv sync
uv run cswap help

更新

cswap upgrade

---

代码质量亮点

claude-swap 的测试套件令人印象深刻：

• 1,929 个测试用例，4 个跳过，全部通过；
• 并行测试：默认开启（-n auto），在多核机器上从 51 秒缩短至 7.7 秒；
• Textual 组件测试：使用 pytest-textual-pilot 进行 TUI 交互式测试；
• 平台模拟：包含 Linux/Windows/macOS 各平台行为模拟。

技术栈：

• Textual：构建交互式 TUI（Python 终端 UI 框架，比 urwid 更现代）；
• truststore：跨平台安全 HTTPS 凭证存储；
• Hatchling：现代 Python 打包工具。

---

局限与注意事项

1. macOS Keychain 缓存：macOS 上凭证缓存在 Keychain 中约 30 秒才过期，如果需要立即切换，需重启 Claude Code；
2. 不管理 API Key 账号：默认不会轮换到纯 API Key 账号（无 refresh token），除非显式传入 --include-api-key-accounts；
3. refresh token 过期处理：token 失效的账号会被隔离（quarantined），需要重新添加或从备份恢复；
4. 需要多账号本身：工具本身不提供账号，需要用户自己拥有多个 Claude Code 账号。

---

总结

维度	评分
功能完整度	⭐⭐⭐⭐⭐ 多账号管理、自动轮换、TUI、menu bar、并行会话全覆盖
使用便捷性	⭐⭐⭐⭐⭐ uv tool install 一行安装，即装即用
代码质量	⭐⭐⭐⭐⭐ 1900+ 测试用例，并行测试，平台模拟完善
平台兼容性	⭐⭐⭐⭐ Linux/Windows/macOS 全平台，macOS 特有 menu bar
适用人群	重度 Claude Code 用户、团队管理员、需要多角色分离的开发者