Imported from lj1270998580-crypto/Agnes-help-skill (SKILL.md). Install upstream with npx skills add lj1270998580-crypto/Agnes-help-skill. Copyright stays with the author.

name: agnes-ai-support version: "1.2.22" description: | Agnes AI API 接入支持与问题排查 Skill。帮助新用户完成 Agnes AI API 的接入配置， 诊断和解决接入过程中遇到的认证、参数、响应、图像生成、视频生成等各类问题。 涵盖 Thinking 模式开启、视频长度调节、流式输出、工具调用等高级功能指导。 兼容 OpenClaw、Claude Code、Hermes、Codex 等工具链。

触发词：Agnes AI、agnes、接入、API Key、401、400、排查、错误、视频生成、图像生成、 thinking、stream、tool calling、模型选择、Base URL、响应格式、timeout、超时、轮询、 FAQ、问题排查、调试、免费调用、RPM、video_id、task_id、Prompt 模板、提示词、 生图、生视频、图生图、文生图、图生视频、文生视频、灰度自检、1M 上下文、4K 图片、4K 图、4K、灰度、自检、反馈、Bug、issue、问题反馈、功能建议。

Agnes AI API 接入支持与问题排查

Skill 版本： v1.2.22 适用工具： OpenClaw / Claude Code / Claude Desktop / Hermes / Codex / WorkBuddy / Cherry Studio / Opencode / Kimi Work 更新日期： 2026-08-27 官方 Bug 反馈： https://github.com/AgnesAI-Labs/Agnes-AI/issues 官方进度看板： https://github.com/users/AgnesAI-Labs/projects/1 官方 Bug 反馈： https://github.com/AgnesAI-Labs/Agnes-AI/issues 官方进度看板： https://github.com/users/AgnesAI-Labs/projects/1 GitHub 仓库： https://github.com/lj1270998580-crypto/Agnes-help-skill 官方平台： https://platform.agnes-ai.com 官方文档： https://agnes-ai.com/doc/overview 操作手册： https://agnes-ai.com/doc/%E5%B8%B8%E7%94%A8%E6%8E%A5%E5%85%A5%E6%96%87%E6%A1%A3 社区教程： https://github.com/Yacey/agnes-ai-generation-skill 社区 Skill： https://github.com/kangarooking/agnes-free-model-skills ComfyUI 节点： https://github.com/16nic/comfyui-agnes-ai 常见问题 QA（飞书）： https://icn1d2hdv39m.feishu.cn/wiki/R7TEwjadJibD62kWeS9cubtpnPi

版本检查与更新提醒

每次加载本 Skill 时，请执行以下检查：

步骤 1：检测版本

1. 读取 GitHub 仓库最新 commit 信息：

   https://api.github.com/repos/lj1270998580-crypto/Agnes-help-skill/commits?per_page=1
   

2. 比较远程最新 commit 的 sha 与本地记录的版本（v1.2.11 对应 sha: ）。

3. 如果 sha 不匹配 → 说明有新版本，继续步骤 2。

步骤 2：读取更新内容（重要）

如果检测到更新，必须读取 README.md 的更新记录来获取本次更新内容：

https://raw.githubusercontent.com/lj1270998580-crypto/Agnes-help-skill/main/README.md

从 README 中提取「更新记录」表格的第一行（最新的那条），获取：

• 更新日期
• 更新内容

步骤 3：向用户报告（在回复开头）

📢 本 Skill 有新版本可用！

当前版本： v1.2.11（您的版本） 最新版本： [远程版本号]

本次更新内容： [从 README 更新记录读取的具体内容，例如：]

• Agnes-2.0-Flash 上下文升级至 512K
• 4K 图片已全面支持
• 新增灰度自检功能
• 新增官方 GitHub 反馈渠道

是否需要更新？ 如果您想获取最新功能，请回复「更新 Skill」，我会帮您安装最新版。

一键更新指令：

请读取并安装 Agnes AI 支持 Skill 最新版：https://raw.githubusercontent.com/lj1270998580-crypto/Agnes-help-skill/main/SKILL.md

如果您暂时不想更新，也可以继续使用当前版本。

步骤 4：用户选择更新

如果用户回复「更新 Skill」或「安装最新版」：

1. 读取最新版 SKILL.md 的 URL
2. 指导用户完成安装（或直接帮用户安装，取决于工具能力）
3. 安装完成后确认：「已更新至最新版本 vX.X.X」

如果用户不更新：

• 继续正常帮助用户，不强制更新
• 但建议用户在方便时更新以获得最新功能和修复

步骤 5：HTML 助手和 API 文档检查

如果用户正在使用 HTML 助手或 API 文档，同样提醒：

检测到 HTML 助手 / API 文档也有更新，建议从仓库下载最新版。

Agnes AI 官方问题反馈渠道

注意：以下渠道是 Agnes AI 官方的反馈渠道，不是本 Skill 的反馈渠道。

当用户遇到 Agnes AI API 官方服务的问题（如 API 返回错误、功能异常、模型行为不符合预期等）时，主动提供以下官方渠道。

情况 1：用户遇到 Bug 或异常

如果用户报告了 API 异常、返回错误、功能不正常等：

🐛 遇到 Bug 了？ 您可以通过以下官方渠道反馈：

1. GitHub Issues（推荐）

• 地址：https://github.com/AgnesAI-Labs/Agnes-AI/issues
• 用途：提交 Bug 反馈、API 使用咨询、需求与建议
• 团队会按优先级标记处理

2. 反馈处理进度看板

• 地址：https://github.com/users/AgnesAI-Labs/projects/1
• 用途：查看问题修复进度、新模型上线、文档更新等
• 建议收藏，可随时查看

3. 支持邮箱

• 邮箱：support@agnes-ai.com
• 适用于：需要详细描述的问题

反馈前准备：

• 错误码（如 400、500）
• 请求参数（脱敏 API Key）
• 复现步骤
• 期望行为 vs 实际行为

情况 2：用户有需求或建议

如果用户提出了功能需求、改进建议：

💡 有建议？ 欢迎通过以下渠道提交：

GitHub Issues： https://github.com/AgnesAI-Labs/Agnes-AI/issues

• 标题格式：[Feature Request] 您的建议标题
• 内容描述：使用场景 + 期望功能 + 优先级
• 团队会评估并纳入开发排期

也可以在反馈进度看板查看需求处理状态： https://github.com/users/AgnesAI-Labs/projects/1

情况 3：用户想查询问题处理进度

📋 查询反馈进度：

https://github.com/users/AgnesAI-Labs/projects/1

看板包含：

• 所有已提交的 Issues 状态
• 问题修复进度
• 新模型上线计划
• 文档更新进度
• 开发排期

建议收藏此链接，可随时查看官方最新动态。

如何使用本 Skill

本 Skill 是你的 Agnes AI 接入助手。安装后，Agent 会自动理解 Agnes API 的完整信息，帮你完成接入、生成内容、排查问题。

Agnes Help Skill 教程信息图

一、用 Skill 让 Agent 帮你生图 / 生视频

步骤：

1. 安装 Skill → 把本 Skill 加载到 Agent（OpenClaw / Claude Code / Kimi Work 等）
2. 配置 API Key → 告诉 Agent 你的 Agnes API Key
3. 告诉 Agent 需求 → "帮我生成一张赛博朋克城市夜景图" / "帮我生成一段 5 秒产品展示视频"
4. Agent 自动执行 → Agent 会根据 Skill 中的参数说明自动选择模型、填写参数、调用 API

示例对话：

用户：帮我安装这个 skill，并帮我配置 Agnes API Key，然后帮我生成一张图片
Agent：（读取 Skill → 指导配置 → 调用 API → 返回图片）

用户：我已经装好 skill，帮我生成一个 5 秒视频
Agent：（读取 Skill → 选择视频模型 → 提交任务 → 轮询 → 返回视频）

💡 你无需选择模型，Agent 会根据你的需求自动判断并选择合适的模型执行。

⚠️ 视频查询一定要用 video_id，不要用 task_id

二、用 Skill 让 Agent 接入你开发的工具

场景： 你有自己的工具、API 或服务，需要让 Agent 帮你接入和使用。

步骤：

1. 安装 Agnes Skill → 让 Agent 以本 Skill 为参考来理解 Agnes 接口
2. 描述你的工具 → 告诉 Agent 你的工具是什么、需要什么能力
3. Agent 生成接入方案 → Agent 会参考 Skill 中的接口信息，帮你生成接入代码、示例、调用方法
4. 联调修复 → 根据 Agent 提供的步骤调试，直至成功接入

示例对话：

用户：我想在我的 Next.js 项目中接入 Agnes AI 的图像生成功能
Agent：（参考 Skill → 生成 Next.js API Route 代码 → 提供前端调用示例）

用户：我的工具需要同时支持文本对话和图像生成
Agent：（参考 Skill → 生成多模态接入方案 → 提供统一封装代码）

⭐ Skill 的价值：让 Agent 更懂你的工具，更快帮你完成接入。

