claude-swap 完整教學 — Claude Code 多帳號切換工具

1. 專案定位

1.1 是什麼？

claude-swap 是一個 Python CLI 工具，讓你在多個 Claude Code 帳號之間快速切換，無需反覆登出登入。支援 Claude Code CLI 與 VS Code extension (VS Code 擴充套件)，以單一指令 cswap 操作所有帳號管理功能。

1.2 解決什麼問題？

開發者使用 Claude Code 時常見以下痛點：

  1. 多帳號需求：個人帳號 + 公司帳號 + 測試帳號，需要切換
  2. 登出再登入太慢：每次切換都要走完整 OAuth flow (OAuth 認證流程)
  3. Usage limit (用量限制) 輪替：當一個帳號的 5h/7d 用量到頂，想切到另一個帳號繼續
  4. 跨機器遷移困難：換電腦時 credential (憑證) 搬移不方便

claude-swap 一次解決：備份 → 切換 → 自動更新 → 跨平台 credential 安全儲存。

1.3 相較於手動操作

操作手動claude-swap
切換帳號登出 → 登入（~30 秒 OAuth flow）cswap --switch（< 1 秒）
查看用量各平台 web 查看cswap --list（含 5h/7d usage + reset time）
跨機器遷移手動複製 credential filescswap --export / --import
安全儲存自行管理macOS Keychain / 0o600 file permissions

2. 安裝指南

2.1 使用 uv（推薦）

1uv tool install claude-swap

2.2 使用 pipx

1pipx install claude-swap

2.3 從原始碼安裝

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

2.4 更新

1cswap --upgrade        # 自動偵測 uv/pipx 並升級
2# 或手動：
3uv tool upgrade claude-swap
4pipx upgrade claude-swap

2.5 驗證安裝

1cswap --help
2# 應顯示完整的 CLI 說明

2.6 系統需求

  • Python 3.12+
  • Claude Code 已安裝並登入至少一個帳號

3. 核心架構解析

3.1 系統架構總覽


graph TB
    subgraph "Claude Code"
        CC_CRED[~/.claude/.credentials.json]
        CC_CONF[~/.claude.json]
    end

    subgraph "claude-swap Core"
        CLI[cli.py
argparse entry]
        SW[switcher.py
核心切換邏輯]
        OAUTH[oauth.py
OAuth token 管理]
        TRANS[transfer.py
匯出入]
        TUI[tui.py
互動式選單]
        MIG[migrations.py
資料遷移]
    end

    subgraph "Credential Storage"
        MAC[macOS Keychain
/usr/bin/security CLI]
        LIN[Linux/WSL
XDG file-based
0o600 permissions]
        WIN[Windows
file-based
credentials/]
    end

    subgraph "Backup Storage"
        BK_MAC[~/.claude-swap-backup/]
        BK_LIN[~/.local/share/claude-swap/]
        BK_WIN[~/.claude-swap-backup/]
    end

    CLI --> SW & TRANS & TUI
    SW --> OAUTH & MIG
    SW -->|read/write| CC_CRED & CC_CONF
    SW -->|backup/restore| MAC & LIN & WIN
    MAC --> BK_MAC
    LIN --> BK_LIN
    WIN --> BK_WIN
    OAUTH -->|refresh token| ANTH[platform.claude.com]
    OAUTH -->|fetch usage| ANTH

3.2 帳號切換資料流


sequenceDiagram
    participant User
    participant cswap as cswap CLI
    participant SW as switcher.py
    participant Cred as Credential Store
    participant CC as Claude Code

    User->>cswap: cswap --switch-to 2
    cswap->>SW: switch_account(2)
    SW->>SW: Create SwitchTransaction
(backup current state)
    SW->>Cred: Read account 2 credentials
    Cred-->>SW: credentials + config
    SW->>CC: Write ~/.claude/.credentials.json
    SW->>CC: Write ~/.claude.json
    SW->>SW: Update sequence file
(activeAccountNumber=2)
    SW-->>User: Switched to Account 2

    Note over SW: On failure → Transaction rollback
restores original credentials

3.3 模組職責

switcher.py（1,734 行）——核心引擎：

  • ClaudeAccountSwitcher 類別：帳號 CRUD、切換、rollback
  • SwitchTransaction：原子性切換操作，失敗時自動 rollback
  • 平台偵測 → 選擇 credential backend（Keychain vs file-based）
  • FileLock 防止並行操作衝突

oauth.py（306 行）——OAuth 管理：

  • Token refresh（platform.claude.com/v1/oauth/token）
  • Usage API 查詢（5h/7d 用量 + reset time）
  • Token 過期檢查（含 5 分鐘 buffer）

macos_keychain.py（163 行）——macOS 安全存取：

  • 呼叫 /usr/bin/security（hardcoded path，防 PATH hijacking）
  • Secrets 透過 stdin 傳入（不出現在 process argv）
  • Hex encoding 避免 escaping 問題

