OpenMontage 是世界上第一个开源的 Agentic 视频生产系统 。它不是又一个文生视频工具，而是一套完整的工作流编排框架——能把你的 AI 编程助手（Cursor、Claude Code、Copilot 等）变成一个全功能的视频制作工作室。系统内置 12 条生产流水线、100+ 工具、700+ Agent 技能文件，支持从调研、脚本、分镜、素材生成到剪辑合成的全流程自动化 。

零 API Key 也能出片：使用本地 Piper TTS 语音合成 + 免费图库素材，即可生成带配音和解说的视频 。如果你愿意配置云 API（可选），60 秒 Pixar 风格动画的制作成本可以低至 $1.33 。

一、部署前环境检查

OpenMontage 的部署方式和普通 Python 项目不同——它不是一个“一键启动”的服务，而是安装到你的 AI 编程助手中的“技能包”。建议先做好环境检查，避免 make setup 中途失败 。

1.1 硬件与系统要求

组件 最低要求 推荐配置
CPU 4 核 16 核
内存 16 GB 64 GB
存储 20 GB 可用空间 50 GB+ SSD
GPU（可选） — NVIDIA T4 / RTX 3060 以上

虽然 OpenMontage 可以在无 GPU 的机器上运行，但如果想启用免费的本地视频生成（WAN、Hunyuan、CogVideo 等模型），则需要一张性能良好的 NVIDIA GPU 。

1.2 软件依赖清单

在开始之前，请确认以下三件套已正确安装 ：

1
2
3
4
5
6
# 检查版本
python3 --version    # 需要 3.10+
node --version       # 需要 18+
npm --version        # 随 Node.js 安装
ffmpeg -version      # 核心视频处理工具
git --version        # 克隆仓库用

安装 FFmpeg（按系统选择）

1
2
3
4
5
6
7
8
9
10
# macOS（使用 Homebrew）
brew install ffmpeg

# Ubuntu / Debian
sudo apt update
sudo apt install ffmpeg

# Windows
# 从 ffmpeg.org/download.html 下载，解压后将 bin 目录添加到系统 PATH
# 或使用 winget: winget install Gyan.FFmpeg

注意：如果 ffmpeg -version 命令无法执行，后续所有视频编码、字幕烧录、音频混合操作都会失败 。

1.3 AI 编程助手

OpenMontage 本身不包含大模型，需要一个 AI 编程助手来充当“导演”角色 。支持以下平台：

  • Claude Code（推荐，指令支持最完善）
  • Cursor
  • GitHub Copilot
  • Codex
  • Windsurf

你只需要用这些工具打开 OpenMontage 项目目录，然后在对话中描述你想要制作的视频即可 。

二、安装 OpenMontage

2.1 克隆仓库

1
2
git clone https://github.com/calesthio/OpenMontage.git
cd OpenMontage

2.2 一键初始化（推荐）

在 macOS 或 Linux 上，直接运行官方提供的 make setup 命令，它会自动完成所有配置 ：

1
make setup

make setup 会自动完成以下工作 ：

  1. 创建 Python 虚拟环境 .venv
  2. 安装所有 Python 依赖 (requirements.txt)
  3. 安装 Node.js 依赖（Remotion 渲染引擎）
  4. 配置 Piper TTS（免费本地语音合成）
  5. 预热 HyperFrames 渲染缓存
  6. 从 .env.example 创建 .env 配置文件

2.3 手动安装（无 make 或 Windows）

如果没有 make 命令，或在 Windows 上遇到问题，可以手动分步安装 。

macOS / Linux（无 make）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 创建并激活虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 安装 Python 依赖
python -m pip install -r requirements.txt

# 安装 Remotion 渲染引擎
cd remotion-composer
npm install
cd ..

# 安装 Piper TTS（本地语音）
python -m pip install piper-tts

# 创建配置文件
cp .env.example .env

Windows PowerShell

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 进入项目目录
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 ..

# 复制配置文件
Copy-Item .env.example .env

Windows 常见问题：如果 npm install 报错 ERR_INVALID_ARG_TYPE，请改用 npx --yes npm install 。如果 PowerShell 拒绝执行脚本，先检查执行策略，或直接用 .\.venv\Scripts\python.exe 执行 Python 命令 。

2.4 验证安装：预检（Preflight）

安装完成后，建议先运行预检，确认工具注册表和 Provider 能力已正确发现 ：

1
2
# 使用 make 预检（推荐）
make preflight

或者手动执行 Python 命令：

1
2
3
4
5
# 查看当前机器支持的所有能力
python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.support_envelope(), indent=2))"

# 查看可用的 Provider 菜单
python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.provider_menu(), indent=2))"

预检输出会显示 18 个能力家族（图像生成、视频生成、配音、音乐、素材获取、后期合成等），每个能力下列出可用和不可用的工具 。命令返回空能力或 Python 导入失败时，不应继续制作视频 。

2.5 可选：预热 HyperFrames 渲染缓存

1
2
make hyperframes-doctor
make hyperframes-warm

这些命令会验证 HyperFrames 运行时可用性，并将 hyperframes npm 包拉取到本地 npx 缓存，避免首次渲染时等待 30-60 秒的冷启动 。

三、配置 API Key（可选）

OpenMontage 采用 “零 API Key 也能跑” 的设计——所有提供商都是可选的，不填则自动降级到免费替代 。编辑项目根目录的 .env 文件，按需添加密钥：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# .env —— 所有 Key 都是可选的

