Toonflow 快速入门：在无限画布上做 AI 短剧与漫剧

这是什么？适合谁？

Toonflow 是一个面向短剧、漫剧与短视频制作的开源 AI 创作平台，上游仓库 HBAI-Ltd/Toonflow-app，官网 toonflow.net，采用 MIT 许可，主体语言 TypeScript，版权方是北京爱阿科技有限公司（README 页脚 2026）。

它和「一个文生视频网页」的区别在组织方式：它把剧本、角色、场景、分镜、图片、视频片段全部放进同一张无限画布上，用节点连起来。所以它的产出不是一段孤立视频，而是一条可编辑的链路——改剧本、换角色参考图、重生成某个镜头，其他节点不动。官方把这条链路写成四步：在文本节点里写剧本与分镜 → 导入参考图或用图片节点生成角色与场景 → 连接文本与参考图、选视频模型生成分镜片段 → 在画布上预览整理后下载。

官方 README 列出的能力面：本地部署（项目与素材留在自己设备或服务器）、无限画布、MCP 连外部工具、插件市场、开放 Agent（开放提示词、工具与 A2A，支持外部协作）、自由接入模型（第三方 API 或本地 ComfyUI 与 LLM）、21 种界面语言。

适合谁：要连续做多集短剧、需要统一角色与场景一致性的个人创作者和小工作室；已经有一堆素材、想把它们组织成可复用流程的人；愿意自备模型 API（或本地显卡）来控制成本与数据的人；要在内网部署的团队。

不适合谁：只想「输入一句话、三十秒出一个片子」的人——Toonflow 不替你写剧本也不替你选模型，它给的是工作台；没有可用模型 API 也没有本地显卡的人（装完是空的，生成不了东西）；不愿碰端口与防火墙的人（它默认的服务端口没有鉴权，见下文）。

核验日期：2026-11-13。本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。

前置准备

• 先选形态。Toonflow 有两条完全不同的落地路径：客户端（Windows / macOS / Linux / Android 安装包，开箱即用）和 服务端（Docker 或裸机 Bun，浏览器访问）。个人创作选客户端；多人共用、要长期挂着跑、或要接内网选服务端。
• 系统门槛：macOS 需要 14 及以上（arm64 与 x64 两种安装包）；Windows 安装器会自动装 WebView2，ARM64 机器还需要 .NET Framework 4.8.1（较新的 Windows 11 已内置）；Linux 提供 Debian / Ubuntu 的 .deb；Android 只支持 ARM64。
• 模型与算力。这是最容易被忽略的前置：Toonflow 本身不提供模型。你要么准备第三方模型服务的 API（语言模型 + 图像模型 + 视频模型，视你要做的镜头而定），要么准备本地 ComfyUI 与本地 LLM 的运行环境与显存。官方 FAQ 明确写「第三方模型服务的 API 调用可能收费；使用本地模型或 ComfyUI 时，需要自行准备相应的运行环境与算力」。
• 服务端额外要求：Docker 路径需要 Git、Docker Engine、Docker Compose（Windows / macOS 用 Docker Desktop 的 Linux 容器模式）；裸机路径需要 Ubuntu / Debian、git、curl、unzip、ffmpeg，以及项目指定的 Bun 1.4.3。
• 磁盘与网络：Docker 镜像内含 FFmpeg；Linux .deb 安装时需要联网，apt 会准备 FFmpeg、curl、unzip、CA 证书等依赖，安装脚本会下载固定版本的 Bun 并校验大小与 SHA-256，下载或校验失败会在解包前中止。所以第一次安装别在断网或代理不稳的环境里做。
• 一个工作目录概念：服务端启动后会有 myProject 工作目录；Docker 安装时配置、插件与项目都在命名卷 toonflowData 里，挂到容器的 /app/data/；裸机安装则在仓库的 data/ 下。迁移或备份必须完整保留这个目录。

安装与启用

路径 A：客户端（最省事，推荐先走这条）

