switch-claude-cli

v1.4.5

Published

2 months ago

Smart Claude API provider switcher with availability detection and caching

0High
0Medium
0Low

dearmrzhang

claude api cli switcher anthropic ai provider third-party

Switch Claude CLI

一个智能的 Claude API Provider 切换工具，帮助你在多个第三方 Claude API 服务之间快速切换。

🌍 多语言文档

🇨🇳 中文 | 🇺🇸 English | 🇯🇵 日本語

👉 开发初衷见我的微信公众号文章：我受够了复制粘贴 Claude Code API ，于是写了个工具，3秒自动切换

📋 文档和更新

📄 更新日志 - 查看所有版本更新记录

✨ 功能特性

🚀 智能检测：自动检测 API 可用性，支持多端点测试和重试机制
⚡ 缓存机制：5分钟内缓存检测结果，避免重复检测
🎯 灵活选择：支持自动选择默认 provider 或交互式手动选择
🔧 配置管理：完整的 provider 增删改查功能
📊 详细日志：可选的详细模式显示响应时间和错误信息
🛡️ 错误处理：完善的错误处理和用户友好的提示信息
🔔 版本更新：自动提醒用户更新到最新版本
📦 配置备份：支持导出、导入、备份和恢复配置
📺 优化显示：显示完整API名称，智能适应终端宽度
✨ TypeScript重构：v1.4.0 新增！完全 TypeScript 重构，类型安全，模块化架构
📈 使用统计：v1.4.0 新增！记录使用统计，支持导出和重置功能
🌐 代理支持：v1.4.2 新增！支持为每个 Provider 配置 HTTP/HTTPS 代理

📦 安装

系统要求

Node.js: 18.0.0 或更高版本
npm: 8.0.0 或更高版本（或 yarn 1.22+）
操作系统: Windows、macOS、Linux

从 NPM 安装（推荐）

npm install -g switch-claude-cli

从源码安装

git clone https://github.com/yak33/switch-claude-cli.git
cd switch-claude-cli
npm install
npm run build
npm link

注意：从 v1.4.0 开始，项目使用 TypeScript，需要先构建再安装。

🚀 快速开始

1. 安装后首次运行

switch-claude
# 或使用快捷命令
scl

首次运行时，工具会自动：

创建配置目录 ~/.switch-claude
生成示例配置文件 ~/.switch-claude/providers.json
提供编辑配置的命令

2. 编辑配置文件

根据提示编辑配置文件：

# Windows
notepad "C:\Users\YourName\.switch-claude\providers.json"

# macOS
open ~/.switch-claude/providers.json

# Linux
nano ~/.switch-claude/providers.json

将示例内容替换为你的真实 API 信息：

[
  {
    "name": "Veloera",
    "baseUrl": "https://zone.veloera.org",
    "key": "sk-your-real-api-key-here",
    "default": true
  },
  {
    "name": "NonoCode",
    "baseUrl": "https://claude.nonocode.cn/api",
    "key": "cr_your-real-api-key-here"
  },
  {
    "name": "AnyRouter-WithProxy",
    "baseUrl": "https://api.anyrouter.com",
    "key": "sk-your-real-api-key-here",
    "proxy": "http://127.0.0.1:7897"
  }
]

代理配置说明 🌐：

如果某个 API 提供方需要通过代理访问（如 VPN），可以在配置中添加 proxy 字段
proxy 格式：http://代理地址:端口（例如：http://127.0.0.1:7897）
未配置 proxy 字段的 Provider 会直接连接，不使用代理

3. 再次运行开始使用

switch-claude

📖 使用方法

快捷命令 ⚡

为了简化输入，工具提供了多个命令别名，完全等价于 switch-claude：

# 以下命令完全等价
switch-claude        <==>  scl  <==>  ccc
switch-claude 1      <==>  scl 1      <==>  ccc 1
switch-claude -v     <==>  scl -v     <==>  ccc -v
switch-claude --list <==>  scl --list <==>  ccc --list

别名说明：

switch-claude - 完整命令，语义清晰
scl - Switch CLaude 首字母缩写
ccc - Choose Claude CLI 缩写

基本用法

# 交互式选择 provider
switch-claude
# 或
scl
# 或
ccc

# 直接选择编号为 1 的 provider
scl 1

