Agnes API Key 生成向导（tokeny 干净版 / .com 专用）

本技能专为 tokeny 环境设计，目标是：让完全不懂 API 的使用者，跟着向导一步步在 Agnes .com 官网生成属于自己的 API Key，校验后仍可一键保存，供 agnes-video / agnes-image 技能复用。

本技能不内置任何 API Key，使用者必须自己到官网创建密钥；它只负责「领着你走」+ 校验 + 保存。

⚠️ 先分清两个域名（关键）

Agnes 的 .com 有两个不同作用的地址，别搞混：

tokeny 用 .com；WorkBuddy 用 .cn（两者 Key 不一定通用）。本向导只面向 .com。

---

使用方式（二选一）

方式 A：交互式向导（推荐，最省心）

在终端运行：

python scripts/get_apikey.py

脚本会：

1. 自动用浏览器打开 .com 官网主页（platform.agnes-ai.com）
2. 逐条提示你：注册 → 登录 → 找密钥页 → 创建密钥 → 复制
3. 等你粘贴密钥后，自动用 .com 接口校验有效性
4. 校验通过即写入 config.json，供视频/图片技能直接复用

全程只需「看提示 + 回车 + 复制粘贴」，不需要懂代码。

方式 B：纯文字引导 + 手动校验

python scripts/get_apikey.py --open      # 只打开官网主页
python scripts/get_apikey.py --api-key sk-你的密钥        # 校验一把密钥
python scripts/get_apikey.py --api-key sk-你的密钥 --save # 校验并保存
python scripts/selfcheck.py              # 校验 Python/网络/Key 格式
python scripts/selfcheck.py --auth       # 额外验证 Key 真实有效

---

在 .com 官网主页上「生成 API 密钥」的完整步骤

（以下也是向导里会逐条提示的内容，可单独照做）

1. 打开 .com 官网主页：浏览器访问 https://platform.agnes-ai.com
2. 邮箱注册：点右上角「登录 / 注册」，用邮箱注册（官网会给有效邮箱发验证码，并设置登录密码）
3. 登录：用刚注册的邮箱 + 密码登录，进入开发者控制台首页
4. 找到密钥管理页：看页面左侧菜单栏 → 点【设置】→【API 密钥 / API Keys 管理】
5. 创建密钥：点【创建新密钥 / Create new secret key】，自定义填一个备注名（如 tokeny 接入，方便以后区分），点确认
6. 复制密钥（⚠️ 只显示这一次！）：页面会展示一长串以 sk- 开头的密钥
   • 立刻全选复制，存到记事本 / 密码管理器
   • 关闭弹窗或刷新后无法再查看完整密钥，务必先保存
7. 回填校验：把复制的 sk-... 粘贴给本向导（或运行 --api-key），脚本会用 .com 接口校验；通过即完成

---

配置 Key 的三种方式（任选其一）

# 方式 A：环境变量（推荐，最安全）
export AGNES_API_KEY=sk-你的真实密钥

# 方式 B：配置文件
cp config.example.json config.json
# 编辑 config.json，把 api_key 改为你的密钥

# 方式 C：每次命令行传入
python scripts/get_apikey.py --api-key sk-你的真实密钥

---

安全说明（重要）

• ❌ 本技能不包含、不硬编码任何 API Key。
• ✅ 密钥仅由使用者自行提供（向导粘贴 / --api-key / 环境变量 AGNES_API_KEY / config.json）。
• ✅ 默认仅面向 .com 节点；若误指向 .cn，脚本会主动警告（tokeny 下 .cn 通常不可达）。
• ✅ 任何日志/提示都不打印真实 Key 的明文片段（已脱敏）。
• 分享本技能时，请确保不要把自己的 config.json 或含密钥的 .env 一起发出去。

技术细节

• 校验有效性：GET https://apihub.agnes-ai.com/v1/models（带 Authorization: Bearer <key>）
  • HTTP 200 → Key 有效（并列出现有模型）
  • HTTP 401/403 → Key 无效 / 过期 / 已吊销 / 不属于 .com 节点
• 校验接口为只读，不消耗任何生成积分。

与其它技能的关系

• 本向导产出的 Key 可直接被 agnes-video、agnes-image 复用（三者读取相同的 AGNES_API_KEY / config.json）。
• 三者均强制 .com 节点，互不冲突，可配套安装。

版本: v1.1.0（tokeny 干净版 / 引导式向导 / 无内置密钥 / .com 专用） 更新时间: 2026-08-14