到发布页按你的设备下载对应的安装包：https://github.com/HBAI-Ltd/Toonflow-app/releases。当前最新正式版是 v2.0.10（2026-11-05 发布，非预发布）。

Linux 安装：

cd ~/Downloads
sudo apt install ./toonflow-2.0.10-linux-x64.deb

装完从应用菜单打开。macOS 打开 DMG 后把 toonflow.app 拖进「应用程序」，再从「应用程序」启动。如果是 Intel Mac 且之前装过旧版，必须下载完整 DMG 覆盖安装，不能用旧版的增量更新直接迁移；升级前退出应用并备份原数据目录。

Android 版手机内置本地 Bun 后端，可以独立跑；也可以在首页「设备互联」里扫码或手动连到已开启共享的电脑或远程后端（支持局域网与公网）。

路径 B：Docker（多人共用 / 长期运行）

git clone https://github.com/HBAI-Ltd/Toonflow-app.git
cd Toonflow-app
docker compose up -d --build

首次构建会安装依赖并编译内置节点、工具、Web 与 Server，基于 Bun 1.4.3，镜像内含 FFmpeg。启动后访问 http://127.0.0.1:3000。首次启动会初始化内置插件，并提供 myProject 工作目录。

日常运维命令：

docker compose logs -f toonflow   # 看日志
docker compose stop               # 停止，保留容器
docker compose start              # 再启动
docker compose down               # 删容器，保留数据卷

绝对不要用 docker compose down -v——-v 会把 toonflowData 数据卷一起删掉，配置、插件和项目全在里面。

备份要在停机状态下做：

docker compose stop
docker compose cp toonflow:/app/data ./toonflowBackup
docker compose start

要加项目目录，可以在页面「选择服务器工作目录」弹窗里新建文件夹（也支持重命名、删除），或者：

docker compose exec toonflow mkdir -p /app/data/workspaces/newProject

路径 C：服务器裸机（Ubuntu / Debian）

sudo apt-get update
sudo apt-get install -y git curl unzip ffmpeg
curl -fsSL https://bun.com/install | bash -s "bun-v1.4.3"
export PATH="$HOME/.bun/bin:$PATH"
bun --version

git clone https://github.com/HBAI-Ltd/Toonflow-app.git
cd Toonflow-app
bun install --frozen-lockfile

# 构建内置节点、工具、Web 与 Server
bun run build:server
mkdir -p data/workspaces/myProject
bun run start:server

看到「服务启动成功」后在服务器本机访问 http://127.0.0.1:3000。上面是前台运行、Ctrl+C 停止；要开机自启就用 Bun 官方的 systemd 指南，工作目录设为仓库目录，启动命令设为 Bun 绝对路径加 run start:server，运行用户要有该目录的读写权限。

服务端的关键一步：把 3000 端口关起来

官方 README 写得很直接：当前服务使用固定端口 3000，业务页面与 API 没有独立登录鉴权。 所以：

• 裸机或 Docker 跑在公网服务器上时，必须用防火墙或安全组限制 3000 端口的来源；
• 要给外部访问，就在前面加一层带认证的反向代理；
• 个人远程使用最省事的做法是 SSH 隧道，完全不对外开放：

ssh -N -L 3000:127.0.0.1:3000 用户名@服务器地址
# 保持连接，然后本地浏览器打开 http://127.0.0.1:3000

第一个完整任务：从一句设定到一个能看的分镜

目标不是做出成片，而是验证整条链路通：剧本节点能写、图片节点能出图、视频节点能出片段、画布上能播放。这是判断「装对了没有」的最短路径。

1. 打开工作区。 客户端启动后直接选工作目录；服务端进页面后选服务器工作区里的 myProject（想换项目就在对应的 workspaces/ 下建子目录）。

2. 配对模型。 在设置里填入你要用的模型服务：语言模型（写剧本、拆分镜）、图像模型（角色与场景）、视频模型（分镜片段）。如果你走本地路线，这里改成接 ComfyUI 与本地 LLM。先只配一个语言模型和一个图像模型，把链路跑通再加视频，排障会简单一个数量级。