三、用 Skill 来排查问题，快速拿到方案

步骤：

1. 描述问题 → 把错误码、日志、截图发给 Agent，清晰描述你遇到了什么问题
2. Agent 分析 → Agent 会参考 Skill 中的错误码表、常见问题、排查指南进行诊断
3. 给出方案 → Agent 输出：原因分析 + 修复步骤 + 示例代码

高效提问模板：

现在【正在做】：我在做什么
目标【期望结果/需求】：我需要什么
问题：遇到了什么问题
已尝试：【做过什么】
请给出：【原因 + 修复步骤 + 示例】

常见错误码速查（Agent 会自动匹配）：

示例对话：

用户：我调用图像生成接口返回 400，提示参数错误
Agent：（参考 Skill 错误码表 → 分析可能原因 → 给出修复方案）

用户：视频任务提交了但一直查不到结果
Agent：（参考 Skill 视频排查指南 → 检查 video_id vs task_id → 给出正确查询方式）

🔔 Agnes AI 官方反馈渠道（如果以上排查均无效）：

当 Agnes AI 官方 API 服务出现问题（Bug、异常、功能不符合预期），请通过以下官方渠道反馈：

• GitHub Issues（推荐）： https://github.com/AgnesAI-Labs/Agnes-AI/issues
• 反馈进度看板： https://github.com/users/AgnesAI-Labs/projects/1
• 支持邮箱： support@agnes-ai.com

反馈前准备： 错误码 + 请求参数（脱敏 Key）+ 复现步骤 + 期望行为 vs 实际行为

补充建议

• 新手可先安装 Skill 再使用 → 快速上手，降低使用门槛
• API 文档可交给 Agent 参考 → 提升理解准确度与效率
• 有更新时查看 GitHub 仓库最新版 → 获取最新功能与修复

0. 重要公告（2026-06 更新）

Agnes 2.0 全模态模型 API 正式开放全球免费调用

不限期、全模态、API 调用完全免费

• 文本模型：免费/默认用户 RPM 20，企业 RPM 40，Token Plan RPM 1000
• 图片模型：
  • 1K 分辨率：免费/默认 RPM 20，企业 RPM 40，Token Plan RPM 100
  • 2K 分辨率：免费/默认 RPM 10，企业 RPM 20，Token Plan RPM 80
  • 3K/4K 分辨率：所有用户类型 RPM 均为 1
• 视频模型：免费/默认用户 RPM 1，企业 RPM 2，Token Plan RPM 5
• 注册官网 → 生成 KEY → 直接调用

• 文本、图像、视频全能适配，高效便捷
• 模型会持续升级并保持免费
• 欢迎大家多用、多吐槽

平台直达： https://platform.agnes-ai.com

🎬 Agnes Video 2.5 Flash 上线通知（2026-08-27 更新）

• Agnes Video 2.5 Flash 已正式上线 API 平台，限时免费开放使用（$0/秒，原价 $0.025/秒）
• 模型 ID：agnes-video-2.5-flash，端点 POST /v1/videos（与 v2.0 相同）
• 支持 文生视频（text）/ 首尾帧控制（keyframe）/ 图片参考（reference） 三种模式
• Flash 专属限制：size 固定为字符串 "720P"；reference 模式 images 最多 5 张；不支持 videos 输入；seconds 为字符串 "4"–"12"；n 固定为 1
• 查询仍推荐 GET /agnesapi?video_id=<ID>&model_name=agnes-video-2.5-flash；纯 video_id 查询仅适用于 text 模式
• 官方文档（国际站）：https://www.agnes-ai.com/zh-Hans/docs/agnes-video-25-flash
• 官方文档（国内站）：https://www.agnes-ai.cn/zh-Hans/docs/agnes-video-25-flash
• 使用中遇到问题或有建议，欢迎在社群内反馈

💰 免费模型一览（2026-08-27 核对官方定价页）

目前所有 Flash 系列模型均免费开放，仅 Pro 推理系列（agnes-2.5-pro / -beta / -alpha）与高清视频 agnes-video-2.5 为付费模型：

官方定价来源：https://www.agnes-ai.com/zh-Hans/docs/pricing 注意：免费/付费状态可能随官方活动调整，以官方定价页与账户账单为准。

视频接口重要更新

• 必须使用 video_id 查询视频结果，不要用 task_id 查询
• 使用 task_id 查询会导致视频排队过长（超过 5 分钟大概率是接口搞错了）
• 视频文档（2.5 Flash）：https://www.agnes-ai.com/zh-Hans/docs/agnes-video-25-flash
• 视频文档（v2.0）：https://agnes-ai.com/doc/agnes-video-v20
• 社区 Skill 中的视频接口可能未更新，请以官方文档为准

⚠️ Agnes-2.0-Flash 上下文窗口回退说明（2026-06-08 更新）

官方更新： Agnes-2.0-Flash 上下文窗口已升级至 512K（此前 256K），Max Output 保持 64K。

当前规格：

• Context：512K
• Max Output：64K

1.5 Flash 保持 512K/64K 不变。

🌐 国内网络域名切换通知（2026-07-28 更新）

针对部分国内网络无法正常访问 Agnes API 的情况，请将 API Endpoint 切换为：

• 原地址（国际）： https://apihub.agnes-ai.com/v1
• 新地址（国内）： https://apihub.agnes-ai.cn/v1（将域名中的 .com 替换为 .cn）

调整说明：

• 请将应用配置、环境变量或项目代码中的 apihub.agnes-ai.com 统一替换为 apihub.agnes-ai.cn
• 本次调整仅涉及接口域名，API Key、模型名称、请求参数及调用方式均无需修改
• 修改完成后，请重启应用或服务，再重新发起请求

1. 快速接入流程（4 步）

Step 1 — 创建 API Key

1. 访问 https://platform.agnes-ai.com 注册/登录
2. Settings → API Keys → Create new secret key
3. 只显示一次，立即复制保存
4. 安全提醒：不要暴露在代码仓库、前端代码、截图、公开文档中

Step 2 — 选择模型

Step 3 — 配置请求

Base URL（国际）: https://apihub.agnes-ai.com/v1
Base URL（国内）: https://apihub.agnes-ai.cn/v1
Headers:
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

Step 4 — 测试请求

curl https://apihub.agnes-ai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agnes-2.0-flash","messages":[{"role":"user","content":"Hello!"}]}'

2. 问题诊断决策树

2.1 认证类问题

401 Unauthorized

1. 检查 Header 格式：Authorization: Bearer YOUR_KEY（Bearer 后有空格）
2. 确认 Key 未过期/被删除（控制台 Settings → API Keys 查看）
3. 确认账户有余额（注册送 $0.1；目前所有 Flash 模型（文本/图像/视频）均免费，但有 RPM 限制：文本 20/min，图片按分辨率 1K:20, 2K:10, 3K/4K:1，视频 1/min；仅 Pro 推理系列与 agnes-video-2.5 为付费模型）
4. 检查 Key 是否有多余空格或换行符
5. 用 curl 直接测试，排除 SDK/框架问题

API Key 泄露

• 立即在控制台删除旧 Key，创建新 Key
• 检查代码仓库历史，用 git filter-repo / BFG 清理敏感信息
• 检查环境变量配置是否被意外提交

2.2 请求类问题（400 Bad Request）

通用排查清单：

1. JSON 格式是否合法（用 jsonlint 校验）
2. 必填参数是否缺失
3. 参数类型是否正确

Chat 模型 400：

• 必填：model + messages
• messages 必须是数组，元素含 role 和 content
• temperature 范围 0-2
• 图片 URL 输入时，content 必须是数组格式

图像模型 400：

• 文生图必填：model + prompt + size
• 图生图必填：model + prompt + size + extra_body.image（image 必须放在 extra_body 中，不能放顶层！）
• response_format 必须放在 extra_body 中，放根级会 400
• 图生图不需要传 tags: ["img2img"]
• size 格式：1K/2K/3K/4K 四种分辨率，必须是 16 的倍数（详见第 4 章参数速查）
• 图片模型生成尺寸必须为 16 的倍数（如 1024x1024、1024x768）

视频模型 400：

• 必填：model + prompt
• num_frames 必须 ≤ 441 且满足 8n + 1
• 有效值：81, 121, 161, 241, 441
• frame_rate 范围 1-60
• 视频模型生成尺寸必须为 64 的倍数（width/height 都需满足）
• 视频长度建议不要超过 15s，否则有失败概率
• 官方建议：24FPS 不超过 15s，30FPS 不超过 10s，60FPS 不超过 5s
• 图生视频：image 需为公网可访问 URL

2.3 响应类问题

无响应 / 超时

• Chat：超时建议 30s
• 图像：超时建议 60-360s（数秒到几十秒）
• 视频：异步任务，创建后需轮询查询，间隔 5s
• 检查网络能否访问 apihub.agnes-ai.com（国际）或 apihub.agnes-ai.cn（国内）
• 如在国内网络无法访问 .com 域名，请切换至 .cn 域名
• 检查防火墙/代理是否拦截

