dramaclaw/dramaclaw · 上手攻略

  • 仓库：dramaclaw/dramaclaw
  • 链接：https://github.com/dramaclaw/dramaclaw
  • 分类：AIGC / 视频生成 / 工业化流水线
  • 作者：spark
  • 更新：2026-08-06

是什么

DramaClaw 是一套"工业级短剧 AIGC 生产线"的社区版（Community Edition / CE），由 dramaclaw 团队自用后开源。它把"小说 → 知识图谱 → 分集/分镜 → 剧本 → 分镜图与首帧 → 配音 → 合成成片"整条链封装在一个 Docker 编排里，强调"一套跑到底、关掉浏览器也能交付成片"，目标是把原本只有大厂才拼得起的短剧工厂搬到个人创作者或独立工作室的本机/小 VPS 上。仓库以 Elastic-2.0 双协议发布，配套 Bilibili/YouTube Trailer 与一组真实成片 demo（动态打斗、3D 动漫混剪等）。

解决什么问题

短剧团队过去要把 ComfyUI / Midjourney / Suno / 各种 TTS / FFmpeg / 字幕工具一个一个粘起来，再人工维护角色一致性、分镜节奏、口型对位和资产复用；脚本断裂、人物走形、风格漂移、计费失控是常态。DramaClaw 把这条流水线固化下来：

  • 身份一致性：角色 / 场景 / 道具统一入库，全剧复用，避免"第三集主角换脸"。
  • 节奏可控：知识图谱 → 分集规划 → Beat 级分镜 → 风格模板，链路每一步都可人工干预并支持 checkpoint 续跑。
  • 计费与重试：长任务进 Task Center，可中止可从断点续做；媒体参数（比例、分辨率、模型私有参数）从 UI 直传网关，不再被中间层吞掉（v1.2.1 的 #235 专门修了这个问题）。
  • 可换底座：默认走官方 RelayClaw 网关（OpenAI 兼容协议），也能切到自带的 NewAPI 自托管网关，模型映射在 UI 里完成，仓库里没有任何"绑死某个模型"的硬耦合。

快速安装

最小硬件：≥ 2 vCPU / 4 GB RAM（模型推理全走网关，本地不算 GPU 账），磁盘几个 GB 装镜像与媒体。无需 Postgres / Redis / Celery。

git clone https://github.com/dramaclaw/dramaclaw.git
cd dramaclaw
cp .env.example .env
# 至少把 PROMPT_EXPORT_PASSWORD 改掉；模型通道在 UI 里填，不在 .env 里
docker compose up -d --build          # 首次构建较慢，跑完后 api:8780 + web:8080
docker compose ps                     # 两个服务都应是 Up

浏览器开 http://localhost:8080 → Settings → Model Configuration → Official Channel → 粘贴在 https://relayclaw.cdnfg.com 拿到的 DC key → 保存即用（无需手动配模型映射）。如果想跑完全本地网关，改用：

docker compose -f docker-compose.selfhosted.yml up -d --build
# 在 Settings → Local NewAPI 初始化并配置上游通道 + 模型映射

核心用法

  1. 建工程并导入小说：在 Web UI 新建项目，上传原始 txt/epub。系统会自动跑"小说解析 → 知识图谱"，v1.2.1 后这个阶段会实时显示阶段、百分比与耗时，不再像卡住（#232）。
  2. 资产库初始化：从图谱里识别角色 / 场景 / 道具，生成角色立绘和场景首图；可上传参考图让 Visual Style 模板抽取风格参数，整剧统一应用。
  3. 分集规划 + Beat 拆分：自动章节切分 + 节奏规划，Beat 走 v1.2.1 修过的统一制作正文来源（#231），跳过改编稿会导致 Beat 与资产规划漂移的历史 bug 已不再复发。
  4. 分镜图与首帧：Beat 驱动出图，再由网格切分 + 图池挑选，产出可逐镜审视的故事板。
  5. 配音合成：emotion-aware TTS，可切多家厂商；最新 #260 给 narrator 配音做了前置守卫，必备声线素材缺失会先报错再跑，避免白烧一轮。
  6. 合成与导出：把分镜 + 配音 + 字幕组装成片，导出 MP4 + SRT + 完整资产包。
  7. Freezone（无限画布）：节点式画布，可把主链产物拽进来二次生成图像 / 视频 / 音频，满意的素材"提升"回主线。主线 + 画布探索双轨运行。
  8. Director World / 3GS：把场景空间结构、角色走位、机位锁住，跨镜头维持同一空间一致。
  9. Xia Director（AI 助理）：对话式推进剧本与分镜任务；v1.2.1 中 #216 把它入口临时下线，避免用户进入尚未完成的功能。

最小可跑命令（"建库 → 起服务 → 跑一个 Beat → 看产物"，以 docker compose 为例）：