# === 视频生成（选一个或多个） ===
FAL_KEY=your-fal-key               # FLUX 图像 + Google Veo / Kling / MiniMax 视频
RUNWAY_API_KEY=your-key            # Runway Gen-4 视频
GOOGLE_API_KEY=your-key            # Google Imagen 图像 + Google TTS
OPENAI_API_KEY=your-key            # OpenAI TTS + GPT Image 2
ATLASCLOUD_API_KEY=your-key        # Atlas Cloud 统一网关

# === 免费图库（强烈推荐，申请简单） ===
PEXELS_API_KEY=your-key            # 免费申请: pexels.com/api
PIXABAY_API_KEY=your-key           # 免费申请: pixabay.com/api/docs
UNSPLASH_ACCESS_KEY=your-key       # 免费申请: unsplash.com/developers

# === 高质量语音 ===
ELEVENLABS_API_KEY=your-key        # 顶级音质 TTS
GOOGLE_API_KEY=your-key            # 700+ 声音，50+ 语言

# === 音乐生成 ===
SUNO_API_KEY=your-key              # AI 音乐生成

3.1 零 API Key 时的免费工具链

能力 免费工具 说明
配音 Piper TTS 完全离线，本地运行
素材 Archive.org / NASA / Wikimedia Commons 免费开放档案
素材 Pexels / Pixabay / Unsplash 需免费申请开发者 Key
渲染 Remotion / HyperFrames 本地 React 渲染引擎
后期 FFmpeg 编码、字幕烧录、音频混合

零 API Key 适合制作纪录片蒙太奇、播客视频化、讲解类内容——无法使用 AI 生成的独创画面，素材全部来自图库和档案库 。

3.2 预算控制（重要）

1
2
3
4
# 可选：在 .env 或 config.yaml 中配置
OPENMONTAGE_BUDGET_CAP=10.00           # 总预算上限（美元），默认 $10
OPENMONTAGE_CONFIRM_THRESHOLD=0.50     # 单次操作超过 $0.50 需确认
OPENMONTAGE_BUDGET_MODE=cap            # observe / warn / cap

系统会在执行前估算成本，超过阈值时暂停请求确认，避免产生意外账单 。

四、第一个视频：快速测试

4.1 运行官方演示

1
make demo

这个命令会渲染一个零 API Key 的示例视频，用于验证渲染链路是否正常工作 。

4.2 在 AI 编程助手中发起任务

这是 OpenMontage 的核心交互方式——在 AI 编程助手中打开项目目录，直接用自然语言描述需求 。

零 API Key 示例（免费路径）

在 AI 助手的对话中输入：

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

或更短的测试任务：

“Make a 30-second animated explainer about why the sky is blue.”

真实素材纪录片路径（无需付费视频 API）

“Make a 90-second documentary montage about what a city feels like at 4am. Use real footage only, no narration, elegiac tone, with music.”

从参考视频开始

“Here’s a YouTube short I love. Make me something like this, but about CRISPR for high school students.”

4.3 验收输出

生成完成后，不要只看 Agent 的总结。建议用以下方法验收成品 ：

1
2
3
4
5
# 找到生成的 MP4 文件
find . -type f -name "*.mp4" -print

# 用 ffprobe 检查视频流
ffprobe -v error -show_entries format=duration:stream=codec_type,width,height -of default=noprint_wrappers=1 <生成的视频文件路径>

首次测试建议从 15-30 秒的短任务开始，而不是直接做长视频，方便快速排查问题 。

五、进阶配置：开启本地 GPU 生成

如果你的机器有 NVIDIA GPU，可以安装本地视频生成模型，实现 完全免费、离线的视频片段生成 ：

1
make install-gpu

然后在 .env 中添加：

1
2
VIDEO_GEN_LOCAL_ENABLED=true
VIDEO_GEN_LOCAL_MODEL=wan2.1-1.3b   # 或 wan2.1-14b, hunyuan-1.5, ltx2-local, cogvideo-5b

make install-gpu 会安装 PyTorch、diffusers 等本地推理依赖。之后运行 make preflight，确认 video_generation 能力下出现了本地模型 。

六、常见问题排查

问题现象 可能原因 解决方案
make setup 失败 依赖版本不匹配 检查 Python ≥3.10、Node ≥18、FFmpeg 已安装
ModuleNotFoundError 虚拟环境未激活 运行 source .venv/bin/activate（macOS/Linux）或 .venv\Scripts\Activate.ps1（Windows）
视频合成失败或黑屏 FFmpeg 未安装或路径错误 运行 ffmpeg -version 确认；Windows 检查 PATH 配置
Windows 上 npm install 报错 Node.js 版本或权限问题 使用 npx --yes npm install 替代
生成的视频只有图片轮播 未配置视频生成 API，或未明确要求“真实素材” 添加 API Key，或改用纪录片蒙太奇提示词
预检返回空能力 工具注册表扫描失败 检查 tools/ 目录是否完整，重新运行 registry.discover()

七、总结

OpenMontage 的部署路径可以概括为：

  1. 检查依赖：Python 3.10+、Node 18+、FFmpeg
  2. 克隆与初始化：git clone → make setup（或手动安装）
  3. 预检验证：make preflight 确认能力已发现
  4. 配置 API Key（可选）：按需添加 .env
  5. 开始创作：在 AI 编程助手中用自然语言描述需求

整个流程大约需要 15-30 分钟（取决于网络和硬件）。如果你是开发者或内容创作者，愿意花一点时间配置，这个项目能为你提供比任何商业视频工具都更灵活、可定制且开源免费的自动化视频生产能力 。

项目地址：https://github.com/calesthio/OpenMontage