HITsz-TMG/VideoClaw · 上手攻略

• 仓库：HITsz-TMG/VideoClaw
• 链接：https://github.com/HITsz-TMG/VideoClaw
• 分类：ai-video / generative-ai / agent-workflow
• 作者：Tom
• 更新：2026-08-11

它是什么

HITsz-TMG/VideoClaw 是一个面向创意视频生产的 AI 导演系统，来自哈尔滨工业大学（深圳）TMG 实验室。它不是单点式的文生视频工具，而是一条覆盖"剧本策划 → 角色/场景设计 → 分镜规划 → 参考图生成 → 视频生成 → 后期剪辑"的全流程生产线。

用户只需给出一句想法或故事梗概，VideoClaw 就会自动拆解为可执行的影视工作流，生成完整的视频成片。与普通文生视频工具的黑盒输出不同，VideoClaw 在每个阶段都支持可视化查看、人工修改和继续生成，形成真正的"AI 导演协作"体验。

该系统与 OpenClaw 深度集成，支持通过对话触发"生成 X 的视频"，同时支持 WebUI、微信、飞书等多端协作。VideoClaw 的设计理念受 FilmAgent（SIGGRAPH Asia 2024）和 Anim-Director（SIGGRAPH Asia 2024/2025）系列论文启发，是学术研究走向工程化落地的案例。

解决什么问题

当前 AIGC 视频工具的核心问题是"单点生成"——用户给一句 Prompt，工具返回一个视频，无法对角色一致性、叙事结构、画面风格做精细控制，也无法在中间环节干预。

VideoClaw 解决的核心问题：

1. 角色一致性：通过第二阶段"角色/场景设计"统一生成参考原画，后续视频生成都基于这些参考，确保同一角色在不同镜头中外观一致。
2. 叙事可控：分镜规划阶段将剧本拆解为具体镜头视角、动作描述，每个分镜都有明确的视觉基准。
3. 全流程可干预：任何阶段不满意都可以回退修改，不必从头重试。
4. 批量轻量任务：除了主流程，还支持解说短视频、动作迁移、数字人口播三类一次性任务，适合快速批量化内容生产。
5. 多端协作：支持 WebUI、微信、飞书，适合团队协作和甲方确认流程。

快速安装

环境要求

• Python ≥ 3.9
• Node.js ≥ 18
• npm ≥ 9
• ffmpeg（系统级，需预装）

Linux / macOS 安装

# 1. 克隆项目
git clone https://github.com/HITsz-TMG/VideoClaw.git
cd VideoClaw

# 2. 进入应用目录执行安装脚本
cd video-claw/video-claw
chmod +x install.sh
./install.sh

# 3. 返回项目根目录
cd ../..

# 4. 配置 API Key（编辑配置文件）
#    编辑 backend/config.yaml，填入各平台 API Key
#    或启动后在前端 WebUI 设置页面配置

# 5. 启动后端
cd video-claw/video-claw/backend
uv run python api_server.py
# 后端默认 http://localhost:8000

# 6. 新终端启动前端
cd video-claw/video-claw/frontend
npm start
# 前端默认 http://localhost:3000

Windows 安装

git clone https://github.com/HITsz-TMG/VideoClaw.git
cd VideoClaw
cd video-claw\video-claw
install.bat
cd ../..

Docker 方式（需自己编写 Dockerfile，仓库未提供 docker-compose）

仓库 ./docker 目录下有 Docker 参考配置，可参考该目录内容自行构建。

OpenClaw Skill 集成安装（推荐）

若本地已安装 OpenClaw 和 clawhub-cli：

# 打开终端，所有询问选 yes
clawhub install video-claw

安装完成后，用 OpenClaw 对话触发：

帮我克隆git仓库：https://github.com/HITsz-TMG/VideoClaw.git
然后把Video-Claw中的video-claw文件夹递归复制到.openclaw/workspace/skills目录下

使用时：

用video-claw来生成一个视频，内容是"一条狗的使命"

⚠️ 模型 API Key 必须配置：VideoClaw 本身不包含视频生成模型，需在 backend/config.yaml 或前端「设置」页面配置各平台的 API Key（见下节）。

核心配置与支持的模型

config.yaml 结构

# backend/config.yaml

api_providers:
  openai:
    api_key: your_openai_key
    base_url: https://api.openai.com/v1
  gemini:
    api_key: your_gemini_key
    base_url: https://generativelanguage.googleapis.com/v1beta
  deepseek:
    api_key: your_deepseek_key
    base_url: https://api.deepseek.com/v1
  dashscope:       # 通义千问/Wan图像/视频
    api_key: your_dashscope_key
    base_url: https://dashscope.aliyuncs.com/api/v1
  ark:             # Seedream图像/Seedance视频（火山方舟）
    api_key: your_ark_key
    base_url: https://ark.cn-beijing.volces.com/api/v3
  kling:           # 可灵视频
    access_key: your_kling_access_key
    secret_key: your_kling_secret_key