503 Service Unavailable

• 服务暂时繁忙，指数退避重试：1s → 2s → 4s → 8s
• 关注 Agnes AI 状态公告
• CC 平台特定：检查模型名称是否正确、是否获取了模型列表、是否选择了兜底模型、是否开启了路由
• Codex 特定：如果显示用模型「gpt-5.4-mini」发送请求，将更多选项里的测试模型也填上 agnes-2.0-flash

502 Bad Gateway

• 本地网络环境问题，检查本地网络环境，修改 DNS，必要时让 AI 帮忙检查修改

520 Web Server Error

• 通常表示网络链路异常或上游服务临时波动，稍后重试

429 Rate Limited

• 降低请求频率
• 文本模型：免费/默认 RPM 20，企业 RPM 40，Token Plan RPM 1000
• 图片模型：按分辨率分档 — 1K RPM 20，2K RPM 10，3K/4K RPM 1（均免费/默认）
• 视频模型：免费/默认 RPM 1（每分钟内只能生成 1 个视频），需排队等待
• 实现客户端队列和退避

Token Plan 订阅配额（与 RPM 同时生效，超出同样触发 429）：

• 文本（agnes-2.5-flash）：Starter 每 5 小时 1,500 次 / 每周 15,000 次；Plus 每 5 小时 7,500 次 / 每周 75,000 次；Pro 每 5 小时 30,000 次 / 每周 300,000 次（按请求次数计数）
• 图片（agnes-image-2.1-flash）：三档均为每天 4,000 张（按生成张数计数）
• 视频（agnes-video-v2.0 / agnes-video-2.5-flash）：三档均为每天 500 秒（按生成时长计数）
• 同一类型的多个 Key 共享同一个限制池，不会叠加额度
• 官方参考：https://www.agnes-ai.com/zh-Hans/docs/tokenplan

2.4 视频排队过长（> 5 分钟）

这是最重要的排查点：

• 大概率是使用了 task_id 查询接口
• 必须使用 video_id 查询：GET /agnesapi?video_id=<ID>
• task_id 查询接口会导致排队异常延长
• 正确做法：创建任务后获取 video_id，用 video_id 轮询查询
• 轮询间隔建议 5 秒

2.5 输出质量问题

• 优化 Prompt 结构：[Role] + [Task] + [Context] + [Requirements] + [Output Format]
• 编程/推理任务开启 Thinking 模式
• 调整 temperature：确定性任务 0.1-0.3，创意任务 0.7-1.0
• 检查 max_tokens 是否足够，避免截断
• 图像任务：提供详细的场景、风格、光照、构图描述

3. 高级功能指南

3.1 Thinking 模式（agnes-2.0-flash）

OpenAI 兼容格式：

{
  "model": "agnes-2.0-flash",
  "messages": [...],
  "chat_template_kwargs": {
    "enable_thinking": true
  }
}

Anthropic 兼容格式：

{
  "model": "agnes-2.0-flash",
  "messages": [...],
  "thinking": {
    "type": "enabled",
    "budget_tokens": 2048
  }
}

budget_tokens 建议：

• 简单编码：2048
• 复杂调试/重构：4096+
• 多步骤 Agent：4096+

3.2 流式输出（SSE）

请求体加 "stream": true

• 响应逐块返回，每块以 data: 开头
• 最后以 data: [DONE] 结束
• 需正确解析 choices[0].delta.content 并拼接

3.3 工具调用

1. 请求中提供 tools 数组（含 function 定义）
2. 模型返回 finish_reason: "tool_calls"
3. 解析 choices[0].message.tool_calls
4. 执行函数后，以 role: tool 回传结果
5. 模型根据工具结果生成最终回复

3.4 视频长度调节

公式： seconds = num_frames / frame_rate

约束：

• num_frames ≤ 441
• num_frames = 8n + 1（81, 121, 161, 241, 441）
• frame_rate：1-60，推荐 24
• 视频长度建议不要超过 15s，否则有失败概率
• 官方建议：24FPS 不超过 15s，30FPS 不超过 10s，60FPS 不超过 5s

常用配置：

更长视频： 增加 num_frames 或降低 frame_rate，但建议不超过 15s

3.5 图像输出格式

URL 输出：

{
  "extra_body": {
    "response_format": "url"
  }
}

Base64 输出（文生图）：

{
  "return_base64": true
}

Base64 输出（图生图）：

{
  "extra_body": {
    "response_format": "b64_json"
  }
}

4. 各模型参数速查

agnes-2.5-flash

• 端点：POST /v1/chat/completions（另支持 Responses POST /v1/responses、Anthropic 兼容 Messages POST /v1/messages）
• Context：512K
• Max Output：65.5K
• 参数：model, messages, temperature, top_p, max_tokens, frequency_penalty, presence_penalty, repetition_penalty, stop, seed, stream, tools, tool_choice, chat_template_kwargs, thinking
• 支持图片 URL 输入（messages[].content 数组格式）
• 支持工具调用、Thinking 模式、流式输出
• 升级自 2.0 Flash：API 完全兼容，只需改模型名即可迁移
• 价格：Input $0.03/1M, Output $0.15/1M（现价 $0，RPM ≤ 20）

agnes-2.5-pro（正式版 · 付费）

• 端点：POST /v1/chat/completions（另支持 Responses POST /v1/responses、Messages POST /v1/messages）
• Context：1M
• Max Output：65536
• 输入模态：文本、图像 URL；输出：文本（Reasoning）
• Agnes 2.5 Pro Alpha 打榜模型的商业化稳定版（2026-08-01 发布），付费模型，需账户开通访问权限
• 权重：Proprietary（非开源）；Alpha 权重已 Apache 2.0 开源
• 支持工具调用、Thinking 模式、流式输出
• 价格：Input $0.45/1M, Output $0.90/1M, Cache hit $0.045/1M

agnes-2.5-pro-beta（Beta · 付费）

• 端点：POST /v1/chat/completions（另支持 Responses POST /v1/responses、Messages POST /v1/messages）
• Context：1M
• Max Output：65536
• 输入模态：文本、图像 URL；输出：文本（Reasoning）
• 已正式上线，付费模型，需账户开通访问权限
• 权重：Proprietary（非开源）
• 支持工具调用、Thinking 模式、流式输出
• 价格：Input $0.10/1M, Output $0.30/1M, Cache hit $0.01/1M

agnes-2.5-pro-alpha

• 端点：POST /v1/chat/completions（另支持 Responses POST /v1/responses、Messages POST /v1/messages）
• Context：1M（此前误标 262K）
• Max Output：65536
• 输入模态：文本、图像 URL；输出：文本（Reasoning）
• ✅ 已转为付费模型，付费通道已开通（2026-07-24 发布，权重已 Apache 2.0 开源）
• 支持图片 URL 输入、工具调用、Thinking 模式、流式输出
• 价格：Input $0.45/1M, Output $0.90/1M, Cache hit $0.045/1M

agnes-2.0-flash

• 端点：POST /v1/chat/completions
• Context：512K
• Max Output：64K
• 额外参数：stream, tools, tool_choice, chat_template_kwargs, thinking
• 支持图片 URL 输入（messages[].content 数组格式）
• 支持工具调用、Thinking 模式、流式输出
• 价格：Input $0.03/1M, Output $0.15/1M（现价 $0，RPM ≤ 20）
• 已升级至 2.5-flash，建议迁移

agnes-image-2.0/2.1-flash

• 端点：POST /v1/images/generations
• 必填：model, prompt, size
• 图生图必填：extra_body.image（URL 数组或 Data URI Base64，必须放在 extra_body 中！）
• size：官方推荐档位 1K / 2K / 3K / 4K（配合 ratio 使用），也兼容 1024x768 这类历史精确尺寸写法，但不支持的尺寸可能被标准化
• ratio 支持：1:1、3:4、4:3、16:9、9:16、2:3、3:2、21:9（默认 1:1）
  • 1K：免费/默认 RPM 20，企业 RPM 40，Token Plan RPM 100
  • 2K：免费/默认 RPM 10，企业 RPM 20，Token Plan RPM 80
  • 3K/4K：所有用户类型 RPM 均为 1
• 尺寸要求： 历史精确尺寸需为 16 的倍数，否则可能返回 500 错误；推荐使用档位 + ratio
• 输出：URL 或 Base64（return_base64: true 或 extra_body.response_format）
• 价格（按张）：1K $0.010/张、2K $0.018/张、3K $0.021/张、4K $0.024/张（现价均 $0）；前 3 张输入参考图免费，第 4 张起 $0.003/张（现价 $0）

agnes-video-v2.0

