@free-air/claude-code

English | 中文 (Chinese)

适配 Anthropic 兼容 AI 提供商的环境配置快速切换工具

特性 • 安装 • 快速开始 • 命令 • 配置 • 故障排除

问题 & 方案

问题： 手动在 Shell 环境中更新 Claude 模型配置很繁琐，容易出错。

• 在不同 AI 提供商（Kimi、GLM、Minimax 等）间切换需要编辑多个环境配置文件
• 配置改动需要重启 Shell 才能生效
• 很容易忘记当前配置的是哪个提供商

方案： freecc 让你能在 Shell 中一键切换模型。

# 之前：编辑文件、重启 shell、检查配置...
# 之后：只需输入这一条！
freecc switch kimi

特性

🎯 便捷切换提供商 - 一条命令即可在 Kimi、GLM、Minimax 等提供商间切换

🚀 零配置安装 - npm 安装时自动配置 shell hook

🐚 跨 Shell 支持 - 支持 Bash、Zsh、Fish、PowerShell 及 5+ 种其他 Shell

🔄 幂等操作 - 安全地多次运行，不会产生重复条目

📦 轻量级 - 最小依赖，总大小仅 ~50KB

✅ Anthropic 兼容 - 支持任何 Anthropic API 兼容的提供商

快速开始

# 全局安装
npm install -g @free-air/claude-code

# 初始化配置文件（包含示例）
free init

# 查看可用的提供商
free list

# 切换到某个提供商
free switch kimi

# 查看当前活跃的配置
free current

安装

全局安装（推荐）

npm install -g @free-air/claude-code

安装后 free 命令将在所有 Shell 中可用。Hook 配置会自动完成。

本地开发

npm install --save-dev @free-air/claude-code
npx free --help

手动安装 Hook

如果自动安装未生效：

free hook

然后打开新的终端或运行：

source ~/.bashrc  # 或 ~/.zshrc、~/.config/fish/config.fish 等

命令

free list

列出所有可用的提供商配置。

$ free list
Available configurations:
  • kimi
  • glm
  • minimax

free current

显示当前活跃的提供商配置。

$ free current
Current config: kimi

free switch <name>

切换到指定提供商并加载其环境变量。

$ free switch glm
export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic"
export ANTHROPIC_AUTH_TOKEN="your_zai_api_key"
export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-4.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.5-air"
export FREE_CURRENT_CONFIG="glm"
[OK] Switched to config: glm

free init

创建模板配置文件（包含示例提供商）。

$ free init
[OK] Created example config file: /home/user/.free.json
Edit this file to add your own configurations and API keys.

free hook

手动安装 hook 函数到 Shell 配置文件。

$ free hook
[OK] Installed to /home/user/.bashrc
[OK] Installed to /home/user/.config/fish/config.fish

free remove

从所有 Shell 配置文件中移除 hook。

$ free remove
[OK] Removed from bash: /home/user/.bashrc
[OK] Removed from zsh: /home/user/.zshrc

配置

配置存储在 ~/.free.json 文件中（JSON 格式）。

配置文件位置

• Linux/macOS: ~/.free.json
• Windows: C:\Users\<用户名>\.free.json

配置示例

{
  "kimi": {
    "ANTHROPIC_BASE_URL": "https://api.moonshot.ai/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your_moonshot_api_key",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "kimi-k2.5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "kimi-k2.5",
    "ENABLE_TOOL_SEARCH": "false"
  },
  "glm": {
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your_zai_api_key",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air"
  },
  "minimax": {
    "ANTHROPIC_BASE_URL": "https://api.minimax.chat/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your_minimax_api_key",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "MiniMax-M1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "MiniMax-Text-01"
  }
}

添加新的提供商

编辑 ~/.free.json 并添加新条目：

{
  "my-provider": {
    "ANTHROPIC_BASE_URL": "https://your-api-endpoint.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your_api_key",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "model-name",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "model-name"
  }
}

然后运行：

free switch my-provider

支持的 Shell

工具会自动检测并支持以下 Shell：

| Shell | 配置文件 | 状态 | |-------|---------|------| | Bash | ~/.bashrc、~/.bash_profile | ✅ 支持 | | Zsh | ~/.zshrc | ✅ 支持 | | Fish | ~/.config/fish/config.fish | ✅ 支持 | | PowerShell | 多个位置 | ✅ 支持 | | Ksh | ~/.kshrc | ✅ 支持 | | Tcsh | ~/.tcshrc | ✅ 支持 | | Csh | ~/.cshrc | ✅ 支持 | | Dash | ~/.dashrc | ✅ 支持 | | Sh | ~/.profile | ✅ 支持 |

工作原理

1. Hook 安装: npm 安装时，工具会自动在 Shell 配置文件中添加函数。

2. 环境变量加载: 运行 free switch <name> 时，工具输出 Shell 命令来设置环境变量。

3. Shell 包装函数: Hook 函数会拦截 free switch 并执行输出的命令，使变量在当前会话中生效。

4. 幂等操作: 安装使用标记块防止重复添加。

使用示例

为不同项目切换提供商

# 对于 Kimi 项目
free switch kimi

# 对于 GLM 项目
free switch glm

# 切回默认
free switch minimax

在脚本中检查当前提供商

current_provider=$(echo $FREE_CURRENT_CONFIG)
echo "使用的提供商: $current_provider"

与 Claude CLI 一起使用

# 切换提供商
free switch kimi

# 运行 Claude 命令（将使用 kimi 的 API 端点）
claude chat "hello world"

与本地提供商一起使用

free switch my-local-provider
# 配置为使用 ANTHROPIC_BASE_URL 的工具现在会使用本地提供商

故障排除

命令未找到

问题: free: command not found

解决方案:

1. 验证 npm 安装: npm list -g @free-air/claude-code
2. 检查 npm bin 目录是否在 PATH 中: echo $PATH
3. 重新安装: npm install -g @free-air/claude-code
4. 手动安装 hook: free hook

新终端中 hook 未加载

问题: 打开新终端后 hook 不可用

解决方案:

1. 运行 free hook 重新安装
2. 打开新的终端窗口
3. 对于 PowerShell: 可能需要修改执行策略

配置文件未找到

问题: Failed to parse ~/.free.json

解决方案:

1. 创建并初始化: free init
2. 验证 JSON 格式: cat ~/.free.json
3. 使用 JSON 验证工具检查语法

环境变量未设置

问题: 运行 free switch 后变量不可用

解决方案:

1. 验证是否使用了包装函数: type free (bash/zsh) 或 Get-Command free (PowerShell)
2. 检查 hook 是否已安装: grep -n "free-env manager" ~/.bashrc
3. 验证配置文件存在: cat ~/.free.json
4. 重新安装 hook: free hook

多个 Shell 配置文件

问题: Hook 安装到了错误的位置

解决方案: 工具检查多个标准位置。如需添加到其他配置文件，可手动添加：

# 对于 bash
source ~/.bashrc

# 对于 zsh
source ~/.zshrc

# 对于 fish
source ~/.config/fish/config.fish

环境变量

运行 free switch kimi 时，工具会设置：

• FREE_CURRENT_CONFIG - 活跃的提供商名称
• 配置中的所有环境变量

检查当前提供商

echo $FREE_CURRENT_CONFIG

卸载

# 全局卸载
npm uninstall -g @free-air/claude-code

# 清理 shell 配置
free remove

API 兼容性

此工具适用于任何遵循 Anthropic API 规范的提供商，包括：

• Moonshot AI (Kimi)
• Zhipu AI (GLM)
• Minimax
• Claude (Anthropic)
• 自定义本地提供商

开发

代码仓库

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

测试

free hook
free list
free switch kimi
free current
free remove

License

MIT License - 可自由用于个人或商业项目

作者

wusfe - GitHub

贡献

欢迎提交 Issue 和 Pull Request 到 GitHub

更新日志

v0.1.0 (2026-04-02)

• 首次发布
• 支持 9 种 Shell 类型（Bash、Zsh、Fish、PowerShell、Ksh、Tcsh、Csh、Dash、Sh）
• 通过 npm postinstall 自动安装 hook
• 通过 free hook 命令手动安装 hook
• 多文件配置支持
• 幂等块插入/删除支持