cc-sw - Claude Code API Provider and Model Switcher

A powerful command-line tool for switching between different API providers and their corresponding models in Claude Code.

Features

• 🔄 Quick Switching: Seamlessly switch between different API providers and their models
• 🔒 Secure Management: Safely manage multiple API keys and configurations
• 🧪 Connection Testing: Test API connections before switching
• 📊 Status Display: View current provider and all available providers
• 🎨 User-Friendly: Intuitive CLI with colored output and interactive prompts
• 📦 Cross-Platform: Works on macOS, Linux, and Windows
• 🤖 Model Management: Automatically switches models when changing providers

Installation

From Source

# Clone the repository
git clone <repository-url>
cd cc-sw

# Install dependencies
npm install

# Build the project
npm run build

# Install globally
npm install -g .

Using Package Manager (when published)

npm install -g cc-sw

Quick Start

1. Add your first provider:

   cc-sw add anthropic

2. List available providers:

   cc-sw list

3. Switch to a provider:

   cc-sw use anthropic

4. Test your connection:

   cc-sw test

Commands

| Command | Alias | Description | |---------|-------|-------------| | cc-sw list | ls | List all available API providers | | cc-sw current | curr | Show current API provider and model | | cc-sw use <provider> | | Switch to specified API provider and model | | cc-sw add <provider> | | Add new API provider configuration | | cc-sw remove <provider> | | Remove API provider configuration | | cc-sw test [provider] | | Test API provider connection | | cc-sw config | | Open configuration file | | cc-sw migrate | | Migrate MCP configurations from other tools | | cc-sw help | | Display help information | | cc-sw --version | | Show version information | | cc-sw sync-use | | Synchronize and switch to a provider using shell integration |

Supported Providers

Anthropic

cc-sw add anthropic

Configuration:

• API Key: Your Anthropic API key
• Base URL: https://api.anthropic.com
• Model: claude-3-5-sonnet-20241022

OpenAI

cc-sw add openai

Configuration:

• API Key: Your OpenAI API key
• Base URL: https://api.openai.com/v1
• Model: gpt-4

Kimi (月之暗面)

cc-sw add kimi

Configuration:

• API Key: Your Kimi API key
• Base URL: https://api.moonshot.cn/v1
• Model: moonshot-v1-8k 或 moonshot-v1-32k 或 moonshot-v1-128k

DeepSeek

cc-sw add deepseek

Configuration:

• API Key: Your DeepSeek API key
• Base URL: https://api.deepseek.com/anthropic
• Model: deepseek-chat

Custom Providers

You can add any custom API provider that follows the OpenAI-compatible format:

cc-sw add my-provider

Configuration

Configuration File

The configuration is stored in ~/.claude/providers.json:

{
  "current": "anthropic",
  "providers": {
    "anthropic": {
      "name": "Anthropic",
      "api_key": "sk-ant-api03-...",
      "base_url": "https://api.anthropic.com",
      "model": "claude-3-5-sonnet-20241022"
    },
    "openai": {
      "name": "OpenAI",
      "api_key": "sk-...",
      "base_url": "https://api.openai.com/v1",
      "model": "gpt-4"
    },
    "deepseek": {
      "name": "DeepSeek",
      "api_key": "sk-...",
      "base_url": "https://api.deepseek.com/anthropic",
      "model": "deepseek-chat"
    }
  }
}

Environment Variables

You can set the following environment variables:

• EDITOR: Default editor for config command (default: nano)
• CC_SW_CONFIG_DIR: Custom configuration directory
• DEEPSEEK_API_KEY: DeepSeek API key (can be used with cc-sw add deepseek)

详细使用指南

cc-sw use 命令详细说明

cc-sw use 是核心命令，用于切换 API 提供商和对应的模型。当您切换到某个提供商时，cc-sw 会自动：

1. 更新 Claude Code 的配置文件 (~/.claude/settings.json)
2. 切换 API 密钥
3. 切换基础 URL
4. 切换到该提供商配置的模型

以 Kimi 为例的完整使用流程

1. 添加 Kimi 提供商

cc-sw add kimi

系统会提示您输入以下信息：

? Display name: Kimi
? API Key: sk-您的Kimi API密钥
? Base URL: https://api.moonshot.cn/v1
? Model: moonshot-v1-32k
? Custom headers (JSON format, optional): [直接回车跳过]

2. 测试 Kimi 连接

cc-sw test kimi

3. 切换到 Kimi

cc-sw use kimi

执行此命令后，cc-sw 会：