• 创建：POST /v1/videos
• 查询（强烈推荐）：GET /agnesapi?video_id=<ID>
• 查询（兼容，不推荐）：GET /v1/videos/{task_id}
• 参数：model, prompt, image, mode, height(768), width(1152), num_frames, frame_rate(24), num_inference_steps, seed, negative_prompt, extra_body.image, extra_body.mode
• 支持分辨率档位：480p、720p、1080p
• 支持宽高比：16:9、9:16、1:1、4:3、3:4
• 支持关键帧动画模式：extra_body.mode: "keyframes"
• 价格：$0.005/second（现价 $0）
• 重要：必须用 video_id 查询，task_id 会导致排队过长

agnes-video-2.5（付费 · 高清）

• 模型 ID：agnes-video-2.5
• 创建：POST /v1/videos
• 查询（强烈推荐）：GET /agnesapi?video_id=<ID>&model_name=agnes-video-2.5
• 查询（兼容，仅 text 模式）：GET /agnesapi?video_id=<ID>
• 模式：text（文生视频）、keyframe（首尾帧控制）、reference（图片/音频/视频参考）
• size："720P" / "960P" / "2K"；aspect_ratio 支持 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16
• seconds：字符串 "4"–"12"（默认 "5"）；n 固定 1
• reference 模式：images/audios/videos 至少一类非空，输入图片前 5 张免费（第 6 张起 $0.005/张）
• 价格：720P $0.025/秒、960P $0.040/秒、2K $0.055/秒（付费模型）
• 计费：总金额 = 输出秒数 × 输出分辨率单价 + 输入视频秒数 × 输出分辨率单价 + max(0, 图片数 - 5) × $0.005（输入视频时长也会计入总时长，按输出分辨率单价计费）
• 重要：必须用 video_id 查询，task_id 会导致排队过长

agnes-video-2.5-flash（新增 · 限时免费）

• 模型 ID：agnes-video-2.5-flash
• 创建：POST /v1/videos
• 查询（强烈推荐）：GET /agnesapi?video_id=<ID>&model_name=agnes-video-2.5-flash
• 查询（兼容，仅 text 模式）：GET /agnesapi?video_id=<ID>
• 模式：text（文生视频）、keyframe（首尾帧控制）、reference（图片/音频参考）
• size 固定字符串 "720P"；aspect_ratio 支持 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16
• seconds：字符串 "4"–"12"（默认 "5"）；n 固定 1
• reference 模式：images 最多 5 张，不支持 videos 输入
• 价格：原价 $0.025/second，现价 $0/second（限时免费）；限时免费期间输出视频秒数、输入视频秒数与参考图片均按 $0 计费（计费公式与 Video 2.5 相同）
• 重要：必须用 video_id 查询，task_id 会导致排队过长

5. 常见错误速查表

🔔 如果以上错误排查均无效？

请通过 Agnes AI 官方反馈渠道提交问题：

• GitHub Issues（推荐）： https://github.com/AgnesAI-Labs/Agnes-AI/issues
• 反馈进度看板： https://github.com/users/AgnesAI-Labs/projects/1
• 支持邮箱： support@agnes-ai.com

反馈前准备： 错误码 + 请求参数（脱敏 Key）+ 复现步骤 + 期望行为 vs 实际行为

6. 接入检查清单

通用

• 已注册账户并创建 API Key（https://platform.agnes-ai.com）
• Base URL 正确（国际：https://apihub.agnes-ai.com/v1，国内：https://apihub.agnes-ai.cn/v1）
• 请求头包含 Authorization 和 Content-Type
• API Key 未暴露在公开代码中
• 已实现错误处理和重试逻辑
• 了解 RPM 限制（文本 20/min，图片按分辨率 1K:20, 2K:10, 3K/4K:1，视频 1/min）

Chat

• 模型名称拼写正确
• messages 数组格式正确
• 图片 URL 使用数组 content 格式
• 流式输出能正确解析 SSE
• 工具调用能处理 finish_reason: tool_calls

图像

• 模型名称正确（推荐 2.1）
• 文生图传 model + prompt + size
• 图生图传了 extra_body.image 数组（不能放顶层！）
• response_format 在 extra_body 中
• 未传 tags: ["img2img"]
• 输入图片 URL 公网可访问
• 客户端超时 ≥ 60s

视频

• 模型名称：agnes-video-v2.0
• num_frames ≤ 441 且满足 8n+1
• frame_rate 在 1-60
• 图生视频图片 URL 公网可访问
• 已实现轮询查询（间隔 5s）
• 使用 video_id 查询结果（不要用 task_id）
• 视频排队超过 5 分钟时检查查询接口是否正确

7. 最佳实践

Prompt 编写

• 使用结构化格式：[Role] + [Task] + [Context] + [Requirements] + [Output Format]
• 编程任务：提供语言、框架、错误信息、期望行为
• Agent 任务：清晰描述目标、可用工具、任务约束
• 图像任务：主体 + 场景 + 风格 + 光照 + 构图 + 质量要求
• 视频任务：主体 + 动作 + 场景 + 镜头运动 + 光照 + 风格

性能优化

• 高并发场景使用 agnes-2.5-flash
• 需要推理/编程使用 agnes-2.0-flash + Thinking
• 图像生成设置合理超时（60-360s）
• 视频生成使用异步 + 轮询模式
• 实现指数退避重试（1s → 2s → 4s → 8s）
• 视频查询必须用 video_id，避免 task_id 导致的排队

Agnes AI，让世界级 AI 属于每一个人。

安全

• API Key 存储在环境变量或密钥管理服务中
• 前端代码中绝不硬编码 Key
• 定期轮换 API Key
• 监控异常用量

Agnes AI，让世界级 AI 属于每一个人。

灰度自检（检查你的账户是否支持 1M 上下文和 4K 图片）

Agnes AI 正在灰度测试以下能力：

• 1M Token 超长上下文：约 50% 概率已开放
• 4K 图片生成：已全面支持（所有用户可用）

触发条件：当用户问"灰度自检"、"是否有1M上下文"、"能生成4K图吗"、"4K图片"等时，执行以下测试。

⚠️ 重要：这些测试是"尽力而为"的方法，结果仅供参考。灰度分配是动态的，可能随时变化。

测试 1：1M 上下文自检

原理：需要发送超过 512K tokens 的文本。如果 API 成功返回 → 支持 1M；如果返回 413/400（上下文过长）→ 当前不支持。

注意：英文文本约 1 token ≈ 4 字符，因此要超过 512K tokens，需要发送 约 2M+ 字符 的 payload。这是一个较大的请求体，可能受客户端/服务端请求大小限制。

curl 方法（示例文本较短，实际测试需要更大payload，推荐用 Python 方法）：

# 此示例payload较小，仅展示调用方式
# 实际测试需要约 1M+ 字符的文本才能超过 256K tokens

curl https://apihub.agnes-ai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-2.0-flash",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "（此处需要放入约 1M+ 字符的文本）"}
    ],
    "max_tokens": 10
  }'

Python 方法（推荐）：

import requests

key = "YOUR_API_KEY"

# 生成约 2.5M 字符（约 625K tokens，超过 512K 边界）
# 注意：实际 token 数取决于 tokenizer，但 2.5M 字符应足够超过 512K tokens
sentence = "Hello world this is a test for long context window capability. "
test_text = sentence * 40000  # 约 2.5M 字符

print(f"测试文本长度: {len(test_text)} 字符")

try:
    resp = requests.post(
        "https://apihub.agnes-ai.com/v1/chat/completions",
        headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
        json={
            "model": "agnes-2.0-flash",
            "messages": [
                {"role": "system", "content": "You are a helpful assistant."},
                {"role": "user", "content": test_text}
            ],
            "max_tokens": 10
        },
        timeout=60
    )

    if resp.status_code == 200:
        print("✅ 支持 1M 上下文（当前在灰度名单内）")
    elif resp.status_code == 413 or resp.status_code == 400:
        error_msg = resp.json().get("error", {}).get("message", resp.text[:200])
        if "context" in error_msg.lower() or "length" in error_msg.lower() or "too long" in error_msg.lower():
            print(f"❌ 当前不支持 1M 上下文（灰度未命中）：{error_msg}")
        else:
            print(f"⚠️ 请求失败（非上下文问题）：{resp.status_code} {error_msg}")
    else:
        print(f"⚠️ 请求失败：{resp.status_code} {resp.text[:200]}")
except Exception as e:
    print(f"⚠️ 请求异常（可能是payload过大导致客户端限制）：{e}")

测试 2：4K 图片自检

4K 图片已全面支持，所有用户均可使用 4096x4096 等 4K 尺寸。

# 尝试生成 4K 尺寸图片
curl https://apihub.agnes-ai.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "A beautiful landscape with mountains and lake, 4K ultra HD",
    "size": "4096x4096",
    "extra_body": {"response_format": "url"}
  }'

Python 方法：

import requests

key = "YOUR_API_KEY"

resp = requests.post(
    "https://apihub.agnes-ai.com/v1/images/generations",
    headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
    json={
        "model": "agnes-image-2.1-flash",
        "prompt": "A beautiful landscape with mountains and lake, 4K ultra HD",
        "size": "4096x4096",
        "extra_body": {"response_format": "url"}
    }
)