3. 建一个文本节点，写最小的剧本。 不要一次写十集。写清三样东西就够：一个角色（外貌与服装的固定描述）、一个场景、一个 5 秒内能演完的动作。比如「雨夜的便利店门口，穿黄色雨衣的女孩把伞收起来，抬头看了一眼招牌」。角色的外观描述要逐字复用到后面每个镜头，这是保持一致性最有效的手段。

4. 建图片节点，用同一段角色描述生成角色定妆图。 出图后挑一张满意的，把它作为参考图接到后续节点——之后每个镜头都挂这张参考图，而不是重新描述一遍。

5. 建视频节点，连上文本与参考图。 选择视频模型与生成模式，按单个镜头生成。官方提醒：支持的参考素材、视频时长、分辨率和音频能力取决于所选模型与供应商——所以这一步报错先怀疑模型能力，不是软件坏了。

6. 在画布上预览与整理，然后下载素材。 画布的价值在这里体现：所有镜头并排摆着，哪条不连贯一眼能看出来，单独重生成那一条即可。

预期结果与成功判据：

• 画布上至少有一个文本节点、一张角色定妆图、一段 3–5 秒的视频片段，且视频内容与参考图里的角色外观一致；
• 下载下来的素材是可直接播放的文件，不是工程文件；
• 关掉再打开，画布和素材都还在（服务端在 data/ 或 toonflowData 卷里，客户端在本机数据目录）。

这一步常见的「失败但正常」：视频时长被截短、没有音频、参考图不生效——这三样都写在官方的「取决于所选模型与供应商」里。换一个支持对应能力的模型再试，比调参快。

初级用法

1）把「角色设定」做成一段可复用的固定文本

新手最容易犯的错是每个镜头重新描述角色，结果十集十个长相。正确做法是在画布里留一个设定节点，写死角色的外观、服装、体型、年龄感，然后每个镜头都从它连参考图。改设定时只改这一处，画布上所有下游节点重跑即可。这条习惯比任何模型选择都更影响成片质量。

2）分清「文本节点」与「分镜」的职责

文本节点里同时写故事、人物小传和镜头描述，很快就会失控。建议分两层：一层写故事与人物（不进图），一层写镜头（要进图，必须只有画面信息，把「她心里很难过」改写成「她低头，肩膀轻微颤动」）。图像与视频模型只吃后者。

3）用插件市场补齐节点，而不是自己写脚本

官方插件市场在 https://api.toonflow.net/console/plugIn，用来扩展节点、工具与创作能力。先看里面有没有你需要的（比如特定的图像处理、拼接、字幕类节点），没有再去碰自定义开发。客户端与服务端都能装，插件文件和项目一起存在数据目录里，备份时一起走。

4）先在画布上做「一镜到底」再谈多镜头

一个镜头从设定到出片完整跑通，再复制成三个镜头。多镜头一致性问题的排查成本，是单镜头的数倍；把单镜头做到稳定（同一角色、同一风格、同一色调），再横向复制，返工量最小。

高级玩法

1）MCP：把外部工具接进创作流

官方支持通过 MCP 连接外部工具与服务。实际价值在于把「画布之外的动作」拉进来——比如把生成好的片段交给外部的转码、拼接、字幕流水线，或者从外部素材库里取参考图，而不需要人工下载再上传。注意：MCP 服务端的安全边界要你自己把关，接第三方 MCP 等于把它的能力暴露给这个工作台。

2）开放 Agent 与 A2A：让流程自己往下走

README 写明它开放提示词、工具和 A2A，支持自定义 Agent 行为与外部协作。也就是说你可以定义「读剧本 → 拆分镜 → 逐镜头生成 → 检查一致性」这样的 Agent 行为，而不是手点每个节点。这是从「工具」走向「流水线」的那一步，也是它和普通画布产品的分界。前提是先把单镜头流程跑稳，否则自动化只会更快地生产废片。

3）接本地 ComfyUI 与你自己的 LLM

