1. 为什么要在 Claude Code 里接 Agnes 这类免费模型Claude Code 本身是个很好用的终端编码助手但它的默认模型走的是 Anthropic 官方通道对不少开发者来说有两个现实问题一是额度有限二是想换模型时得改环境变量、改配置来回折腾。我平时写脚本、调接口、做小工具很多时候并不需要顶级模型一个响应快、能稳定返回结果的免费模型就够了。Agnes 就是这类场景里比较合适的选择它提供 OpenAI Chat Completions 兼容接口意味着只要把请求地址和 Key 换掉Claude Code 就能把请求发到 Agnes 上。但问题来了Claude Code 原生并不直接支持「随便填一个第三方 OpenAI 兼容地址」这种玩法它认的是 Anthropic 的协议格式。这时候 cc-switch 就派上用场了。cc-switch 是一个专门给 Claude Code 做供应商切换的小工具它能在本地起一个路由层把 Claude Code 发出的 Anthropic 格式请求转换成 OpenAI Chat Completions 格式再转发到你填的 Base URL 上。换句话说Claude Code 以为自己在跟 Anthropic 说话实际上请求被 cc-switch 转给了 Agnes。这套链路适合谁适合已经装好 Claude Code、想用统一 Key 管理多个模型调用的开发者适合不想每次都改环境变量、希望点几下就能切换供应商的人也适合想先拿免费模型练手、验证自己工作流是否跑得通的新手。整条链路的核心就三样东西Base URL、API Key、Model ID。把这三个填对剩下的交给 cc-switch 的路由。我试过把这套流程走了一遍踩过的坑主要集中在「API 格式选错」和「模型列表拉不出来」这两步。下面我把完整链路拆开讲包括 cc-switch 的配置文件片段、Key 和 Base URL 的填写位置以及怎么用一次 OpenAI Chat Completions 格式的请求来验证 Agnes 是否真的通了。2. 前置准备Claude Code、cc-switch 与 TaoToken 的定位在动手之前先把三样东西的角色理清楚不然后面配置容易乱。Claude Code 是终端里的编码助手你输入claude就能跟它对话。它默认读的是 Anthropic 的接口所以我们需要一个「翻译层」。cc-switch 就是这个翻译层它负责把 Claude Code 的请求转成 OpenAI 兼容格式。而 Agnes 是最终提供模型推理的服务方它的接口地址是https://apihub.agnes-ai.com/v1走的是标准 OpenAI Chat Completions 协议。那 TaoToken 在这里是什么角色TaoToken 是一个统一管理 API Key 和模型调用的平台你可以把它理解成「Key 的中转管家」。它的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。当你需要在多个模型、多个供应商之间切换时TaoToken 能帮你把 Key 和 Base URL 统一管起来不用每换一个模型就重新找一遍配置。对于本文这种「Claude Code cc-switch Agnes」的组合TaoToken 的价值在于你可以把 Agnes 的 Key 和地址登记到 TaoToken 的体系里后续想换模型时改一处就行。前置条件其实不多第一Claude Code 已经装好终端里输入claude能正常启动第二cc-switch 已经装好能打开它的配置界面第三Agnes 账号已经注册并且能进开放平台创建 API Key。这三样齐了就可以往下走。这里要提醒一句cc-switch 的配置界面在不同版本里位置可能略有差异但核心字段是一样的——API Key、请求地址、API 格式、模型列表。你只要找到这几个字段剩下的就是填值。如果你还没装 cc-switch可以先把它当成一个「Claude Code 的供应商切换器」来理解它的作用就是让你不用手动改 Claude Code 的底层配置而是在一个图形界面里点选。另外TaoToken 的 Coding Plan 适合长期做编码和 Agent 的场景如果你后面想把多个模型统一管起来可以关注 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。不过本文的重点还是先把 Agnes 这条链路跑通跑通之后再考虑统一管理的事。3. 可复制配置cc-switch 里填 Key、Base URL 与 API 格式这一步是整篇文章的核心也是最容易出错的地方。我把它拆成「拿 Key」「填 cc-switch」「选格式」「拉模型」四个动作每个动作都给出可复制的片段。3.1 在 Agnes 开放平台创建 API Key打开 Agnes 的开放平台找到「创建 API Key」的入口名称随便起比如claude-code-test。创建完成后页面会显示一串 Key这就是你后面要填到 cc-switch 里的值。注意这串 Key 只显示一次复制后先存到安全的地方别直接贴在聊天窗口里。3.2 cc-switch 的配置片段打开 cc-switch选择「自定义供应商」。你会看到几个关键字段我按填写位置说明API Key粘贴刚才从 Agnes 复制的 Key。请求地址Base URL填https://apihub.agnes-ai.com/v1。注意结尾的/v1不能少这是 OpenAI 兼容接口的路径约定。API 格式点开「高级」选项选择OpenAI Chat Completions。这一步非常关键如果选成 Anthropic 格式请求会被发成错误的协议后面验证必然失败。如果你习惯用配置文件的方式管理cc-switch 的配置本质上是一个 JSON 结构核心字段如下路径以你本机 cc-switch 的实际配置目录为准通常在用户目录下的.cc-switch或类似位置{ provider: custom, name: agnes, baseUrl: https://apihub.agnes-ai.com/v1, apiKey: 你的Agnes API Key, apiFormat: openai-chat-completions, model: agnes 模型 ID }这段 JSON 里的apiFormat必须和界面里选的OpenAI Chat Completions一致。model字段先留空也行后面通过「获取模型列表」来选。3.3 获取模型列表并选择模型填完 Key 和地址、选好格式之后点「获取模型列表」。如果网络和 Key 都正常cc-switch 会拉回 Agnes 支持的模型列表。从列表里选一个你要用的模型比如 Agnes 提供的某个通用对话模型。选完后点「添加并启动配置」。这里有个细节模型 ID 一定要和列表里显示的一致不要自己手写。手写容易多空格或者大小写不对导致后面请求返回model not found。3.4 开启路由并指向 Claude Code在 cc-switch 的设置页面开启「路由」功能然后点选claude code。这一步的作用是让 cc-switch 在本地监听一个端口Claude Code 的请求会先到这个端口再被转发到 Agnes。开启之后cc-switch 的界面通常会显示一个「运行中」的状态。如果你用的是 Codex 或者 Cline MCP 这类工具配置逻辑是一样的都是三件套Base URL、Key、Model ID。比如 Codex 的auth.json里也是填这三样只是字段名不同。Cline MCP 则是在 MCP 配置里指定供应商和模型。核心不变地址对、Key 对、模型 ID 对。配置完成后cc-switch 的界面应该显示当前供应商是agnesAPI 格式是OpenAI Chat Completions路由已开启。这时候 Claude Code 的请求就会被正确转发。4. 验证请求用 OpenAI Chat Completions 格式确认 Agnes 返回结果配置填完不代表通了必须做一次实际请求验证。验证分两层先用 curl 直接打 Agnes 的接口确认 Key 和地址本身没问题再启动 Claude Code确认整条链路通了。4.1 用 curl 直接验证 Agnes 接口打开终端执行下面这条命令把你的Agnes API Key和模型ID替换成实际值curl https://apihub.agnes-ai.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的Agnes API Key \ -d { model: 模型ID, messages: [ {role: user, content: 用一句话说明什么是递归} ] }如果返回的 JSON 里有choices字段并且choices[0].message.content里有内容说明 Agnes 的 Key、地址、模型 ID 都是对的。这一步是「最小验证」排除了 cc-switch 的干扰直接确认服务方可用。如果这一步就报错那问题在 Agnes 侧不在 cc-switch。常见的是 Key 复制不全、模型 ID 写错、或者账户额度问题。4.2 启动 Claude Code 验证整条链路curl 通了之后回到终端输入claude然后随便问一个问题比如「帮我写一个 Python 函数判断一个数是不是质数」。如果 Claude Code 能正常返回回答说明 cc-switch 的路由生效了请求被正确转成了 OpenAI Chat Completions 格式并转发到了 Agnes。这里要注意Claude Code 启动时读的是它自己的配置而 cc-switch 的路由会拦截它的请求。如果你之前改过 Claude Code 的环境变量比如ANTHROPIC_BASE_URL可能会和 cc-switch 冲突。建议先把这些环境变量清掉让 cc-switch 接管。4.3 验证成功的标志成功的标志有三个第一curl 返回的 JSON 里有choices第二Claude Code 能正常对话第三cc-switch 界面显示路由运行中且没有报错日志。三个都满足说明「Claude Code → cc-switch → Agnes」这条链路完全通了。如果你想进一步确认请求确实走了 Agnes可以在 cc-switch 的日志里看请求记录通常会显示转发的目标地址和模型 ID。看到apihub.agnes-ai.com就说明转发正确。5. 常见报错排查401、local proxy failed、reading choices、OAuth配置过程中最容易遇到四类报错我按实际遇到的顺序说。401 Unauthorized这是最常见的。原因通常是 API Key 填错、Key 前后有空格、或者 Key 已经失效。排查方法把 Key 重新复制一遍注意不要多复制换行符用 curl 直接打 Agnes 接口如果 curl 也 401那就是 Key 本身的问题去 Agnes 开放平台重新创建一个。local proxy failed这个报错说明 cc-switch 的本地路由没起来或者端口被占用。排查方法检查 cc-switch 是否显示「运行中」如果端口被占用换一个端口重启 cc-switch 再试。有时候是 Claude Code 启动时 cc-switch 还没准备好先启动 cc-switch 再启动 Claude Code 就能解决。reading choices 相关报错比如cannot read property choices of undefined这通常说明返回的 JSON 结构不对。原因可能是 API 格式选错了——比如选成了 Anthropic 格式但 Agnes 返回的是 OpenAI 格式解析自然失败。回到 cc-switch 的高级设置确认 API 格式是OpenAI Chat Completions。另一个可能是模型 ID 不对导致返回了错误信息而不是正常的 choices 结构。OAuth 相关报错如果你在 Claude Code 里看到 OAuth 相关的提示说明 Claude Code 还在尝试走 Anthropic 的官方认证流程没有走 cc-switch 的路由。排查方法检查 cc-switch 的路由是否开启并点选了claude code检查是否有残留的 Anthropic 环境变量必要时重启终端和 Claude Code。除了这四类还有一个隐蔽的坑模型列表拉不出来。这通常是 Base URL 结尾少了/v1或者网络请求被本地防火墙拦了。确认地址是https://apihub.agnes-ai.com/v1并且 cc-switch 有网络访问权限。如果你在多个工具之间切换比如同时用 Claude Code、Cline MCP、Codex建议把三件套Base URL、Key、Model ID记在一个地方避免每次重新找。TaoToken 的 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 可以帮你统一管理这些 Key接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 遇到配置问题可以先翻文档对照。6. 统一 Key 管理把 Agnes 接入 TaoToken 的后续思路链路跑通之后你可能会遇到一个新问题模型越来越多Key 越来越杂。今天用 Agnes明天想换另一个免费模型后天又要切回 Claude 官方每次都要改 cc-switch 的配置很烦。这时候统一 Key 管理的价值就出来了。TaoToken 的思路是你把各个供应商的 Key 和 Base URL 登记到它的体系里然后用一个统一的入口去调用。对于 Claude Code 这种场景你可以把 cc-switch 的请求地址指向 TaoToken 的 API 入口 https://taotoken.net/api 由 TaoToken 来决定最终转发到哪个模型。这样你换模型时只需要在 TaoToken 侧改配置cc-switch 和 Claude Code 都不用动。具体操作上你可以先在 TaoToken 的模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 验证一下 Agnes 模型是否可用确认返回正常后再把 Key 和地址填到 cc-switch 里。如果你长期做编码和 Agent 开发Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 会更适合它针对编码场景做了优化。对于 Claude Code 的深度用户还有一个入口是 ClaudeCodeAnthropichttps://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 它专门处理 Claude Code 相关的接入配置。如果你在 cc-switch 里遇到协议转换的问题可以参考这个页面的说明。最后说一个实用技巧把 cc-switch 的配置文件和 TaoToken 的 Key 分开管理。cc-switch 的配置里只放 Base URL 和模型 IDKey 统一从 TaoToken 的 API Keys 页面获取。这样即使你换了 Key也只需要改一处。另外每次改完配置后先用 curl 打一次接口确认返回正常再启动 Claude Code能省掉很多排查时间。整条链路的核心就是三件套对齐Base URL 对、Key 对、Model ID 对剩下的都是细节。