if resp.status_code == 200:
    data = resp.json()
    if "data" in data and len(data["data"]) > 0 and data["data"][0].get("url"):
        print("✅ 支持 4K 图片生成（当前在灰度名单内）")
    else:
        print("⚠️ 请求成功但无图片返回，请检查参数")
elif resp.status_code == 400:
    error_msg = resp.json().get("error", {}).get("message", resp.text[:200])
    if "size" in error_msg.lower() or "dimension" in error_msg.lower() or "4096" in error_msg.lower():
        print(f"❌ 当前不支持 4K 图片（灰度未命中）：{error_msg}")
    else:
        print(f"⚠️ 请求失败（非尺寸问题）：400 {error_msg}")
else:
    print(f"⚠️ 请求失败：{resp.status_code} {resp.text[:200]}")

测试结果解读：

注意： 灰度是动态分配的，不支持时无需担心，未来会逐步全量开放。以上测试仅供参考，实际以官方公告为准。

Agnes AI，让世界级 AI 属于每一个人。

8. Prompt 模板库

复制以下模板，替换方括号中的内容即可直接使用。

8.1 文生图 Prompt 模板

通用结构公式：

[主体] + [场景/背景] + [风格] + [光照] + [构图] + [质量要求]

模板 1 — 电商产品图

A clean product photo of a [产品] on a [背景颜色] studio background, soft shadows, high detail, professional commercial photography, 8K quality

示例：A clean product photo of a wireless earbuds case on a pure white studio background, soft shadows, high detail, professional commercial photography, 8K quality

模板 2 — 社交媒体海报

A vibrant social media poster featuring [主题], bold typography space at [位置], [风格] color palette, eye-catching composition, modern design, 4K

示例：A vibrant social media poster featuring summer sale, bold typography space at top, tropical color palette, eye-catching composition, modern design, 4K

模板 3 — 人物肖像

Portrait of a [年龄/性别] [职业/角色], [表情], wearing [服装], [场景背景], [风格] lighting, cinematic composition, highly detailed, professional photography

示例：Portrait of a young female scientist, confident smile, wearing a white lab coat, modern laboratory background, soft natural lighting, cinematic composition, highly detailed, professional photography

模板 4 — 风景/场景

A breathtaking [场景类型] at [时间], [天气/氛围], [风格] style, dramatic lighting, ultra-wide angle, 8K resolution, photorealistic

示例：A breathtaking mountain lake at golden hour, misty atmosphere, fantasy art style, dramatic lighting, ultra-wide angle, 8K resolution, photorealistic

模板 5 — 图标/插画

A minimalist [风格] icon of [对象], flat design, [主色调] color scheme, clean lines, white background, vector style, UI/UX design

示例：A minimalist line art icon of a rocket launching, flat design, blue and orange color scheme, clean lines, white background, vector style, UI/UX design

8.2 图生图编辑指令模板

通用结构公式：

[编辑动作] + [保留元素] + [目标风格/场景] + [光照] + [构图]

模板 1 — 风格转换

Transform this image into [目标风格] style while preserving the main subject and composition

示例：Transform this image into a cinematic cyberpunk style while preserving the main subject and composition

模板 2 — 颜色替换

Change the [对象] color to [颜色] while keeping the original lighting and shadows

示例：Change the car color to matte black while keeping the original lighting and shadows

模板 3 — 背景替换

Replace the background with [新背景], keep the foreground subject unchanged, match the lighting

示例：Replace the background with a sunset beach scene, keep the foreground subject unchanged, match the lighting

模板 4 — 添加元素

Add [元素] to the scene, maintain the original style and perspective, natural integration

示例：Add floating lanterns to the scene, maintain the original style and perspective, natural integration

模板 5 — 季节/时间转换

Change the scene to [季节/时间], adjust lighting and atmosphere accordingly, preserve architecture

示例：Change the scene to winter night with snowfall, adjust lighting and atmosphere accordingly, preserve architecture

8.3 视频生成 Prompt 模板

文生视频通用结构：

[主体] + [动作] + [场景] + [镜头运动] + [光照] + [风格] + [时长暗示]

模板 1 — 产品展示视频

A [产品] rotating slowly on a [背景] platform, smooth 360-degree product showcase, soft studio lighting, clean and minimal, professional commercial video

示例：A luxury watch rotating slowly on a marble platform, smooth 360-degree product showcase, soft studio lighting, clean and minimal, professional commercial video

模板 2 — 人物动作视频

A [人物描述] [动作], natural movement, [场景], [镜头运动], cinematic lighting, realistic style

示例：A young woman walking through a cherry blossom garden, natural movement, petals falling around her, slow tracking shot, golden hour lighting, realistic style

模板 3 — 场景转换视频

A smooth cinematic transition from [场景A] to [场景B], maintaining visual consistency, dramatic lighting change, wide angle

示例：A smooth cinematic transition from a rainy city street to a sunny countryside road, maintaining visual consistency, dramatic lighting change, wide angle

图生视频通用结构：

Animate [元素] with [动作], keep [需保持的元素] consistent, [风格]

示例：Animate the character with subtle breathing motion, hair moving gently, while keeping the face and outfit consistent, realistic style

关键帧动画结构：

Generate a smooth cinematic transition between keyframes, maintaining [元素] consistent, [风格]

示例：Generate a smooth cinematic transition between keyframes, maintaining character appearance consistent, fantasy art style

8.4 文本模型 Prompt 模板

模板 1 — 代码生成

Role: Senior [语言] Developer
Task: Write a [功能描述]
Context: [框架/库], [已有代码/约束]
Requirements: [具体要求，如错误处理、类型安全、性能]
Output: Complete code with comments

模板 2 — 代码调试

Role: Debugging Expert
Task: Fix the bug in the following code
Context: [语言/框架], [错误信息], [期望行为]
Code: [粘贴代码]
Requirements: Explain the root cause, provide the fix, suggest prevention measures

模板 3 — 内容创作

Role: Professional [领域] Writer
Task: Write a [内容类型] about [主题]
Target Audience: [受众描述]
Tone: [语气，如专业/轻松/权威]
Requirements: [字数、结构、SEO关键词等]

模板 4 — 数据分析

Role: Data Analyst
Task: Analyze the following data and provide insights
Data: [粘贴数据或描述]
Requirements: [分析维度], identify trends, suggest actionable recommendations
Output: Structured report with key findings

模板 5 — Agent 任务

Role: [Agent 角色]
Goal: [明确目标]
Tools Available: [可用工具列表]
Constraints: [限制条件，如时间、预算、格式]
Step-by-step plan required: Yes

9. 社区资源

• 官方平台：https://platform.agnes-ai.com
• 官方文档：https://agnes-ai.com/doc/overview
• 操作手册：https://agnes-ai.com/doc/%E5%B8%B8%E7%94%A8%E6%8E%A5%E5%85%A5%E6%96%87%E6%A1%A3
• 视频文档：https://agnes-ai.com/doc/agnes-video-v20
• 常见问题 QA：https://icn1d2hdv39m.feishu.cn/wiki/R7TEwjadJibD62kWeS9cubtpnPi
• 社区教程：https://github.com/Yacey/agnes-ai-generation-skill
• 社区 Skill：https://github.com/kangarooking/agnes-free-model-skills
• ComfyUI 节点：https://github.com/16nic/comfyui-agnes-ai
• 支持邮箱：support@agnes-ai.com
• 公司：Sapiens AI / Agnes AI

10. 社区 Skill 接入指南

以下社区资源提供了更丰富的 Agnes AI 集成方式，可根据你的使用场景选择。

9.1 Yacey 的 Agnes AI 生成 Skill（推荐 Agent 用户）

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

特点：

• 封装 Agnes 官方文本、图片、视频 API 的标准 Skill
• 支持中文提示词自动翻译为英文（提升视频生成稳定性）
• 提供 Python 脚本直接调用
• 兼容 Codex、Claude Code、OpenClaw、Cursor、Windsurf

安装方式：

# 安装到当前 Agent
npx skills add Yacey/agnes-ai-generation-skill

# 安装到所有支持的 Agent
npx skills add Yacey/agnes-ai-generation-skill --all

配置 API Key：

# 临时配置（当前 PowerShell 会话）
$env:AGNES_API_KEY="YOUR_API_KEY"

# Windows 用户级持久配置
[Environment]::SetEnvironmentVariable("AGNES_API_KEY", "YOUR_API_KEY", "User")

脚本也识别以下变量名：

• AGNES_API_KEY
• AGNES_API_TOKEN
• APIHUB_AGNES_API_KEY

使用示例：

# 文本生成
python scripts/agnes_api.py text --prompt "Write a product tagline for an AI assistant."

# 文生图
python scripts/agnes_api.py image --prompt "A luminous floating city above a misty canyon at sunrise, cinematic realism" --size 1024x768

# 图生图
python scripts/agnes_api.py image --prompt "Turn the scene into a rainy cyberpunk night" --image https://example.com/input.png

