用Codex CLI与剪映Skill读写草稿JSON，实现口播视频全自动剪辑

做视频的人应该都有这种体验一条口播视频光是把每句话拆开、把废镜头剪掉、字幕一条条对齐、BGM音量压住就能吃掉大半天。更气人的是这套流程做完下一期换个素材又来一遍纯机械劳动。我前阵子试了一条新的生产链路用 Codex CLI 配合一个自制的“剪映Skill”让 AI 直接读写剪映草稿里的时间线 JSON把“逐条剪”变成“生成草稿 人工预览”。这篇文章是这套方案的完整实操记录包括剪映草稿和 Skill 的原理、环境配置、Skill 怎么编写、一条口播视频的全自动生产流程以及我踩过的一些真正卡人的坑。它适合有短视频批量生产需求、又不排斥命令行和 JSON 的创作者——按我的经验只要能跑通一个最小案例后续的边际收益会非常可观。1. 先把原理吃透剪映草稿本质是一份JSONSkill是教Codex说“剪映方言”的词典1.1 剪映草稿不是加密工程包而是一份可读写的“剪辑乐谱”剪映的项目文件并不是什么加密工程包而是一个普通文件夹。每个草稿对应剪映草稿目录下的一个子目录里面装着draft_content.json和draft_meta_info.json素材文件也按类型分类放在旁边。草稿位置可以在剪映的“全局设置-草稿位置”里看到Windows 上通常默认在用户目录下的JianyingPro\User Data\Projects\com.lveditor.draft。draft_content.json里是完整的时间线数据核心是三层结构materials声明所有可用素材视频、音频、文本、贴纸、特效等tracks定义各轨道视频轨、音频轨、字幕轨、文本轨等轨道里的segments数组记录每一段素材从什么时候开始、持续多久、是否做过裁剪。每个 segment 通过material_id指向materials里的具体素材target_timerange决定它在时间线上的位置source_timerange决定它引用素材的哪一段。可以把它想成一份“剪辑乐谱”剪映编辑器只是演奏这份乐谱的乐器乐谱本身是 JSON。只要能按规则生成和修改这份 JSON就等于绕过了界面上所有拖拽、裁剪、对齐操作直接写剪辑结果。这也是那么多开源项目把剪映草稿当成自动化突破口的原因——它不是私有二进制格式结构清晰还能用脚本校验。需要提醒的是不同版本剪映的 draft JSON 字段偶尔会调整轨道类型可能改名时间戳单位也可能变化。所以第一步永远是先手动建一个空草稿打开生成的 JSON 确认当前版本的实际结构再让 Skill 说明对齐这个版本不要拿网上旧教程的字段直接套。1.2 Codex 的 Skill 机制把“剪映方言”教给代码模型Codex CLI 是 OpenAI 的命令行编程代理能根据自然语言指令读写文件、执行命令。它的 Skill 机制有点像给 Agent 装“行业插件”在~/.codex/skills/下建一个目录里面放一个SKILL.md就能通过技能名的方式让 Codex 在任务里加载这套专业知识。SKILL.md 本质上是一份给模型看的行为规范可以包含字段说明、工作流程、约束条件。仓库级的通用约定可以写在AGENTS.md里但跨项目复用的剪映知识更适合放进 Skill。一个 Skill 的价值在于把隐性知识结构化。模型本身并不知道draft_content.json的字段细节SKILL.md 写清楚对象模型、字段含义、操作约束、校验方式之后Codex 就能按这套规则去生成和修改草稿。相比每次在 prompt 里重复粘贴说明Skill 是持久化、可版本化、可团队共享的——这也是“剪映Skill”这个名字的来源。1.3 为什么选择“写JSON”而不是“模拟点击剪映”有人会问为什么不直接让 Codex 控制剪映界面、模拟鼠标拖拽我最早也这么想过但实测下来这条路很难走。剪映的界面层级随版本变动频繁坐标定位脆弱每一步操作都要等界面响应批量处理时又慢又容易出意外一个弹窗挡住按钮整条流程就断了。写 JSON 的路线正好相反。它是确定性的草稿文件结构正确剪映打开后展示的时间线就是确定的它支持批量循环生成几十个草稿改的只是 JSON它可回溯修改前备份一份坏了随时还原。代价是需要理解一点数据结构但这对 Codex 来说恰好是强项——LLM 生成结构化 JSON 的可靠性远高于它们在 GUI 上做精细点击的稳定性。后面的整套方案都是围绕这个判断展开的。2. 环境准备Codex CLI 安装与认证环节的经典关卡2.1 桌面版、CLI版、VS Code扩展怎么选Codex 官方给了几种用法。桌面版有完整界面安装直观适合第一次体验CLI 版通过npm install -g openai/codex安装适合被脚本集成、批量调用也是这篇文章的主角如果你主要在 VS Code 里写脚本可以装 Codex 编辑器扩展它和 CLI 共享登录态和配置目录切换成本很低。CLI 版要求本机有 Node.js 环境建议用 LTS 版本。安装包尽量走官方渠道避免第三方打包版本夹带问题。装完首次运行codex会引导登录配置文件默认在~/.codex/config.toml——从这里开始就是大多数人踩坑的地方。2.2 登录认证的三个高频报错第一个是codex auth token is unavailable。这通常意味着登录状态没写进本地配置或者终端没有读到认证文件。排查思路很直接执行codex login重新走一遍浏览器授权确认返回的 token 已保存如果还报错就去检查~/.codex/下认证文件是否存在、当前终端会话的 HOME 路径是否正确。第二个是登录时的手机号验证问题。验证码收不到或者多次填错多半是浏览器授权流程里的状态同步问题。可以换默认浏览器、清理目标站点缓存后重试或者干脆改用 API Key 方式登录。第三个是模型权限问题报错类似the gpt-5.6-sol model is not supported when using codex with a chatgpt account。这个错的本质是用 ChatGPT 账号登录时Codex 只能使用当前账号套餐支持的模型某些新模型或特定命名模型只面向 API 用户开放。遇到别硬试打开官方文档确认账号类型对应的模型清单在配置里把model改成当前账号确实能用的那个。2.3 接入第三方兼容 APIDeepSeek 的配置思路很多团队不想把生产流程绑定单一模型或者出于成本考虑想接入 DeepSeek 这类兼容 OpenAI 协议的模型 API。Codex 支持在config.toml里声明自定义模型服务商把base_url指向对应服务的 API 地址设置模型名通过环境变量注入 API Key。配置大致长这样# ~/.codex/config.toml 示例字段以当前官方文档为准 [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY model deepseek-chat model_provider deepseek提示模型选型直接决定自动化成败。先用最小样本测试目标模型的 JSON 输出质量再决定是否接入生产流程。注意接入第三方模型后整个 Skill 的质量底线就取决于该模型的指令遵循能力。如果模型连“严格按 JSON 结构输出”都经常做不到那就不适合做草稿生成因为剪映对字段的容错很低一个小数点错位都会导致打开失败。先拿一小段草稿做压力测试确认能稳定输出合格 JSON再全量铺开。3. 剪映Skill的核心设计素材、时间线、校验三层结构3.1 SKILL.md 里到底写什么我的 Skill 放在~/.codex/skills/jianying/目录结构如下~/.codex/skills/jianying/ ├── SKILL.md └── scripts/ ├── preprocess_media.py └── validate_draft.pySKILL.md 不需要很长但每段都必须是能直接指挥行动的内容草稿位置说明剪映草稿目录在哪修改前必须先整体复制一份备份对象模型materials / tracks / segments三层关系素材必须先出现在materials里才能被segment引用常用轨道类型当前剪映版本里视频轨、音频轨、字幕轨、文本轨、贴纸轨的 type 值以及各轨道 segment 的特殊字段时间单位与坐标时间戳使用微秒整数target_timerange与source_timerange的含义和计算规则素材路径规则只允许引用预处理脚本确认存在的文件操作流程备份 → 修改 JSON → 运行validate_draft.py→ 提示用户退出剪映、替换草稿、重新打开预览禁止事项不删除用户未指定的素材不把未经确认的路径写进草稿。写清楚之后Codex 生成草稿时的行为会完全不一样。我试过不加载 Skill 直接让它写剪映草稿结果它经常编造字段名、漏掉素材引用打开剪映直接黑屏加载 Skill 之后结构层的错误出现率大幅下降。3.2 配套脚本ffmpeg 预处理与 JSON 校验器只靠 SKILL.md 还不够我给 Skill 配了两个脚本。第一个是素材预处理脚本。剪映对素材编码格式有兼容性要求冷门编码放进时间线可能无法预览。我的做法是用 ffmpeg 统一转成 H.264 AAC 的 MP4音频统一 44.1kHz视频统一成目标分辨率并按seq_序号_用途.mp4的规则重命名。这样 Codex 生成 JSON 时能直接从文件名判断素材的顺序和用途减少张冠李戴。第二个是 JSON 校验脚本用 Python 实现。它读取草稿的draft_content.json检查三件事所有 segment 引用的material_id是否都存在于materials列表所有素材路径指向的文件是否真实存在每段target_timerange的起止时间是否合理、是否与素材实际时长冲突。校验通过后我才允许 Codex 停止修改、让我打开剪映预览。这一步是整个自动化里最值得投入工程量的地方——与其让 Codex 反复试错不如用脚本把低级错误全部挡在外面。3.3 生成—预览—导出的闭环整个 Skill 的工作流最终固化成一个闭环用户在终端向 Codex 提出需求Codex 读取 SKILL.md调用预处理脚本确认素材状态生成或修改草稿 JSON跑一遍校验脚本通过后提示用户退出剪映、替换草稿、重新打开预览。这里必须强调剪映在运行时会缓存草稿数据直接改文件大概率不生效必须完全退出剪映再替换 JSON。预览这一步目前仍然需要人——画面审美、字幕断句、转场节奏模型还判断不了但工作量已经从“逐条剪辑”降到了“看一眼、不满意就反馈一句让 Codex 改”。批量场景下你可以一次生成多个草稿逐个预览确认效率提升非常明显。4. 一条口播视频的完整自动化实战4.1 输入侧脚本、素材、需求描述拿一条典型的口播知识视频举例。输入侧通常有三样东西一段已录好的主视频比如 8 分钟人物讲话、一份用于穿插的 B-roll 目录5-8 个演示镜头或资料画面、一份字幕文件SRT没有就先语音转写再校对。然后我给 Codex 一个任务描述下面是一个我实际用过的 prompt 示例jianying 请为下面这条口播视频生成剪映草稿 1. 主视频 interview_full.mp4 作为视频轨第一段 2. 使用 subtitles.srt 自动生成字幕轨白字黑边、底部居中、字号约为屏幕宽度 6% 3. B-roll 按文件名顺序依次插入主视频第 2、4、6 分钟处每段 8 秒覆盖主视频原声 4. bgm.mp3 从第 1 秒开始音量 -18dB最后 3 秒淡出 5. 最后 2 秒加文本关注我们淡入淡出。 输出要求先生成完整 draft_content.json运行校验脚本再告诉我如何替换草稿文件。4.2 Codex 的执行链路从需求到可预览的草稿Codex 拿到需求后内部大致走这几步先盘点素材确认文件存在、编码可处理调用预处理脚本统一格式根据主视频时长和 SRT 时间戳生成字幕轨 segment 列表逐条对齐target_timerange为 B-roll 和 BGM 创建对应轨道 segment写入音量与淡入淡出参数把所有素材登记进materials、把 segment 挂到对应轨道最后跑校验输出替换草稿的指令。最能体现“不用逐条剪”的就是字幕轨。以前我在剪映里逐字调整字幕起止时间、对齐口型现在 Codex 直接从 SRT 时间戳生成整段字幕 segment精确到微秒。一条 8 分钟口播的几十个字幕片段一次生成打开剪映就是排好的状态。4.3 预览与迭代人机协作的最后一公里草稿替换成功后我打开剪映先完整播放一遍检查黑屏、字幕错位、素材被误裁。发现问题直接在终端里反馈一句“第 3 条和第 4 条字幕重叠了 0.5 秒改成顺延B-roll 第三段换成文件名含 product_demo 的素材。” Codex 改 JSON校验脚本再查一遍重新打开剪映就是新版。这个反馈循环是整套方案里体验最好的部分以前要回到时间线上一帧帧找问题、拖拽修改现在只要描述现象机器负责执行。一个人可以同时盯着好几条视频迭代剪辑执行被压缩成了“提需求和验收”两个动作。4.4 批量生产同一套 Skill 复制到多集内容口播账号最怕的就是“每集从零开始剪”。用这套方案后我把每集内容整理成统一输入格式素材目录 SRT 需求描述模板再写一个简单的 shell 循环让 Codex 逐条生成草稿每条独立指定输出草稿名避免覆盖。批量模式下模型的上下文互相隔离不会出现内容串味。批量跑的时候我还会让 Codex 在每个草稿目录里写一份generation_report.md记录关键决策哪条字幕自动延长了显示时间、哪个 B-roll 因为素材缺失被跳过、音量参数做过什么调整。这个习惯后来救了我好几次——过了几天回头看能立刻知道某个草稿当时为什么长这样不用对着时间线猜。5. 踩坑清单配置、模型、JSON 结构三类高频问题5.1 配置类配置文件被忽略、切换工具本地服务异常先说codex is ignoring 1 unrecognized configuration setting这类提示。Codex 启动时会解析config.toml遇到不认识的键名会直接忽略“不认识”的配置。这个坑大多来自复制网上的配置片段时键名写错或缩进不对尤其常见于模型服务商和模型名的层级关系。排查用二分法把非必需配置逐行注释保留一份最小可运行配置再逐步加回来很快就能定位到出错的那一行。另一类报错来自 CC Switch 这类配置切换工具。它的作用是后台起一个本地服务帮你快速切换不同 API 提供商的配置避免每次手改 config.toml。报错常见于切换后 Codex 请求端点时报本地服务连接失败。我遇到时第一反应不是去改 Codex 配置而是先重启切换工具的本地服务或者取消当前切换状态、重新选择一次模型服务商。多数情况是切换工具自己的进程没起来或端口被占用不是 Codex 本身的问题。如果 Codex 一直打不开也先检查终端里有没有这类残留服务的报错。5.2 模型类账号与模型不匹配、上下文污染模型权限问题是整个环境准备里最头疼的。前面提的gpt-5.6-sol not supported本质上是账号类型和模型不匹配。建议把使用方式、可用模型范围、用途整理成一张表放在团队文档里使用方式可用模型范围适用场景ChatGPT 账号登录当前账号套餐开放的 Codex 模型日常交互、少量草稿生成API KeyAPI 侧开放的模型可接第三方兼容服务批量生产、脚本集成还有一个容易忽略的坑上下文污染。连续处理多条草稿时如果没做隔离模型可能把上一条的素材路径、字段风格带到下一条。我的处理方式每个草稿一个独立工作目录任务开始前先切到对应目录确保 Skill 只读当前项目的文件。5.3 JSON 结构类版本差异、素材引用、时间戳精度这一块是真正决定“打开剪映能不能正常显示”的硬伤。第一是版本差异。剪映升级后draft_content.json里某些字段会被废弃或改名用旧版说明去生成新版本草稿会打开失败或者时间线错乱。我每次升级剪映都会先手动建一个空白草稿对比新旧 JSON 的字段差异同步更新 SKILL.md。建议把 Skill 目录纳入 Git 管理版本升级后用 diff 快速定位变化点。第二是素材引用错误。segment 里的material_id必须在materials里存在路径必须真实有效。引用一旦漂移剪映就会黑屏或提示素材缺失。校验脚本能挡住九成错误剩下的一成是素材文件还在但路径被移动了这类问题脚本查不出来只能靠预览时人眼发现。第三是时间戳精度。剪映时间轴常用微秒级精度生成 JSON 时如果只精确到秒个别片段会短一两帧造成画面跳动。我在 SKILL.md 里明确规定所有时长字段使用微秒整数并要求 Codex 生成后自检数值位。5.4 节奏控制一次只改一个环节最后这条建议听着简单但我吃过亏才懂不要在同一个任务里让 Codex 同时改字幕、换 B-roll、调色、加贴纸。改动越多出错时越难定位到底是哪一项把草稿搞坏的。把需求拆成小步先搭主时间线预览通过再上字幕预览再上 BGM 和转场预览。每一步都跑一次校验。自动化项目里“小步快跑”不是口号是真能省下大量排查时间的实操纪律。6. 这套方案适合谁以及还能往哪扩展6.1 适合与不适合从我的使用体感看这套方案最适合三类人口播/知识类自媒体视频结构接近、重复劳动多课程制作团队需要批量给录播配上字幕和片头片尾接单剪辑工作室用模板化草稿快速出初版再在剪映里做精细调整省掉大量从零搭建的时间。不太适合的场景我也说清楚靠创意和手感吃饭的艺术向剪辑自动生成草稿反而像一种束缚。它解决的是“编排量大但规则明确”的重复劳动替代不了审美决策。另外如果对 JSON 完全没有概念建议先花半天熟悉剪映草稿结构再上手否则出了问题你很难和 Codex 有效沟通。6.2 几个已经跑通的扩展方向这套方案的可扩展性很强说几个我已经在做的字幕样式模板化在 Skill 里维护一个样式库不同账号用不同字体、字号、描边生成草稿时按账号名自动套用批量出片时字幕风格统一横竖屏衍生横版草稿生成后复制一份让 Codex 按 9:16 重构时间线B-roll 位置和字幕字号同步调整一次出横竖两个版本语音识别粗剪把录音或直播切片转写成带重点标记的 SRT让 Codex 按标记自动砍掉废话片段生成粗剪草稿交付清单生成生成草稿的同时输出各平台的导出参数表分辨率、码率、封面要求配合剪映导出时照着设置。目前这套流程里真正的瓶颈已经不是“能不能剪出来”而是“怎么把规则描述得更准”。我准备在下一个版本里把字幕断句的人工校对也纳入反馈循环让 Codex 根据历史修改记录自动学习账号偏好的字幕风格。最后说点个人体会。这套方案真正改变的不是“剪辑变简单了”而是“剪辑执行被吸收掉了”——你不再需要花一整天拖时间线而是把时间花在描述需求、验收结果、打磨审美这些机器做不好的事情上。踩过一轮坑之后我最大的感受是自动化项目的核心不是让模型写得多聪明而是把规则、校验、回滚做扎实Skill 的价值也不在它有多长而在于它让模型的每一次输出都有据可依。如果你手里也有大量重复剪辑工作建议先从一个最小场景试起一条口播、一份 SRT、一个草稿跑通了再加复杂度。