乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > Hyperframes 在 OpenClaw 中的完整使用指南

Hyperframes 在 OpenClaw 中的完整使用指南

当前时间： 2026-04-22 02:31:22 更新时间： 2026-04-22 分类：软件教程 评论(0)

Hyperframes 在 OpenClaw 中的完整使用指南

事情是这样的。

今天朋友问我，怎么在 OpenClaw 里用 Hyperframes 这个工具。我说好，然后我们就一起折腾了几个小时，从安装到创建第一个项目，踩了几个小坑，最后算是跑通了。

现在把整个过程整理出来，方便以后参考。

一、Hyperframes 是什么

坦率的讲，第一次听到 Hyperframes 的时候我也愣了一下。查了一下才发现，这是 HeyGen 开源的一个视频渲染框架。

它的核心理念特别简单：用 HTML 写视频。

不是那种复杂的视频编辑软件，而是写一段 HTML + CSS + GSAP 动画代码，然后直接渲染成 MP4。对于有前端基础的人来说，这简直太友好了。

几个特点：

  • HTML-native
    ：纯 HTML 文件，不用学新的 DSL
  • AI-first
    ：专门为 AI Agent 设计的工作流
  • 确定性渲染
    ：同样的输入，输出永远一样
  • Apache 2.0
    ：完全开源，商用也没问题

跟 Remotion 的区别在于，Remotion 用 React 组件，Hyperframes 用纯 HTML。哪个顺手用哪个。

二、环境准备

要用 Hyperframes，需要准备两样东西：

1. Node.js >= 22

这个应该大家都有了。检查一下：

node --version

2. FFmpeg（坑点）

这是今天最大的坑。

Hyperframes 渲染视频需要 FFmpeg，但很多 Windows 机器默认没有。

我试了 winget 安装，结果超时中断了。最后发现手动安装最靠谱：