# 文生视频（默认 num_frames=121, frame_rate=24）
python scripts/agnes_api.py video --prompt "A cinematic shot of a cat walking on the beach at sunset" --poll

# 图生视频
python scripts/agnes_api.py video --prompt "Animate subtle camera movement" --image https://example.com/image.png --poll

# 多图 / 关键帧视频
python scripts/agnes_api.py video --prompt "Create a smooth transition" --image https://example.com/a.png --image https://example.com/b.png --mode keyframes --poll

# 查询视频任务
python scripts/agnes_api.py video-get task_123456

# 运行测试
python scripts/agnes_api.py smoke-test

⚠️ 重要提醒：

• 该 Skill 的视频查询默认使用 task_id，但 Agnes 官方已更新为推荐使用 video_id 查询
• 如视频排队超过 5 分钟，请检查是否使用了正确的查询方式
• 中文提示词会自动翻译为英文后再调用 API

9.2 kangarooking 的免费模型 Skills（推荐 Codex 用户）

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

特点：

• 3 个独立 Skill：文本、图片、视频
• 可直接放入 Codex skills 目录使用
• 提供 Python 辅助脚本

包含 Skill：

安装方式：

# 克隆仓库
git clone https://github.com/kangarooking/agnes-free-model-skills.git

# 复制需要的 skill 到 Codex skills 目录
cp -R agnes-free-model-skills/agnes-free-text ~/.codex/skills/
cp -R agnes-free-model-skills/agnes-free-image ~/.codex/skills/
cp -R agnes-free-model-skills/agnes-free-video ~/.codex/skills/

配置环境变量：

export AGNES_API_KEY="your_api_key_here"

备用变量名：

• AGNES_TOKEN
• AGNES_API_BASE（可覆盖默认地址）

使用示例：

# 文本
python3 agnes-free-text/scripts/agnes_text.py chat --message "解释 Agent skill 是什么"

# 图片
python3 agnes-free-image/scripts/agnes_image.py generate --prompt "科技感插画，干净明亮"

# 视频
python3 agnes-free-video/scripts/agnes_video.py create --prompt "竖屏短视频，医疗科普画面"

# 视频轮询并下载
python3 agnes-free-video/scripts/agnes_video.py status --task-id task_123456 --wait --download-dir downloads

9.3 16nic 的 ComfyUI 节点（推荐 ComfyUI 用户）

仓库： https://github.com/16nic/comfyui-agnes-ai

特点：

• ComfyUI 自定义节点插件
• 7 个功能节点，覆盖 Agnes 全模态能力
• 支持 API Key 持久化、画质选择、宽高比选择
• 视频输出支持 ComfyUI 原生 VIDEO 类型

功能节点：

安装方式：

cd ComfyUI/custom_nodes
git clone https://github.com/16nic/comfyui-agnes-ai.git
cd comfyui-agnes-ai
pip install -r requirements.txt

配置 API Key（推荐方式）：

1. 在节点菜单 → Agnes AI → 添加 Agnes API Key Config
2. 在 api_key 输入框填入你的 API Key
3. 运行一次（Ctrl+Enter / Queue Prompt）
4. Key 自动保存到 api_key_config.json
5. 之后其他 Agnes 节点的 api_key 字段留空即可自动加载

API Key 加载优先级：

环境变量 AGNES_API_KEY > api_key_config.json > 运行时回退加载 > 节点输入框手动填写

画质 × 宽高比对照表（图片）：

注意事项：

• 视频生成是异步任务，通常需要 2-6 分钟
• 免费 API 高峰期可能有排队（503）或 GPU OOM（500）
• 建议首次使用先测试文生图，确认 API Key 正常工作

11. Codex 集成指南

区分两个工具：

• Codex++（Agnes 官方文档推荐）：第三方 GUI 工具，通过管理界面配置供应商
• OpenAI Codex CLI（命令行工具）：OpenAI 官方终端 AI 编程智能体，通过 ~/.codex/config.toml 配置

10.1 Codex++ 配置（Agnes 官方推荐）

Codex++ 是一款支持多供应商的 GUI 管理工具，Agnes 官方文档提供完整接入指南。

Step 1 — 下载 Codex++

• 仓库：https://github.com/BigPizzaV3/CodexPlusPlus
• 最新版：https://github.com/BigPizzaV3/CodexPlusPlus/releases/latest
• 根据系统选择安装包：
  • Windows：windows-x64-setup.exe
  • Intel Mac：macos-x64.dmg
  • Apple Silicon Mac：macos-arm64.dmg

Step 2 — 安装

正常安装即可。Mac 用户若提示"已损坏，无法打开"，在终端执行：

sudo xattr -rd com.apple.quarantine "/Applications/Codex++.app"
sudo xattr -rd com.apple.quarantine "/Applications/Codex++ 管理工具.app"

Step 3 — 打开管理工具，添加 Agnes 供应商

打开"Codex++ 管理工具" → 左侧菜单"供应商配置" → "添加供应商"，填写：

⚠️ 关键注意事项：

• Key 只填写 sk- 开头的密钥，不要填写 Bearer
• Base URL 只填写到 /v1，不要填写 /chat/completions
• 上游协议必须选择 Chat Completions

Step 4 — 启用并启动

1. 保存配置后，回到供应商列表，选择 Agnes，点击"使用/切换到此供应商"
2. 左侧菜单"概览" → "启动 Codex++"（或右上角"重启 Codex"）
3. 启动完成后，新建会话测试：输入"你好，请介绍一下你自己"，正常回复即配置成功

10.2 OpenAI Codex CLI 配置（命令行用户）

如果你使用的是 OpenAI 官方的 codex 命令行工具，可通过以下方式接入 Agnes：

Step 1 — 创建配置目录

mkdir -p ~/.codex

Step 2 — 编辑 ~/.codex/config.toml

#:schema https://developers.openai.com/codex/config-schema.json

# 使用 Agnes AI 作为后端
model = "agnes-2.0-flash"
model_provider = "openai"
openai_base_url = "https://apihub.agnes-ai.com/v1"

# 推荐日常配置
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Step 3 — 配置 API Key

方式 A：环境变量（推荐）

# macOS / Linux
export OPENAI_API_KEY="YOUR_AGNES_API_KEY"

# Windows PowerShell
$env:OPENAI_API_KEY="YOUR_AGNES_API_KEY"

方式 B：认证文件 编辑 ~/.codex/auth.json：

{
  "OPENAI_API_KEY": "YOUR_AGNES_API_KEY"
}

Step 4 — 验证配置

codex doctor

codex doctor 会自动检测运行时、认证、网络连通性和 config.toml 格式，所有项目绿色即配置成功。

多 Provider 配置（灵活切换）：

# 默认使用 Agnes
model = "agnes-2.0-flash"
model_provider = "openai"
openai_base_url = "https://apihub.agnes-ai.com/v1"

# 同时保留官方 OpenAI 配置
[model_providers.openai]
name = "OpenAI Official"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"

# 或其他 Provider
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"

切换 Provider 时只需修改：

model_provider = "openai"  # 使用 Agnes
# 或
model_provider = "deepseek"  # 使用 DeepSeek

10.3 使用 Agnes 的各模型

注意： Codex/Codex++ 主要使用 Chat Completions API，图像和视频生成需要通过 Agnes 的独立端点调用。如需在 Codex 中使用图像/视频生成，建议：

1. 安装 kangarooking 的 agnes-free-image / agnes-free-video Skill
2. 或直接使用 curl / Python 脚本调用

10.4 常见问题

Q: Codex++ 配置后无法连接？

• 确认 Key 只填写 sk- 部分，不含 Bearer
• 确认 Base URL 只到 /v1，不含 /chat/completions
• 确认上游协议选择 Chat Completions
• 确认网络可正常访问 https://apihub.agnes-ai.com

Q: OpenAI Codex CLI 提示 "自定义配置不生效"？

• 确认 config.toml 路径正确（~/.codex/config.toml）
• 确认 model_provider 名称匹配
• 确认 base_url 完整（包含 /v1）
• 确认环境变量名与 env_key 一致

Q: 如何同时使用 Agnes 和官方 OpenAI？

• Codex++：在供应商列表中切换
• Codex CLI：使用多 Provider 配置（见 10.2）

Q: Codex 的 Agent 模式能调用 Agnes 的工具调用吗？

• 可以。Agnes 2.0 Flash 支持 OpenAI 兼容的工具调用格式
• 在 Codex 中正常使用 tools 即可
• 模型返回 finish_reason: "tool_calls" 时，Codex 会自动处理

Agnes AI，让世界级 AI 属于每一个人。

12. OpenClaw 接入指南

官方文档：https://agnes-ai.com/doc/cid1

11.1 概述

OpenClaw 是一款支持自定义模型服务商的 Agent 工具。配置完成后，OpenClaw 可以通过 Agnes AI API 网关调用模型，用于本地 Agent 任务。

11.2 配置步骤

Step 1 — 打开终端

• macOS / Linux：使用终端
• Windows：使用命令提示符、PowerShell 或开发环境中的终端