# 只设置环境变量，不启动 claude
scl -e 1

# 查看版本并检查更新
scl --version

检测和缓存

# 强制刷新缓存，重新检测所有 provider
scl --refresh

# 显示详细的检测信息（响应时间、错误详情等）
scl -v 1

配置管理

# 列出所有 providers
switch-claude --list

# 添加新的 provider
switch-claude --add

# 编辑编号为 2 的 provider
switch-claude --edit 2

# 删除编号为 2 的 provider
switch-claude --remove 2

# 设置编号为 1 的 provider 为默认
switch-claude --set-default 1

# 清除默认设置（每次都需要手动选择）
switch-claude --clear-default

配置备份与恢复 📦 v1.3.0

# 导出配置到文件（自动添加时间戳）
switch-claude --export

# 导出到指定文件
switch-claude --export my-providers.json

# 从文件导入配置（替换现有配置）
switch-claude --import backup.json

# 导入并合并（不会覆盖已有的同名 provider）
switch-claude --import new-providers.json --merge

# 备份到系统目录（~/.switch-claude/backups/）
switch-claude --backup

# 查看所有备份
switch-claude --list-backups

功能特点：

🔒 导入前自动备份原配置
🔄 支持合并导入，避免覆盖现有配置
📅 导出文件包含版本和时间信息
🗑️ 自动清理旧备份（保留最近10个）
📁 备份存储在 ~/.switch-claude/backups/ 目录

版本更新 🆕 v1.3.0

# 查看当前版本并检查更新
switch-claude --version
# 或
switch-claude -V

# 手动检查更新
switch-claude --check-update

自动更新提醒：

🔔 每次运行时自动检查是否有新版本（每6小时检查一次）
📦 如果有新版本，会显示醒目的黄色边框提示
🚀 提供便捷的更新命令

使用统计 📊 v1.4.0

# 查看使用统计信息
switch-claude --stats

# 导出统计数据到文件
switch-claude --export-stats
switch-claude --export-stats my-stats.json

# 重置所有统计数据
switch-claude --reset-stats

统计功能特点：

📈 命令使用统计：记录每个命令的使用频率和时间
🎯 Provider 性能统计：跟踪每个 API 提供商的成功率和响应时间
⏰ 24小时使用分布：可视化显示使用时间分布
🐛 错误统计分析：记录和分析各种错误类型
📤 数据导出：支持导出统计数据到 JSON 文件
🔄 数据重置：支持清空所有统计数据

统计数据存储：

统计数据存储在 ~/.switch-claude/usage-stats.json
数据会自动保存，无需手动操作
重装或升级时统计数据会保留

帮助信息

# 显示完整帮助
switch-claude --help

🔧 命令行选项

| 选项 | 简写 | 描述 | | ---------------------- | ---- | --------------------------------------- | | --help | -h | 显示帮助信息 | | --version | -V | 显示版本信息并检查更新 | | --refresh | -r | 强制刷新缓存，重新检测所有 provider | | --verbose | -v | 显示详细的调试信息 | | --list | -l | 只列出 providers 不启动 claude | | --env-only | -e | 只设置环境变量，不启动 claude | | --add | | 添加新的 provider | | --remove <编号> | | 删除指定编号的 provider | | --set-default <编号> | | 设置指定编号的 provider 为默认 | | --clear-default | | 清除默认 provider（每次都需要手动选择） | | --check-update | | 手动检查版本更新 | | --export [文件名] | | 导出配置到文件 | | --import <文件名> | | 从文件导入配置 | | --merge | | 与 --import 配合使用，合并而不是替换 | | --backup | | 备份当前配置到系统目录 | | --list-backups | | 列出所有备份文件 | | --stats | | 显示使用统计信息 | | --export-stats [文件名] | | 导出统计数据到文件 | | --reset-stats | | 重置所有统计数据 |

📁 配置文件位置

配置目录结构

~/.switch-claude/
├── providers.json    # API 配置文件
├── cache.json       # 检测结果缓存
├── usage-stats.json       # 使用统计数据 (v1.4.0+)
└── backups/         # 备份文件目录
    ├── backup-2024-09-22T10-30-00.json
    └── backup-2024-09-22T14-15-30.json

配置目录位置：

