前言

最近 AI 圈最火的免费 API 非 Agnes AI 莫属。自 6 月 1 日免费开放以来，短短两周内全模态周调用量就突破了3.12T Token，其中文本模型贡献 1.9T，图片与视频合计贡献 1.2T—— 这组数据足以说明，它不是噱头式的 "免费试用"，而是真正能扛住生产级流量的可用服务。

对于开发者来说，最大的利好莫过于可以把它接入 Claude Code，用免费的大上下文模型跑代码分析、项目重构、测试用例生成等重度任务；对于内容创作者，4K 图片生成和视频能力也能大幅降低素材制作成本。

这篇文章就带你完整梳理 Agnes AI 的全栈能力，以及从零接入 Claude Code 的详细步骤，同时附上常见坑点排查和生态工具盘点。

---

一、Agnes AI 核心能力全盘点

目前 Agnes 开放了文本、图片、视频三大模态 API，TTS 语音能力正在灰度中，整条内容生成链路已经非常完整。

1. 文本模型：Agnes-2.0-Flash

最大亮点是支持1M Token 上下文窗口，且无需额外配置、不用改模型名，只要请求内容在范围内就能直接调用。

很多人对 1M Token 没概念，简单说：

• 普通技术文档≈5000 字 / 10 页，1M Token 能吃下约 1500 页
• 一个中等规模的后端项目，核心代码 + 配置 + 文档基本可以一次性装入
• 跨章节问答、代码库全量分析、合同风险审查这类任务，不用再做切片和检索增强

但要注意：上下文大≠盲目塞内容。正确的用法是先通过目录、文件名、关键词定位核心文件，再把目标模块完整放入上下文，让模型做跨文件的链路分析和风险排查。1M 窗口是放大了工作台，不是替代了上下文工程。

2. 图片模型：Agnes-Image-2.1-Flash

这次升级最直观的就是支持4K 分辨率生成，最高 4096x4096，覆盖 1:1、3:4、4:3、16:9、9:16、21:9 等几乎所有主流比例。

实测下来，4K 的优势不是 "看起来更大"，而是细节质感的提升：

• 产品主图：材质反光、边缘锐利度、阴影层次明显更真实
• 场景图：远处建筑窗格、地面纹理、文字边缘不容易糊
• 图标 / UI 元素：放大后边缘干净，不会出现锯齿和模糊

生成格式同时支持 URL 和 base64，方便接入不同工作流。对于高频生成的场景，建议固定好比例、风格和负面约束，做成模板化调用。

3. 视频模型：Agnes-Video-2.0

支持 720P/1080P 输出，覆盖文生视频、图生视频、首尾帧生成、多帧引导等主流玩法，也支持镜头切换、运镜和光影氛围控制。

目前阶段更适合做：

• 短视频草稿和分镜预览
• 产品展示动画、广告素材初稿
• 剧情类视频的关键片段生成
• 图生视频保持主体一致性的场景

视频任务是异步处理，需要轮询状态，接入自动化工作流时记得做好超时和重试机制。

---

二、Claude Code 接入完整步骤

这是开发者最关心的部分。整条链路是：Claude Code → CC Switch → Agnes API，通过 CC Switch 做协议转换和参数兼容，让 Claude Code 无缝使用 Agnes 模型。

前置准备

1. Agnes API Key：前往 Agnes API Platform 注册创建
   
2. CC Switch 工具：从 GitHub Releases 下载安装
3. Claude Code / Claude Desktop 客户端
   可参考Claude Code安装配置

步骤 1：配置供应商

打开 CC Switch，顶部选择claude标签页（桌面端选对应 desktop 标签），点击右上角加号新增供应商：

• 供应商类型：claude
• 配置方式：自定义配置
• API Key：粘贴你在 Agnes 平台创建的密钥
• 请求地址：https://apihub.agnes-ai.com/v1
• API 格式：openai chat completions
• 模型：agnes-2.0-flash

填完后点击 "获取模型列表"，能正常拉到agnes-2.0-flash，说明地址和 Key 基本没问题，再按提示完成模型映射。

步骤 2：启用路由

回到 CC Switch 设置页 → 路由配置 → 本地路由，找到 Claude 相关路由并启用。

这一步很多人漏掉：前面配置全对，但路由没开，请求根本不会走 Agnes 这条线，自然一直没反应。

步骤 3：验证连通性

打开 Claude Code，此时界面显示的模型名可能还是haiku，但实际流量已经走 Agnes。

三、常见报错与排坑指南

配置过程中最容易遇到的问题，按优先级排查即可：

1. 请求完全没反应，CC Switch 无日志

• 检查本地路由是否启用
• 确认 Claude Code 代理是否指向 CC Switch 端口
• 重启 CC Switch 和 Claude Code 客户端

2. 返回参数错误 / 模型不识别

• 核对模型名是否为小写agnes-2.0-flash
• API 格式是否选了openai chat completions

3. 鉴权失败 / 401 错误

• 检查 API Key 是否复制完整，有没有多余空格
• 确认 Key 是在 Agnes 平台创建，不是其他中转平台
• 检查请求地址是否正确，后缀/v1不能少

4. 响应慢、排队、超时

• 免费服务高峰期有排队属于正常现象，避开高峰时段会快很多
• 长上下文、大任务本身耗时更长，属于正常情况
• 如果是自动化调用，建议加上指数退避重试机制

---

四、生态工具：不用从零写代码

目前 GitHub 上已经有不少现成的封装和插件，可以直接拿来用：

1. Agnes AI Generation Skill

仓库地址：Yacey/agnes-ai-generation-skill

把 Agnes 全模态 API 封装成 Agent Skill，支持 Claude Code、Cursor、Windsurf、Codex 等主流工具。内置中文提示词自动英译，减少视频生成不稳定的问题，覆盖文生图、图生图、文生视频、多图生成视频等能力。

2. Agnes Free Model Skills

仓库地址：kangarooking/agnes-free-model-skills

拆分成三个独立本地 Skill，职责更清晰：

• agnes-free-text：文本对话、流式输出、工具调用
• agnes-free-image：文生图、图生图、自动下载结果
• agnes-free-video：异步视频任务创建、状态轮询、结果下载

---

五、谁适合用？怎么用效率最高？

推荐人群

1. 重度编码开发者：经常用 Claude Code 做项目分析、代码审查、测试生成，Token 消耗大，免费 API 能大幅降低试错成本
2. 内容创作者：需要大量产出封面、海报、商品图、视频草稿，4K 免费可以放心多跑几个方向
3. AI 应用原型开发者：文本 + 图片 + 视频一套 API 搞定，快速打通产品流程，不用对接多家供应商

高效使用建议

• 文本场景：不要盲目塞满 1M 上下文，先定位核心文件再全量装入；复杂任务拆成多轮，比单次巨量请求效果更稳
• 图片场景：固定常用比例和风格模板，明确列出 "不要项"（文字、水印、Logo 等），减少返工
• 工作流接入：务必做好重试、超时、降级处理；免费服务有波动，核心场景留好备用方案
• 结果审核：代码要跑测试，图片视频要人工筛选，尤其是人物、产品、品牌相关素材

---

写在最后

对开发者来说，最有价值的还是 1M 上下文 + Claude Code 的组合 —— 以前舍不得用大模型跑的全项目分析、跨模块重构、完整测试用例生成，现在可以放心跑。对创作者来说，4K 图片和视频能力也足够覆盖大部分素材初稿需求。

当然，免费服务必然有高峰期波动和稳定性问题。