Step 2 — 进入 OpenClaw 配置界面

openclaw config

Step 3 — 选择本地配置

在配置菜单中选择：Local，按 Enter。

Step 4 — 进入模型配置

选择：Model，按 Enter。

Step 5 — 选择定制服务商

选择：Custom Provider，按 Enter。

Step 6 — 配置 API Base URL

输入：

https://apihub.agnes-ai.com/v1

Step 7 — 填写 API Key

输入你的 Agnes API Key（sk- 开头）。

⚠️ 注意： 通常不需要手动添加 Bearer，除非 OpenClaw 明确要求输入完整的授权标头。

Step 8 — 填写模型名称

输入：

agnes-2.0-flash

Step 9 — 保存配置

完成所有必填项后，确认并保存。

11.3 完整配置示例

Provider Type: Custom Provider
API Base URL: https://apihub.agnes-ai.com/v1
API Key: YOUR_API_KEY
Model: agnes-2.0-flash

11.4 验证配置

配置完成后，运行一个 OpenClaw 任务或启动测试会话。如果能正常返回模型响应，说明配置成功。

11.5 常见问题

Q: API 请求失败？

• 检查 API Base URL 是否正确：https://apihub.agnes-ai.com/v1
• 确认 API Key 是否有效

Q: 提示"缺乏模型"？

• 确认模型名称填写正确，区分大小写
• 建议直接复制平台提供的模型名称

Q: 鉴权失败？

• 检查 API Key 是否过期
• 确认账户余额充足
• 确认该 Key 具备访问目标模型的权限

Q: 网络错误？

• 确认设备可正常访问 API
• 检查防火墙、代理或 VPN 设置

Q: API Base URL 到底要不要填 /chat/completions？

• 不要。只填写到 /v1
• 正确：https://apihub.agnes-ai.com/v1
• 错误：https://apihub.agnes-ai.com/v1/chat/completions
• 除非 OpenClaw 明确要求输入完整接口地址

13. HermesAgents 接入指南

官方文档：https://agnes-ai.com/doc/cid2

12.1 概述

HermesAgents 是一款支持自定义模型服务商的 Agent 工具。配置完成后，HermesAgents 将模型请求发送到 Agnes AI API 网关，并使用 Agnes 模型完成 Agent 任务。

12.2 配置步骤

HermesAgents 使用命令行配置，格式为：

hermes config set <配置项> <值>

Step 1 — 配置模型服务商

hermes config set model.provider custom

Step 2 — 配置 API Base URL

hermes config set model.base_url https://apihub.agnes-ai.com/v1

Step 3 — 配置 API Key

hermes config set model.api_key YOUR_API_KEY

⚠️ 注意： 通常不需要手动添加 Bearer，除非 HermesAgents 明确要求输入完整的授权标头。

也可以通过环境变量配置：

hermes config set OPENAI_API_KEY YOUR_API_KEY

但在自定义模型服务商配置中，推荐优先使用 model.api_key。

Step 4 — 配置模型名称

hermes config set model.default agnes-2.0-flash

12.3 完整配置示例

hermes config set model.provider custom
hermes config set model.base_url https://apihub.agnes-ai.com/v1
hermes config set model.api_key sk-xxxxxxxxxxxxxxxx
hermes config set model.default agnes-2.0-flash

12.4 验证配置

配置完成后，运行一个 HermesAgents 任务或启动测试会话。如果能正常返回模型响应，说明配置成功。

12.5 常见问题

Q: 鉴权失败？

• 重新执行 hermes config set model.api_key YOUR_API_KEY
• 确认账户余额或积分充足

Q: API 请求失败？

• 确认 API Base URL 正确：https://apihub.agnes-ai.com/v1
• 确认网络、防火墙、代理或 VPN 设置正常

Q: 模型名称不生效？

• 确认模型 ID 区分大小写
• 建议直接复制平台提供的模型名称

Q: API Base URL 要不要填 /chat/completions？

• 不要。只填写到 /v1
• 正确：https://apihub.agnes-ai.com/v1
• 错误：https://apihub.agnes-ai.com/v1/chat/completions

14. Claude CLI 接入指南（通过 CC-Switch）

官方文档：https://agnes-ai.com/doc/cid3

13.1 概述

Claude CLI 是 Anthropic 官方的终端 AI 编程工具。由于 Claude CLI 原生不支持自定义 OpenAI-Compatible API，需要通过 CC-Switch 作为代理路由，将请求转发到 Agnes AI API 网关。

所需工具：

• Claude CLI（已安装）
• CC-Switch v3.16.1+（下载：https://github.com/farion1231/cc-switch/releases）
• Agnes AI API Key

13.2 配置步骤

Step 1 — 获取 Agnes API Key

访问 https://platform.agnes-ai.com/，登录后进入 API Key 页面，创建并复制 API Key。

Step 2 — 打开 CC-Switch

启动 CC-Switch，在顶部工具栏选择：Claude CLI

Step 3 — 添加新供应商

点击右上角加号，添加新供应商：

• 供应商类型选择：Claude Provider → Custom Provider

Step 4 — 填写配置信息

⚠️ 注意： 通常不需要手动添加 Bearer 前缀。

Step 5 — 模型映射

点击"获取模型列表"，确认可正常连接 Agnes API。

然后将 Claude CLI 的模型映射到 Agnes 模型：

Step 6 — 添加自定义参数（重要）

为避免模型请求中出现不兼容参数，建议在自定义参数中加入：

{
  "allowed_openai_params": [
    "thinking",
    "context_management"
  ],
  "litellm_settings": {
    "drop_params": true
  }
}

作用：

• 允许指定的 OpenAI 参数通过
• 自动丢弃模型不兼容的未知参数
• 提高 Claude CLI 通过代理调用 OpenAI-Compatible API 时的兼容性

Step 7 — 保存并启用

• 保存供应商配置
• 进入 CC-Switch 设置 → Route → 打开 Local Route
• 在本地路由中启用 Claude 路由切换
• 返回供应商列表，启用 Agnes Provider

13.3 验证配置

打开 Claude CLI，执行一次测试对话或代码任务。如果能正常返回 Agnes 模型响应，说明配置成功。

13.4 常见问题

Q: 无法获取模型列表？

• 检查 API Base URL：https://apihub.agnes-ai.com/v1
• 确认 API Key 有效
• 确认网络可正常访问 Agnes API
• CC 平台：检查 CC-Switch 版本是否最新，旧版本可能无法获取模型列表

Q: Claude CLI 返回错误或不兼容参数？

• 确认已添加自定义参数（allowed_openai_params + litellm_settings.drop_params）
• 确认 API 格式选择为 OpenAI Chat Completions

Q: 配置保存后 Claude CLI 仍走官方 Anthropic？

• 确认 CC-Switch 的 Local Route 已开启
• 确认 Claude 路由切换已启用
• 确认 Agnes Provider 已启用

15. Claude Desktop 接入指南（通过 CC-Switch）

官方文档：https://agnes-ai.com/doc/cid4

14.1 概述

Claude Desktop 是 Anthropic 官方的桌面端 AI 应用。与 Claude CLI 类似，需要通过 CC-Switch 作为代理路由，将请求转发到 Agnes AI API 网关。

所需工具：

• Claude Desktop（下载：https://claude.com/download）
• CC-Switch v3.16.1+（下载：https://github.com/farion1231/cc-switch/releases）
• Agnes AI API Key

14.2 配置步骤

Step 1 — 安装 Claude Desktop

根据系统选择安装包：

• Windows：.exe
• macOS：.dmg
• Linux：AppImage

Step 2 — 打开 CC-Switch

启动 CC-Switch，在顶部切换到：Claude Desktop 或 ClaudeCode Desktop

Step 3 — 添加新供应商

点击"添加新供应商"：

• 选择：Custom Provider

Step 4 — 填写配置信息

Step 5 — 开启模型映射并获取模型列表

• 开启"模型映射"功能
• 点击"获取模型列表"，确认可正常连接 Agnes API

Step 6 — 配置模型映射

Step 7 — 保存并启用路由

• 保存配置
• 进入 CC-Switch 设置 → Route → 打开本地路由开关
• 启用 Claude 路由
• 返回供应商列表，启用 Agnes Provider

14.3 验证配置

打开 Claude Desktop，发起一次测试对话。如果能正常通过 Agnes 模型返回响应，说明配置成功。

14.4 常见问题

Q: Claude Desktop 无法调用模型？

• 确认 CC-Switch 本地路由已开启
• 确认 Claude 路由已启用

Q: 无法获取模型列表？

• 检查 API Base URL：https://apihub.agnes-ai.com/v1
• 确认 API Key 有效
• CC 平台：检查 CC-Switch 版本是否最新，旧版本可能无法获取模型列表
• 确认已开启模型映射功能
• 确认 Claude 模型已映射到 Agnes 模型

Q: API 请求失败或鉴权失败？

• 检查网络、防火墙、代理或 VPN 设置
• 确认 API Key 正确，账户余额充足

