npm package: @limiantiao/claude-switch
Description: 快速切换 Claude Code API 配置的命令行工具 - 支持多个 API 提供商配置管理
Author: Your Name
Latest version: 1.0.1

# Claude Code 配置切换工具

这是一个用于快速切换 Claude Code 不同 API 配置的工具集，支持在任何目录下快速切换不同的 Claude API 服务提供商。

## 🚀 快速开始

### 方式一：NPM 安装（推荐）

```bash
# 全局安装
npm install -g @limiantiao/claude-switch

# 或使用 npx（无需安装）
npx @limiantiao/claude-switch install

# 安装后：
# 1. 初始化配置
claude-switch-setup init

# 2. 编辑配置文件
claude-switch-setup config

# 3. 重新加载 shell 配置
source ~/.bashrc  # 或 ~/.zshrc

# 4. 开始使用
cs anyrouter      # 切换到 anyrouter 配置
claude-status     # 查看当前配置
```

### 方式二：手动安装

```bash
# 1. 克隆或下载项目到任意目录
git clone https://github.com/yourname/claude-switch.git
cd claude-switch

# 2. 复制配置模板并添加你的 API 配置
cp .env.example .env
# 编辑 .env 文件

# 3. 运行安装脚本
bash scripts/setup-global-claude.sh

# 4. 重新加载配置
source ~/.bashrc  # 或 ~/.zshrc

# 5. 开始使用
cs anyrouter      # 切换到 anyrouter 配置
claude-status     # 查看当前配置
```

**支持平台：** macOS、Linux、Windows (Git Bash/WSL/MSYS2/Cygwin)

## 📁 文件说明

### NPM 包结构
- **bin/claude-switch.js** - CLI 命令行工具入口
- **lib/install.js** - 自动安装逻辑
- **scripts/setup-global-claude.sh** - 全局安装脚本，配置系统别名
- **scripts/switch-claude.sh** - 核心切换脚本
- **.env** - 配置文件，存储所有 API 配置（JSON 格式）
- **.env.example** - 配置模板文件
- **README.md** - 使用说明文档
- **CLAUDE.md** - Claude Code 工作指南
- **MIGRATION.md** - 配置迁移指南（可选）

### 配置文件位置

**NPM 全局安装：**
- 配置文件位置：`~/.claude-switch/.env`
- 脚本位置：npm 全局目录

**手动安装：**
- 配置文件位置：项目目录下的 `.env`
- 脚本位置：项目目录

## 🔧 工作原理

### 工作流程
1. `setup-global-claude.sh` 检测当前 shell 类型（bash/zsh）
2. 自动找到对应的配置文件（.bashrc/.bash_profile/.zshrc/.profile）
3. 在配置文件中添加全局别名和函数
4. `switch-claude.sh` 从 `.env` 读取 JSON 格式配置
5. 设置环境变量 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN`

### 核心功能
- **claude-switch** / **cs** - 切换配置的别名命令
- **claude-status** - 查看当前配置状态
- 支持多种 shell 环境
- 自动备份配置文件
- 使用 JSON 格式存储配置
- 配置文件自动添加到 .gitignore

## 🖥️ Windows 兼容性

### ✅ 完全兼容
经过优化，脚本现在完全支持 Windows bash 环境：
- **Git Bash** - 完全支持
- **WSL (Windows Subsystem for Linux)** - 完全支持
- **MSYS2** - 完全支持
- **Cygwin** - 完全支持

### 🔧 已解决的兼容性问题

1. **配置文件自动创建**
   - 脚本会自动检测并创建缺失的配置文件（.bashrc/.zshrc/.profile）
   - 支持 Windows 环境下的各种 shell 配置

2. **sed 命令兼容性**
   - 自动检测操作系统类型
   - macOS 使用 `sed -i ''`，Linux/Windows 使用 `sed -i`

3. **临时文件处理**
   - 自动检测临时目录（/tmp 或用户主目录）
   - 避免 Windows 环境下的路径问题

4. **脚本路径自适应**
   - 移除硬编码路径，支持任意目录安装
   - 通过环境变量传递脚本位置

### 🎯 Windows 特定优化
- 自动处理不存在的配置文件
- 兼容不同的临时目录结构
- 支持包含空格的路径
- 跨平台的 sed 命令处理

## 🚀 安装和配置

### 第一步：下载文件
将所有脚本文件下载到任意目录，例如：

**Windows 环境：**
- Git Bash: `C:\Users\YourName\claude-tools\`
- WSL: `/home/username/claude-tools/`
- 任意位置都可以，脚本会自动适配

**macOS/Linux：**
- `~/claude-tools/` 或任意目录

### 第二步：配置 API 信息

**重要：所有配置都在 `.env` 文件中进行，这是唯一的配置源！**

复制配置模板并编辑：

```bash
# 复制模板文件
cp .env.example .env