安装步骤：

  1. 访问 https://www.gyan.dev/ffmpeg/builds/
  2. 下载 ffmpeg-release-essentials.zip
  3. 解压到 C:\ffmpeg\
  4. 添加到系统 PATH：

    [Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\ffmpeg\bin", "Machine")
  5. 重启终端，验证：

    ffmpeg -version

如果显示版本号，就说明安装成功了。

其他：

渲染视频需要 FFmpeg，选择以下任一方式安装：

方式 1: 通过 Winget（推荐）

winget install Gyan.FFmpeg -e

方式 2: 通过 Scoop

scoop install ffmpeg

方式 3: 手动下载

  1. 访问 https://ffmpeg.org/download.html
  2. 下载 Windows build (gyan.dev)
  3. 解压到 C:\ffmpeg
  4. 将 C:\ffmpeg\bin 添加到系统 PATH

三、安装 Hyperframes

有两种方式：

方式 1：全局安装 CLI（推荐）

npm install -g hyperframes
方式 2：克隆源码（可选）

如果想看源码或者二开：

git clone https://github.com/heygen-com/hyperframes.gitcd  hyperframes

不过源码需要用 bun 安装依赖，npm install 可能会报错（workspace 协议不支持）。

四、创建第一个项目

安装好 FFmpeg 之后，就可以开始创作了。

1. 初始化项目

npx hyperframes init my-first-videocd my-first-video

这会生成以下文件：

my-first-video/├── index.html          # 主视频文件（HTML + GSAP）├── hyperframes.json    # 项目配置├── meta.json           # 元数据└── AGENTS.md           # AI Agent 使用指南

2. 核心概念

打开 index.html，你会看到 Hyperframes 的核心结构：

<divid="root"data-composition-id="main"data-start="0"data-duration="10"data-width="1920"data-height="1080"><!-- 在这里添加视频元素 --></div><script>window.__timelines = window.__timelines || {};const tl = gsap.timeline({ paused: true });// 动画代码...window.__timelines["main"] = tl;</script>

几个关键属性：

属性
说明
data-start
开始时间（秒）
data-duration
持续时间（秒）
data-track-index
轨道索引，同轨道不能重叠
class="clip"
必须加，框架用它控制可见性

3. 添加视频元素

文字：

<divid="title"class="clip"data-start="0"data-duration="5"data-track-index="1"style="font-size: 64px; color: #fff;">  Hello World</div>

图片：

<imgid="logo"class="clip"data-start="1"data-duration="4"data-track-index="2"src="logo.png" />

视频（注意 muted）：

<videoid="clip"class="clip"data-start="0"data-duration="10"data-track-index="0"src="video.mp4"mutedplaysinline></video><!-- 音频单独加 --><audioid="audio"class="clip"data-start="0"data-duration="10"data-track-index="3"src="audio.mp3"data-volume="0.5"></audio>

4. GSAP 动画

动画用 GSAP，时间轴要 paused，还要注册到 window.__timelines：

const tl = gsap.timeline({ paused: true });// 从下方淡入tl.from("#title", { y: 60, opacity: 0, duration: 0.7, ease: "power3.out"}, 0.3);// 淡出退场（最后一幕才用）tl.to("#title", { opacity: 0, duration: 0.5}, 9);window.__timelines["main"] = tl;

五、预览与渲染

1. 浏览器预览

npx hyperframes preview
这会在浏览器打开实时预览，支持热更新，改代码自动刷新。

2. 检查代码

npx hyperframes lint
能发现很多潜在问题，建议每次修改后都跑一下。

3. 渲染 MP4

npx hyperframes render

输出在 renders/ 目录，文件名带时间戳。

六、添加预设组件

Hyperframes 提供了很多现成的组件：

# 数据图表npx hyperframes add data-chart# 社交按钮npx hyperframes add instagram-follow# 过渡效果npx hyperframes add flash-through-white

更多组件：https://hyperframes.heygen.com/catalog

七、完整示例

今天给写了一个 10 秒的品牌介绍视频，代码大概长这样：

<!doctype html><html><head><scriptsrc="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script><style>body {width: 1920px;height: 1080px;background: linear-gradient(135deg, #1a1a2e, #0f3460);display: flex;justify-content: center;align-items: center;    }.title { font-size: 120px; color: #fff; }.subtitle { font-size: 42px; color: #e8e8e8; margin-top: 24px; }</style></head><body><divdata-composition-id="main"data-start="0"data-duration="10"data-width="1920"data-height="1080"><divid="title"class="clip title"data-start="0"data-duration="10"data-track-index="0">      Hyperframes</div><divid="subtitle"class="clip subtitle"data-start="0"data-duration="10"data-track-index="1">      Write HTML. Render Video.</div></div><script>window.__timelines = window.__timelines || {};const tl = gsap.timeline({ paused: true });    tl.from("#title", { y: 60, opacity: 0, duration: 0.7 }, 0.3);    tl.from("#subtitle", { y: 40, opacity: 0, duration: 0.5 }, 0.6);window.__timelines["main"] = tl;</script></body></html>

运行 npx hyperframes render，十秒后就能拿到 MP4。

八、重要规则（容易踩坑）

  1. 视频必须 muted
    ，音频单独用 <audio> 标签
  2. 所有 timed 元素必须加 class=”clip”
  3. GSAP 时间轴必须 paused
    ，还要注册到 window.__timelines
  4. 不能用 Math.random() 或 Date.now()
    ，要确定性输出
  5. 不能用 repeat: -1
    ，要算好具体重复次数
  6. 不要异步构建时间轴
    ，必须在页面加载时同步完成

九、参考资源

  • 官方文档：https://hyperframes.heygen.com/introduction
  • GitHub：https://github.com/heygen-com/hyperframes
  • 组件目录：https://hyperframes.heygen.com/catalog
  • Prompting 指南：https://hyperframes.heygen.com/guides/prompting

十、总结

整个过程其实挺顺的，主要卡点就在 FFmpeg 安装上。

一旦跑通，用 HTML 写视频的感觉真的很爽。特别是对于有前端基础的人来说，不用学新的视频软件，直接用熟悉的 HTML/CSS/JS 就能做视频，这个体验太对味了。

如果你也想试试，按照上面的步骤来，有问题随时问我。

以上，既然看到这里了，如果觉得有用，随手点个赞。

我们，下次再见。

文档整理：米学编程时间：2026-04-21