16. WorkBuddy 接入指南

官方文档：https://agnes-ai.com/doc/cid5

15.1 概述

WorkBuddy 是一款支持自定义模型的 AI 工作助手。配置完成后，WorkBuddy 可以直接调用 Agnes 文本模型进行对话、代码和 Agent 任务，也可以通过 Skill 方式使用 Agnes 图像和视频模型。

本教程基于 WorkBuddy v4.24.5 版本。

15.2 文本模型配置步骤

Step 1 — 获取 Agnes API Key

访问 https://platform.agnes-ai.com/，登录后进入 API Key 页面，创建并复制 API Key。

Step 2 — 进入自定义模型配置

打开 WorkBuddy，点击：Auto → 配置自定义模型

Step 3 — 选择自定义提供商

在提供商列表中向下滑动到最后，选择：其他 或 Custom

Step 4 — 添加 Agnes 文本模型

点击"添加模型"，填写：

Step 5 — 保存并选择模型

保存后，在 WorkBuddy 对话界面中选择：agnes-2.0-flash

Step 6 — 验证

发起一次普通对话，例如："你好，请介绍一下你自己。"正常返回即配置成功。

15.3 图像和视频模型配置（通过 Skill）

Agnes 的图像和视频模型可以通过创建 Skill 的方式在 WorkBuddy 中使用。

创建 Skill 的提示词：

我想要使用 Agnes Image 2.0 模型生图生视频，访问它的 API 平台 https://agnes-ai.com/doc/overview，并将它打包成一份 Skill。

WorkBuddy 会根据 Agnes API 文档自动生成图像和视频相关 Skill。

使用图像 Skill：

• 点击技能列表，选择图像生成 Skill（如 agnes-image-gen）
• 输入提示词，例如："生成一张赛博朋克城市夜景，霓虹灯光，电影感，高细节。"

使用视频 Skill：

• 选择视频生成 Skill（如 agnes-video-gen）
• 输入提示词，例如："生成一段亚洲女生模特在白色摄影棚中展示黑色连衣裙的视频，从全景缓慢切到半身特写，保持自然转身，5 秒。"

15.4 常见问题

Q: 文本模型无法返回？

• 检查 API Base URL：https://apihub.agnes-ai.com/v1
• 确认 API Key 有效

Q: 模型列表中看不到 agnes-2.0-flash？

• 确认模型名称填写正确，区分大小写
• 建议直接复制平台提供的模型名称

Q: 图像或视频 Skill 创建失败？

• 确认 WorkBuddy 可以正常访问 Agnes 文档地址
• 确认当前模型具备读取文档和创建 Skill 的能力

Q: 视频任务长时间没有完成？

• 视频生成通常需要一定时间，请耐心等待
• 确认使用 video_id 查询结果（不要用 task_id）

Q: 鉴权失败？

• 检查 API Key 是否正确
• 确认账户余额或 credits 充足

17. Cherry Studio 接入指南

官方文档：https://agnes-ai.com/doc/cid6

16.1 概述

Cherry Studio 是一款支持多模型服务商的 AI 客户端。配置完成后，Cherry Studio 可以调用 Agnes 文本模型进行对话，也可以通过技能或智能体绑定的方式使用 Agnes 图像和视频模型。

16.2 文本模型配置步骤

Step 1 — 获取 Agnes API Key

访问 https://platform.agnes-ai.com/，登录后进入 API Key 页面，创建并复制 API Key。

Step 2 — 添加提供商

进入 Cherry Studio 的 API 服务商或模型设置页面，点击：添加提供商

Step 3 — 选择提供商类型

提供商类型选择：OpenAI（或支持 OpenAI-Compatible API 的自定义类型）

Step 4 — 填写配置信息

⚠️ 注意： 通常不需要手动添加 Bearer。

Step 5 — 获取模型列表

点击"获取模型列表"，确认可正常连接 Agnes API。选择文本模型：agnes-2.0-flash

Step 6 — 保存并验证

保存后，在 Cherry Studio 中新建对话框，选择 agnes-2.0-flash，发送测试消息。正常返回即配置成功。

16.3 图像和视频模型使用方式

Cherry Studio 中，图像和视频模型建议通过创建技能并绑定智能体的方式使用。

• 创建图像 Skill（如 Agnes Image Skill），绑定到智能体
• 创建视频 Skill（如 Agnes Video Skill），绑定到智能体
• 通过对话方式生成图片或视频

16.4 常见问题

Q: 无法获取模型列表？

• 检查 API 地址：https://apihub.agnes-ai.com/v1
• 确认 API Key 有效
• CC 平台：检查 CC-Switch 版本是否最新，旧版本可能无法获取模型列表

Q: 鉴权失败？

• 确认 API Key 填写正确
• 确认账户余额充足

Q: 无法从外部链接下载或安装 Skills？

• 通常表示智能体无法联网请求 skills，检查网络连接
• 尝试手动下载 Skill 文件并本地安装
• 确认 Agent 工具支持外部网络请求

Q: 文本模型可用，但图片或视频不能用？

• Cherry Studio 的普通 OpenAI 兼容文本模型配置通常只适合文本对话
• 图像和视频模型建议通过技能或智能体工具绑定方式使用

Q: API 地址要不要填 /chat/completions？

• 不要。只填写到 /v1
• 正确：https://apihub.agnes-ai.com/v1
• 错误：https://apihub.agnes-ai.com/v1/chat/completions

18. Opencode 接入指南

官方文档：https://agnes-ai.com/doc/cid7

本指南基于 OpenCode 1.15.13 版本整理。

18.1 概述

Opencode 是一款支持 OpenAI-Compatible API 的 AI 编程工具。配置完成后，你可以在 OpenCode 中直接使用 Agnes 模型进行代码生成、项目分析、代码修改和多轮对话。

前置条件：

• 已注册 Agnes AI 账号
• 已进入 Agnes API Platform 并创建 API Key
• 当前网络环境可以访问 Agnes API Gateway

18.2 OpenCode CLI 配置

适用场景： 通过终端使用 OpenCode CLI 的用户。

Step 1 — 打开配置文件

如果你已有 OpenCode 配置文件，在原有配置中新增 agnes provider，并将默认模型设置为：

"model": "agnes/agnes-2.0-flash"

Step 2 — 添加 Agnes Provider 配置

{
  "$schema": "https://opencode.ai/config.json",
  "model": "agnes/agnes-2.0-flash",
  "provider": {
    "agnes": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Agnes",
      "options": {
        "baseURL": "https://apihub.agnes-ai.com/v1",
        "apiKey": "{env:AGNES_API_KEY}"
      },
      "models": {
        "agnes-2.0-flash": {
          "name": "agnes-2.0-flash"
        }
      }
    }
  }
}

⚠️ 注意： 如果你已有其他 provider，不要直接覆盖整个配置文件。只需要在 provider 下新增 agnes，并将 model 改为 agnes/agnes-2.0-flash。

Step 3 — 配置环境变量

在终端中配置 Agnes API Key：

export AGNES_API_KEY="你的 Agnes API Key"

如果希望长期生效，写入 shell 配置文件：

# Bash 用户
echo 'export AGNES_API_KEY="你的 Agnes API Key"' >> ~/.bashrc
source ~/.bashrc

# zsh 用户（macOS 默认）
echo 'export AGNES_API_KEY="你的 Agnes API Key"' >> ~/.zshrc
source ~/.zshrc

Step 4 — 验证配置

启动 OpenCode 后，输入：

/models

如果配置成功，可以看到：

Agnes
agnes-2.0-flash

选择 Agnes / agnes-2.0-flash 后，即可开始使用 Agnes 模型。

18.3 OpenCode Desktop 配置

适用场景： 使用 OpenCode Desktop 图形界面的用户。

Step 1 — 打开设置

启动 OpenCode Desktop，点击左下角的设置按钮。

Step 2 — 选择自定义提供商

在提供商列表中找到自定义提供商，点击右侧的连接。

Step 3 — 填写 Agnes 提供商配置

⚠️ 注意： API Key 只填写密钥本身，不需要填写 Bearer。

Step 4 — 保存配置

保存后，OpenCode Desktop 将使用 Agnes 模型进行对话和代码生成。

18.4 配置参数速查

18.5 常见问题

Q: 配置后不显示 Agnes 模型？

• 确认 baseURL 正确：https://apihub.agnes-ai.com/v1
• 确认 AGNES_API_KEY 环境变量已正确设置
• 确认 provider 下的 agnes 配置语法正确

Q: 已有其他 provider，如何添加 Agnes？

• 不要覆盖整个 provider 对象
• 在 provider 下新增 agnes 键值对
• 将顶层 model 改为 agnes/agnes-2.0-flash

Q: Desktop 和 CLI 配置冲突？

• CLI 配置保存在 ~/.config/opencode/ 或项目目录的 .opencode 文件夹中
• Desktop 配置保存在应用内部设置中
• 两者独立，不会互相覆盖

Agnes AI，让世界级 AI 属于每一个人。