Toonflow 使用教程-cmzhiku

项目简介

Toonflow 是北京爱阿科技开源的 AI 短剧、漫剧和短视频创作工具，GitHub 约两万星、三千六百次 fork，协议是 MIT。它把剧本、分镜、角色、场景和视频镜头放在同一张无限画布上，而不是让你在对话框里一条一条碰运气。

画布上有文本、图片和视频节点。你可以先写故事和镜头，再出角色与场景图，然后把参考图连到每个镜头上出视频。模型自己接：第三方接口、本地 ComfyUI 或语言模型都可以。另外还有 3D 导演台，用来预演站位和机位。界面支持 21 种语言。

它自带 MCP 和一份给外部 Agent 用的 skill。Codex 连上之后，可以读当前画布、写分镜、触发生成。窗口要开着，画布上的改动才会落到你正在看的那一页。

📎 相关链接与下载地址（点击展开）

核心亮点

🖼️ 无限画布

剧本、角色、分镜和视频片段在同一张画布上连线。哪一镜不满意，只重出这一镜。

🤖 Codex 能接管

打开 MCP，导出 skill，Codex 用一句话读写画布、排分镜、触发生成。

🔌 模型自己接

第三方视频和图片接口、本地 ComfyUI、语言模型都能配。分辨率和时长以你接的模型为准。

🏠 跑在自己机器上

Windows、Mac、Android、Docker 和 Linux 服务器都能装。项目和素材留在你自己的目录里。

它能做什么、输出什么

项目	说明
输入	故事大纲、人物设定、镜头描述，以及你导入或生成的角色、场景、道具参考图
适用类型	短剧、漫剧、短视频。都市、古风、悬疑、甜宠都能做，风格取决于提示词和所选模型
输出	分镜文本、角色与场景图、按镜头生成的视频片段。素材可在画布里预览后下载
语言 / 兼容	界面 21 种语言。MCP 走本机 HTTP，Codex 等支持 MCP 的工具都能接
规格 / 容量	单张画布读取有分页和体积上限。视频时长、分辨率、是否带声音，以当前节点里选的模型为准

环境要求

环境	建议配置
操作系统	Windows 桌面版、macOS（Apple Silicon）、Android ARM64。服务器用 Ubuntu / Debian
运行环境	桌面版直接装。源码和 Docker 使用 Bun 1.4.3。MCP 的 stdio 桥需要 Node.js 20 或更新版本，也可用 Bun
硬件	软件本身不要求独立显卡。画面生成走你接入的模型。若自己用 ComfyUI 在本机出图出视频，再按那个工作流准备显卡
低配方案	只装桌面客户端，模型走在线接口，本机不跑大模型。手机 Android ARM64 版也能独立运行，或扫码连到电脑上的后端
关键依赖	桌面版安装包自带运行所需组件，Windows 会尝试安装 WebView2。Docker 镜像里含 FFmpeg。源码部署需自行安装 Git、FFmpeg 和指定版本的 Bun

如何使用

💡 最快的路径：下桌面客户端，在设置里接好视频模型，打开 MCP，把配置和 skill 交给 Codex，然后直接说要拍的故事。

步骤 1

安装桌面客户端

在 GitHub 搜索 Toonflow-app，进入 Releases 页面，按系统下载安装包。Windows 安装器会检测 WebView2，装完若闪退，再去安装 WebView2 运行时。Mac 把应用拖进「应用程序」后打开；若提示无法验证开发者，到「系统设置 → 隐私与安全性」里点「仍要打开」。

步骤 2

用 Docker 或服务器跑（可选）

不想用桌面版时，先在 GitHub 搜索 Toonflow-app 并克隆仓库。Docker 在仓库根目录执行：

bash

docker compose up -d --build

首次构建会装依赖并编译内置节点。数据在命名卷里，不要执行带删除卷的关闭命令，否则项目文件会一起没。

bash

docker compose logs -f toonflow
docker compose stop
docker compose start

直接在 Linux 上跑时，先装 Git、curl、unzip、FFmpeg 和 Bun 1.4.3，再在仓库根目录：

bash

bun install --frozen-lockfile
bun run build:server
mkdir -p data/workspaces/myProject
bun run start:server

看到「服务启动成功」后，用本机 3000 端口打开页面。这个端口没有登录鉴权，放到公网前要用防火墙或带认证的反向代理挡住。

步骤 3

接上模型，在画布上做一集

打开项目，进入工作区。在设置里配好语言模型、图片模型和视频模型。然后按这个顺序做：

步骤	做什么
写剧本和分镜	文本节点里整理故事、人物和每一镜的描述，让语言模型起草，你再改
出角色和场景	导入参考图，或用图片节点生成角色、场景、道具。角色可以先出三视图
逐镜出视频	把文本和参考图连到视频节点，选模型和时长，一镜一镜生成
预览和下载	在画布里看结果。某一镜不对，只重出这一镜，不要整集推倒

官方记录过一个案例：大约两小时做出约两分钟成片，视频用 Seedance 2.0，图片用 GPT Image 2，语言用 Claude Opus 4.6。换成你自己的模型，时长和画质都会不一样。

步骤 4

打开 MCP

Toonflow 保持打开。进入「设置 → MCP」，打开开关。默认只监听本机，首选端口 10588，被占用会自动往后顺延。地址变了，就从这一页重新复制配置。

点「复制 HTTP 配置」。里面已经带上当前地址和访问凭证，整段贴进 Codex 的 MCP 配置，不要自己改凭证。再点「导出 Skill」，把得到的 toonflow 目录放进 Codex 的 skills 目录。只连 MCP、不放 skill 也能调用工具，但 skill 写了操作顺序，建议一起放。

⚠️ 凭证等于这台机器上画布的钥匙。只交给你自己的 Codex，不要发到群里。关掉开关或更换凭证，正在进行的操作会取消。

步骤 5

结合 Codex 使用

画布开着，在 Codex 里直接说人话，例如：

提示词

把这个故事做成漫剧，角色先出三视图

它应先调用 getAppState，确认连的是哪一个窗口、哪一块画布，再写分镜和提示词、触发生成。返回「已开始」只表示任务提交了，要等节点里的生成状态变成完成，才算这镜出好了。开了多个 Toonflow 窗口时，用连接编号指定要改的那一个。

✅ 说完一句，分镜、角色图和每一镜的视频都落在你眼前这块画布上，不用在网页里来回复制提示词。

典型应用场景

📖 小说改漫剧

把一章拆成若干镜头，角色先固定三视图，再逐镜出视频。

🏙️ 都市短剧

逆袭、甜宠这类连续剧情，同一套角色图贯穿每一镜。

🏯 古风玄幻

人物和场景分开出图，复杂站位先在 3D 导演台里摆机位。

🔍 悬疑推理

线索镜头和人物反应分开生成，不对的一镜单独重出。

🎨 换画风试稿

同一分镜换图片模型或提示词，在画布上并排比较。

🤝 交给 Codex 打草稿

你定故事和角色，分镜和第一版镜头让 Codex 在画布上铺开，你再改。

和直接出视频有什么不同

对比	说明
对话框一次出一条	提示词和参考图每次重贴，角色容易漂。Toonflow 把参考图连在节点上，每一镜沿用同一套角色
只出成片、不管过程	这里留下剧本、分镜、角色图和镜头，后面改某一镜不用从头再讲一遍故事
绑定一家模型	视频、图片、语言模型都在设置里换。软件不负责生成本身，生成质量取决于你接的模型
体量	公开仓库约两万星。技术栈是 TypeScript、Vue 3、Bun 1.4.3，桌面端用 Electrobun