OpenMontage 的 Windows 手动安装串，以及那条 `ERR_INVALID_ARG_TYPE` 的已知问题

OpenMontage 的 Quick Start 在 README 里只有三行：git clone、cd OpenMontage、make setup。这三行在 macOS 和多数 Linux 发行版上是顺的，到了 Windows 就断在第三行——大部分 Windows 开发机上并没有 make。

好在 README 自己也想到了这一点，紧跟着给了一段「No make?」的替代路径，而且 macOS/Linux 和 Windows PowerShell 分成两条串分别写。这篇只干一件事：把 Windows 那条串拆开讲清楚，再把 README 单独用一行记下来的那条已知问题——npm install 报 ERR_INVALID_ARG_TYPE——按排查的顺序走一遍。

先说清底线：下面所有命令都照抄自仓库 README，我们没有在任何机器上执行过，也没有跑过 make setup、没有渲染过任何一条视频。这篇能给你的是「这串命令每一段在动什么、报错时该看哪里」，不是「我装成功了所以你也会成功」。

装之前先确认四项前置

README 的 Prerequisites 只有四项，但第四项最容易被跳过：

• Python 3.10+
• FFmpeg（README 给的获取方式是 brew install ffmpeg、sudo apt install ffmpeg，或去 ffmpeg.org）
• Node.js 18+
• 一个 AI 编码助手：Claude Code、Cursor、Copilot、Windsurf 或 Codex

第四项不是「建议」，是前置条件。README 对 make setup 之后的描述是：在 AI 编码助手里打开这个项目，然后用自然语言说你要什么，比如 "Make a 60-second animated explainer about how neural networks learn"。也就是说，你把依赖装完，手上还得有一个能读文件、能跑代码的编码助手，这套东西才有人开动。README 给的兼容平台各自有配置文件：Claude Code 对 CLAUDE.md，Cursor 对 CURSOR.md 加 .cursor/rules/，GitHub Copilot 对 COPILOT.md 加 .github/copilot-instructions.md，Codex 对 CODEX.md，Windsurf 对 .windsurfrules，全部指向共享的 AGENT_GUIDE.md 与 PROJECT_CONTEXT.md。

前三项里，FFmpeg 和 Node.js 都不在后面那串命令里安装，得你自己先备好。这一点值得强调：手动串里没有任何一条负责装 FFmpeg 或 Node，它们属于 Prerequisites 那一节，README 把安装方式留给了你自己（FFmpeg 那三个获取渠道就写在 Prerequisites 里，Node 连获取方式都没给，只标了版本下限 18+）。

Windows PowerShell 那条串，逐段看

README 原文给的两条串是这样的。macOS/Linux：

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

Windows PowerShell：

py -3 -m venv .venv; .\.venv\Scripts\Activate.ps1; python -m pip install -r requirements.txt; cd remotion-composer; npm install; cd ..; python -m pip install piper-tts; Copy-Item .env.example .env

两条串做的事一一对应，写法上有几处不能混：创建虚拟环境用 py -3 -m venv .venv 而不是 python3；激活用 .\.venv\Scripts\Activate.ps1 而不是 source .venv/bin/activate；复制示例配置用 Copy-Item 而不是 cp。

还有一处差别是连接符：macOS/Linux 那条用 &&，Windows 那条用 ;。在 PowerShell 里分号只是语句分隔，前一条失败了后面几条照样会执行——这是 PowerShell 本身的行为，不是 OpenMontage 文档写的内容，README 也没有对此做任何说明。实际后果是：如果你把整串一次性粘进去，中间某一步炸了，屏幕会继续滚过后面几条，最后一屏看到的可能是 Copy-Item 成功了，很容易误以为全装好了。所以在 Windows 上，我更建议把它按分号断成八条分别执行，每条看一眼输出再走下一条。

八段各自在做什么：

段	命令	在动什么
1	py -3 -m venv .venv	在项目根建虚拟环境目录 .venv
2	.\.venv\Scripts\Activate.ps1	激活它
3	python -m pip install -r requirements.txt	装 Python 侧依赖
4	cd remotion-composer	进入 React/Remotion 合成目录
5	npm install	装该目录的 Node 依赖（已知问题就出在这一步）
6	cd ..	回到项目根
7	python -m pip install piper-tts	装 Piper TTS
8	Copy-Item .env.example .env	由示例文件生成 .env

第 5 段和第 7 段值得单独说两句，因为它们直接对应 README 「What You Get With Zero API Keys」那张能力表里的两行：Piper TTS 对应 Narration（免费离线的文字转语音），Remotion 对应 Composition (React)（基于 React 的渲染）。也就是说，手动串里显式装的这两样，正是零密钥路径要用到的东西——串没跑完，那条「不用任何付费密钥也能出片」的路径就是残的。那张能力表还有开放素材、HyperFrames、FFmpeg 后期、内置字幕等几行，本批另有一篇专门逐行拆，这里不重复。

第 8 段生成的 .env，README 的原话是 every key is optional，示例里每个密钥都写成 your-key 占位符。你不填，按 README 的说法零密钥路径照样成立。真要填，请只写到本机 .env 里，别把它提交进仓库、别贴进聊天窗口；这句是通用运维常识，不是 OpenMontage 文档的内容。

