OpenChatCut接入Codex与Claude Code：外部AI Agent通过MCP剪辑视频工程完整教程

OpenChatCut接入Codex与Claude Code：外部AI Agent通过MCP剪辑视频工程完整教程

【免费下载链接】OpenChatCutOpen-source, local-first conversational AI video editor with a professional multi-track timeline, Agent Skills, MCP integration, and Remotion rendering.项目地址: https://gitcode.com/gh_mirrors/op/OpenChatCut

OpenChatCut是一款开源、本地优先（local-first）的对话式 AI 视频编辑器：内置专业多轨时间线、Agent Skills 与 MCP 集成，并基于 Remotion 渲染导出。本教程完整讲解如何将Codex 与 Claude Code这两个外部 AI Agent 通过MCP（Model Context Protocol）接入 OpenChatCut，让 AI 直接读取、剪辑并导出可继续编辑的真实视频工程——而不是一段不可修改的生成视频。

为什么需要 MCP：一套工具面，两种 Agent

传统做法是"AI 生成视频 → 下载 → 手动重剪"。OpenChatCut 的路径完全不同：

• 内置 Agent与外部 MCP Agent（Codex、Claude Code、Cursor 等）共用同一套编辑工具和EditorCore命令；
• 每次修改都落到真实工程的轨道、片段、转场、字幕和特效上，可预览、可撤销、可继续手动调整；
• 外部 Agent 的修改先进入隔离草稿，不会污染正式时间线。

一句话：Codex 或 Claude Code 不是"替你生成视频"，而是"替你操作剪辑软件"。

编辑器内打开外部 Agent 接入 (MCP)对话框，可以看到统一端点和各客户端的一键连接入口：

准备工作：启动 OpenChatCut 并获取 MCP 端点

1. 安装并启动

三种方式任选其一：

源码运行需要 Node.js 24.x。启动后通过http://localhost:5199访问（必须是本机回环地址，否则浏览器会禁用 WebCrypto 等能力）。

2. 拿到端点与令牌

OpenChatCut 暴露的 Streamable HTTP MCP 端点默认是：

http://localhost:5199/api/external-mcp/mcp

令牌（Bearer Token）只在编辑器设置 → MCP页面展示；即使本机连接也强制要求令牌，服务重启后令牌会变化，需要重新复制配置。

工程列表界面就是外部 Agent 将要读取的"目标工程池"，Codex / Claude Code 连接的正是这些数据：

接入 Codex：两步完成连接

在 Codex 的配置中加入 MCP 服务（~/.codex/config.toml）：

[mcp_servers.openchatcut] url = "http://localhost:5199/api/external-mcp/mcp"

或直接用 CLI 注册（令牌建议放环境变量，避免写入仓库或聊天历史）：

export OPENCHATCUT_MCP_TOKEN='<从 设置 → MCP 复制的令牌>' codex mcp add openchatcut \ --url http://localhost:5199/api/external-mcp/mcp \ --bearer-token-env-var OPENCHATCUT_MCP_TOKEN

接入 Claude Code：一条命令

claude mcp add --transport http \ -H "Authorization: Bearer <令牌>" \ openchatcut http://localhost:5199/api/external-mcp/mcp

如果你使用其他 MCP 客户端（Qoder、Cursor、千问办公等），把端点注册为 Streamable HTTP 服务、Authorization头设为Bearer <令牌>即可。

推荐：安装官方 Agent Skill

让 Agent 自动完成上面的注册、并学会正确的工作流：

npx skills add 0xsline/OpenChatCut

安装后对 Agent 说"设置 OpenChatCut"即可。该 Skill 是一个单入口路由技能，按需在编辑器内加载 26 个专项技能（时间线、文字稿、字幕、音频、色彩、导出等），避免技能列表爆炸。技能定义可查看 SKILL.md，连接排障指南见 getting-started.md，编辑工作流见 editing-workflow.md。

核心工作流：编辑会话四步法

无论 Codex 还是 Claude Code，剪辑工程都走同一套会话流程（源码见 server/external-agent/）：

1. begin_edit_session— 创建编辑会话，保存返回的editSessionId，选择approvalMode：
   • manual（默认）：修改进入草稿，由你在 OpenChatCut 界面内逐条审阅、预览、勾选应用或拒绝；
   • auto：无人值守模式，review_edit_session直接应用完整草稿。
2. 传入editSessionId执行读取/编辑— 会话中每个工程工具都带上该 id，所有修改只写入隔离草稿。
3. review_edit_session— 草稿完成，提交审阅。
4. get_edit_session— 轮询状态，得到applied/rejected/discarded；manual会话需你在编辑器内点"应用"后才算生效。

两个值得注意的安全设计：

• 会话只暴露可安全进入草稿的工程读取/编辑工具；生成、导出、删除工程这类有即时副作用的工具不在会话内开放（拒绝了也回滚不了）；
• 两种模式下应用的操作都会原子提交为一个撤销节点——一次Ctrl+Z就能撤销 Agent 的全部修改。

接入成功后，Codex / Claude Code 操作工程的效果就像你在编辑器里让内置 Agent 干活一样：素材、转场、字幕、BGM 全部落到多轨时间线上，随时可以继续手动精修：

实战示例：对 Agent 说人话就够了

连接完成后，直接描述编辑任务即可，例如：

启动一个 OpenChatCut 编辑会话，读取草稿，在第二条音频轨的 8 秒处添加划盘音效， 并给相邻视频添加故障转场。提交草稿供审阅，等待我在 OpenChatCut 内应用后， 再报告修改已经生效。

Agent 会自动：openchatcut_status探活 →list_projects定位工程 →target_project锁定 →begin_edit_session开会话 → 调用时间线工具写入草稿 →review_edit_session提交。

常见问题速查

更完整的错误恢复策略见 known-errors.md。

小结

用三条命令概括全文：启动 OpenChatCut → 复制 MCP 端点与令牌 → 在 Codex / Claude Code 中注册。之后外部 AI Agent 就能和你共用同一个视频工程：它负责粗剪、转场、字幕与配乐，你负责审阅、精修与导出 MP4 / 字幕 / FCPXML。这就是 OpenChatCut "Agent-native + local-first" 的核心体验——AI 参与剪辑，但控制权始终在你手里。

【免费下载链接】OpenChatCutOpen-source, local-first conversational AI video editor with a professional multi-track timeline, Agent Skills, MCP integration, and Remotion rendering.项目地址: https://gitcode.com/gh_mirrors/op/OpenChatCut