官方支持通过自定义供应商适配接入已有的 ComfyUI 工作流，以及本地 LLM。这条路的好处是数据不出机器、边际成本只有电费；代价是你要自己维护 ComfyUI 的工作流兼容性——模型、节点、自定义插件任何一处升级都可能让旧工作流失效。稳妥做法是给 ComfyUI 单独锁一个环境，别和日常实验共用。

4）Android 端做「远程监看与控制」而不是主力生产

Android 客户端内置本地 Bun 后端可以独立跑，也能通过「设备互联」连到已开启共享的电脑或远程后端（支持局域网与公网）。实用姿势是：手机上只看进度、挑素材、给反馈，重活留在电脑或服务器上。手机端跑视频生成不现实，但用它当遥控器很顺手。

5）Docker 部署下把「数据」与「镜像」彻底分开

把 toonflowData 卷当成唯一真相来源：升级镜像只重建容器，数据不动；备份就是 docker compose cp 那一条命令。配合 docker compose down（不带 -v）做版本回滚，你可以在几分钟内切回上一版而不丢任何项目。

小技巧

1. 第一次装先走客户端，不要一上来就 Docker。 客户端能让你在十分钟内确认「这个工作台合不合我的流程」，避免把时间花在构建和端口上。确定要长期用之后再迁服务端，项目目录可以直接搬。
2. 装 Linux .deb 时保持网络稳定。 安装脚本要下载固定版本的 Bun 并校验 SHA-256，校验失败会在解包前中止——所以「装到一半失败」通常不是包坏了，是网络断在下载阶段，重跑即可。
3. Windows 装完闪退，先补 WebView2。 官方给出的第一条处置就是去微软的 WebView2 下载页手动装运行时，因为安装器的自动检测可能漏掉。
4. macOS 提示「无法验证开发者」时按官方三步走：先在「系统设置 → 隐私与安全性」里点「仍要打开」；仍不行再对确认来源可信的 app 执行 sudo xattr -rd com.apple.quarantine /Applications/toonflow.app；sudo spctl --master-disable 是最后手段，而且会放宽所有 App 的限制，用完记得改回来。
5. 升级前先备份数据目录。 服务端备份一条命令（见上文），客户端就手动复制它的数据目录。README 明确要求在迁移 Intel Mac 客户端前退出应用并备份原数据目录，这条对所有平台都适用。
6. 把 myProject 当成「一部剧」而不是「一个文件」。 一部剧一个工作区目录，素材、参考图、生成的片段都在里面，交付时整目录打包，比零散下载可靠。

进阶学习路径

1. README 的「亮点」与「如何用 Toonflow 制作 AI 短剧与漫剧」两节 —— 四步流程的官方版本，先按它走一遍再改。
2. README 的「下载并安装」全节 —— 五平台客户端、Docker、服务器三条路径的完整参数与排障折叠块，含 macOS 安全提示、WebView2、.NET 版本这些具体条件。
3. 官方使用教程（飞书文档） —— https://qcn7xdsqgc4z.feishu.cn/docx/RXFqdgR2Xo0dXZxGfd0cZCGgnwf，节点操作的图文步骤。
4. 开发者文档（飞书文档） —— https://qcn7xdsqgc4z.feishu.cn/docx/KNBNd9naqolsy6xjAOCcEAkqnRd，自定义供应商、插件与 Agent 的接口约定。
5. 插件市场 —— https://api.toonflow.net/console/plugIn，看别人怎么扩节点，比从零设计快。
6. GitHub Releases 与 Issues —— https://github.com/HBAI-Ltd/Toonflow-app/releases，每次发版的更新说明是你判断「要不要升级」的唯一依据；issue 区能查到别人踩过的模型兼容性问题。
7. 样例作品的案例信息 —— README 第 5 节列了作品示例与案例信息，看一个成片是怎么拆节点的，比看功能列表有用。

踩坑记录

