[工具分享]CCSwitch 接入Claude 无限token
直接切入正题，今天要分享的是一个开源、免费、跨平台的AI环境切换工具——CCSwitch。同时我拿AgnesAI来给大家做一把完整的配置演示。目前AgnesAI那边还提供了免费的Token可以用，所以有兴趣的话可以直接上手体验整套流程。
1. 概念
CCSwitch 本质上是一个跨平台桌面端AI环境切换助手，完全开源免费，覆盖Windows、macOS和Linux三大平台。它的核心作用——帮你统一管理多个AI编程工具的API配置，并且做到一键切换，彻底告别手动调参数的麻烦。
举个例子，如果你同时在用Claude Code、Codex、Gemini CLI这些工具，每个都需要单独配API Key和模型参数，手动折腾确实挺累人。CCSwitch的思路很简单：你只需要在它里面配好各个供应商的信息，鼠标点一下，配置自动同步到对应的CLI工具里。
这个工具目前支持Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes Agent等7款主流AI编程工具，内置了50多个预设的供应商配置，基本覆盖了主流的中外模型服务商。
本文这次要用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
- Windows 用户：
- 推荐下载
.msi安装包，支持自动更新，双击运行安装即可 - 默认装在C盘，建议改到非系统盘（比如
D:Program FilesCC Switch） - 如果不想写注册表，可以下Portable便携版（
.zip），解压后直接双击CC-Switch.exe就能跑
- macOS 用户：
- 下载
.dmg文件，打开后把CC Switch.app拖入「应用程序」文件夹 - 首次启动弹出“未知开发者”或“无法验证开发者”的提示——这很正常。关掉提示，到「系统设置」→「隐私与安全性」找到CCSwitch相关提示，点「仍然打开」就能用了
- 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
- macOS：
- 通过npm安装Claude Code：
npm install -g @anthropic-ai/claude-code - 装完后在终端里跑个
claude命令验证一下就行
提示：如果你主要用其他工具（比如Codex或Gemini CLI），这步可以跳过，配置逻辑是一样的。
# 查看是否安装成功 node -v claude -v
第三步：注册 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
注册步骤：
- 访问Agnes AI平台注册地址：https://platform.agnes-ai.com/login，用Github账号直接登录很方便
- 注册并登录账号
- 进入后台的「API密钥」页面，或直接访问：https://platform.agnes-ai.com/settings/apiKeys
- 点「创建新密钥」，生成一个新的API Key
- 务必复制并保存好这个Key（格式类似
sk-xxxxxxxxxxxxxxxx）。出于安全考虑，之后你没法再通过账户查看这个Key，丢了只能重新生成
3. 配置
好，准备工作做完了，咱们就可以进入正题，在CCSwitch里把Agnes加进去作为供应商了。
第一步：打开新增供应商界面
启动CCSwitch后，根据你要用的AI工具点一下顶部对应的图标（我这里用的是Claude Code，所以点第一个Claude图标），然后点右上角的「+ 新增供应商」。
第二步：创建自定义供应商
- 预设供应商选「自定义配置」
- 供应商类型也选「自定义配置」
第三步：填写 API 信息
下面这几项是关键信息，填对就能跑：
| 配置项 | 填写内容 |
|---|---|
| 名称 | 任意备注名，比如Agnes-Free |
| API Key | 粘贴刚才复制的Agnes API Key |
| 请求地址 | https://apihub.agnes-ai.com/v1 |
| API 格式 | 选择OpenAI Chat Completions 兼容格式 |
第四步：获取模型列表并添加模型
- 在配置页面找到「模型映射」，点「获取模型列表」
- 系统会自动拉取你当前账号可用的模型列表
- 拉取成功的话，通过下拉框选不同的模型映射就行。我这里全部映射到agnes-2.0-flash
- 点「添加」完成模型创建
Claude Code实际跑起来的时候，可能会带一些模型不认识的参数，比如thinking、context_management这些。为了避免请求因为参数不兼容直接挂掉，可以在CCSwitch里加上如下参数：
"allowed_openai_params": [
"thinking",
"context_management"
],
"litellm_settings": {
"drop_params": true
}
第五步：开启本地路由映射（重要！）
如果你用的是Claude Code，这一步千万不能少：
- 在配置页面找到「需要本地路由映射」，打开开关
- 进入CCSwitch的「设置」 → 「本地路由」，确保下面两个开关都打开：
- 路由总开关：开启
- Claude Code 路由：开启
⚠️ 很多新手配置完发现不能用，十有八九就是本地路由没开。这个环节很关键，务必确认到位！
第六步：切换到新创建的渠道
回到CCSwitch主界面，点一下刚创建的Provider（比如Agnes-Free），再点「启用」，配置就会自动生效。
4. 验证
全部配置完成后，怎么确认它真的跑起来了？
- 健康检查：在CCSwitch中点Provider旁边的「健康检查」按钮，发个测试请求验证API Key和网络连通性
- 重启客户端：关掉Claude Code再重新打开（或者其他你用的AI工具），让配置重新加载
# 终端输入claude，启动claude cli claude
- 实际测试：随便问个问题，看能不能正常返回结果
如果健康检查过了但工具还是用不了，回头检查一下本地路由开关开了没。
顺便说一句，虽然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编程环境。把核心步骤再拎一下：
- 安装CCSwitch（跨平台，3分钟搞定）
- 注册Agnes AI获取免费API Key（免费，无限期）
- 在CCSwitch中添加自定义Provider（填好Base URL和API Key）
- 开启本地路由映射（Claude Code用户必经之路）
- 启用并测试
配置完成后，就能在Claude Code、Codex这些工具里自由调用Agnes-2.0-Flash模型了。如果你平时在多个AI编程工具之间来回切换、手头握了好几套不同的API配置，CCSwitch确实值得一试。