# 编辑 .env 文件
vim .env  # 或使用其他编辑器
```

编辑 `.env` 文件，添加你的 API 配置：

```bash
# Claude Code 配置文件
# ⚠️ 此文件包含敏感信息，请勿提交到 git

# JSON 格式配置
CLAUDE_CONFIGS_JSON='{
  "anyrouter": {
    "url": "https://anyrouter.top",
    "api_key": "sk-your-api-key-here"
  },
  "wenwen": {
    "url": "https://code.wenwen-ai.com",
    "api_key": "sk-your-api-key-here"
  },
  "k2": {
    "url": "https://api.moonshot.cn/anthropic/",
    "api_key": "sk-your-api-key-here"
  },
  "qwen": {
    "url": "https://dashscope.aliyuncs.com/api/v2/apps/claude-code-proxy",
    "api_key": "sk-your-api-key-here"
  }
}'
```

**配置说明：**
- 使用 JSON 格式存储配置
- 每个配置包含 `url` 和 `api_key` 两个字段
- 配置名称可以自定义，用于切换时的标识
- 注意 JSON 格式的逗号和引号
- `.env` 文件已自动添加到 `.gitignore`

### 第三步：运行安装脚本

#### Windows 环境：

**Git Bash：**
```bash
# 进入脚本目录
cd /c/Users/YourName/claude-tools

# 运行安装脚本
bash setup-global-claude.sh
```

**WSL：**
```bash
# 进入脚本目录
cd /home/username/claude-tools
# 或从 Windows 路径
cd /mnt/c/Users/YourName/claude-tools

# 运行安装脚本
bash setup-global-claude.sh
```

**PowerShell + Git Bash：**
```powershell
# 在 PowerShell 中启动 Git Bash
"C:\Program Files\Git\bin\bash.exe" -c "cd '/c/Users/YourName/claude-tools' && bash setup-global-claude.sh"
```

#### macOS/Linux：
```bash
cd /path/to/claude-tools
chmod +x setup-global-claude.sh
./setup-global-claude.sh
```

### 第四步：重新加载配置
```bash
# 重新加载 shell 配置
source ~/.bashrc    # 或 ~/.zshrc

# 或者重新启动终端
```

## 📖 使用方法

### NPM 命令（全局安装后）

```bash
# 查看帮助
claude-switch-setup --help

# 初始化配置文件
claude-switch-setup init

# 编辑配置文件
claude-switch-setup config

# 查看配置文件路径
claude-switch-setup path

# 手动安装到系统
claude-switch-setup install

# 卸载
claude-switch-setup uninstall
```

### Shell 命令（安装后可用）

### 查看可用配置
```bash
cs  # 显示当前状态和可用配置
```

### 切换配置
```bash
# 使用完整命令
claude-switch anyrouter

# 使用简短别名
cs wenwen
```

### 查看当前状态
```bash
claude-status
```

### 示例输出
```
✅ 已切换到配置: anyrouter
   URL: https://anyrouter.top
   Token: sk-WINbp3JV4Xoy9qWr...