症状：Windows 装完打开就闪退。 原因：安装器自动检测 WebView2 失败，或系统缺少运行时。 解决：去 https://developer.microsoft.com/microsoft-edge/webview2/ 手动安装 WebView2 运行时，再启动。

症状：Linux 安装到一半中止，提示下载或校验失败。 原因：安装脚本要在解包应用前下载固定版本的 Bun 并校验大小与 SHA-256，网络中断或代理改写会导致校验不过。 解决：确认网络与代理稳定后重跑 sudo apt install ./安装包文件名.deb；不要跳过校验，那是官方刻意设的闸。

症状：docker compose 跑完，打开页面一片空白或连不上。 原因：首次构建要编译内置节点、工具、Web 与 Server，比较慢；或者容器还在构建中就被访问了。 解决：先 docker compose logs -f toonflow 看构建/启动进度，等出现启动成功再访问 http://127.0.0.1:3000。

症状：数据全没了，项目、插件、配置一起消失。 原因：执行了 docker compose down -v，-v 删除了 toonflowData 数据卷。 解决：数据卷删了就恢复不了，只能从备份重建。正确命令是 docker compose down（不带 -v），并且升级前先 docker compose cp toonflow:/app/data ./toonflowBackup。

症状：公网上能直接打开 3000 端口，没有任何登录。 原因：服务端固定用 3000，且业务页面与 API 没有独立登录鉴权。 解决：立刻用防火墙或安全组限制来源，公网访问必须在前面加带认证的反向代理；个人远程改用 SSH 隧道而不是开放端口。

症状：视频生成报错说时长、分辨率或参考图不支持。 原因：这些能力取决于所选模型与供应商，不是所有模型都支持参考图、长时长或音频。 解决：换一个官方文档里写明支持该能力的模型；先做一个 3–5 秒的无参考图版本确认基础链路，再逐步加能力。

症状：Intel Mac 从旧版升级后打不开，或数据读不出来。 原因：官方说明旧版 Intel Mac 客户端首次迁移必须下载完整 DMG 覆盖安装，不能走旧版增量更新。 解决：退出应用、备份原数据目录，下载完整 macos-x64.dmg 覆盖安装，再从「应用程序」启动。

常见问题

Q：Toonflow 是免费的吗？模型调用要另外付钱吗？ A：软件本身 MIT 开源，可自行部署，不收费。模型调用是另一笔账：第三方模型服务的 API 调用可能收费，用本地模型或 ComfyUI 则要自备运行环境与算力。官方还特别说明：README 里作品示例标注的制作费用只代表那个案例，不是固定价格。

Q：它的许可到底是什么？我搜到过 AGPL 和 Apache 的说法。 A：当前是 MIT（仓库 LICENSE 与 GitHub API 的 license 字段一致）。README 有一段「不追溯条款」解释了历史：v1.0.8 发布前基于 AGPL-3.0 使用的用户继续按 AGPL-3.0 执行，v1.0.8 到 v1.1.8 按 Apache-2.0 与附加协议执行，不受本次协议变更约束。也就是说老版本用户的权利不会被新许可收回，新用户按 MIT 走。

Q：我的数据存在哪里？会不会上传到厂商服务器？ A：客户端存在本机；Docker 安装存在命名卷 toonflowData（挂到容器 /app/data/）；裸机安装存在仓库的 data/ 目录。但「自托管」不等于「数据完全不出网」：你配置的第三方模型服务会收到你提交的提示词与参考图，这是模型推理的必然结果。要彻底不出网，就得走本地 ComfyUI 与本地 LLM 那条路。

Q：能不能不装客户端，直接在服务器上跑、用浏览器访问？ A：可以，Docker 与裸机 Bun 两条路径都是浏览器访问。但要记住官方的前提：固定端口 3000、页面与 API 没有独立登录鉴权。所以要么只在内网，要么套一层带认证的反向代理，要么用 SSH 隧道。

