从图片到视频：创建 agnes-video 异步技能的新经验与标准流程

在 OpenClaw 生态里，图片生成技能 agnes-image 已经相当成熟，但视频生成技能 agnes-video 的创建过程暴露了一个根本性差异：图片 API 是同步的，视频 API 是异步的。这个差异不是小细节，它决定了整个技能的结构、脚本逻辑、用户体验和后续运维方式。

本文把创建 agnes-video 过程中踩过的坑和沉淀的经验整理出来，也适用于任何基于异步 API 的 OpenClaw 技能开发。

同步 vs 异步：两种 API 模式的天壤之别

在动手写脚本之前，必须先判断 API 是同步还是异步。agnes-image 和 agnes-video 来自同一个平台，但交互模式完全不同：

关键洞察：如果你的技能脚本里只有一个 HTTP 请求就能拿到结果，那它是同步的；如果请求后拿到一个 task_id，需要定期去查状态，那它就是异步的。后者在视频生成、大模型训练、长时批处理场景中非常常见。

异步技能的标准创建流程

基于 agnes-video 的创建经验，异步技能可以提炼出以下标准流程：

需求分析 → 文档调研 → 参考实现 → 确认异步模式 → 创建脚本（含轮询逻辑）→ 测试验证 → 记录 task_id → 安排后续检查

每一步的具体含义：

1. 需求分析：明确技能要调用什么 API，输入输出格式是什么
2. 文档调研：找到官方 API 文档，确认是同步还是异步
3. 参考实现：如果有同类技能的脚本（比如 agnes-image），可以直接借鉴结构
4. 确认异步模式：通过一次测试调用确认返回 task_id 而非直接结果
5. 创建脚本（含轮询逻辑）：脚本不仅要会「发起请求」，还要会「查询状态」和「下载结果」
6. 测试验证：提交一个小任务，完整跑一遍 create → poll → download 流程
7. 记录 task_id：把关键任务的 task_id 记录下来，方便后续排查
8. 安排后续检查：长时任务需要定时查看，可以用 cron 或手工提醒

关键经验点：这些坑我都替你踩过了

1. 异步模式识别

问题：第一次调用视频 API 时，如果按照图片 API 的思路写代码，会拿到一个 task_id 而不是视频 URL，程序会不知所措。

解决：在脚本设计阶段就区分「创建任务」和「查询结果」两个函数。创建时立刻返回 task_id，让用户知道接下来需要等待。

2. GPU 排队时间

问题：视频生成依赖 GPU 资源，高峰时段任务排队可能长达数小时。如果脚本一直阻塞等待，用户体验会很差。

解决：提供 --no-poll 选项，让用户选择是否自动轮询。如果不自动轮询，脚本输出 task_id 后直接退出，用户可以稍后手动查询。

3. num_frames 限制

问题：视频 API 对帧数有严格要求，不是随便写个数字就行。必须满足两个条件：≤ 441 且满足 8n+1 的数学形式。

解决：在脚本中加入参数校验，只允许合法值：

# 合法的 num_frames 选项
ALLOWED_FRAMES="81 121 161 241 441"

用户传入非法值时，脚本直接报错并列出可选值，避免把错误请求发到 API。

4. 任务状态追踪

问题：异步任务提交后，如果用户关掉了终端，下次怎么知道任务状态？靠记忆不可靠。

解决：创建 TODOWNLOAD.md 记录关键信息：

cat > TODOWNLOAD.md << 'EOF'
- task_id: abc-123-def
- status: queued
- created_at: 2026-06-05 23:06
- 检查时间: 明天 09:00
EOF

这个文件放在技能目录下，下次打开时一眼就能看到有哪些任务在跑、什么时候该去查。

5. 凭证复用

问题：视频和图片 API 来自同一个平台，不需要重新申请 Key。

解决：在 ~/.openclaw/.env 中配置一次 AGNES_AI_API_KEY，agnes-image 和 agnes-video 共用同一个环境变量。

6. Skill Workshop 更快

问题：第一次创建技能时走了很多弯路，比如搜索文档、下载脚本、本地化调整。

解决：第二次创建类似技能时，直接从 GitHub 原始仓库下载脚本，跳过本地化步骤，创建时间从 2 小时缩短到 30 分钟。

7. SKILL.md 补做

问题：有时候是先下载脚本、跑通功能，后补写 SKILL.md 说明文档。

解决：应该在创建技能目录时同步生成 SKILL.md，功能代码和说明文档一起迭代，避免事后补文档时遗忘关键细节。

异步技能通用目录结构

对比同步技能，异步技能需要多一个任务追踪文件：

skills/<skill-name>/
├── SKILL.md              # 技能定义（主文档）
├── scripts/
│   └── <skill-name>.py   # CLI 脚本（含轮询逻辑）
├── references/
│   └── api.md            # API 参考文档
└── TODOWNLOAD.md         # 异步任务记录（新！）

TODOWNLOAD.md 是异步技能特有的文件，用来记录待下载的任务。对于同步技能，结果即时返回，不需要这个文件。

两种技能创建对比

把 agnes-image 和 agnes-video 的创建过程放在一起看，差异非常清晰：

有趣的是：agnes-video 虽然逻辑更复杂（需要轮询、需要追踪任务），但第二次创建反而更快，因为有了 agnes-image 的结构可参考，而且直接用了 GitHub 原始文件跳过了一些步骤。这说明「先难后易」在技能创建中是很常见的模式。

异步任务追踪最佳实践

把任务追踪流程标准化，以后任何异步技能都能复用：

# 1. 提交任务并记录
python3 scripts/agnes-video.py generate \
  --prompt "A cat playing piano" \
  --num-frames 161

# 2. 记录到 TODOWNLOAD.md
cat > TODOWNLOAD.md << 'EOF'
- task_id: abc-123-def
- status: queued
- created_at: 2026-06-05 23:06
- 检查时间: 明天 09:00
EOF

# 3. 后续查询命令
python3 scripts/agnes-video.py status \
  --task-id abc-123-def \
  --wait \
  --download

如果需要自动化检查，可以用 OpenClaw 的 cron 功能定时执行查询命令，完成后自动通知你。

总结

创建 agnes-video 最大的收获不是「又多了一个技能」，而是摸清了异步 API 技能的标准开发模式。这个模式可以复用于任何需要长时间等待的 API 调用：大模型微调、批量数据处理、3D 渲染等。

核心要点回顾：

• 先判断 API 是同步还是异步，这决定了脚本结构
• 异步技能必须有轮询逻辑和超时处理
• 用 TODOWNLOAD.md 追踪长时间任务，不要靠记忆
• 参数校验要前置，把错误拦截在客户端
• 凭证能复用就复用，不要重复配置

如果你也在为 OpenClaw 创建技能，希望这些经验能帮你少走弯路。

参考来源

• OpenClaw 官方文档
• ClawHub 技能市场
• agnes-image 技能文档
• OpenClaw /skills 页面

关联阅读

• [[self-improving-agent]]
• [[已装可用技能]]
• [[OpenClaw安装技能]]
• [[创建 agnes-image 技能的经验和最佳实践]]

–全文完–

若你有故事想讲、有困惑想聊、或是想找个人说说心里话，甚至只是吐槽发泄一下情绪，都欢迎来找我聊聊：　　　《内容已折叠，点击展开》

希望我写的每一个字，成为我自己和某个人活下去、拼下去的力量。　　　　　　　　　　　　　　　　　　　　　《内容已折叠，点击展开》

“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”

转载请注明来自https://oklife.me。