Claude Code + Agnes：接入无限期免费文本、图片、视频模型，告别 Token 焦虑

一句话速览：Claude Code 通过 CC Switch 做协议转换接入 Agnes 免费模型，支持 Sonnet/Opus/Haiku 三档模型映射到 Agnes 的文本/图片/视频模型，是四个主流 IDE 中接入最复杂但功能最全的方案。本文从 CC Switch 安装到 env 环境变量配置，保姆级全流程实操。

背景：Agnes AI 是什么？

Agnes AI 是新加坡 Sapiens AI 公司旗下的全模态模型品牌，自研文本、图像、视频三大模型，完全兼容 OpenAI API 格式。自 2026 年 6 月 1 日起，三大模型 API 无限期、全球范围免费开放------无需绑卡、无 Token 额度上限，仅限制每分钟请求数（约 30 RPM）。

而 Claude Code 原生使用 Anthropic 协议，不能直接调用 OpenAI 兼容接口。通过 CC Switch 做协议转换，可以让 Claude Code 无缝使用 Agnes 模型。

一、Claude Code 用户的痛点

Claude Code 需要 Anthropic API Key，免费额度极少，付费 Claude Pro 每月 $20 但有使用上限。对于经常用 Claude Code 做项目分析、代码审查、测试生成的重度开发者，Token 消耗大，成本高。

解法：通过 CC Switch 将 Agnes 免费模型接入 Claude Code，保留 Claude Code 全部交互能力，底层流量走 Agnes，零成本使用。

二、为什么 Claude Code 接入最复杂？

四个主流 IDE 中，Claude Code 是唯一需要协议转换的：

IDE	接入方式	复杂度
Cursor	BYOK（4 行 JSON）	最简单
Trae	界面添加自定义模型	简单
Codex	CC Switch / Codex++	中等
Claude Code	CC Switch + 协议转换 + env 环境变量 + 参数兼容	最复杂

原因：Claude Code 原生走 Anthropic Messages API 协议，而 Agnes 是 OpenAI Chat Completions 格式。需要 CC Switch 底层基于 LiteLLM 做协议转换，还要处理 Claude Code 发送的私有参数（thinking、context_management），否则会报参数不识别错误。

复杂归复杂，但 Claude Code 的模型映射机制可以让 Sonnet/Opus/Haiku 三个级别分别映射到不同的 Agnes 模型，是唯一能在一个配置里同时挂载文本、图片、视频三个模型的方案。

三、第一步：前置准备

准备项	说明
Claude Code	已安装（`npm install -g @anthropic-ai/claude-code`）
CC Switch	从 GitHub Releases 下载：`https://github.com/farion1231/cc-switch/releases`
Agnes API Key	下方第二步获取

四、第二步：注册 Agnes 拿 Key（2 分钟）

访问 https://platform.agnes-ai.com
注册登录（邮箱 / Google / GitHub，无需绑卡）
进入「设置」→「API 密钥」→ 创建新密钥
复制 sk-xxxx 密钥（仅展示一次，丢失需重新创建）

五、第三步：配置 CC Switch（核心步骤）

5.1 切换工作模式

打开 CC Switch，顶部选择 claude-cli 标签页（桌面端选 desktop 标签）。

5.2 开启本地路由

点击左上角「设置」图标
切换到「路由配置」标签
路由模式选择「本地路由」
找到 Claude 专属路由，开启启用开关

踩坑警告：这一步最容易漏掉！前面配置全对，路由没开，请求不会走 Agnes 这条线，自然一直没反应。

5.3 新增 Agnes 供应商

回到 Claude 主界面，点击右上角「+」新增供应商：

配置项	填写内容
供应商类型	`claude`
配置方式	`自定义配置`
API Key	`sk-你的密钥`
请求地址	`https://apihub.agnes-ai.com/v1`
API 格式	`OpenAI Chat Completions`
模型	`agnes-2.5-flash`

点击「获取模型列表」，能拉到模型说明地址和密钥正确。选中 agnes-2.5-flash 完成映射绑定。

5.4 参数兼容配置（Claude Code 必配）

Claude Code 原生请求会携带私有参数 thinking、context_management，Agnes 模型不识别这些字段，必须配置自动丢弃。

进入供应商高级设置，粘贴以下 JSON（与 env、theme 同级，合并到一个根对象）：

json 复制代码

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的API密钥",
    "ANTHROPIC_BASE_URL": "https://apihub.agnes-ai.com/v1",
    "ANTHROPIC_MODEL": "agnes-2.5-flash",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "agnes-2.5-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "agnes-2.5-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "agnes-2.5-flash"
  },
  "allowed_openai_params": ["thinking", "context_management"],
  "litellm_settings": {
    "drop_params": true
  }
}

配置参数	功能说明
`env.ANTHROPIC_BASE_URL`	将 Claude Code 请求转发到 Agnes
`env.ANTHROPIC_AUTH_TOKEN`	Agnes API 密钥
`env.ANTHROPIC_MODEL`	默认模型
`env.ANTHROPIC_DEFAULT_*_MODEL`	Sonnet/Opus/Haiku 三档模型映射
`allowed_openai_params`	声明允许透传的 Claude 扩展参数
`litellm_settings.drop_params`	自动丢弃模型不识别的未知参数

JSON 格式踩坑 ：所有内容只允许一对最外层 {}。如果 theme 闭合后又新开一组 {}，JSON 语法报错。env 内部最后一行不加逗号，theme 后面必须加逗号。

5.5 启用供应商