• ✅ 测试 Kimi 的 API 连接
• ✅ 备份当前配置
• ✅ 更新提供商配置为 Kimi
• ✅ 更新 Claude Code 配置文件：
  • model: moonshot-v1-32k
  • api_key: 您的 Kimi API 密钥
  • base_url: https://api.moonshot.cn/v1

4. 验证切换结果

cc-sw current

输出示例：

Current API Provider:

Name: Kimi
Model: moonshot-v1-32k
Base URL: https://api.moonshot.cn/v1
API Key: sk-xxxxxxxx...

多模型管理示例

添加不同模型的 Kimi 配置：

# 添加 8K 版本
cc-sw add kimi-8k
# Display name: Kimi 8K
# API Key: sk-您的Kimi API密钥
# Base URL: https://api.moonshot.cn/v1
# Model: moonshot-v1-8k

# 添加 128K 版本
cc-sw add kimi-128k
# Display name: Kimi 128K
# API Key: sk-您的Kimi API密钥
# Base URL: https://api.moonshot.cn/v1
# Model: moonshot-v1-128k

在不同模型间切换：

# 切换到 8K 模型
cc-sw use kimi-8k

# 切换到 128K 模型
cc-sw use kimi-128k

实际工作流程示例

# 1. 查看所有可用的提供商
cc-sw list

# 2. 查看当前使用的提供商和模型
cc-sw current

# 3. 切换到 Kimi 进行长文本处理
cc-sw use kimi-128k

# 4. 验证连接
cc-sw test

# 5. 切换回 Anthropic 进行代码任务
cc-sw use anthropic

# 6. 再次验证
cc-sw current

cc-sw sync-use 命令详细说明

cc-sw sync-use 是一个高级命令，用于通过 shell 集成实现更智能的 API 提供商切换。它结合了 use 命令的切换功能和 shell 环境变量的同步能力。

功能特点

• Shell 环境同步: 自动同步切换的提供商到当前 shell 环境
• ZSH 集成: 支持 ZSH shell 的自动补全和提示
• 环境变量管理: 自动设置相关的环境变量
• 即时生效: 无需重新打开终端窗口

使用场景

1. 在脚本中使用

#!/bin/bash
# 在部署脚本中使用 sync-use
cc-sw sync-use anthropic
echo "已切换到 Anthropic 提供商"

2. 在 CI/CD 流程中使用

# 在 CI 环境中设置提供商
cc-sw sync-use deepseek
echo "DEEPSEEK_API_KEY 已设置"

3. 与 shell 别名配合使用

# 在 ~/.zshrc 中设置别名
alias use-kimi='cc-sw sync-use kimi'
alias use-anthropic='cc-sw sync-use anthropic'

与 cc-sw use 的区别

| 特性 | cc-sw use | cc-sw sync-use | |------|-----------|----------------| | 基本功能 | ✅ 切换提供商 | ✅ 切换提供商 | | Shell 集成 | ❌ 无 | ✅ 有 | | 环境变量 | ❌ 不设置 | ✅ 自动设置 | | 即时生效 | ✅ 是 | ✅ 是 | | 脚本友好 | ✅ 支持 | ✅ 更好支持 |

实际使用示例

示例 1：基本使用

# 使用 sync-use 切换到 Kimi
cc-sw sync-use kimi

# 验证环境变量已设置
echo $CURRENT_PROVIDER  # 输出: kimi
echo $CURRENT_MODEL     # 输出: moonshot-v1-32k

示例 2：在项目中使用

# 在项目根目录创建 .cc-sw 文件指定默认提供商
echo "kimi" > .cc-sw

# 使用 sync-use 加载项目配置
cc-sw sync-use $(cat .cc-sw)

示例 3：与 shell 函数集成

# 在 ~/.zshrc 中添加函数
switch-provider() {
    if [ -f .cc-sw ]; then
        cc-sw sync-use $(cat .cc-sw)
        echo "已切换到 $(cat .cc-sw) 提供商"
    else
        echo "未找到 .cc-sw 配置文件"
    fi
}

# 使用函数
switch-provider

Shell 集成设置

ZSH 集成

# 安装 shell 集成
curl -sSL https://raw.githubusercontent.com/your-repo/cc-sw/main/install-shell-integration.sh | bash

# 或者手动添加到 ~/.zshrc
echo 'source ~/.cc-sw-completion.zsh' >> ~/.zshrc
source ~/.zshrc

Bash 集成

# 添加到 ~/.bashrc
echo 'source ~/.cc-sw-completion.bash' >> ~/.bashrc
source ~/.bashrc

环境变量支持

cc-sw sync-use 会自动设置以下环境变量：

# 基础信息
CURRENT_PROVIDER=当前提供商名称
CURRENT_MODEL=当前模型名称
CURRENT_BASE_URL=当前基础URL

# API 密钥（可选）
ANTHROPIC_API_KEY=sk-xxx
OPENAI_API_KEY=sk-xxx
KIMI_API_KEY=sk-xxx
DEEPSEEK_API_KEY=sk-xxx

# 提供商特定变量
PROVIDER_KIMI_API_KEY=sk-xxx
PROVIDER_ANTHROPIC_API_KEY=sk-xxx

配置文件同步

项目级配置

# 在项目根目录创建配置文件
mkdir -p .cc-sw
echo 'kimi' > .cc-sw/default-provider

# 使用 sync-use 加载项目配置
cc-sw sync-use --project-config

团队共享配置

# 创建团队共享配置
echo 'kimi' > .cc-sw-team

# 团队成员使用
cp .cc-sw-team ~/.cc-sw/default-provider
cc-sw sync-use $(cat ~/.cc-sw/default-provider)

故障排除

问题：sync-use 命令未找到

# 重新安装 shell 集成
npm run install-shell-integration

# 或者手动检查路径
which cc-sw
ls -la ~/.cc-sw-completion.*

问题：环境变量未设置

# 检查 shell 集成是否正确安装
echo $SHELL
type cc-sw-sync-use

# 手动设置环境变量
export CURRENT_PROVIDER=kimi
export CURRENT_MODEL=moonshot-v1-32k

问题：ZSH 自动补全不工作

# 重新生成补全脚本
cc-sw completion zsh > ~/.cc-sw-completion.zsh
source ~/.cc-sw-completion.zsh

# 添加到 .zshrc
echo 'fpath=(~/.cc-sw-completion $fpath)' >> ~/.zshrc
echo 'autoload -U compinit && compinit' >> ~/.zshrc

MCP Migration

The cc-sw migrate command allows you to easily migrate MCP (Model Context Protocol) configurations from other tools like Cursor, VS Code, Windsurf, Cline, and Claude Desktop to Claude Code.

Supported Tools

• Cursor - Migrates from ~/.cursor/mcp.json
• VS Code - Migrates from ~/.vscode/mcp.json
• Windsurf - Migrates from ~/.windsurf/mcp.json
• Cline - Migrates from ~/.cline/mcp.json
• Claude Desktop - Migrates from ~/Claude/claude_desktop_config.json

Usage

# Run the migration tool
cc-sw migrate

# Interactive migration process:
# 1. Detects existing MCP configurations
# 2. Shows available configurations to migrate
# 3. Creates automatic backup
# 4. Migrates selected configurations

Migration Process

1. Detection: Automatically scans for MCP configs in supported tools
2. Selection: Interactive selection of configurations to migrate
3. Backup: Creates timestamped backup of existing Claude Code MCP config
4. Migration: Safely migrates MCP servers with unique naming to avoid conflicts
5. Reporting: Shows detailed migration summary

Example Migration

$ cc-sw migrate

🔄 MCP Configuration Migration Tool

? Select MCP configurations to migrate: (Press <space> to select, <a> to toggle all, <i> to invert selection)
 ❯◉ Cursor (3 servers)
   ◉ VS Code (2 servers)
   ◯ Claude Desktop (1 server)

📋 Migration Summary:

  Cursor:
    - github-mcp-server
    - filesystem-mcp-server
    - web-search-mcp-server

  VS Code:
    - postgres-mcp-server
    - redis-mcp-server

? Migrate 5 MCP server(s) to Claude Code? Yes

💾 Backup created: /Users/user/.claude/mcp_backup_20241203_143022.json

✅ Migration completed successfully!

📊 Migration Details:
  github-mcp-server → cursor_github-mcp-server (from Cursor)
  filesystem-mcp-server → cursor_filesystem-mcp-server (from Cursor)
  web-search-mcp-server → cursor_web-search-mcp-server (from Cursor)
  postgres-mcp-server → vscode_postgres-mcp-server (from VS Code)
  redis-mcp-server → vscode_redis-mcp-server (from VS Code)

Configuration Structure

After migration, your Claude Code configuration will include:

{
  "current": "anthropic",
  "providers": { ... },
  "mcp": {
    "cursor_github-mcp-server": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxx" }
    },
    "cursor_filesystem-mcp-server": {
      "command": "npx", 
      "args": ["@modelcontextprotocol/server-filesystem", "/Users/user/workspace"],
      "env": {}
    }
  }
}

Best Practices

1. Always backup: Migration creates automatic backups before changes
2. Review configurations: Check migrated MCP servers work correctly
3. Update environment variables: Ensure API keys and tokens are available
4. Test connections: Verify each migrated MCP server works with Claude Code

Examples

Basic Usage

# List all providers
cc-sw list

# Show current provider
cc-sw current

# Switch to Anthropic
cc-sw use anthropic

# Use sync-use for shell integration (advanced)
cc-sw sync-use kimi

# Test current provider
cc-sw test

# Test specific provider
cc-sw test openai

# Add new provider
cc-sw add my-custom-provider

# Remove provider
cc-sw remove old-provider

# Open config file
cc-sw config

Advanced Usage

# Add provider with custom headers
cc-sw add custom-provider
# When prompted, enter JSON headers:
# {"Authorization": "Bearer token", "X-Custom": "value"}

# Test connection before switching
cc-sw test anthropic
cc-sw use anthropic

# Use sync-use for shell integration and environment variables
cc-sw sync-use deepseek

# Batch operations
cc-sw add provider1 && cc-sw add provider2 && cc-sw use provider1

工作原理

cc-sw通过管理Claude Code的配置文件来实现API提供商和模型的切换。以下是详细的工作原理：

核心机制

1. 配置文件管理

• 提供商配置: ~/.claude/providers.json - 存储所有API提供商的配置信息
• Claude配置: ~/.claude/settings.json - Claude Code的主配置文件，cc-sw通过修改此文件来切换提供商

2. 切换流程

用户执行 cc-sw use kimi
        ↓
测试Kimi API连接
        ↓
备份当前配置
        ↓
更新providers.json中的current字段
        ↓
修改Claude settings.json：
  - model: moonshot-v1-32k
  - api_key: 用户Kimi API密钥
  - base_url: https://api.moonshot.cn/v1
        ↓
切换完成

技术实现

配置文件结构:

// ~/.claude/providers.json
{
  "current": "kimi",
  "providers": {
    "kimi": {
      "name": "Kimi",
      "api_key": "sk-xxxxxxxx",
      "base_url": "https://api.moonshot.cn/v1",
      "model": "moonshot-v1-32k"
    },
    "anthropic": {
      "name": "Anthropic", 
      "api_key": "sk-ant-api03-xxxxxxxx",
      "base_url": "https://api.anthropic.com",
      "model": "claude-3-5-sonnet-20241022"
    }
  }
}

Claude配置修改: 当执行cc-sw use kimi时，cc-sw会：

1. 读取~/.claude/settings.json
2. 更新以下字段：

   {
     "model": "moonshot-v1-32k",
     "api_key": "sk-your-kimi-api-key",
     "base_url": "https://api.moonshot.cn/v1"
   }

3. 保存配置文件
4. Claude Code下次启动时自动使用新配置

连接测试机制

cc-sw在切换前会测试API连接，确保目标提供商可用：

// 发送测试请求
POST https://api.moonshot.cn/v1/chat/completions
Headers:
  Authorization: Bearer sk-your-api-key
  Content-Type: application/json
Body:
{
  "model": "moonshot-v1-32k",
  "max_tokens": 10,
  "messages": [{"role": "user", "content": "test"}]
}

安全特性

1. 配置备份

• 每次切换前自动创建备份文件
• 备份文件命名：providers.json.backup.2024-xx-xx
• 支持手动恢复配置

2. 权限保护

• 配置文件存储在用户主目录：~/.claude/
• 文件权限自动设置为仅用户可读写
• API密钥加密存储（可选）

3. 连接验证

• 切换前强制测试API连接
• 连接失败时需要用户确认才继续
• 显示详细的错误信息和响应时间

支持的API格式

1. Anthropic格式

{
  "base_url": "https://api.anthropic.com",
  "headers": {
    "x-api-key": "sk-xxx",
    "anthropic-version": "2023-06-01"
  },
  "endpoint": "/v1/messages"
}

2. OpenAI兼容格式

{
  "base_url": "https://api.openai.com/v1",
  "headers": {
    "Authorization": "Bearer sk-xxx"
  },
  "endpoint": "/chat/completions"
}

3. 自定义提供商

• 支持任何OpenAI兼容的API
• 可自定义HTTP头部
• 灵活的模型配置

错误处理机制

1. 网络错误

• 超时设置：10秒
• 自动重试机制
• 详细的错误诊断

