claude-code-account-switch

v3.10.3

Published

3 days ago

Claude Code 多账号切换工具，支持 Windows/macOS/Linux/WSL，OAuth + API Key 双模式，多端 web 共享同步

0High
0Medium
0Low

ahmaderic

claude claude-code account switch switcher credentials oauth keychain wsl

CCS - Claude Code Account Switcher

Windows / macOS / Linux / WSL 多平台 CLI 工具，通过备份和还原 Claude Code 凭证（Windows/Linux 文件、macOS Keychain）及 ~/.claude.json 中的账号字段，实现 Claude Code 多账号一键切换。支持 Web UI 操作和多端 LAN 内共享同步登录态，同时支持 OAuth 和 API Key 两种账号类型。

不代理请求，不切换 profile 目录，不影响 .claude/sessions、history.jsonl 和项目状态。

⚠️ 安全须知：Web 服务本身不带鉴权，监听端口的任何人都能通过 API 切换账号、查看共享密钥、导入/删除账号。
默认绑 127.0.0.1（仅本机访问）→ 安全
共享同步切换到 0.0.0.0（LAN 可达）后，仅限可信内网/VPN 使用，不要暴露到公网，也避免在共用 Wi-Fi 等不可信环境启用
共享同步的 Bearer 密钥保护 /api/share/* 端点，但不保护其他 API（/api/switch、/api/import 等）

npm：https://www.npmjs.com/package/claude-code-account-switch
GitHub：https://github.com/ALaDingAhmad/claude-code-account-switch
Gitee 镜像：https://gitee.com/superas/claude-code-account-switch

安装

# 推荐：从 npm 安装
npm install -g claude-code-account-switch

# 或本地源码
git clone https://github.com/ALaDingAhmad/claude-code-account-switch.git
cd claude-code-account-switch && npm install -g .

环境要求：Node.js 18+。Windows 安装后自动在桌面创建「CCS 管理界面」快捷方式（mac/Linux 不创建）。

Web UI（推荐入口）

启动后浏览器自动打开 http://127.0.0.1:7899：

ccs web                # 默认 7899，端口被占自动 +1
ccs web 8080           # 指定端口

页面功能：

当前账号 hero 区一键切换 / 退出登录
导入账号（OAuth 一键导入当前 live、API Key 填 Token + Base URL）
编辑账号（OAuth 显示 token/套餐/过期，API Key 可改 Token 和 baseUrl）
删除账号
多端共享同步配置区（见下节）
账号用量监控开关（v3.8.8+）：勾选即在后台 spawn 守护进程独立轮询用量并自动切换，状态卡片展示 pid、运行时长、最近 30 行日志
顶部显示版本号 + 关闭服务按钮

Windows 双击桌面快捷方式即可启动（无 cmd 窗口）。普通模式 web 服务 5 分钟无请求自动关闭。

多端共享同步

架构：1 个主节点 + N 个从节点（主从同步）

主节点：HTTP 服务端，不主动发请求，只响应从节点的查询。它是数据的权威源（所有从节点都跟它对账）。配置里「主节点 URL」留空
从节点：每 30 秒访问主节点，按账号粒度比较 hash + updatedAt：自己新就 push 给主节点，主节点新就 pull。任意从节点的改动都会先同步到主节点，再通过其他从节点的轮询扩散到所有节点

activeAccount 不同步，各端独立。账号删除会通过墓碑同步（v3.8.0+，按 createdAt 和 deletedAt 时间戳决策，避免删后重导入被对端再次推回）。

一键命令（推荐）

Step 1 — 起主节点（任选一台稳定常驻、LAN 可达的机器）：

ccs web share

终端打印主节点 URL 和自动生成的 Secret：

本机角色  : 主节点（被动响应，等待从节点访问）
本机 URL  : http://192.168.1.168:7899
共享密钥  : ca3eace3acdc1e39db7995e2ffc52215ad0dc9ba7780d715de223c7db814ea47

Step 2 — 每个从节点一行命令（用 Step 1 给的 URL 和 Secret）：

ccs web share --peer http://192.168.1.168:7899 --secret <粘贴 Secret>

N 个从节点重复 Step 2 即可，从节点之间不需要互联，全靠主节点扇出。

Web UI 配置（推荐入口）

也可以在 Web UI「多端共享同步」区域勾选启用，填好 URL 和 Secret 保存。

CLI 一键模式

任一端跑 ccs web share，后台守护启动 web 并自动打印 URL+Secret：

$ ccs web share
URL    : http://192.168.1.168:7900
Secret : ca3eace3acdc1e39db7995e2ffc52215ad0dc9ba7780d715de223c7db814ea47
角色   : 被动方（等待对端访问）
停止服务: ccs web stop

对端粘贴提示行即可：

ccs share enable --peer http://192.168.1.168:7900 --secret <粘贴 secret>
ccs web 7899

注意事项

每次 OAuth refresh 会 rotate refresh_token，旧的立即作废。share sync 启用时本端刷完后通过主动方自动同步到其他端；如同步链路断开期间发生 refresh，未同步的端会失效
凭证走 LAN 明文（仅 Bearer 鉴权），仅建议同一可信网络内使用
启用 share 后 web 不退 idle，需 ccs web stop 或浏览器访问 /api/shutdown 停止
macOS 端理论支持（通过 security CLI 读写 Keychain），第一次接收同步弹 Keychain 授权框选「始终允许」后免确认；未在真实多机环境验证过

CLI 用法

Web UI 是推荐入口。CLI 用于无浏览器场景（Linux 服务器、自动化脚本）或快捷操作。完整命令用 ccs --help 查看。

# 切换
ccs <name>                # 切到 <name>
ccs                       # 看当前状态 + 账号列表 + web/share 运行状态

# 导入：在 Claude Code 登录目标账号后
ccs import <name>

# 共享同步
ccs web share             # 一键后台启动
ccs share enable --peer http://X:7899 --secret abc
ccs web stop

API Key 账号

支持通过 ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL 使用第三方 API 服务：

在 Web UI「导入 → API Key」标签填入名称、Token 和 Base URL（或用 CLI）
切换到该账号后 CCS 自动写入 ~/.claude/settings.json 的 env 字段并清空 OAuth 凭证
切回 OAuth 账号时自动清除 API Key 环境变量

状态栏脚本

配合 ccs 切换账号，让 Claude Code 状态栏实时显示当前真实账号信息和用量。

切换账号后状态栏自动清缓存，下次刷新立即显示新账号信息。输出：

第一行：user@host MSYSTEM 当前目录
第二行：模型 | ctx 用量 | 累计费用 | 5h / 7d 速率限制
第三行：OAuth 姓名、邮箱、套餐
第四行（条件性）：最近 5 分钟内被监控守护切过账号时显示「最近切到 X（HH:MM）」

在 Web UI 的「Claude Code 状态栏」区块一键安装 / 卸载。

自动切换守护进程

独立轮询用量、在撞墙前主动切换；入口：Web UI「账号用量监控」区块勾选启用。

用量 < 90% 闲时低频轮询，越接近 99% 越频繁
撞 5h 墙时自动切到可用账号；所有账号都用尽时切到最快能恢复的号并等到它恢复
Web UI 状态卡片展示运行状态、最近日志，10s 自动刷新
守护进程意外死亡会被自动拉起（看门狗 + Windows 登录自启）

版本变更

v3.10.2：修复用量监控反复误切账号的 bug；所有账号都用尽时改为切到最快恢复的号并等到它恢复
v3.10.1：开机后等环境就绪再启动守护，避免开机瞬间误判失败
v3.10.0：守护进程意外退出会自动拉起；Windows 开机自动启动
v3.9.0：状态栏只展示用量，切换决策统一交给 Web UI 后台守护
v3.8.9：守护进程更稳，不会因为用量没到阈值就提前退出
v3.8.8：Web UI 新增「账号用量监控」开关，不依赖状态栏也能用
v3.8.7：用量监控独立成后台守护进程
v3.8.6：自动切换后状态栏提示重启 Claude Code
v3.8.4：候选账号查不到用量时也能乐观切过去（v3.10.2 已收紧）
v3.8.3：ccs --version + 状态栏显示版本号
v3.8.2：状态栏脚本支持 5h ≥ 99% 自动切账号
v3.8.1：状态栏 macOS 兼容
v3.8.0：账号删除多端同步（解决删了又被对端推回的 bug）
v3.7.13：修复状态栏装错位置导致不显示
v3.7.12：ccs web 记住上次端口，URL 不再老变
v3.7.11：切回 OAuth 后立即生效，老 Claude 进程无需重启
v3.7.10：ccs web share 复用本机服务，不再抢端口
v3.7.9：ccs web share --secret 一行命令邀请对端
v3.7.8：ccs web share 启动提示按本机角色分支
v3.7.7：共享同步方向判据更可靠
v3.7.6：修复共享同步「无差异/掉线」bug
v3.7.5：README 和 Web UI 加安全须知 + footer
v3.7.4：Web UI 一键安装 / 卸载状态栏
v3.7.3：共享同步术语统一「主节点 / 从节点」
v3.7.2：README 重排，加徽章和多仓库链接
v3.7.1：v3.7.0 后续打磨（后台模式、端口自动避让、CLI 子命令系列）
v3.7.0：多端共享同步（Windows ↔ WSL/Linux/Mac）
v3.6.0：切换前自动续期，避免切回时凭证已失效
v3.5.0：Web UI 新增「退出当前账号」
v3.4.0：Web 服务 5 分钟空闲自动退出
v3.3.1：活跃 OAuth 账号显示实时反映续期
v3.3.0：macOS 通过 Keychain 读写 OAuth 凭证
v3.2.0：Windows 桌面快捷方式无窗口启动
v3.1.0：API Key 账号支持；Web UI 导入 / 编辑 / 删除
v3.0.0：纯文件操作模式

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme