1. 概念

CCSwitch 是一款开源免费的跨平台桌面 AI 环境切换助手，支持 Windows、macOS 和 Linux。它的核心作用是帮你统一管理多个 AI 编程工具的 API 配置，实现一键切换。

简单来说，如果你同时使用 Claude Code、Codex、Gemini CLI 等多个 AI 编程工具，每个工具都需要单独配置 API Key 和模型参数——手动改来改去非常麻烦。CCSwitch 就是解决这个痛点的工具：你只需要在 CCSwitch 里配置好各个 Provider（供应商），然后点一下就能切换，它会自动把配置同步到对应的 CLI 工具中。

CCSwitch 支持管理的 AI 工具包括：Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes Agent 等七大主流工具。它还内置了 50 多个预设 Provider 配置，覆盖了主流的中外模型服务商。

本文将以 Claude Code + CCSwitch + Agnes-2.0-Flash 的组合为例，手把手教你完成配置。Agnes-2.0-Flash 是 Agnes AI 开放的一款完全免费的文本模型，支持 1M Token 上下文，非常适合新手入门。

2. 安装

在开始配置之前，需要先做一些前置工作。

第一步：下载并安装 CCSwitch

官方网址：https://www.ccswitch.io/zh/

官方下载地址：https://github.com/farion1231/cc-switch/releases

1. Windows 用户：

• 下载 .msi 安装包（推荐，支持自动更新），双击运行安装程序
• 默认安装到 C 盘，建议修改到非系统盘（如 D:\Program Files\CC Switch）
• 如果不想写注册表，可以下载 Portable 便携版（.zip 文件），解压后直接运行 CC-Switch.exe

2. macOS 用户：

• 下载 .dmg 文件，双击打开后将 CC Switch.app 拖入「应用程序」文件夹
• 首次启动时如果提示“未知开发者”或“无法验证开发者”，这是正常情况。关闭提示后，前往「系统设置」→「隐私与安全性」，找到 CCSwitch 相关提示，点击「仍然打开」即可

3. Linux 用户：

• 根据发行版选择 .deb、.rpm 或 .AppImage 格式
• 使用 .AppImage 的话，下载后添加执行权限即可运行

第二步：准备 Claude Code 环境（可选）

如果你打算用 Claude Code 来调用 Agnes 模型，需要先安装并配置好 Claude Code 基础环境：

• 安装 Node.js（推荐 LTS 版本）
  • macOS：brew install node@20
  • Windows：去 nodejs.org 官网下安装包，一路 Next
  • Linux：curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
• 通过 npm 安装 Claude Code：npm install -g @anthropic-ai/claude-code
• 安装完成后，可以在终端中运行 claude 命令验证是否成功

提示：如果你主要用其他工具（如 Codex 或 Gemini CLI），也可以跳过这一步，配置原理是一样的。

第三步：注册 Agnes AI 账号并获取 API Key

Agnes AI 开放了多款核心模型的 API，其中 Agnes-2.0-Flash 是完全免费、无限期使用的文本模型。

Agnes 的 API 地址是 https://apihub.agnes-ai.com/v1，你可以分别按需去配置模型，比如说：

• 文本模型：agnes-2.0-flash
• 图片模型：agnes-image-2.1-flash
• 视频模型：agnes-video-v2.0

注册步骤：

1. 访问 Agnes AI 平台注册地址：https://platform.agnes-ai.com/login 。可直接通过Github账号登录
2. 注册并登录账号

3. 进入后台的「API密钥」页面，或直接访问：https://platform.agnes-ai.com/settings/apiKeys
4. 点击「创建新密钥」，生成一个新的 API Key

5. 复制并保存好这个 Key（格式类似 sk-xxxxxxxxxxxxxxxx）。出于安全考虑，之后你将无法再次通过账户查看这个 Key，遗失需要重新生成

3. 配置

完成准备工作后，就可以在 CCSwitch 中添加 Agnes 作为 Provider 了。

第一步：打开新增供应商界面

启动 CCSwitch 后，根据你要使用的 AI 工具点击顶部对应的图标（例如：我这里使用的是 Claude-cli就点击 第一个Claude 图标），然后点击右上角的 「+ 新增供应商」。