2. 配置错误

• JSON格式验证
• 必填字段检查
• API密钥格式验证

3. 恢复机制

• 自动备份恢复
• 配置文件修复
• 紧急模式启动

工作流程最佳实践

场景1：开发与测试切换

# 开发时使用 Anthropic Claude
cc-sw use anthropic

# 测试长文本处理时切换到 Kimi 128K
cc-sw use kimi-128k

# 快速任务切换到 8K 模型
cc-sw use kimi-8k

场景2：多模型测试

# 为同一提供商添加不同模型配置
cc-sw add kimi-dev     # 开发环境用 8K
cc-sw add kimi-test    # 测试环境用 32K  
cc-sw add kimi-prod    # 生产环境用 128K

# 在不同环境间快速切换
cc-sw use kimi-dev
cc-sw use kimi-test
cc-sw use kimi-prod

场景3：成本优化

# 简单任务使用 8K 模型（成本更低）
cc-sw use kimi-8k

# 复杂任务使用 128K 模型（处理能力更强）
cc-sw use kimi-128k

Development

Setup Development Environment

# Clone repository
git clone <repository-url>
cd cc-sw

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Lint code
npm run lint

Project Structure

cc-sw/
├── src/
│   ├── cli/           # CLI command implementations
│   ├── utils/         # Utility functions
│   └── index.ts       # Main entry point
├── bin/               # Executable files
├── dist/              # Compiled output
├── package.json       # Project configuration
├── tsconfig.json      # TypeScript configuration
└── README.md          # This file

Building for Distribution

# Build TypeScript
npm run build

# Create executables for different platforms
npm run pkg

# The executables will be in dist/bin/

Testing

# Run all tests
npm test

# Run tests with coverage
npm run test -- --coverage

# Run specific test file
npm test -- list.test.ts

故障排除

常见问题

1. 权限问题

chmod +x bin/cc-sw

2. 命令未找到

• 确保包已全局安装：npm install -g .
• 检查 PATH 环境变量

3. 配置文件问题

• 检查文件权限：ls -la ~/.claude/
• 验证 JSON 格式：cat ~/.claude/providers.json

4. API 连接问题

• 测试 API 密钥：cc-sw test <provider>
• 检查网络连接
• 验证 API 端点 URL

cc-sw use 命令特定问题

问题：切换后模型未生效

# 解决方案：验证切换结果
cc-sw current

# 如果模型不正确，手动重新切换
cc-sw use kimi

问题：Kimi API 连接失败

# 1. 检查 API 密钥格式
cc-sw add kimi
# 确保 API 密钥以 sk- 开头

# 2. 验证基础 URL
# 正确的 URL：https://api.moonshot.cn/v1
# 错误的 URL：https://api.moonshot.cn (缺少 /v1)

# 3. 测试连接
cc-sw test kimi

问题：模型配置错误

# 常见的 Kimi 模型名称：
# moonshot-v1-8k
# moonshot-v1-32k  
# moonshot-v1-128k

# 如果使用了错误的模型名称，重新添加提供商：
cc-sw remove kimi
cc-sw add kimi

配置文件恢复

如果配置出现问题，可以手动恢复：

# 1. 查看备份文件
ls -la ~/.claude/providers.json.backup.*

# 2. 恢复最新的备份
cp ~/.claude/providers.json.backup.2024-xx-xx ~/.claude/providers.json

# 3. 重新初始化配置
rm ~/.claude/providers.json
cc-sw add anthropic

调试模式

启用调试日志：

export DEBUG=cc-sw:*
cc-sw <command>

Troubleshooting

Common Issues

1. Permission Denied

   chmod +x bin/cc-sw

2. Command Not Found

   • Make sure the package is installed globally: npm install -g .
   • Check your PATH environment variable

3. Configuration File Issues

   • Check file permissions: ls -la ~/.claude/
   • Validate JSON format: cat ~/.claude/providers.json

4. API Connection Issues

   • Test your API key: cc-sw test <provider>
   • Check your internet connection
   • Verify API endpoint URLs

Debug Mode

Enable debug logging:

export DEBUG=cc-sw:*
cc-sw <command>

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Run tests: npm test
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Create an issue on GitHub
• Check the troubleshooting section above
• Review the configuration examples

Changelog

v1.0.0

• Initial release
• Support for multiple API providers
• Connection testing
• Interactive configuration management
• Cross-platform support
• Model switching: Automatically switch models when changing providers
• Enhanced documentation: Added comprehensive usage guide with Kimi examples