OpenReel AI Agent 接入指南BYOK 对话、桌面 MCP 与 Headless CLI 自动化剪辑【免费下载链接】openreel-videoOpenReel Video - Professional browser-based video editor. Open source CapCut alternative. 100% browser-based, no installation, no cloud uploads, no watermarks.项目地址: https://gitcode.com/GitHub_Trending/op/openreel-video本文基于开源仓库 OpenReel Video 的官方 AI Agent 用户指南docs/AGENT-GUIDE.md展开系统讲解如何让任意 AI Agent 直接驱动浏览器端视频编辑器完成专业剪辑。文章覆盖三大接入方式——Web 端 BYOK 对话、桌面端 MCP 服务器、无界面 Headless CLI——并深入到 packages/agent-runner 与 packages/agent 的源码实现帮助你理解这套 Agent 工具层的调用链与安全机制。读完本文你将能独立配置三种接入场景、掌握对话控制项与确认门控的用法并用一条 CLI 命令对项目 JSON 执行批量自动化编辑。同一套工具层三个接入面OpenReel 的核心理念是AI Agent 的编辑能力不绑定任何一种界面形态。仓库用同一套工具层同时支撑三种使用场景Web BYOK chat—— 在浏览器编辑器内直接与模型对话密钥由你自己Bring Your Own Key提供Desktop MCP server—— 桌面应用内置一个本地 Model Context Protocol 服务器外部 MCP 客户端如 Claude Desktop、Cursor、Cline可连接并驱动当前打开的项目Headless runner—— 不打开任何应用在服务器或 CLI 环境中直接编辑已存储的项目文件适合批量编辑与定时任务。三者共享同一套能力集也就是由工具注册表自动生成的 docs/AGENT-CAPABILITIES.md 中定义的228 个工具外加execute_action/batch_actions两个逃生舱escape hatch。这意味着 Agent 能完成的编辑动作与专业剪辑师基本对齐导入素材、搭建时间线、修剪、裁剪、变换、调色、添加文字与图形、打关键帧、管理转场、配字幕、音频处理乃至 3D 场景与产品片头创作等。说明能力清单文档由openreel/agent的generateCapabilityMarkdown()自动生成见 docs/AGENT-CAPABILITIES.md因此工具数量会随版本演进请以该文件当前内容为准。Bring Your Own KeyWeb 与桌面聊天的基础配置BYOK自带密钥是 Web 与桌面两种交互式聊天场景的第一步核心原则是密钥只属于你自己绝不经过 OpenReel 服务器。配置步骤打开设置Settings→ API Keys添加一个 OpenAI 或 Anthropic 的 API Key。Web 端密钥在主密码master password保护下加密落盘桌面端密钥存放在**操作系统钥匙串OS keychain**中。打开AI Editor 面板工具栏中的机器人图标。在面板头部选择provider供应商与 model模型。用自然语言描述你的编辑需求例如“把第一段素材剪到 5 秒加一个淡入效果并在开头放一张标题卡。”密钥安全边界文档明确了两条安全承诺docs/AGENT-GUIDE.md密钥永远不会被发送或存储到 OpenReel 服务器生产环境中Web 应用以**同源代理same-origin proxy**的方式转发模型请求而不持久化密钥桌面端请求则直接经由原生钥匙串发起。从源码看无界面的 Headless 场景同样遵循“即用即弃”原则cli.ts 中resolveApiKey按优先级读取OPENREEL_API_KEY若未设置再回退到ANTHROPIC_API_KEY/OPENAI_API_KEY密钥仅用于当次请求不落盘、不打日志。AI Editor 面板的五个对话控制项在 AI Editor 面板中除输入框外还有一组面向安全与可审计性的控制项控制项图标/名称作用确认门控Confirm gate默认开启破坏性或高成本动作删除、移除、导出、AI 任务在默认情况下暂停等待你的批准自动批准Auto-approve盾牌图标跳过确认提示直接执行破坏性动作预演Dry-run烧瓶图标只规划工具调用序列不应用任何变更撤销本回合Undo this turn—将一整轮 AI 操作作为一条历史记录整体回退停止Stop—中止正在执行的回合并回滚已产生的部分编辑Token 计量Token meter—显示对话累计的输入/输出 token 数这套控制机制的价值在于确认门控兜底高风险操作dry-run 用于先看方案再执行undo/stop 提供整轮级的事务性回退。它与后文 Headless 场景中的“原子回合atomic turns”设计一脉相承——无论交互入口是什么一次 AI 操作都被当作一个可撤销的事务单元来管理。连接外部 Agent桌面 MCP 服务器桌面版应用内置了一个本地 Model Context Protocol 服务器使外部 MCP 客户端能够驱动你当前打开的项目这是把 OpenReel 接入 Cursor、Cline 或 Claude Desktop 这类 Agent 工作流的标准方式。连接步骤打开设置Settings→ MCP仅桌面端。面板会显示一个loopback URL和bearer tokentoken 可随时轮换。将客户端配置片段复制到你的 MCP 客户端中。它指向随应用打包的openreel-mcpstdio 桥接器由该桥接器把你的客户端连接到正在运行的应用{ mcpServers: { openreel: { command: node, args: [path to openreel-mcp] } } }默认情况下通过 MCP 发起的破坏性/高成本工具调用会被拒绝并返回 “confirmation required” 提示如需放行可开启Trusted local — auto-allow让受信任的本地客户端直接执行。使用Test connection验证服务器可达。传输层的安全设计指南强调docs/AGENT-GUIDE.mdHTTP 传输只绑定127.0.0.1并拒绝任何缺少 bearer token 的请求——即仅限本机、必须鉴权。源码中stdio 桥接器apps/desktop/src/mcp-shim/index.ts先从本地 endpoint 文件读取{ url, port, token }随后将收到的 JSON-RPC 行逐条转发并在请求头携带Authorization: Bearer token见 mcp-shim 的 postRpc 实现。也就是说client ↔ stdio shim ↔ 本地 HTTP 端点全程不经过公网。Headless / 自动化编辑CLI 一次搞定openreel/agent-runner包在不打开任何应用的情况下编辑已存储的项目非常适合批处理“把这条配方应用到 N 个项目”、定时任务与 CI 流水线。基本用法openreel-agent \ --project ./reel.json \ --prompt Add a title that says Welcome for the first 3 seconds \ --provider anthropic --model claude-sonnet-4-20250514 \ --out ./reel.edited.json命令执行后./reel.edited.json会写入编辑结果终端输出本次回合的stoppedReason、工具调用次数以及输入/输出 token 用量见 cli.ts。参数与默认值与源码逐项对应对照 packages/agent-runner/src/cli.ts 的参数解析逻辑L15-L47完整参数表如下参数简写含义默认值--project path-p要编辑的项目 JSON 文件必填--prompt text-m自然语言编辑指令必填--provider name—anthropic或openaianthropic--model id—模型 IDprovider 默认值Anthropic 为claude-sonnet-4-20250514OpenAI 为gpt-4o见 cli.ts 的 DEFAULT_MODEL--out path-o输出路径不传则就地覆盖编辑就地编辑--dry-run—只规划工具调用不应用变更关闭命令名openreel-agent由 packages/agent-runner/package.json 的bin字段注册。API Key 与环境变量API Key 从OPENREEL_API_KEY读取其次按 provider 回退到ANTHROPIC_API_KEY/OPENAI_API_KEY密钥按请求使用绝不存储、不打日志未设置密钥时进程会以非零码退出并提示错误见 cli.ts。从 CLI 到引擎的调用链CLI 并非直接操作文件而是走一条完整的“工具注册 → 回合执行 → 项目持久化”链路run.ts 的 runHeadlessEdit 创建HeadlessHost内存中的项目宿主、构造 LLM 客户端node-llm.ts依据 provider 用toAnthropicTools()/toOpenAITools()将统一工具注册表转换为对应平台的工具定义并调用runTurn执行单回合对话回合结束后由runHeadlessEditFile决定是否把结果写回文件——出错或 dry-run 时不落盘saved标志见 run.ts。配套的测试packages/agent-runner/src/run.test.ts、project-io.test.ts覆盖了回合执行与项目读写两个环节可作为理解行为边界的参考。导出与 GPU 任务--dry-run之外Headless 场景还支持导出/渲染任务委托给 GPU worker由auth broker授权内置的导出队列export-queue.ts可并发驱动多个导出任务例如“把这 N 个变体都导出来”GPU 任务执行器gpu-job-runner.ts 承载渲染作业的调度与执行并配有对应测试gpu-job-runner.test.ts。安全与限制机制无论通过哪种接入面Agent 回合都受同一套保护机制约束docs/AGENT-GUIDE.md原子回合Atomic turns每一回合都是一个可撤销的事务一旦发生致命错误整回合变更全部回滚不会留下半成品状态。这正是上文“Undo this turn”/“Stop”能在 UI 层面成立的根本原因。成本上限Cost ceiling可选的每回合 token 预算防止某个失控回合无限消耗 token。CLI 侧对应HeadlessEditOptions.maxTokens与limits.maxSteps / maxToolCalls等约束见 run.ts 的选项定义。限流与重试Rate limitingprovider 返回 429 / 5xx 时以**指数退避exponential backoff**自动重试提升长任务在波动网络下的完成率。深入阅读docs/AGENT-CAPABILITIES.md —— 完整能力参考228 个工具按 read / motion / project / track / media / clip / speed / transform / effect / color / audio / subtitle / keyframe / transition / marker / text / graphics / raw / export / ai 分类附枚举与参数范围清单blendModes、videoFilterTypes、easings、shapeTypes、filterPresets、colorGrading 范围等并包含 motion合成动画与 creation3D 场景/产品创作两大扩展域docs/superpowers/specs/2026-06-18-ai-agent-editing-design.md —— AI Agent 编辑能力的原始设计文档说明工具层与三接入面统一的架构动机实现源码packages/agent工具注册表、回合执行、能力清单生成、packages/agent-runnerCLI、导出队列、GPU 任务执行器、apps/desktop/src/mcp-shimMCP stdio 桥接器。【免费下载链接】openreel-videoOpenReel Video - Professional browser-based video editor. Open source CapCut alternative. 100% browser-based, no installation, no cloud uploads, no watermarks.项目地址: https://gitcode.com/GitHub_Trending/op/openreel-video创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenReel AI Agent 接入指南：BYOK 对话、桌面 MCP 与 Headless CLI 自动化剪辑
OpenReel AI Agent 接入指南BYOK 对话、桌面 MCP 与 Headless CLI 自动化剪辑【免费下载链接】openreel-videoOpenReel Video - Professional browser-based video editor. Open source CapCut alternative. 100% browser-based, no installation, no cloud uploads, no watermarks.项目地址: https://gitcode.com/GitHub_Trending/op/openreel-video本文基于开源仓库 OpenReel Video 的官方 AI Agent 用户指南docs/AGENT-GUIDE.md展开系统讲解如何让任意 AI Agent 直接驱动浏览器端视频编辑器完成专业剪辑。文章覆盖三大接入方式——Web 端 BYOK 对话、桌面端 MCP 服务器、无界面 Headless CLI——并深入到 packages/agent-runner 与 packages/agent 的源码实现帮助你理解这套 Agent 工具层的调用链与安全机制。读完本文你将能独立配置三种接入场景、掌握对话控制项与确认门控的用法并用一条 CLI 命令对项目 JSON 执行批量自动化编辑。同一套工具层三个接入面OpenReel 的核心理念是AI Agent 的编辑能力不绑定任何一种界面形态。仓库用同一套工具层同时支撑三种使用场景Web BYOK chat—— 在浏览器编辑器内直接与模型对话密钥由你自己Bring Your Own Key提供Desktop MCP server—— 桌面应用内置一个本地 Model Context Protocol 服务器外部 MCP 客户端如 Claude Desktop、Cursor、Cline可连接并驱动当前打开的项目Headless runner—— 不打开任何应用在服务器或 CLI 环境中直接编辑已存储的项目文件适合批量编辑与定时任务。三者共享同一套能力集也就是由工具注册表自动生成的 docs/AGENT-CAPABILITIES.md 中定义的228 个工具外加execute_action/batch_actions两个逃生舱escape hatch。这意味着 Agent 能完成的编辑动作与专业剪辑师基本对齐导入素材、搭建时间线、修剪、裁剪、变换、调色、添加文字与图形、打关键帧、管理转场、配字幕、音频处理乃至 3D 场景与产品片头创作等。说明能力清单文档由openreel/agent的generateCapabilityMarkdown()自动生成见 docs/AGENT-CAPABILITIES.md因此工具数量会随版本演进请以该文件当前内容为准。Bring Your Own KeyWeb 与桌面聊天的基础配置BYOK自带密钥是 Web 与桌面两种交互式聊天场景的第一步核心原则是密钥只属于你自己绝不经过 OpenReel 服务器。配置步骤打开设置Settings→ API Keys添加一个 OpenAI 或 Anthropic 的 API Key。Web 端密钥在主密码master password保护下加密落盘桌面端密钥存放在**操作系统钥匙串OS keychain**中。打开AI Editor 面板工具栏中的机器人图标。在面板头部选择provider供应商与 model模型。用自然语言描述你的编辑需求例如“把第一段素材剪到 5 秒加一个淡入效果并在开头放一张标题卡。”密钥安全边界文档明确了两条安全承诺docs/AGENT-GUIDE.md密钥永远不会被发送或存储到 OpenReel 服务器生产环境中Web 应用以**同源代理same-origin proxy**的方式转发模型请求而不持久化密钥桌面端请求则直接经由原生钥匙串发起。从源码看无界面的 Headless 场景同样遵循“即用即弃”原则cli.ts 中resolveApiKey按优先级读取OPENREEL_API_KEY若未设置再回退到ANTHROPIC_API_KEY/OPENAI_API_KEY密钥仅用于当次请求不落盘、不打日志。AI Editor 面板的五个对话控制项在 AI Editor 面板中除输入框外还有一组面向安全与可审计性的控制项控制项图标/名称作用确认门控Confirm gate默认开启破坏性或高成本动作删除、移除、导出、AI 任务在默认情况下暂停等待你的批准自动批准Auto-approve盾牌图标跳过确认提示直接执行破坏性动作预演Dry-run烧瓶图标只规划工具调用序列不应用任何变更撤销本回合Undo this turn—将一整轮 AI 操作作为一条历史记录整体回退停止Stop—中止正在执行的回合并回滚已产生的部分编辑Token 计量Token meter—显示对话累计的输入/输出 token 数这套控制机制的价值在于确认门控兜底高风险操作dry-run 用于先看方案再执行undo/stop 提供整轮级的事务性回退。它与后文 Headless 场景中的“原子回合atomic turns”设计一脉相承——无论交互入口是什么一次 AI 操作都被当作一个可撤销的事务单元来管理。连接外部 Agent桌面 MCP 服务器桌面版应用内置了一个本地 Model Context Protocol 服务器使外部 MCP 客户端能够驱动你当前打开的项目这是把 OpenReel 接入 Cursor、Cline 或 Claude Desktop 这类 Agent 工作流的标准方式。连接步骤打开设置Settings→ MCP仅桌面端。面板会显示一个loopback URL和bearer tokentoken 可随时轮换。将客户端配置片段复制到你的 MCP 客户端中。它指向随应用打包的openreel-mcpstdio 桥接器由该桥接器把你的客户端连接到正在运行的应用{ mcpServers: { openreel: { command: node, args: [path to openreel-mcp] } } }默认情况下通过 MCP 发起的破坏性/高成本工具调用会被拒绝并返回 “confirmation required” 提示如需放行可开启Trusted local — auto-allow让受信任的本地客户端直接执行。使用Test connection验证服务器可达。传输层的安全设计指南强调docs/AGENT-GUIDE.mdHTTP 传输只绑定127.0.0.1并拒绝任何缺少 bearer token 的请求——即仅限本机、必须鉴权。源码中stdio 桥接器apps/desktop/src/mcp-shim/index.ts先从本地 endpoint 文件读取{ url, port, token }随后将收到的 JSON-RPC 行逐条转发并在请求头携带Authorization: Bearer token见 mcp-shim 的 postRpc 实现。也就是说client ↔ stdio shim ↔ 本地 HTTP 端点全程不经过公网。Headless / 自动化编辑CLI 一次搞定openreel/agent-runner包在不打开任何应用的情况下编辑已存储的项目非常适合批处理“把这条配方应用到 N 个项目”、定时任务与 CI 流水线。基本用法openreel-agent \ --project ./reel.json \ --prompt Add a title that says Welcome for the first 3 seconds \ --provider anthropic --model claude-sonnet-4-20250514 \ --out ./reel.edited.json命令执行后./reel.edited.json会写入编辑结果终端输出本次回合的stoppedReason、工具调用次数以及输入/输出 token 用量见 cli.ts。参数与默认值与源码逐项对应对照 packages/agent-runner/src/cli.ts 的参数解析逻辑L15-L47完整参数表如下参数简写含义默认值--project path-p要编辑的项目 JSON 文件必填--prompt text-m自然语言编辑指令必填--provider name—anthropic或openaianthropic--model id—模型 IDprovider 默认值Anthropic 为claude-sonnet-4-20250514OpenAI 为gpt-4o见 cli.ts 的 DEFAULT_MODEL--out path-o输出路径不传则就地覆盖编辑就地编辑--dry-run—只规划工具调用不应用变更关闭命令名openreel-agent由 packages/agent-runner/package.json 的bin字段注册。API Key 与环境变量API Key 从OPENREEL_API_KEY读取其次按 provider 回退到ANTHROPIC_API_KEY/OPENAI_API_KEY密钥按请求使用绝不存储、不打日志未设置密钥时进程会以非零码退出并提示错误见 cli.ts。从 CLI 到引擎的调用链CLI 并非直接操作文件而是走一条完整的“工具注册 → 回合执行 → 项目持久化”链路run.ts 的 runHeadlessEdit 创建HeadlessHost内存中的项目宿主、构造 LLM 客户端node-llm.ts依据 provider 用toAnthropicTools()/toOpenAITools()将统一工具注册表转换为对应平台的工具定义并调用runTurn执行单回合对话回合结束后由runHeadlessEditFile决定是否把结果写回文件——出错或 dry-run 时不落盘saved标志见 run.ts。配套的测试packages/agent-runner/src/run.test.ts、project-io.test.ts覆盖了回合执行与项目读写两个环节可作为理解行为边界的参考。导出与 GPU 任务--dry-run之外Headless 场景还支持导出/渲染任务委托给 GPU worker由auth broker授权内置的导出队列export-queue.ts可并发驱动多个导出任务例如“把这 N 个变体都导出来”GPU 任务执行器gpu-job-runner.ts 承载渲染作业的调度与执行并配有对应测试gpu-job-runner.test.ts。安全与限制机制无论通过哪种接入面Agent 回合都受同一套保护机制约束docs/AGENT-GUIDE.md原子回合Atomic turns每一回合都是一个可撤销的事务一旦发生致命错误整回合变更全部回滚不会留下半成品状态。这正是上文“Undo this turn”/“Stop”能在 UI 层面成立的根本原因。成本上限Cost ceiling可选的每回合 token 预算防止某个失控回合无限消耗 token。CLI 侧对应HeadlessEditOptions.maxTokens与limits.maxSteps / maxToolCalls等约束见 run.ts 的选项定义。限流与重试Rate limitingprovider 返回 429 / 5xx 时以**指数退避exponential backoff**自动重试提升长任务在波动网络下的完成率。深入阅读docs/AGENT-CAPABILITIES.md —— 完整能力参考228 个工具按 read / motion / project / track / media / clip / speed / transform / effect / color / audio / subtitle / keyframe / transition / marker / text / graphics / raw / export / ai 分类附枚举与参数范围清单blendModes、videoFilterTypes、easings、shapeTypes、filterPresets、colorGrading 范围等并包含 motion合成动画与 creation3D 场景/产品创作两大扩展域docs/superpowers/specs/2026-06-18-ai-agent-editing-design.md —— AI Agent 编辑能力的原始设计文档说明工具层与三接入面统一的架构动机实现源码packages/agent工具注册表、回合执行、能力清单生成、packages/agent-runnerCLI、导出队列、GPU 任务执行器、apps/desktop/src/mcp-shimMCP stdio 桥接器。【免费下载链接】openreel-videoOpenReel Video - Professional browser-based video editor. Open source CapCut alternative. 100% browser-based, no installation, no cloud uploads, no watermarks.项目地址: https://gitcode.com/GitHub_Trending/op/openreel-video创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考