Windows: C:\Users\YourName\.switch-claude\
macOS: /Users/YourName/.switch-claude/
Linux: /home/YourName/.switch-claude/

providers.json

[
  {
    "name": "Provider名称", // 必需：显示名称
    "baseUrl": "https://api.url", // 必需：API Base URL
    "key": "your-api-key", // 必需：API Key（支持各种格式）
    "default": true // 可选：是否为默认 provider
  }
]

配置安全

自动创建：首次运行自动创建配置目录和示例文件
用户目录：配置文件存储在用户主目录下，避免权限问题
API Key 保护：显示时会被部分遮码（只显示前12位）
缓存隔离：每个用户的缓存文件独立存储

🎯 使用场景

场景一：有稳定的主要 Provider

设置一个默认 provider：

switch-claude --set-default 1

日常使用（自动选择默认）：

switch-claude

临时切换到其他 provider：

switch-claude 2

场景二：经常切换 Provider

清除默认设置：

switch-claude --clear-default

每次运行都会显示选择界面：

switch-claude

场景三：调试和测试

详细模式查看所有信息：

switch-claude -v --refresh

只设置环境变量，手动运行 claude：

switch-claude -e 1
claude

🔍 API 检测机制

工具使用多层检测策略确保 API 可用性：

轻量级检测：首先尝试 GET /v1/models
功能性检测：然后尝试 POST /v1/messages（最小 token 请求）
重试机制：每个端点最多重试 3 次
超时控制：单次请求超时 8 秒
错误分类：区分网络错误、认证错误、服务错误等

🗂️ 缓存机制

缓存时长：5分钟
缓存文件：cache.json
缓存标识：基于 baseUrl 和 API Key 的后8位
强制刷新：使用 --refresh 参数

❗ 错误处理

如果遇到 "spawn claude ENOENT" 错误：

检查安装：确保 Claude Code 已正确安装
检查 PATH：确保 claude 命令在系统 PATH 中
使用 --env-only：

switch-claude -e 1
# 然后手动运行
claude

API 连接问题

常见错误及解决方案：

DNS解析失败：检查网络连接和 URL 正确性
连接被拒绝：检查防火墙设置
连接超时：网络问题或服务不可用
HTTP 401：API Key 无效或过期
HTTP 403：权限不足或配额用完

🔒 安全注意事项

配置文件安全

用户目录隔离：配置文件存储在 ~/.switch-claude/ 下，每个用户独立
自动初始化：首次运行自动创建配置目录和示例文件
API Key 保护：显示时会被部分遮码（只显示前12位）

文件权限：在 Unix 系统上建议设置适当的文件权限：

chmod 700 ~/.switch-claude          # 仅所有者可访问目录
chmod 600 ~/.switch-claude/*        # 仅所有者可读写文件

数据安全

✅ 配置文件存储在用户目录，不会影响其他用户
✅ 缓存文件独立存储，避免冲突
✅ 敏感信息不会记录到日志中
⚠️ 定期轮换 API Key 以确保安全
⚠️ 谨慎分享 配置文件或截图

🔧 开发

代码规范

# 运行 ESLint 检查
npm run lint

# 自动修复 ESLint 问题
npm run lint:fix

# 运行 Prettier 格式化
npm run format

# 检查 Prettier 格式
npm run format:check

测试

# 运行所有测试
npm test

# 观察模式
npm run test:watch

# 测试覆盖率
npm run test:coverage

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🆘 常见问题

Q: 如何添加新的 provider？

A: 使用 switch-claude --add 命令，按提示输入信息。

Q: 如何备份配置？

A: 有多种方式：

使用 switch-claude --export 导出到文件
使用 switch-claude --backup 自动备份到系统目录
手动复制 ~/.switch-claude/providers.json 文件

Q: 工具支持哪些平台？

A: 支持 Windows、macOS 和 Linux。

Q: 如何更新工具？

A: 工具会自动提醒你更新！你也可以：

运行 switch-claude --version 查看是否有新版本
运行 switch-claude --check-update 手动检查更新
使用 npm update -g switch-claude-cli 更新到最新版本

Q: 缓存文件可以删除吗？

A: 可以。删除 cache.json 不会影响功能，只是下次运行会重新检测。

项目地址: GitHub
问题反馈: Issues
NPM 包: switch-claude-cli
更新日志: CHANGELOG.md