# claude-swap - Claude Code 多账号一键切换工具

> 支持 CLI 与 VS Code 插件双端，安全存储 OAuth 凭证，带额度追踪，Python 编写，跨平台可用。

**claude-swap** 是 GitHub 上目前最活跃、功能最全的 Claude Code 多账号切换工具（⭐150，持续更新中）。它通过"备份-替换"本地凭证的方式，让你**无需重新走 OAuth 登录流程**，就能在多个 Claude Pro / OAuth 账号之间秒切，而且**同时支持 Claude Code CLI 和 VS Code 扩展**。

🔗 GitHub: https://github.com/realiti4/claude-swap

---

## 一、它是干嘛的？

Claude Code 官方只支持单账号登录。如果你有多个 Claude Pro/OAuth 账号，遇到 5小时/7天额度限制时需要手动退出再登录，非常麻烦。

**claude-swap** 通过备份-替换本地凭证的方式，让你无需重新走 OAuth 登录流程，就能在多个账号之间秒切。

---

## 二、核心亮点

| 亮点 | 说明 |
|------|------|
| **双端支持** | 同时支持终端里的 `claude` 命令 和 VS Code 的 Claude Code 插件 |
| **安全存储** | 凭证不存明文。Windows 用 Credential Manager，macOS 用 Keychain，Linux 用受限文件 |
| **会话恢复** | 切换账号后可以恢复之前的对话会话（conversation cache 会重建） |
| **用量追踪** | `--list` 直接显示每个账号的 5h/7d 使用量和额度重置时间 |
| **slot 管理** | 支持按编号（slot）存放账号，覆盖前会提示确认 |
| **尊重环境变量** | 最新版本已支持 `CLAUDE_CONFIG_DIR` 自定义配置路径 |

---

## 三、安装方式

### 1. uv 安装（推荐）
```bash
uv tool install claude-swap
```

### 2. pipx 安装
```bash
pipx install claude-swap
```

### 3. 源码安装
```bash
git clone https://github.com/realiti4/claude-swap.git
cd claude-swap
uv sync
uv run cswap --help
```

**依赖极少**：Python ≥3.12，只有一个运行时依赖 `keyring>=25.0.0`（用于安全存储）。

---

## 四、所有命令详解

命令入口有两个：`claude-swap` 和简写 `cswap`。

### 基础操作
```bash
cswap --add-account
```
> 把**当前已登录**的 Claude Code 账号存到 claude-swap 里。如果该账号已存在会自动更新凭证，不会重复创建。

```bash
cswap --add-account --slot 3
```
> 强制存到第 3 号 slot。如果 slot 3 已经有账号，会提示你是否覆盖。

```bash
cswap --switch
```
> 轮询切换到下一个账号（1→2→3→1）。

```bash
cswap --switch-to 2
cswap --switch-to user@example.com
```
> 直接切换到指定 slot 编号或邮箱的账号。

```bash
cswap --list
```
> 列出所有已保存的账号，并显示每个账号的 **5小时额度 / 7天额度** 使用情况，以及**下次重置时间**。这对管理多个 Pro 账号非常有用。

```bash
cswap --status
```
> 显示当前生效的是哪个账号。

```bash
cswap --remove-account 2
```
> 删除 slot 2 的备份账号。

```bash
cswap --purge
```
> **清空所有 claude-swap 数据**（包括凭证和配置备份）。

---

## 五、使用流程（完整示例）

**第一次 setup：**
1. `claude` 登录你的第一个账号
2. `cswap --add-account`
3. `claude` 退出登录，再用第二个账号登录
4. `cswap --add-account`
5. 现在 `cswap --switch` 就能在两者之间切换了

**Token 过期刷新：**
如果某个账号的 OAuth token 过期了，直接用 `claude` 重新登录该账号，然后 `cswap --add-account` 即可更新存储的凭证。

**切换后必须做的一步：**
切换完成后，需要**重启 Claude Code**（关闭 VS Code 的 Claude 标签页再打开，或在终端里退出 `claude` 重进），新账号才会生效。

---

## 六、技术原理

1. **添加账号时**：读取 Claude Code 当前生效的 OAuth token 和配置文件，打包成"账号快照"
2. **切换时**：把当前生效的凭证和当前账号的快照对调（即把当前账号存回去，把目标账号换出来）
3. **凭证隔离**：账号相关的敏感信息（token）走系统安全存储；配置类的非敏感信息放在本地备份目录

### 数据存放位置

| 平台 | 敏感凭证存储 | 配置备份目录 |
|------|-------------|-------------|
| **Windows** | Windows Credential Manager | `~/.claude-swap-backup/` |
| **macOS** | macOS Keychain | `~/.claude-swap-backup/` |
| **Linux** | 文件系统 `~/.claude-swap-backup/credentials/`（权限受限） | `~/.claude-swap-backup/` |

### 路径解析（最新修复）
作者在 2026-04-14 的 commit 里刚修复了路径解析逻辑，现在 `claude-swap` **完全镜像了 Claude Code 自身的配置路径规则**：
- 优先读取 `CLAUDE_CONFIG_DIR` 环境变量
- 否则默认使用 `~/.claude`
- 同时兼容 legacy 的 `.config.json` 路径

这意味着即使你自己改了 Claude Code 的配置目录，这个工具也能找对文件。

---

## 七、VS Code 扩展支持详解

这是它相比其他竞品最大的优势之一。

- 你可以在**任意终端**里运行 `cswap --switch`
- 然后回到 VS Code，**关闭 Claude Code 插件标签页，再重新打开**
- 插件就会以新账号身份启动

而且它的 README 明确提到：你可以在新账号下**恢复之前的会话**。操作方法就是切换后重新打开插件，选择之前的 session 即可（只是第一条消息可能会额外消耗一些 token，因为 conversation cache 要重建）。

---

## 八、会话连续性（Tips）

README 里有一个很实用的 tip：

> 你可以在切换账号后恢复同一个 Claude Code 会话。关闭 Claude Code / VS Code 插件 → 运行 `cswap --switch` → 重新打开并选择之前的会话。

这对于需要跨账号继续同一个代码审查或调试任务的场景很有用。

---

## 九、卸载

先清数据：
```bash
cswap --purge
```

再卸载：
```bash
uv tool uninstall claude-swap
# 或
pipx uninstall claude-swap
```

---

## 十、总结：适合谁用？

如果你符合以下任意条件，**realiti4/claude-swap** 基本是目前 GitHub 上的首选：

1. **有多个 Claude 账号**（个人+工作、或为了绕开额度限制）
2. **不想每次手动扫码/OAuth**
3. **同时在 VS Code 插件和终端 CLI 里用 Claude Code**
4. **看重安全存储**（不想把 token 扔在明文 JSON 里）
5. **想看到每个账号的剩余额度/重置时间**

它的更新频率、文档完整度、双端支持和安全设计，都比其他同类产品（比如已归档的 ming86、Node.js 的 Leuconoe、只支持 macOS Desktop 的 jasonmx）要更成熟。

---

**分类**：软件
**标签**：账号 · Code · cswap
**作者**：Xiao.Xi
**链接**：https://octohz.com/p/1519