Q：支持接入我自己的模型和 ComfyUI 工作流吗？ A：可以配置语言模型与媒体模型服务，也可以通过自定义供应商适配接入已有的 ComfyUI 工作流。具体接入方式取决于服务 API、模型与工作流本身。代价是兼容性要你自己维护——ComfyUI 侧的模型或自定义节点升级，可能让旧工作流失效。

Q：支持中文吗？ A：支持，界面共 21 种语言，包括简体中文、繁體中文、English、日本語、Русский、Tiếng Việt、ไทย、한국어、हिन्दी、Bahasa Indonesia、Bahasa Melayu、Filipino、বাংলা、اردو、தமிழ்、తెలుగు、मराठी、ਪੰਜਾਬੀ、العربية、فارسی、Türkçe。

Q：项目成熟度怎么样？ A：上游数据（GitHub API，2026-11-13 读数）：21,566 stars / 3,895 forks / 5 个开放 issue，仓库创建于 2026-01-29，最近一次 push 是 2026-11-05，未归档，MIT，TypeScript；最新正式版 v2.0.10 发布于 2026-11-05。近一年的持续发版、五个平台的原生安装包和 Apple 公证流程，说明它不是玩具项目；但开放 issue 数少也可能只是因为 issue 被引导到了微信群或飞书，不能拿来当质量证据。

权限、隐私、成本与平台限制

权限：客户端是本地应用，权限就是你的用户权限，能读写它自己的数据目录。服务端以启动它的用户身份运行，能读写 data/（或数据卷），没有内置的角色与权限体系——谁能访问 3000 端口，谁就拥有完整操作权。这是它当前最大的安全边界，必须靠网络层补齐。

隐私：项目文件、素材与插件默认留在你自己的存储上。但生成请求会发给你配置的模型供应商，图与视频都会离开本机；具体留存与使用条款由该供应商决定，需要逐家核对。Android 端的「设备互联」支持公网连接，开之前先想清楚谁能连。

成本：软件免费（MIT）。真实成本是模型调用：第三方 API 按 token 或按次计费，视频模型通常是最贵的一环；本地路线是硬件与电费。官方没有在 README 里给出任何「一部剧大约多少钱」的固定数字，作品示例里的费用只对该案例成立——任何把它当报价的说法都不要信。

平台限制：macOS 需要 14+；Android 仅 ARM64；Windows ARM64 需要 .NET Framework 4.8.1；服务端固定端口 3000 且无鉴权；视频的参考素材、时长、分辨率、音频能力取决于所选模型；云平台部署只有官方授权的合作镜像（智星云）一条公开路径。

成熟度边界：MagicNetWorld 没有安装运行 Toonflow，没有做过多集短剧的端到端制作，也没有测过任何模型的成片质量、一致性与生成耗时。上文所有功能描述来自官方 README 与 GitHub 元数据，属于文档级证据。

参考链接

• 代码仓库与 README（亮点、四步流程、五平台安装、Docker、服务器、许可）：https://github.com/HBAI-Ltd/Toonflow-app
• 官网：https://toonflow.net
• 发布页（v2.0.10 及历史版本的全部安装包）：https://github.com/HBAI-Ltd/Toonflow-app/releases
• GitHub REST API 元数据（stars / forks / 开放 issue / 创建与推送时间 / 许可）：https://api.github.com/repos/HBAI-Ltd/Toonflow-app
• 最新正式版元数据（v2.0.10，2026-11-05）：https://api.github.com/repos/HBAI-Ltd/Toonflow-app/releases/latest
• 官方使用教程（飞书）：https://qcn7xdsqgc4z.feishu.cn/docx/RXFqdgR2Xo0dXZxGfd0cZCGgnwf
• 开发者文档（飞书）：https://qcn7xdsqgc4z.feishu.cn/docx/KNBNd9naqolsy6xjAOCcEAkqnRd
• 插件市场：https://api.toonflow.net/console/plugIn
• WebView2 运行时下载（Windows 闪退时的第一处置）：https://developer.microsoft.com/microsoft-edge/webview2/
• Bun 1.4.3 安装说明与 systemd 部署指南：https://bun.sh/docs/installation