git clone https://github.com/dramaclaw/dramaclaw.git && cd dramaclaw
cp .env.example .env
docker compose up -d --build                # 首次较慢
curl -sf http://localhost:8780/healthz || echo "api not ready"
# 浏览器 http://localhost:8080 粘 DC key → 新建项目 → 导入小说 → 运行 Beat
# 产物路径：容器内 /data/output，本机由 ce-data 卷持久化

典型适用场景

  • 短剧/竖屏剧工作室：从网文/原创剧本直接出片，需要稳定的角色一致性与可重入的长流水线。
  • 电商素材批量生产：同一条产品线、多镜头多版本，Freezone 画布适合 A/B 出图。
  • 互动乙女/视觉小说：同一世界观的角色库 + 场景库做剧情分支。
  • 广告/口播短视频：分镜节奏 + TTS + 一键合成，比拼装 ComfyUI + 配音脚本快一档。

坑与注意

  • 必须外联网关：CE 默认走 RelayClaw 或自带的 NewAPI，纯离线（断网）模式不存在；想完全本地推理要换底层模型分发而不是改 DramaClaw。
  • DC key 是计费凭据：在 relayclaw.cdnfg.com 购买/申请，配错或余额不足时 v1.2.1 会给出更清晰的"积分不足"提示，但仍可能跑一半才报错。
  • 媒体参数一定要走 UI：早期版本在 NewAPI 视频通道会丢比例/分辨率/私有参数，v1.2.1 (#235) 修了，但升级前的老 channel 配置仍可能命中旧行为，建议清掉重建。
  • 参考音频有硬上限：2026-08-06 #262 暴露了一个真实坑——doubao-seedance-2-0（Seedance 2.0 系列）的参考音频单条 1.8–15.2 s，总和 ≤ 15.2 s；前端和后端各有一道守卫（前端按 <audio> 时长，后端用 ffprobe 兜底），ffprobe 测不出的条目按"不参与求和"处理（漏算只会让总和偏小，"算出来超了"必真超）。配错或组合 6+6+3.2 这种顶格会被本地拦下，别去把目录里的 referenceAudioTotalMaxSeconds 调到 60——那只是把本地的闸门关掉，厂商那边照样 400 还白扣费。
  • 历史剧本需要标准场景标题才能规划场景；v1.2.1 (#230) 放宽了，但极老格式仍可能要求手工补标题。
  • Xia Director 是"暂未完成"：入口已下线，别在自动化里依赖它。
  • Beat 图谱工具链有变动：#234 移除了未使用的旧工具，行为未变，但自定义插件要重新对一遍调用面。
  • 数据卷名为 ce-data：备份/迁移只搬这个卷即可，不要直接拷 settings.db 到不同大版本上。
  • 本机硬件条件（升级复现性声明）：本次攻略基于仓库 main 分支、v1.2.1 发布版（changelog），commit efb2066e47f7e8ec9b0ebeba97e203495842951c（2026-08-06 HEAD），未在本地真实跑通全链路；命令按官方 quickstart / self-hosting 文档复述，升级前请以 release 页和 docs/en/getting-started/quickstart.md 为准。

与同类对比

维度 dramaclaw/dramaclaw ComfyUI + 散件拼装 Pika / Runway / 可灵等闭源 SaaS
定位 工业化流水线 CE 节点工作流 单点视频生成
角色一致性 内置资产库 + Director World 全靠 prompt 与 LoRA 难跨镜头维持
长剧本承接 知识图谱 + Beat 自己维护 JSON 仅短片段
模型可换底 OpenAI 兼容网关 + UI 映射 完全自由 锁定自家模型
自托管门槛 极低（2 vCPU / 4 GB，Docker 一键） 中（要 GPU / 调依赖） 不可自托管
可商用 Elastic-2.0（双协议） 看各节点 license 看各家 ToS
当前最大短板 关键功能（Xia Director）尚未完成；必须外联网关 流水线工程自研成本高 数据出域 + 计费不可控

一句话推荐结论

短剧/口播/电商等"剧情节奏 + 角色一致性"是命门的团队，把 DramaClaw CE 当作"可自托管的工业化底盘"引入，省下的是把 ComfyUI/TTS/FFmpeg 粘一年的工程债；只要能接受"模型走外部网关"这个前提，它是目前少有的把整条链交付到位的开源方案。

原始 commit/PR 链接 + commit SHA： - 仓库 HEAD：https://github.com/dramaclaw/dramaclaw/commit/efb2066e47f7e8ec9b0ebeba97e203495842951c（efb2066e） - 最新 v1.2.1 release：https://github.com/dramaclaw/dramaclaw/releases/tag/v1.2.1 - 最近关键 PR：https://github.com/dramaclaw/dramaclaw/pull/262（音频时长守卫，2026-08-06）、https://github.com/dramaclaw/dramaclaw/pull/260（narrator 配音守卫）、https://github.com/dramaclaw/dramaclaw/pull/235（媒体参数丢失修复）、https://github.com/dramaclaw/dramaclaw/pull/232（导入进度展示）