agnes-ai-support

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

Skill 版本： v1.2.5

适用工具： OpenClaw / Claude Code / Claude Desktop / Hermes / Codex / WorkBuddy / Cherry Studio / Opencode / Kimi Work

更新日期： 2026-06-06

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. 读取 GitHub 仓库最新版本信息：

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

1. 比较远程最新 commit 的 sha 与本地记录的版本。

1. 如果检测到更新，在回复开头提醒用户：

> 📢 本 Skill 有新版本可用！ 建议从 GitHub 获取最新版以获得完整功能和最新接入指南。 > > 仓库地址：https://github.com/lj1270998580-crypto/Agnes-help-skill > > 一键更新指令： > `` > 请读取并安装 Agnes AI 支持 Skill 最新版：https://raw.githubusercontent.com/lj1270998580-crypto/Agnes-help-skill/main/SKILL.md > ``

1. 如果用户正在使用 HTML 助手或 API 文档，同样提醒检查对应文件是否有更新。

如何使用本 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 → 给出正确查询方式）

补充建议

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

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

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

• •不限期、全模态、API 调用完全免费（RPM 20 以内）
• •注册官网 → 生成 KEY → 直接调用
• •文本、图像、视频全能适配，高效便捷
• •模型会持续升级并保持免费
• •欢迎大家多用、多吐槽

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

视频接口重要更新

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

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

官方已回退： Agnes-2.0-Flash 的上下文窗口从 1M 回退至 256K，Max Output 回退至 65.5K。

此前官方短暂开放了 1M Token 超长上下文支持，但发现稳定性问题后已回退至原有规格。

当前规格：

- Context：256K

- Max Output：65.5K

1.5 Flash 保持 256K/65.5K 不变。

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
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，当前所有模型免费但有 RPM 限制）
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 格式：1024x768 / 1024x1024 / 768x1024

视频模型 400：

• •必填：model + prompt
• •num_frames 必须 ≤ 441 且满足 8n + 1
• •有效值：81, 121, 161, 241, 441
• •frame_rate 范围 1-60
• •图生视频：image 需为公网可访问 URL

2.3 响应类问题

无响应 / 超时

• •Chat：超时建议 30s
• •图像：超时建议 60-360s（数秒到几十秒）
• •视频：异步任务，创建后需轮询查询，间隔 5s
• •检查网络能否访问 apihub.agnes-ai.com
• •检查防火墙/代理是否拦截

503 Service Unavailable

• •服务暂时繁忙，指数退避重试：1s → 2s → 4s → 8s
• •关注 Agnes AI 状态公告

429 Rate Limited

• •降低请求频率
• •免费账户 RPM 限制为 20，充值可提升
• •实现客户端队列和退避

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

常用配置：

更长视频： 增加 num_frames 或降低 frame_rate

3.5 图像输出格式

URL 输出：

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

Base64 输出（文生图）：

{
  "return_base64": true
}

Base64 输出（图生图）：

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

4. 各模型参数速查

agnes-1.5-flash

• •端点：POST /v1/chat/completions
• •Context：256K
• •Max Output：65.5K
• •参数：model, messages, temperature, top_p, max_tokens, frequency_penalty, presence_penalty, repetition_penalty, stop, seed
• •价格：Input $0.07/1M, Output $0.15/1M（现价 $0，RPM ≤ 20）

agnes-2.0-flash

• •端点：POST /v1/chat/completions
• •Context：256K
• •Max Output：65.5K
• •额外参数：stream, tools, tool_choice, chat_template_kwargs, thinking
• •支持图片 URL 输入（messages[].content 数组格式）
• •支持工具调用、Thinking 模式、流式输出
• •价格：Input $0.1/1M, Output $0.2/1M（现价 $0，RPM ≤ 20）

agnes-image-2.0/2.1-flash

• •端点：POST /v1/images/generations
• •必填：model, prompt, size
• •图生图必填：extra_body.image（URL 数组或 Data URI Base64，必须放在 extra_body 中！）
• •size：1024x768 / 1024x1024 / 768x1024
• •输出：URL 或 Base64
• •价格：$0.003/image（现价 $0，RPM ≤ 20）

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
• •价格：$0.005/second（现价 $0，RPM ≤ 20）
• •重要：必须用 video_id 查询，task_id 会导致排队过长

5. 常见错误速查表

6. 接入检查清单

通用

• •[ ] 已注册账户并创建 API Key（https://platform.agnes-ai.com）
• •[ ] Base URL 正确：https://apihub.agnes-ai.com/v1
• •[ ] 请求头包含 Authorization 和 Content-Type
• •[ ] API Key 未暴露在公开代码中
• •[ ] 已实现错误处理和重试逻辑
• •[ ] 了解 RPM 限制（免费 20/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-1.5-flash
• •需要推理/编程使用 agnes-2.0-flash + Thinking
• •图像生成设置合理超时（60-360s）
• •视频生成使用异步 + 轮询模式
• •实现指数退避重试（1s → 2s → 4s → 8s）
• •视频查询必须用 video_id，避免 task_id 导致的排队

安全

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

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
• •支持邮箱：[email protected]
• •公司：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

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 有效

Q: 模型映射失败？

• •确认已开启模型映射功能
• •确认 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 有效

Q: 鉴权失败？

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

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

17.1 概述

Opencode 是一款支持 OpenAI-Compatible API 的 AI 编程工具。当前 Agnes 官方文档中仅提供通用接入模板，以下为推荐配置参数。

17.2 推荐配置参数

如果 Opencode 支持 OpenAI-Compatible API，可以使用以下配置：

17.3 注意事项

• •API Base URL 通常以 /v1 结尾
• •正确： https://apihub.agnes-ai.com/v1
• •不推荐： https://apihub.agnes-ai.com/v1/chat/completions
• •除非 Opencode 明确要求填写完整的接口地址

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