/Agnes-help-skill

name: agnes-ai-support
version: "1.3.2"
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.3.2 > **适用工具：** OpenClaw / Claude Code / Claude Desktop / Hermes / Codex / WorkBuddy / Cherry Studio / Opencode / Kimi Work > **更新日期：** 2026-09-23 > **官方 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 的完整信息，帮你完成接入、生成内容、排查问题。


一、用 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 会自动匹配）：**

| 错误码 | 含义 | 常见原因 | |--------|------|----------| | 401 | 认证错误 | API Key 错误、过期、格式不对 | | 400 | 参数错误 | 必填参数缺失、类型错误、response_format 放错位置 | | 429 | 频率限制 | 文本/图像 RPM 超过 20，或视频 RPM 超过 1（每分钟只能生成 1 个视频） | 降低请求频率，视频需排队等待 | | 503 | 服务繁忙 | 服务端负载高，稍后重试 |

**示例对话：**

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

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

---

> **🔔 Agnes AI 官方反馈渠道（如果以上排查均无效）：** > > 当 Agnes AI 官方 API 服务出现问题（Bug、异常、功能不符合预期），请通过以下**官方渠道**反馈： > - **GitHub Issues（推荐）：** http