OpenMontage 使用教程：把 AI 编程助手变成视频制作流水线

OpenMontage 不是“一句话返回一个视频文件”的在线生成器，而是一套由 AI 编程助手驱动的本地视频生产流水线。它会在项目目录中完成研究、方案、脚本、分镜、素材选择、配音、合成和质检，因此安装成功的判断不能只看依赖是否装完，还要确认工具注册表、Provider 能力和最终媒体文件都可验证。

项目地址：calesthio/OpenMontage

快速结论

最低准备项是 Python 3.10+、Node.js 18+、FFmpeg 和一个能读取文件并执行命令的 AI 编程助手。
make setup 是 macOS/Linux 的最短路径；Windows 应使用独立虚拟环境和 PowerShell 安装命令。
没有付费 API Key 也能使用 Piper、开放档案素材和 Remotion/HyperFrames，但实际可用能力必须通过工具注册表确认。
第一次不要直接做长视频。先运行零 Key 示例或 15 至 30 秒测试片段，再检查输出文件、时长、音轨和日志。

安装前先做环境检查

不要等 make setup 中途失败后才查版本。先运行：

1
2
3
4
5


python3 --version
node --version
npm --version
ffmpeg -version
git --version

Python 应不低于 3.10，Node.js 应不低于 18。只要 ffmpeg -version 无法执行，后续编码、字幕烧录或音频混合就不可能完整通过。

macOS 和 Ubuntu 可以分别安装 FFmpeg：

1
2
3


brew install ffmpeg
sudo apt update
sudo apt install ffmpeg

macOS 或 Linux 安装

官方快速开始如下：

1
2
3


git clone https://github.com/calesthio/OpenMontage.git
cd OpenMontage
make setup

没有 make 时，使用虚拟环境执行手动安装，避免把依赖写进系统 Python：

1
2
3
4
5
6
7
8


python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cd remotion-composer
npm install
cd ..
python -m pip install piper-tts
cp .env.example .env

安装结束后重新打开终端时，需要再次执行 source .venv/bin/activate。

Windows PowerShell 安装

Windows 不要直接照抄 Bash 的 source 和 cp：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


git clone https://github.com/calesthio/OpenMontage.git
Set-Location OpenMontage
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
Set-Location remotion-composer
npm install
Set-Location ..
python -m pip install piper-tts
Copy-Item .env.example .env

若 npm install 返回 ERR_INVALID_ARG_TYPE，官方 README 给出的替代命令是：

1

npx --yes npm install

如果 PowerShell 拒绝激活脚本，先确认是执行策略问题，而不是反复重建环境。也可以不激活，直接用 .\.venv\Scripts\python.exe 执行后续 Python 命令。

用注册表验证实际能力

文件安装完成不代表视频工具都已发现。在仓库根目录、虚拟环境已激活的情况下运行：

1
2


python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.support_envelope(), indent=2))"
python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.provider_menu(), indent=2))"

第一条用于确认当前机器能够支持哪些生产能力，第二条显示可以选择的 Provider。命令非零退出、Python 导入失败或返回空能力时，都不应继续让 Agent 制作完整视频。

从零 Key 示例开始

OpenMontage 官方提供 make demo 作为低成本渲染入口：

1

make demo

也可以让 Codex、Claude Code 或 Cursor 在已打开的仓库中执行一个范围明确的任务：

1

Make a 30-second animated explainer about why the sky is blue, with narration and captions. Use only tools available without paid API keys.

验收时不要只看 Agent 的总结。先定位新生成的 MP4，再用 FFprobe 检查媒体流：

1
2


find . -type f -name "*.mp4" -print
ffprobe -v error -show_entries format=duration:stream=codec_type,codec_name -of json PATH_TO_OUTPUT.mp4

合格结果至少应包含非零时长的视频流；要求配音时还应有音频流。只有项目文件、没有最终 MP4，说明流水线未完成。

配置 Provider，但不要一次打开全部 Key

复制 .env.example 后，只加入本轮测试需要的服务：

1
2
3
4
5
6


PEXELS_API_KEY=your-key
PIXABAY_API_KEY=your-key
UNSPLASH_ACCESS_KEY=your-key
ELEVENLABS_API_KEY=your-key
OPENAI_API_KEY=your-key
FAL_KEY=your-key

先验证免费素材或单个 Provider，再逐个增加能力。把所有 Key 同时写入后才开始测试，会让 401、429、额度不足和模型不可用混在一起。.env 不应提交到 Git；提交前运行 git status --short，确认它没有进入暂存范围。

本地 NVIDIA GPU 路径需要额外安装：

1

make install-gpu

然后再启用对应模型：

1
2


VIDEO_GEN_LOCAL_ENABLED=true
VIDEO_GEN_LOCAL_MODEL=wan2.1-1.3b

本地生成失败时先检查 CUDA、显存和模型下载，不要把“Python 可以导入”误判成“GPU 推理可用”。

从参考视频发起任务

参考视频更适合用于约束节奏、结构和镜头语言，而不是复制原内容：

1

Analyze this reference video and propose three original 45-second variants about quantum computing. Keep the pacing pattern, but do not reuse its script or assets. Show estimated tool choices and cost before generation.

在素材生成前检查 proposal、预计费用和 render_runtime。数据驱动解说通常更适合 Remotion，偏 HTML/CSS 动效的内容可能走 HyperFrames；真正使用哪条路径，应以项目记录为准。

常见失败怎么判断

现象	先检查	判断标准
`ModuleNotFoundError`	当前 Python 路径和虚拟环境	`python -c "import sys; print(sys.executable)"` 应指向 `.venv`
`ffmpeg` 找不到	PATH 与 FFmpeg 安装	新终端中 `ffmpeg -version` 仍能成功
Remotion 安装失败	Node/npm 版本、`remotion-composer/node_modules`	`npm install` 必须零退出，不能只看到部分包下载
Provider 请求失败	对应环境变量、额度和 Provider 日志	区分 401、429、超时与模型不存在，不要连续更换多个 Key
有画面无声音	TTS 产物、音轨和 FFprobe 输出	MP4 中应出现预期音频流
Agent 声称完成但没有成片	项目输出目录和最终质检步骤	必须找到可播放 MP4 并通过 FFprobe

恢复到可工作的安装状态

依赖环境损坏时，不要直接覆盖整个仓库。先保留现场并确认代码是否被 Agent 改动：

1
2
3


git status --short
git rev-parse --short HEAD
python -c "import sys; print(sys.executable)"

可以把旧虚拟环境改名为 .venv-broken，再按安装步骤创建新的 .venv；这样仍可对比旧环境。前端依赖问题应只在 remotion-composer 内重装，不要同时更换 Python、Node、FFmpeg 和 Provider。

如果新 Provider 或 GPU 配置导致失败，先从 .env 移除刚加入的那一项，重新运行能力注册表和零 Key 示例。恢复标准不是“错误消失”，而是同一个短片样本重新生成，并通过 FFprobe 检查。

最终验收清单

Python、Node、FFmpeg 在新终端中都能读取版本。
两条工具注册表命令零退出，并显示符合预期的能力和 Provider。
一个 15 至 30 秒测试任务生成了可播放 MP4。
FFprobe 显示非零时长以及预期的视频、音频流。
.env 和生成素材没有误入 Git。
已实际演练移除新增 Provider 后回到零 Key 或上一可用配置。

OpenMontage 适合愿意检查中间产物和成本的流水线实验，不适合在没有验收记录时直接承担商用批量生产。先把一个短样本做成可重复基线，再增加视频长度、Provider 和本地 GPU，排错成本会低很多。