CC Switch

🚀 Claude Code 配置切换器 - 轻松管理多个 Claude Code 配置

CC Switch 是一个命令行工具，帮助您轻松管理和切换多个 Claude Code 配置。支持存储多组 URL 和 Token，并可一键切换，提升开发效率。

✨ 特性

• 🔧 多配置管理 - 存储和管理多个 Claude Code 配置
• 🔄 一键切换 - 快速切换不同的 URL 和 Token
• 🛡️ 安全存储 - Token 安全遮蔽显示，配置文件权限保护
• 💾 自动备份 - 切换前自动备份，支持手动备份和恢复
• 🔍 智能检测 - 自动检测 Claude Code 配置文件位置
• 📊 系统诊断 - 全面的系统状态检查和问题诊断
• 🌐 跨平台 - 支持 macOS、Linux 和 Windows

📦 安装

系统要求

• Node.js 18 或更高版本
• Claude Code 已安装

快速安装

macOS / Linux

# 克隆项目
git clone https://github.com/songunity/ccswitch.git
cd cc-switch

# 安装依赖
npm install

# 运行安装脚本
./install.sh

Windows

# 克隆项目
git clone https://github.com/songunity/ccswitch.git
cd cc-switch

# 安装依赖
npm install

# 运行安装脚本
install.bat

手动安装

# 构建项目
npm run build

# 全局链接（开发模式）
npm link

# 或直接使用
node dist/cli.js

🚀 快速开始

1. 检查系统状态

ccs diagnostics

2. 添加配置

# 添加开发环境配置
ccs add dev https://api.anthropic.com sk-ant-api03-your-dev-token

# 添加生产环境配置  
ccs add prod https://api.anthropic.com sk-ant-api03-your-prod-token

3. 查看配置列表

ccs list

4. 切换配置

# 切换到开发环境
ccs switch dev

# 切换到生产环境
ccs switch prod

5. 查看当前配置

ccs current

📋 命令参考

基础命令

| 命令 | 简写 | 描述 | 示例 | |------|------|------|------| | add <name> <url> <token> | a | 添加新配置 | ccs add dev https://api.anthropic.com sk-xxx | | list | ls | 显示所有配置 | ccs list | | switch <name> | sw | 切换到指定配置 | ccs switch dev | | remove <name> | rm | 删除配置 | ccs remove dev | | current | cur | 显示当前配置 | ccs current |

高级命令

| 命令 | 简写 | 描述 | 示例 | |------|------|------|------| | backup | - | 创建手动备份 | ccs backup | | restore <backup-file> | - | 从备份恢复 | ccs restore ~/.claude/settings.json.backup.xxx | | diagnostics | diag | 系统诊断 | ccs diagnostics |

帮助命令

# 显示帮助信息
ccs --help

# 显示版本信息
ccs --version

# 显示特定命令帮助
ccs help <command>

🛡️ 安全特性

Token 安全

• 智能遮蔽: 根据 token 类型（sk-ant-, sk-, pk- 等）智能遮蔽显示
• 安全存储: 配置文件权限设置为 600（仅所有者可读写）
• 原子操作: 使用临时文件和原子重命名确保写入安全

备份保护

• 自动备份: 每次切换前自动创建备份
• 备份管理: 自动保留最近 5 个备份文件
• 恢复功能: 支持从任意备份文件恢复配置

权限检查

• 文件权限: 自动检查和设置适当的文件权限
• 目录权限: 确保配置目录权限安全
• 访问验证: 切换前验证目标文件的读写权限

📁 配置文件位置

CCS 配置文件

• 位置: ~/.ccswitcher/configs.json
• 权限: 600 (仅所有者可读写)
• 内容: 存储所有 CCS 配置和设置

Claude Code 配置文件

CCS 自动检测以下位置的 Claude Code 配置：

1. ~/.claude/settings.json (用户级别，优先)
2. .claude/settings.json (项目级别)
3. .claude/settings.local.json (项目本地)

🔧 配置选项

全局设置

CCS 配置文件支持以下全局设置：