transfer.py（448 行）——匯出入：

  • Portable JSON envelope 格式
  • 支援單帳號 / 全帳號 / full backup（含 ~/.claude.json）
  • Dedup：匯入時自動跳過已存在的帳號

migrations.py（522 行）——資料遷移：

  • Legacy ~/.claude-swap-backup/ → XDG path
  • keyring → macOS Keychain（v0.12.0 新增）
  • 中斷恢復機制（flag file + idempotent）

4. CLI 命令詳細用法

4.1 帳號管理

 1# 新增帳號（從目前登入的 Claude Code 帳號）
 2cswap --add-account
 3
 4# 新增到指定 slot
 5cswap --add-account --slot 3
 6
 7# 從 raw OAuth token 新增（headless server 適用）
 8cswap --add-token sk-ant-oat01-...
 9cswap --add-token sk-ant-oat01-... --slot 3 --email user@example.com
10cswap --add-token - --slot 3    # 從 stdin 讀取
11
12# 移除帳號
13cswap --remove-account 2

4.2 切換帳號

1# 輪替到下一個帳號
2cswap --switch
3
4# 切換到指定帳號（by number or email）
5cswap --switch-to 2
6cswap --switch-to user@example.com

切換後是否需要重啟？

  • Linux / Windows：通常不需要——Claude Code 會自動偵測 credential file 變化
  • macOS：Keychain 有 ~30 秒 cache，等 cache 過期後自動生效；想立即生效需重啟 Claude Code

4.3 查看狀態

1# 列出所有帳號（含 5h/7d usage 和 reset time）
2cswap --list
3
4# 顯示目前帳號
5cswap --status

--list 輸出範例：

1Account 1: user1@example.com [personal]
2  5h usage: 42% | 7d usage: 18% | resets in 2h 15m
3
4Account 2: user2@corp.com [Acme Inc]  ← active
5  5h usage: 89% | 7d usage: 55% | resets in 45m

4.4 匯出入（跨機器遷移）

 1# 匯出所有帳號
 2cswap --export backup.cswap
 3
 4# 匯出單一帳號
 5cswap --export backup.cswap --account 2
 6
 7# 匯出完整備份（含 ~/.claude.json）
 8cswap --export backup.cswap --full
 9
10# 匯入（自動跳過已存在的帳號）
11cswap --import backup.cswap
12
13# 強制覆蓋
14cswap --import backup.cswap --force

安全注意：匯出檔為 plaintext JSON。如需加密：

1cswap --export - | gpg -c > backup.gpg
2gpg -d backup.gpg | cswap --import -

4.5 互動式 TUI

1cswap --tui

啟動 curses-based 互動選單，支援 arrow key 選擇帳號、新增、切換等操作。

4.6 其他命令

1cswap --upgrade   # 升級到最新版
2cswap --purge     # 刪除所有 claude-swap 資料

5. 應用場景

5.1 個人多帳號切換

最基本的使用場景——個人帳號 + 公司帳號之間切換：

 1# 初次設定
 2# 1. 用個人帳號登入 Claude Code
 3cswap --add-account     # → Account 1
 4
 5# 2. 登出，用公司帳號登入 Claude Code
 6cswap --add-account     # → Account 2
 7
 8# 日常使用
 9cswap --switch-to 1     # 切到個人帳號
10cswap --switch-to 2     # 切到公司帳號
11cswap --switch           # 輪替到下一個

5.2 Usage Limit 輪替

當一個帳號的 5h usage 到頂，快速切到另一個帳號：

1cswap --list             # 查看各帳號用量
2# Account 1: 99% 5h usage → 切換
3cswap --switch-to 2      # 切到用量較低的帳號

5.3 Headless Server / CI 環境

在沒有瀏覽器的環境使用 setup-token 新增帳號：

1# 在有瀏覽器的機器上取得 token
2claude setup-token
3
4# 在 headless server 上
5cswap --add-token sk-ant-oat01-... --email ci@example.com

5.4 跨機器遷移

1# 舊機器
2cswap --export backup.cswap --full
3
4# 新機器
5cswap --import backup.cswap

5.5 Token 過期重新整理

OAuth token 過期後，重新登入該帳號：

1# Claude Code 會提示 /login
2# 登入後：
3cswap --add-account      # 自動偵測到已存在帳號，更新 credential

6. 資安掃描報告

6.1 掃描範圍

  • 原始碼 src/claude_swap/（18 個模組，4,838 行）
  • 檢查項目：credential 儲存安全、subprocess 使用、網路請求、檔案權限

6.2 發現與評估

🟢 整體風險等級：低

