Code Bestie Docs

Appearance

Code Bestie × Codex 接入 HyperFrames 教程 ​

本教程演示如何先用 Code Bestie 接入 Codex，再让 Codex 在项目里使用 HyperFrames 生成和渲染视频。

HyperFrames 是 HeyGen 开源的 HTML/CSS/JS 视频生成框架。它的思路是：让 Codex 这类 coding agent 写网页和动画，再用 HyperFrames 把画面稳定渲染成 MP4 或 WebM。

国内网络环境

如果 npx skills add、GitHub 或 npm 下载不稳定，请先看 国内网络环境安装 Codex 与 HyperFrames。这条路径使用 Gitee 分发安装脚本和 HyperFrames starter kit。

你会完成什么 ​

  1. 使用 Code Bestie API Key 配置 Codex。
  2. 在项目里安装 HyperFrames skills。
  3. 让 Codex 创建一个 HyperFrames 视频草稿。
  4. 用 HyperFrames 预览、检查并渲染视频。

前置条件 ​

  • 已注册 Code Bestie，并创建 API Key。不会操作的话先看 注册与兑换码使用教程。
  • 已安装 Node.js。HyperFrames 官方建议使用 Node.js 22+。
  • 已安装 FFmpeg。macOS 可用 brew install ffmpeg，Windows 可用 winget install Gyan.FFmpeg。
  • 已安装 Codex CLI，并能通过 Code Bestie 正常启动。不会配置的话先看 Codex 快速开始指南。

TIP

本文截图中的 HyperFrames 安装和检查命令都在临时 sandbox 目录中执行，避免污染真实项目和全局配置。

一、用 Code Bestie 配置 Codex ​

先确认 Codex 能使用 Code Bestie 的 API Key。

1. 创建 API Key ​

登录 Code Bestie 控制台，进入「API 密钥」，点击「创建密钥」。

创建后复制 API Key。API Key 只会显示完整内容一次，请保存到安全位置。

2. 写入 Codex 配置 ​

在 ~/.codex/config.toml 写入：

toml
model_provider = "codebestie"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.codebestie]
name = "codebestie"
base_url = "https://codebestie.org"
wire_api = "responses"
requires_openai_auth = true

在 ~/.codex/auth.json 写入：

json
{
  "OPENAI_API_KEY": "YOUR_API_KEY"
}

把 YOUR_API_KEY 替换成你在 Code Bestie 控制台创建的 Key。

3. 验证 Codex ​

进入任意项目目录，运行：

bash
codex

如果 Codex 能正常进入对话并读取项目文件，说明 Code Bestie 接入成功。

二、安装 HyperFrames skills ​

HyperFrames 提供了面向 coding agent 的 skills。进入你要制作视频的项目目录后运行：

bash
npx skills add heygen-com/hyperframes

如果希望一次安装仓库里的全部 HyperFrames 相关 skills，可以运行：

bash
npx skills add heygen-com/hyperframes --all

也可以直接让 HyperFrames 初始化项目，它会检测 Codex 并安装对应 skills：

bash
npx hyperframes init codebestie-hyperframes-demo --yes

下面是 sandbox 中的初始化截图。可以看到 HyperFrames 检测到了 codex agent，并把 skills 安装到项目目录。

HyperFrames 初始化并安装 Codex skills

初始化后，项目里通常会出现：

text
AGENTS.md
CLAUDE.md
hyperframes.json
index.html
meta.json
package.json
skills-lock.json
.agents/skills/

其中 index.html 是视频画面入口，.agents/skills/ 是给 Codex 等 coding agent 使用的技能说明。

三、让 Codex 创建视频草稿 ​

在 HyperFrames 项目目录里启动 Codex：

bash
cd codebestie-hyperframes-demo
codex

可以直接把下面这段提示词发给 Codex：

text
请使用项目中的 HyperFrames skills，创建一个 10 秒的 Code Bestie 产品介绍视频。

要求：
1. 使用 HTML/CSS/JS 和 GSAP 动画，不要生成 SVG 插画。
2. 画面比例 16:9，分辨率 1920x1080。
3. 第一幕展示标题：Code Bestie × Codex。
4. 第二幕展示 4 个步骤：创建 API Key、配置 Codex、安装 HyperFrames、渲染视频。
5. 使用 Code Bestie 的绿色系品牌感，但不要整屏单一颜色。
6. 所有带 data-start 或 data-duration 的元素必须加 class="clip"。
7. 完成后运行 npx hyperframes lint，并根据结果修复。
8. 最后运行 npx hyperframes snapshot，生成关键帧截图供我检查。

重点是第 6 条。HyperFrames 的校验会要求带时间属性的元素加上 class="clip"，否则这些元素可能不按时间轴显示。

四、检查和预览 ​

先检查本机环境：

bash
npx hyperframes doctor

再检查项目：

bash
npx hyperframes lint

生成关键帧：

bash
npx hyperframes snapshot

下面是 sandbox 里的检查结果。Node.js、FFmpeg、Chrome 都通过；Docker 未运行只影响需要 Docker 的云端或容器流程，不影响普通本地预览和渲染。

HyperFrames doctor、lint 和 snapshot 输出

snapshot 会输出多张关键帧和一张 contact sheet，适合让 Codex 或人工快速检查画面是否跑偏。

HyperFrames 关键帧总览

下面是一张第 5 秒画面示例：

HyperFrames 第 5 秒画面示例

如果要打开可交互预览：

bash
npx hyperframes preview

根据终端提示打开本地预览地址，检查动画、字幕、画面节奏和元素位置。

五、渲染视频 ​

确认画面没有问题后，渲染为 MP4：

bash
npx hyperframes render --output demo.mp4

如果需要透明背景素材，可以渲染 WebM：

bash
npx hyperframes render --format webm --output overlay.webm

渲染完成后，可以把视频发给客服、同事或继续交给 Codex 做二次修改。

六、推荐工作流 ​

text
Code Bestie 创建 API Key
→ 配置 Codex
→ 新建 HyperFrames 项目
→ 安装 HyperFrames skills
→ 让 Codex 写 index.html
→ npx hyperframes lint
→ npx hyperframes snapshot
→ 人工检查截图
→ npx hyperframes preview
→ npx hyperframes render --output demo.mp4

常见问题 ​

npx hyperframes doctor 提示 Node.js 版本过低 ​

升级到 Node.js 22+ 后重试。建议安装 LTS 版本。

提示找不到 FFmpeg ​

先安装 FFmpeg，再重新打开终端。

macOS：

bash
brew install ffmpeg

Windows：

powershell
winget install Gyan.FFmpeg

npx skills 找不到命令 ​

先确认 Node.js 和 npm 可用：

bash
node -v
npm -v

如果 npm 可用但 skills 仍不可用，直接使用：

bash
npx skills add heygen-com/hyperframes

hyperframes lint 提示 timed element 没有 class="clip" ​

给所有带 data-start 或 data-duration 的时间轴元素加上 class="clip"。

错误示例：

html
<div id="title" data-start="0" data-duration="5">Hello</div>

正确示例：

html
<div id="title" class="clip" data-start="0" data-duration="5">Hello</div>

Codex 没有使用 HyperFrames skills ​

确认当前目录下存在 .agents/skills/ 和 skills-lock.json。如果没有，重新运行：

bash
npx skills add heygen-com/hyperframes --all

然后在 Codex 提示词里明确写上「请使用项目中的 HyperFrames skills」。

Code Bestie 使用文档

Copyright © 2026 Code Bestie