{
  "configs": [...],
  "currentConfig": "dev",
  "settings": {
    "backupRetentionCount": 5,
    "autoBackup": true
  }
}

配置验证

• URL 验证: 必须是有效的 HTTP/HTTPS URL
• Token 验证: 不能为空，至少 10 个字符
• 名称验证: 不能包含特殊字符，不能使用保留字

🐛 故障排除

常见问题

1. 配置文件不存在

# 运行诊断检查
ccs diagnostics

# 确保 Claude Code 已安装并至少运行过一次
# 手动创建目录（如需要）
mkdir -p ~/.claude

2. 权限被拒绝

# 修复文件权限
chmod 755 ~/.claude
chmod 644 ~/.claude/settings.json

# 修复 CCS 配置权限
chmod 700 ~/.ccswitcher
chmod 600 ~/.ccswitcher/configs.json

3. 切换后配置不生效

# 检查当前状态
ccs current

# 重新切换配置
ccs switch <config-name>

# 检查 Claude Code 配置文件
cat ~/.claude/settings.json

错误代码

| 错误代码 | 描述 | 解决方案 | |----------|------|----------| | CONFIG_NOT_FOUND | 配置不存在 | 使用 ccs list 查看可用配置 | | CONFIG_EXISTS | 配置名称已存在 | 选择不同的名称或删除现有配置 | | CLAUDE_CONFIG_NOT_FOUND | Claude 配置文件不存在 | 运行 Claude Code 创建配置文件 | | PERMISSION_DENIED | 权限不足 | 检查并修复文件权限 | | INVALID_URL | URL 格式错误 | 确保 URL 以 http:// 或 https:// 开头 | | INVALID_TOKEN | Token 格式错误 | 检查 token 长度和格式 |

🔄 使用流程

典型工作流程

# 1. 初次设置
ccs diagnostics                    # 检查系统状态
ccs add dev https://dev-api.com sk-dev-token    # 添加开发配置
ccs add prod https://api.com sk-prod-token      # 添加生产配置

# 2. 日常使用
ccs list                          # 查看所有配置
ccs switch dev                    # 切换到开发环境
# 进行开发工作...
ccs switch prod                   # 切换到生产环境
# 进行生产部署...

# 3. 维护
ccs backup                        # 手动备份
ccs current                       # 检查当前状态
ccs diagnostics                   # 定期诊断检查

团队协作

# 导出配置（不包含敏感信息）
ccs list > team-configs.txt

# 团队成员添加相同的配置结构
ccs add staging https://staging-api.com <their-staging-token>
ccs add production https://prod-api.com <their-prod-token>

📊 系统监控

诊断报告

ccs diagnostics 命令提供全面的系统状态报告：

• 系统信息: 平台、Node.js 版本、主目录
• 配置状态: CCS 配置文件状态和统计
• Claude 配置: 所有检测到的 Claude 配置文件状态
• 权限检查: 文件创建和读取权限验证
• 问题识别: 自动识别问题并提供解决建议

状态检查

# 快速状态检查
ccs current

# 详细系统诊断
ccs diagnostics

# 配置列表和状态
ccs list

🎯 最佳实践

配置命名

• 使用描述性名称：dev, staging, prod
• 避免特殊字符和空格
• 保持简短且易记

安全建议

• 定期更换 Token
• 不要在公共场所显示配置
• 定期备份重要配置
• 使用系统诊断检查安全状态

维护建议

• 定期运行 ccs diagnostics
• 清理不需要的配置：ccs remove <name>
• 检查备份文件占用空间
• 更新 CCS 到最新版本

🆘 获取帮助

内置帮助

ccs --help              # 总体帮助
ccs help add            # 特定命令帮助
ccs diagnostics         # 系统诊断

社区支持

• GitHub Issues: 项目地址
• 文档: 详细文档

问题报告

报告问题时，请包含：

1. CCS 版本：ccs --version
2. 系统诊断：ccs diagnostics
3. 具体错误信息
4. 复现步骤

📝 许可证

此项目基于 ISC 许可证开源。

🤝 贡献

欢迎贡献代码、报告问题或提出改进建议！

Happy Coding with CC Switch! 🚀