用 Agnes AI 免费模型增强 Claude Code：从零上手指南
你是否想过，Claude Code 不仅可以调用 Anthropic 自家的模型，还能通过代理接入第三方 AI 平台？本文将介绍一个名为 Agnes AI 的平台，以及如何将其接入 Claude Code，让你在本地开发中免费使用强大的 AI 模型。
一、Agnes AI 是什么？
Agnes AI 是一个提供开放 AI 模型服务的平台，其核心产品是一个兼容 OpenAI API 格式的模型网关（API Gateway）。它提供的 agnes-2.0-flash 等模型，能够在 Claude Code 这类本地 Agent 工具中无缝运行。
为什么 Agnes AI 是免费的？
Agnes AI 选择提供免费服务，背后有几个关键原因：
- 降低 AI 开发门槛 --- 很多开发者有想法，但被 API 费用挡在外面。Agnes AI 希望每个人都能零成本地尝试和构建 AI 应用。
- 生态先行策略 --- 通过免费模式快速积累用户和开发者社区，为后续的商业化探索打下基础。
- 开放兼容的设计 --- 采用 OpenAI Chat Completions 兼容格式，意味着任何支持 OpenAI SDK 的工具都能直接接入，无需额外改造。
简单来说，Agnes AI 让"免费用大模型做开发"这件事真正变得可行。
二、为什么要在 Claude Code 中使用 Agnes AI？
Claude Code 是 Anthropic 官方的命令行 AI Agent，广泛用于代码编写、调试和重构。它默认使用 Anthropic 自己的模型（Sonnet / Opus / Haiku），但这些模型的 API 调用是有费用的。
将 Agnes AI 接入 Claude Code 后，你可以获得：
- 零成本调用 --- 不再消耗 Anthropic 的 API 额度
- 本地 Agent 体验不变 --- 所有 Claude Code 的功能照常使用
- OpenAI 兼容 --- 任何支持 OpenAI 格式的工具都可以复用这套配置
三、准备工作
在开始之前，确保你已满足以下条件：
| 条件 | 说明 |
|---|---|
| Claude CLI | 已安装 Claude Code |
| CC-Switch | 已安装 CC-Switch，用于代理路由 |
| Agnes API Key | 在 Agnes AI Platform 注册并获取 |
| 网络 | 能正常访问 https://apihub.agnes-ai.com/v1 |
四、获取 Agnes API Key
- 访问 Agnes AI Platform
- 登录你的账号
- 进入 API Key 管理页面
- 创建一个新的 API Key 并复制保存
注意： 拿到 Key 后不要泄露给他人，后续配置中通常不需要手动添加
Bearer前缀。
五、配置 CC-Switch 代理
CC-Switch 是连接 Claude Code 和 Agnes AI 的桥梁。它充当本地代理，将 Claude Code 发出的模型请求转发到 Agnes 的 API 网关。
步骤 1：启动 CC-Switch
启动 CC-Switch 后，在顶部工具栏中选择 Claude CLI，进入 Claude CLI 的模型代理配置界面。
步骤 2：添加自定义供应商
点击右上角的 加号，添加一个新的供应商：
- 供应商类型选择 Claude Provider
- 进一步选择 Custom Provider（自定义服务商）
步骤 3：填写 API Key
在 API Key 输入框中粘贴你从 Agnes AI Platform 获取的 Key：
YOUR_API_KEY一般只需填写 Key 本身，不需要手动加 Bearer 前缀。
步骤 4：配置请求地址
在请求地址栏中填入：
https://apihub.agnes-ai.com/v1这是 Agnes AI 的 API 网关地址，所有请求都会通过这里转发。
步骤 5：选择 API 格式
API 格式选择 OpenAI Chat Completions。
Agnes AI 完全兼容 OpenAI 的接口格式，所以 Claude Code 发出的请求不需要任何修改就能直接使用。
步骤 6：配置认证字段
认证字段保持默认即可。如果需要手动配置，使用：
ANTHROPIC_AUTH_TOKEN步骤 7：获取模型列表
点击"获取模型列表"按钮，确认 CC-Switch 能正常连接到 Agnes AI 网关。这一步能帮你提前发现网络或 Key 的问题。
步骤 8：配置模型映射
将 Claude Code 中的模型映射到 Agnes 的模型。推荐映射如下：
Sonnet → agnes-2.0-flash
Opus → agnes-2.0-flash
Haiku → agnes-2.0-flash你也可以根据 Agnes 平台实际提供的其他模型进行灵活替换。
步骤 9：添加自定义参数（重要）
为了避免某些不兼容参数导致请求失败，建议在自定义参数中添加以下 JSON 配置：
json
{
"allowed_openai_params": [
"thinking",
"context_management"
],
"litellm_settings": {
"drop_params": true
}
}这段配置的作用：
allowed_openai_params--- 允许指定的 OpenAI 参数透传通过drop_params: true--- 自动丢弃模型不兼容的未知参数，避免报错
这大大提高了通过代理调用 OpenAI-Compatible API 时的兼容性。
步骤 10：保存供应商配置
确认所有配置无误后，点击 保存。保存成功后，供应商列表中会出现你的 Agnes 配置项。
六、开启路由
配置完供应商后，还需要告诉 CC-Switch 把流量导向 Agnes。
- 点击 CC-Switch 左上角的 设置，进入路由配置
- 选择 Route
- 打开 Local Route 开关
- 在本地路由中启用 Claude 路由
启用 Agnes 供应商
返回供应商列表，找到你刚才配置的 Agnes Provider，点击 启用。
启用之后，Claude Code 发出的所有请求都会自动通过 CC-Switch 转发到 Agnes AI 网关。
七、验证配置
打开终端，启动 Claude Code：
bash
claude发送一条测试消息，比如：
帮我写一个简单的 Python 函数，计算斐波那契数列的第 n 项如果配置正确，你会收到来自 Agnes 模型的响应。整个过程中，Claude Code 的界面和操作习惯没有任何变化，只是背后的"大脑"换成了 Agnes AI。
八、常见问题排查
无法获取模型列表
- 检查 API Base URL 是否为
https://apihub.agnes-ai.com/v1 - 确认 API Key 是否正确且未过期
鉴权失败
- 确认 API Key 填写正确，没有多余空格
- 通常只需填写 Key 本身，不要手动添加
Bearer前缀
请求报错或参数不兼容
- 确认已按步骤 9 添加自定义参数配置
drop_params: true能解决大部分兼容性问题
Claude Code 没有走 Agnes 模型
- 检查 CC-Switch 的 Local Route 是否已开启
- 确认 Agnes Provider 已启用
模型响应异常
- 确认模型映射是否正确（Sonnet/Opus/Haiku → agnes-2.0-flash）
- 尝试重新获取模型列表刷新缓存
九、总结
通过 CC-Switch 代理，我们可以将 Claude Code 的模型请求路由到 Agnes AI 的 API 网关，实现免费使用强大的 AI 模型来完成本地开发任务。整个过程的核心步骤是：
- 注册 Agnes AI 并获取 API Key
- 配置 CC-Switch 作为本地代理
- 映射 Claude Code 的模型到 Agnes 模型
- 开启 本地路由并启用供应商
这套方案不仅适用于 Agnes AI，任何支持 OpenAI 兼容格式的第三方模型平台都可以用同样的方式接入 Claude Code。掌握这个方法，你就拥有了自由切换 AI 模型的能力。