现在可以运行 'claude' 命令使用新配置
```

## 🔧 高级配置

### 添加新的 API 配置

只需编辑 `.env` 文件，在 JSON 中添加新配置：

```bash
CLAUDE_CONFIGS_JSON='{
  "anyrouter": {
    "url": "https://anyrouter.top",
    "api_key": "sk-your-api-key"
  },
  "my_config": {
    "url": "https://my-api-url.com",
    "api_key": "sk-my-api-key"
  },
  "development": {
    "url": "https://dev-api.com",
    "api_key": "dev-key"
  },
  "production": {
    "url": "https://prod-api.com",
    "api_key": "prod-key"
  }
}'
```

**配置立即生效，无需重新安装或重启！**

### 自定义别名
你可以在安装后修改 shell 配置文件，添加自定义别名：
```bash
alias claude-dev='cs development'
alias claude-prod='cs production'
alias claude-test='cs testing'
```

### 配置管理最佳实践
- **单一配置源**：所有 API 配置只在 `.env` 中维护
- **版本控制**：`.env` 文件已自动添加到 `.gitignore` 保护敏感信息
- **团队共享**：`.env.example` 作为模板供团队使用
- **备份配置**：定期备份 `.env` 文件
- **文件权限**：建议设置 `.env` 文件权限为 600（仅所有者可读写）

```bash
# 设置文件权限
chmod 600 .env
```

## 🛠️ 故障排除

### 通用问题

#### 命令不存在
- 确保已运行 `setup-global-claude.sh`
- 重新加载 shell 配置：`source ~/.bashrc` 或 `source ~/.zshrc`
- 检查配置文件是否正确添加了别名
- 重启终端窗口

#### 配置不生效
- 检查 `.env` 文件是否存在
- 验证 JSON 格式是否正确（注意逗号和引号）
- 使用 `claude-status` 检查当前配置
- 确保配置文件在脚本同一目录下

#### JSON 格式错误
```bash
# 使用在线工具验证 JSON 格式
# 或使用 jq 命令（如果已安装）
echo "$CLAUDE_CONFIGS_JSON" | jq .
```

### Windows 特定问题

#### Git Bash 环境
```bash
# 检查当前 shell
echo $SHELL

# 手动加载配置
source ~/.bashrc

# 检查别名是否存在
alias | grep claude
```

#### WSL 环境
```bash
# 确保使用正确的配置文件
ls -la ~/.*rc

# WSL 可能需要重启
wsl --shutdown
# 然后重新打开 WSL
```

#### 路径问题
- Windows 路径包含空格时，确保使用引号
- Git Bash 路径格式：`/c/Users/YourName/`
- WSL 路径格式：`/mnt/c/Users/YourName/`

#### 权限问题
```bash
# 检查文件权限
ls -la setup-global-claude.sh

# 如果需要，添加执行权限
chmod +x *.sh
```

### 高级故障排除

#### 调试模式
```bash
# 启用调试输出
bash -x setup-global-claude.sh

# 检查环境变量
env | grep CLAUDE
env | grep ANTHROPIC
```

#### 手动验证
```bash
# 检查脚本路径
echo $CLAUDE_SCRIPT_DIR

# 手动测试切换
source /path/to/switch-claude.sh anyrouter

# 验证环境变量
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

# 验证 .env 配置
cat .env
```

## 🔒 安全性

1. **API 密钥保护**：
   - `.env` 文件已自动添加到 `.gitignore`
   - 不会被 git 跟踪和提交
   - 建议设置文件权限为 600

2. **敏感信息处理**：
   - Token 在输出时只显示前 20 个字符
   - 使用 `.env.example` 作为安全的模板

3. **文件权限建议**：
   ```bash
   chmod 600 .env  # 仅所有者可读写
   ```

## 📝 注意事项

1. **安全性**：API 密钥存储在 `.env` 文件中，已自动添加到 `.gitignore`
2. **备份**：安装脚本会自动备份原有的 shell 配置文件
3. **路径**：脚本可以放在任意目录，安装时会自动检测路径
4. **兼容性**：支持 bash、zsh 等主流 shell
5. **JSON 格式**：配置使用 JSON 格式，注意语法正确性

## 🔄 更新和卸载

### 更新配置
直接修改 `.env` 文件，无需重新安装

### 卸载
1. 编辑你的 shell 配置文件（~/.bashrc 或 ~/.zshrc）
2. 删除 "# Claude Code 配置切换别名" 部分的所有内容
3. 重新加载配置或重启终端
4. 可选：删除 `.env` 文件和脚本目录

## 📚 相关文档

- **CLAUDE.md** - Claude Code 工作指南，包含架构设计和开发命令
- **MIGRATION.md** - 如果你从旧版本升级，查看此文档了解迁移步骤

---

**享受快速切换 Claude API 配置的便利！** 🎉