值得先扫一眼这个文件里的字段名，因为它们决定了你后面往哪儿填。README 的 .env 示例按用途分了几组，字段名是写死的：图片/视频网关那组是 FAL_KEY 与 ATLASCLOUD_API_KEY；Kling 官方直连是 KLING_API_KEY，另有一个 KLING_API_BASE_URL，示例里留空并注明是可选、默认走新加坡端点；免费素材那组是 PEXELS_API_KEY、PIXABAY_API_KEY、UNSPLASH_ACCESS_KEY；音乐是 SUNO_API_KEY；语音与图像那组包含 ELEVENLABS_API_KEY、OPENAI_API_KEY、XAI_API_KEY、GOOGLE_API_KEY；视频侧还有 HEYGEN_API_KEY 与 RUNWAY_API_KEY。名字对不上就是没生效，别自己按印象改写成别的拼法。

另外有一处 Windows 上要提前想清楚的：README 折叠了一段「有 GPU 时的本地视频生成」，给的开关是往 .env 里加两行 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——又是一个 make 目标。你正因为没有 make 才走的手动串，这条对你同样不可直接用。这两个字段和那五个取值是 README 原文写死的，具体每个模型要多少显存、能不能在你的卡上跑，README 没给，我们也没跑过，不做任何推断。

ERR_INVALID_ARG_TYPE：README 单独记的那条

现象。 README 用一行单独记了 Windows 的已知问题，原文是：如果 npm install 失败并报 ERR_INVALID_ARG_TYPE，改用 npx --yes npm install。

怎么确认是这个问题。 三个可核查的判定点，缺一个就别往下套：

1. 报错发生的位置是第 5 段，也就是你已经 cd remotion-composer 之后的 npm install，不是根目录里的任何命令；
2. 报错文本里确实出现 ERR_INVALID_ARG_TYPE 这个串，不是「npm 装不上」的笼统印象；
3. 你当前工作目录确实在 remotion-composer——分号串的坑就在这里，如果第 4 段的 cd 没成功，第 5 段是在项目根跑的 npm install，那是另一回事。

处置。 README 给的替代只有一条，原样照抄，不要自己加参数：

npx --yes npm install

README 只写了现象和这条替代命令，没有写原因。为什么会撞上这个错、跟哪个 Node 版本或哪个包有关，仓库文档没有交代，我们也不推断——这类推断一旦写下去就是编造。

处置后怎么验证。 README 没有给这一步的专门验证方法，能拿来当自检的有两处，都不需要 API 密钥。一是回到项目根把剩下两段补完（cd ..、python -m pip install piper-tts、Copy-Item .env.example .env），二是跑 README 给的契约测试：

make test-contracts   # 契约测试，不需要 API 密钥
make test             # 全部测试

make test-contracts 这条在 Windows 上同样需要 make——如果你正是因为没有 make 才走的手动串，这条自然也用不了。那就退回 README 「给 agent 的最短上手路径」里那两条查能力边界的命令，它们是纯 Python，不依赖 make：

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))"

以上命令均照抄自仓库文档，我们没有运行过，实际输出以你本地跑出来的为准。

什么情况说明不是这个原因。 如果你的报错文本里根本没有 ERR_INVALID_ARG_TYPE，那 README 这条已知问题对你不适用，npx --yes npm install 也不该被当成万能替换往上套。同样，如果失败发生在第 3 段的 pip install -r requirements.txt、第 1 段的 venv 创建，或者第 8 段的 Copy-Item，那都是另外的问题——README 只为第 5 段这一个现象留了这一条处置，别越界使用。

装完之后，别对着屏幕等界面

手动串跑完，你手上是一个装好依赖的项目目录，不是一个能点开的软件。README 对下一步的描述始终是：在 AI 编码助手里打开这个项目，用自然语言说需求。走真实素材路线的示例 prompt 长这样：

"Make a 75-second documentary montage about city life in the rain. Use real footage only, no narration, elegiac tone, with music."

README 里确实提到一块叫 Backlot 的本地看板，说 agent 会在制作启动时自动为你打开它，还提供了几张截图。我们没有运行过它，所以这里不描述它长什么样、好不好用——只如实说明 README 里有这么一块东西。

还有两件事得在动手前就摆进预期。一是本地 LLM：README 明写通过 Ollama 和 LM Studio 支持本地 LLM 是 “Coming soon”，那是计划不是现有能力，别按「装完就能全离线跑」来规划。二是成本：README 给几段演示视频和几档示例 prompt 标了金额（例如两档区间标的是 ~$0.15–$1.50 与 ~$1–$3），这些都是项目方在 README 中自行标注的数字，不是我们验证过的报价，也不能拿来推算你自己做一条要花多少钱。

最后补一句和安装无关但装之前该知道的：这个仓库的许可是 AGPL-3.0，和常见的 MIT、Apache-2.0 不是一类。我们没有读过 LICENSE 正文，这里只指路，不做任何解读。

---

本文依据 OpenMontage 官方仓库（github.com/calesthio/OpenMontage）的 README、 AGENT_GUIDE.md、config.yaml、pipeline_defs/ 与 lib/ 下的治理模块整理，核对日 2026-08-09。 本文内容为仓库源码与文档口径，我们没有安装或运行过该系统，也没有调用过其中任何一个 provider API， 文中出现的成本数字均为项目方在 README 中自行标注的金额，非我们的实测结果。 该项目以 AGPL-3.0 发布，部分流水线在 manifest 中自标 stability: beta，请以仓库最新内容为准。 许可条款请以官方 LICENSE 原文为准，本文不构成法律意见。 安全相关做法请结合自身环境评估，本文不构成安全方案建议。