models:
  llm: qwen3.5-plus
  vlm: qwen3.5-plus
  image_t2i: doubao-seedream-5.0-260128
  image_it2i: doubao-seedream-5.0-260128
  video: wan2.7-i2v
  video_first_frame: wan2.7-i2v
  video_start_end: wan2.7-i2v
  video_reference: wan2.7-r2v

generation:
  style: realistic
  video_ratio: '16:9'
  video_resolution: 720P
  video_generation_mode: first_frame  # 推荐默认：first_frame

⚠️ 配置原则：只需要填写你实际使用的模型对应的平台 Key。例如用 doubao-seedream-* 做图生成，需配置 ark.api_key；用 wan* 做视频生成，需配置 dashscope.api_key。配置错误或不完整时，直接报错而非静默失败。

支持的模型清单（参考）

⚠️ 模型列表时效：模型清单以 video-claw/video-claw/backend/models/config_model.py 为准，前端会按模型能力标签筛选；实际可用模型取决于各平台 API 的当前状态。

主流程六阶段

第五阶段支持三种视频生成方式： - 首帧生视频（推荐）：使用第四阶段首帧参考图 + 分镜提示词生成，推荐优先使用。 - 首尾帧生视频：首帧 + 下一片段尾帧，追求片段间画面衔接。 - 参考图生视频：直接读取第二阶段角色图和场景图作为参考，适合强角色/场景一致性的场景。

典型适用场景

1. 短剧/微短剧自动生成：输入故事梗概，自动生成多集短剧（示例展示了"逆袭之路"8集连续生成 + 续写2集）。
2. 广告/宣传片制作：分镜驱动的参考图生成，确保画面风格和品牌调性一致。
3. 教育视频自动化：输入教材内容，自动生成包含旁白和解说的教学视频。
4. 数字人口播：Pipeline 中的"数字人口播"模式，适合电商和教育场景的批量视频生产。
5. 动作迁移视频：Pipeline 中的"动作迁移"模式，将参考动作迁移到目标角色。
6. AI 导演协作：团队成员通过微信/飞书参与确认流程，甲方可在中间阶段提出修改意见。

坑与注意

1. API Key 全部自备：VideoClaw 本身免费，但视频生成依赖第三方 API（DashScope/Kling/ARK/OpenAI 等），需要用户自己拥有相应平台的账号和额度。
2. 模型依赖第三方服务稳定性：视频生成质量完全取决于所选模型的输出质量；Wan/Doubao-Seedance/Kling 等模型的可用性和速度受制于各自的服务器状态。
3. 安装脚本需要 ffmpeg：Linux/macOS 安装前需确保 ffmpeg 已安装（可用 brew install ffmpeg 或系统包管理器安装），Windows 用户可能需要额外配置 PATH。
4. uv vs pip：推荐使用 uv 作为 Python 包管理器以加速安装，但仓库也支持传统 python -m venv venv && pip install -r requirements.txt 方式。
5. 前端构建耗时：首次安装时 npm build 可能需要几分钟，耐心等待；如需跳过前端构建：AIGC_DIRECTOR_SKIP_FRONTEND_BUILD=1 ./install.sh。
6. Session ID 与 Task ID 混淆：Session ID（毫秒级时间戳）关联主流程上下文数据；Task ID（YYYYMMDD_HHMMSS_Hash）关联 Pipeline 一次性任务元数据，两者存储路径不同，排查问题前先确认是哪种任务。
7. 仓库分支大小写注意：GitHub 上仓库名为 VideoClaw（C大写），但部分文档链接使用 Video-Claw（中间有连字符），clone 时注意大小写匹配；README 中还有 Video-Claw.git 和 VideoClaw.git 两种写法混用的情况，建议用 https://github.com/HITsz-TMG/VideoClaw.git 避免歧义。

与同类对比

核心差异：VideoClaw 的最大优势在于"分镜驱动的可控生成 + 全流程可视化干预"，是当前 AIGC 视频工具中工作流最完整的开源方案之一。它的局限在于完全依赖外部视频生成 API，无法离线运行，且生成质量上限取决于所选模型。

一句话推荐结论

VideoClaw 是目前开源 AIGC 视频工具中工作流最完整的"AI 导演"方案，如果你需要从剧本到成片的全链路可控视频生成，且愿意自备 API Key，它是目前最值得评估的候选——尤其适合短剧、广告和教育视频的批量生产场景；但请确保你有稳定可靠的视频生成模型 API 渠道。

⚠️ 本篇攻略基于 2026-08-11 的仓库 README；视频模型 API 的可用性、模型版本和定价可能随时变化，配置前请以各平台最新文档为准；Session/Task ID 存储结构和 config.yaml 的具体字段以仓库 backend/models/config_model.py 为准。