第二步：创建自定义供应商

• 预设供应商选择 「自定义配置」
• 供应商类型选择「自定义配置」

第三步：填写 API 信息

填写以下关键信息：

第四步：获取模型列表并添加模型

1. 在配置页面找到 「模型映射」，点击 「获取模型列表」

• 系统会自动读取当前账号可用的模型列表
• 如果成功拉取到列表，通过下拉框选择不同模型映射即可。我这里全部选择映射到agnes-2.0-flash

4. 点击「添加」完成模型创建

Claude Code 真实跑起来时，可能会带一些模型不认识的参数，比如 thinking、context_management 这类字段。

为了避免请求因为参数不兼容直接失败，可以再CC Switch 里加如下参数：

第五步：开启本地路由映射（重要！）

如果你使用的是 Claude Code，需要额外开启本地路由映射：

• 在配置页面找到 「需要本地路由映射」 选项，打开开关
• 进入 CCSwitch 的 「设置」 → 「本地路由」，确保以下两个开关都打开：
  • 路由总开关：开启
  • Claude Code 路由：开启

?? 很多新手配置完发现无法使用，原因就是本地路由没有开启。这一步非常关键，请务必确认！

第六步：切换到新创建的渠道

返回 CCSwitch 主界面，点击刚刚创建的 Provider（如 Agnes-Free），再点击 「启用」。配置就会自动生效。

4. 验证

配置完成后，可以通过以下方式验证：

1. 健康检查：在 CCSwitch 中点击 Provider 旁边的「健康检查」按钮，发送测试请求来验证 API Key 和网络连通性

• 重启客户端：关闭并重新打开 Claude Code（或你使用的其他 AI 工具），让配置重新加载

3. 实际测试：随便问一下，看是否能正常返回结果

如果健康检查通过但工具无法使用，请检查本地路由开关是否已开启。

同时如果虽然Claude页面显示还是Opus 4.8模型，但因为我们做了模型映射，实际请求已经走到了Agnes，大家也可以到Agnes官网去查看自己的token用量。

token用量查询地址：https://platform.agnes-ai.com/billing/billing

常见问题

Q1：首次启动 CCSwitch 时提示“未识别的开发者”

A：这是 macOS 的安全机制。关闭警告窗口后，前往「系统设置」→「隐私与安全性」，找到 CCSwitch 相关提示，点击「仍然打开」即可。

Q2：系统托盘里没有 CCSwitch 图标

A：Windows 版本可能默认启动后隐藏在任务栏了，点击系统托盘区域的小箭头展开查看。如果还是没有，尝试重新启动软件。

Q3：切换 Provider 后 AI 工具没有生效

A：检查是否在 CCSwitch 顶部正确选中了对应的应用（如 Claude Code 或 Codex），因为每个应用的配置是独立管理的。另外记得重启对应的客户端。

Q4：获取模型列表失败

A：检查 API Key 是否正确、Base URL 是否填写为 https://apihub.agnes-ai.com/v1。错误配置 Base URL 会导致 404 错误。

Q5：Agnes 模型真的完全免费吗

A：是的。Agnes AI 开放了核心全模态模型的 API，免费、无限期开放、无需等待名单。文本模型 Agnes-2.0-Flash 支持 1M Token 上下文，足够日常编程使用。

总结

通过 CCSwitch + Agnes AI 的组合，你可以零成本搭建一个多模型切换的 AI 编程环境。整个过程的核心步骤就是：

1. 安装 CCSwitch（跨平台，3 分钟搞定）
2. 注册 Agnes AI 获取免费 API Key（免费，无限期）
3. 在 CCSwitch 中添加自定义 Provider（填好 Base URL 和 API Key）
4. 开启本地路由映射（Claude Code 用户必做）
5. 启用并测试

配置完成后，你就可以在 Claude Code、Codex 等工具中自由使用 Agnes-2.0-Flash 模型了。如果你平时在多个 AI 编程工具之间切换、手上有几套不同的 API 配置，CCSwitch 绝对值得一试。