回到供应商列表，找到 Agnes 供应商，点击「Enable」启用。

5.6 重启 Claude Code

完全关闭终端，重新打开。在项目文件夹输入 claude，此时界面可能仍显示 Claude 原模型名（前端 UI 展示缺陷），但底层流量已走 Agnes，以 CC Switch 代理日志为准。

六、进阶：三档模型映射（Claude Code 独有优势）

Claude Code 的 Sonnet/Opus/Haiku 三级模型架构，可以分别映射到 Agnes 的不同模型，实现一个配置挂载三大能力：

json 复制代码

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://apihub.agnes-ai.com/v1",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "agnes-2.5-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "agnes-image-2.1-flash",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "agnes-2.5-flash"
  },
  "allowed_openai_params": ["thinking", "context_management"],
  "litellm_settings": { "drop_params": true }
}

Claude Code 档位	映射到 Agnes 模型	实际能力
Sonnet（主力编码）	agnes-2.5-flash	文本编码
Opus（高级任务）	agnes-image-2.1-flash	切换到生图
Haiku（轻量任务）	agnes-2.5-flash	文本编码

这是 Claude Code 独有的玩法------其他 IDE 只能手动切换模型，Claude Code 可以通过 CC Switch 的模型映射机制，让不同档位自动走不同模型。

七、实测效果

文本编码

agnes-2.5-flash 支持 256K 上下文窗口、Tool Calling 和 Thinking Mode。大型代码项目全量分析（目录梳理、核心模块定位、调用依赖梳理、TODO/FIXME 识别）数分钟完成。跨文件协同修改、主动定位消除 Bug、从零构建完整应用都能搞定。

文生图

通过 Opus 档位映射 agnes-image-2.1-flash，或通过 Skill 封装调用。微服务架构图、电商下单流程图等技术图表生成效果良好------这是 Agnes 图片模型的核心优势，不局限于插画创作。支持最高 4K（4096×4096）输出。

文生视频

通过 Skill 或 API 调用 agnes-video-v2.0，支持 720P/1080P，原生同步生成音频，最长 18 秒。

视频踩坑 ：帧数必须是 8n+1（9/17/25...81），填错必报错；高峰期可能 500，错开重试。

八、踩坑避雷速查表

问题	原因	解决方案
请求完全没反应，CC Switch 无日志	本地路由未启用	设置 → 路由 → 开启 Claude 路由
`unrecognized parameter` 报错	未配置 drop_params	高级设置添加 `litellm_settings.drop_params: true`
401 认证失败	密钥复制不全或带空格	重新复制密钥，确认无多余字符
503 "No available channel"	模型名大小写错误	用 `GET /v1/models` 查实际模型名
界面显示 Claude 原模型名	前端 UI 展示缺陷	正常现象，以 CC Switch 代理日志为准
JSON 语法报错	多个根对象 `{}`	合并到一个 `{}` 内，检查逗号
图片/视频调用失败	未做模型映射或 Skill 封装	配置 Opus 档位映射或封装 Skill
视频报错	帧数不是 8n+1	帧数填 9/17/25/33...81

九、生态工具：GitHub 现成封装

不想手动配置，可以直接用社区现成的 Skill：

Agnes AI Generation Skill

仓库：https://github.com/Yacey/agnes-ai-generation-skill

支持 Claude Code、Cursor、Windsurf、Codex 等主流工具，内置中文提示词自动英译，覆盖文生图、图生图、文生视频、多图生成视频。

Agnes Free Model Skills

仓库：https://github.com/kangarooking/agnes-free-model-skills

拆分为三个独立 Skill：agnes-free-text（文本）、agnes-free-image（图片）、agnes-free-video（视频），职责更清晰。

十、适用场景

场景	推荐方案	说明
大型代码库全量分析	agnes-2.5-flash	256K 上下文，零成本
微服务架构图 / 流程图	Opus 映射 agnes-image	技术图表是 Agnes 图片模型优势
项目重构 / 测试生成	agnes-2.5-flash	重度任务零成本
短视频素材	agnes-video-v2.0 Skill	音画同步，支持 18 秒

总结：最复杂但最值

步骤	操作	耗时
1. 前置准备	安装 Claude Code + CC Switch	5 分钟
2. 注册拿 Key	platform.agnes-ai.com 注册 + 创建密钥	2 分钟
3. 配 CC Switch	切模式 → 开路由 → 加供应商 → 配参数	8 分钟
4. 配模型映射	env 环境变量 + 三档映射	3 分钟

Claude Code + Agnes 是四个 IDE 中接入最复杂、但功能最全的方案。协议转换、参数兼容、模型映射三道关卡让配置门槛高于其他 IDE，但换来的是：三档模型映射（一个配置挂载文本+图片+视频）、256K 上下文编码零成本、保留 Claude Code 全部交互能力。对于重度使用 Claude Code 做项目分析的开发者，这是目前最彻底的免费方案。

参考链接

Agnes 官方 Claude CLI 集成指南：https://wiki.agnes-ai.com/zh-Hans/docs/cid3
Agnes 官方 Claude Desktop 集成指南：https://wiki.agnes-ai.com/zh-Hans/docs/cid4
Agnes 官方开发者平台：https://platform.agnes-ai.com
Agnes 官方 FAQ（免费政策与定价）：https://wiki.agnes-ai.com/en/docs/faqs

本文数据截至 2026年9月14日，基于多方信源交叉验证。免费政策与模型版本以官方最新文档为准。

觉得有用？点赞 + 收藏 + 关注，后续持续跟进相关内容。