項目等級說明
macOS Keychain 存取🟢 佳使用 hardcoded /usr/bin/security 路徑，防 PATH hijacking
Secret 傳遞方式🟢 佳透過 security -i stdin 傳入，不出現在 process argv
檔案權限🟢 佳credential 檔 0o600、目錄 0o700，全面保護
subprocess 使用🟢 低僅用於 macOS security CLI，參數非使用者可控
OAuth 網路請求🟢 低HTTPS 連線至 platform.claude.com，用於 token refresh 與 usage 查詢
匯出檔安全🟡 注意--export 為 plaintext JSON（文件已明確建議使用者自行加密）
Update check🟡 注意查詢 PyPI 最新版本（可自行不使用 --upgrade）
FileLock🟢 佳檔案鎖防止並行操作衝突導致 credential 損壞
Transaction rollback🟢 佳SwitchTransaction 確保切換失敗時自動恢復原始 credential
Migration safety🟢 佳Flag file + idempotent 設計，支援中斷後恢復
No eval / exec🟢 佳完全沒有 eval()、exec()、shell=True

6.3 安全建議

  1. 匯出檔務必加密：cswap --export - | gpg -c > backup.gpg
  2. 備份目錄保護已自動處理：0o600 / 0o700 由 cswap 自動設定
  3. macOS Keychain：v0.12.0 起改用原生 security CLI，比 Python keyring library 更穩定安全
  4. Token 定期更新：過期 token 重新 --add-account 即可更新

7. FAQ

Q1: 切換帳號會被 ban 嗎？

README 未提及被 ban 的風險，Issue #31 也有討論。claude-swap 只是在本地切換 credential，等同於在不同裝置登入不同帳號，這是正常的 OAuth 使用模式。

Q2: 支援哪些平台？

macOS、Linux、WSL、Windows。每個平台有不同的 credential 儲存方式：

  • macOS：Keychain（v0.12.0+，原生 security CLI）
  • Linux/WSL：file-based + XDG path（~/.local/share/claude-swap/）
  • Windows：file-based（~/.claude-swap-backup/credentials/）

Q3: 支援 Codex CLI 嗎？

尚未。Issue #15 為 open feature request。目前僅支援 Claude Code CLI 與 VS Code extension。

Q4: 一個 VS Code 視窗一個帳號可以嗎？

尚未。Issue #19 為 open feature request。目前所有 Claude Code 實例共享同一組 credential。

Q5: Token 過期怎麼辦？

直接用該帳號重新登入 Claude Code，然後 cswap --add-account。cswap 會自動偵測到是同一個帳號，更新 credential 而不是建立重複。

Q6: 匯出檔格式？

Portable JSON envelope，包含帳號的 OAuth credentials + config。Plaintext，建議搭配 GPG 加密。

8. 進階技巧

8.1 Usage 監控腳本

1# 檢查所有帳號用量，自動切換到最低的
2cswap --list
3# 觀察 5h usage 百分比，手動或腳本化決定切換

8.2 搭配 Shell Alias

1# ~/.bashrc 或 ~/.zshrc
2alias cs='cswap --switch'
3alias csl='cswap --list'
4alias css='cswap --status'
5alias cst='cswap --tui'

8.3 多帳號快速 Setup

1# 一次設定多帳號（需逐個登入）
2for i in 1 2 3; do
3  echo "請登入第 $i 個帳號，完成後按 Enter"
4  read
5  cswap --add-account
6done

8.4 XDG 自定義路徑

Linux 使用者可透過環境變數自定 backup 路徑：

1export XDG_DATA_HOME=~/my-data
2# 備份將存於 ~/my-data/claude-swap/

8.5 Claude Config 目錄自定義

1export CLAUDE_CONFIG_DIR=/custom/claude/config
2# cswap 會自動使用此路徑

9. 整合進其他工作流

9.1 與 AIKT Pipeline 整合

在長時間 research pipeline 運行中，cswap 可用來：

  1. Usage limit 輪替：當一個帳號的 5h limit 到頂，快速切到下一個帳號繼續 session
  2. 多帳號成本分攤：不同 research domain 使用不同帳號，便於成本追蹤
1# 在 pipeline 中間檢查用量
2cswap --list
3# 如果當前帳號用量 > 90%
4cswap --switch

9.2 與 agentsview 搭配

agentsview 追蹤所有 agent session 的 token 用量，cswap 則管理帳號切換：

1# 查看帳號 usage（cswap）
2cswap --list
3
4# 查看 session 細節（agentsview）
5agentsview usage daily --breakdown

9.3 CI/CD 環境自動化

1# 在 CI 中使用 setup-token 設定帳號
2cswap --add-token "$CLAUDE_TOKEN" --email ci@example.com --slot 1
3cswap --add-token "$CLAUDE_TOKEN_2" --email ci2@example.com --slot 2
4
5# 自動切換
6cswap --switch-to 1

10. 重點摘要 Checklist

  • 安裝 claude-swap（uv tool install claude-swap）
  • 用第一個帳號登入 Claude Code → cswap --add-account
  • 用第二個帳號登入 Claude Code → cswap --add-account
  • 試跑 cswap --list 確認帳號列表正確
  • 試跑 cswap --switch 確認切換正常
  • 確認切換後 Claude Code 能正常使用（Linux/Win 自動，macOS 等 ~30 秒）
  • （選用）設定 shell alias 加速操作
  • （選用）cswap --export backup.cswap 備份帳號資料
  • （選用）匯出檔用 GPG 加密保護

11. 進一步閱讀