Package Exports
- switch-claude-cli
- switch-claude-cli/dist/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (switch-claude-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
Switch Claude CLI
一个智能的 Claude API Provider 切换工具，帮助你在多个第三方 Claude API 服务之间快速切换。
👉 开发初衷见我的微信公众号文章：我受够了复制粘贴 Claude Code API ，于是写了个工具，3秒自动切换
📋 文档和更新
- 📄 更新日志 - 查看所有版本更新记录
- 🚀 TypeScript重构分支 - 全新的模块化架构正在开发中！
- ✨ 完整的TypeScript类型安全
- 🏗️ 模块化架构，更易维护和扩展
- 🧪 更好的测试支持
✨ 功能特性
- 🚀 智能检测：自动检测 API 可用性，支持多端点测试和重试机制
- ⚡ 缓存机制：5分钟内缓存检测结果，避免重复检测
- 🎯 灵活选择：支持自动选择默认 provider 或交互式手动选择
- 🔧 配置管理：完整的 provider 增删改查功能
- 📊 详细日志：可选的详细模式显示响应时间和错误信息
- 🛡️ 错误处理：完善的错误处理和用户友好的提示信息
- 🔔 版本更新：v1.3.0 新增！自动提醒用户更新到最新版本
- 📦 配置备份：v1.3.0 新增！支持导出、导入、备份和恢复配置
- 📺 优化显示：v1.3.3 新增！显示完整API名称，智能适应终端宽度
📦 安装
从 NPM 安装（推荐）
npm install -g switch-claude-cli🚀 预发布版本 (TypeScript 重构)
我们提供了完全重构的 TypeScript 版本供测试，具有更好的代码结构和类型安全：
# 安装 Beta 版本（推荐用于测试）
npm install -g switch-claude-cli@beta
# 安装 Alpha 版本（最新开发版本）
npm install -g switch-claude-cli@alphaBeta 版本特性：
- ✨ 完全 TypeScript 重构，类型安全
- 🏗️ 模块化架构，更易维护和扩展
- 🧪 完整的单元测试覆盖
- 🐛 修复了原版的一些已知问题
- 🔄 与原版功能完全兼容
- 📦 更好的错误处理和用户体验
注意事项：
- Beta 版本仍在测试阶段，建议在非生产环境使用
- 如遇到问题，请在 GitHub Issues 反馈
- 配置文件与稳定版本完全兼容，可以无缝切换
切换版本：
# 切换回稳定版本
npm install -g switch-claude-cli@latest
# 切换到 Beta 版本
npm install -g switch-claude-cli@beta从源码安装
git clone https://github.com/yak33/switch-claude-cli.git
cd switch-claude-cli
npm install
npm link🚀 快速开始
1. 安装后首次运行
switch-claude首次运行时，工具会自动：
- 创建配置目录
~/.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"
}
]3. 再次运行开始使用
switch-claude📖 使用方法
基本用法
# 交互式选择 provider
switch-claude
# 直接选择编号为 1 的 provider
switch-claude 1
# 只设置环境变量，不启动 claude
switch-claude -e 1
# 查看版本并检查更新
switch-claude --version检测和缓存
# 强制刷新缓存，重新检测所有 provider
switch-claude --refresh
# 显示详细的检测信息（响应时间、错误详情等）
switch-claude -v 1配置管理
# 列出所有 providers
switch-claude --list
# 添加新的 provider
switch-claude --add
# 删除编号为 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小时检查一次）
- 📦 如果有新版本，会显示醒目的黄色边框提示
- 🚀 提供便捷的更新命令
帮助信息
# 显示完整帮助
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 |
列出所有备份文件 |
📁 配置文件位置
配置目录结构
~/.switch-claude/
├── providers.json # API 配置文件
├── cache.json # 检测结果缓存
└── 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分钟
- 缓存文件：
.switch-claude-cache.json - 缓存标识：基于 baseUrl 和 API Key 的后8位
- 强制刷新：使用
--refresh参数
❗ 错误处理
Claude 命令未找到
如果遇到 "spawn claude ENOENT" 错误：
- 检查安装：确保 Claude Code 已正确安装
- 检查 PATH：确保 claude 命令在系统 PATH 中
- 使用 --env-only：
switch-claude -e 1
# 然后手动运行
claudeAPI 连接问题
常见错误及解决方案：
- 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: 可以。删除 .switch-claude-cache.json 不会影响功能，只是下次运行会重新检测。
Q: Beta 版本和稳定版本有什么区别？
A: Beta 版本是 TypeScript 重构版本，主要区别：
Beta 版本优势：
- ✨ 完全 TypeScript 重构，类型安全
- 🏗️ 更好的代码架构和可维护性
- 🐛 修复了一些已知问题
- 📦 更好的错误处理
兼容性：
- 🔄 功能与稳定版本完全兼容
- 📁 配置文件可以无缝切换
- 🔧 命令行参数完全一致
如何选择：
- 生产环境：推荐使用稳定版本
@latest - 测试环境：可以尝试 Beta 版本
@beta - 开发环境：可以使用 Alpha 版本
@alpha
项目地址: GitHub
问题反馈: Issues
NPM 包: switch-claude-cli
预发布版本: switch-claude-cli@beta 🚀
更新日志: CHANGELOG.md
TypeScript重构: feature/typescript-refactor