在 Windows 上把 ChatCut 适配为 Codex 个人插件从安装卡住到 52 个工具验证成功说明本文是一次本地兼容性排查记录不构成产品推荐。文中不会展示访问令牌、刷新令牌或其他账号凭据。不同版本的 Codex 与 ChatCut 可能存在界面或配置差异请以官方文档为准。将 ChatCut MCP 插件从 Codex 桌面应用移植到 WorkBuddy —— 完整适配实录一、问题背景ChatCut 提供面向 AI Agent 的视频编辑插件可以把项目管理、时间线编辑、字幕、转录、Motion Graphics、素材生成和导出等能力通过 MCP 暴露给 Agent。ChatCut 官方仓库说明这个插件包主要由以下部分组成.codex-plugin/plugin.jsonCodex 插件清单.mcp.jsonChatCut MCP 服务配置skills/常用视频工作流技能assets/图标等资源。参考ChatCut Agent Plugin 官方仓库。官方安装页给出的常规路径是在桌面版 ChatGPT/Codex 中添加 Git marketplace、安装插件、完成 MCP 登录然后创建一个全新任务。官方也特别提醒安装任务本身不会动态获得刚安装的 MCP 工具最终必须进入新任务验证。参考ChatCut ChatGPT/Codex 安装指南、Codex 插件构建文档。本次环境遇到了两个实际问题浏览器自动安装链路连续出现扩展网络错误Git 仓库拉取超时桌面应用内置 Codex CLI 在当前终端直接执行时又出现访问受限。与此同时同一台电脑上的 WorkBuddy 已经成功连接 ChatCut并扫描到 52 个工具。这提供了一条更直接的排查思路复用已落地的官方插件文件和授权状态再转换为 Codex 个人插件结构。二、先区分三个概念这次排查最容易混淆的是“插件已显示”“技能已启用”和“MCP 工具可调用”。它们不是一回事。1. 插件清单插件清单负责告诉 Codex 插件叫什么、版本是多少、技能目录在哪里、MCP 配置文件在哪里。它决定插件能否被 Codex 识别和展示。2. Skills 工作流Skills 是面向 Agent 的操作指南例如素材导入、字幕、转录、Motion Graphics、导出和验证。它们帮助 Agent 选择工具、安排步骤和检查结果但技能本身不是远程视频编辑 API。3. MCP 工具真正执行项目读取、时间线修改、字幕管理、素材生成和导出的是 ChatCut 远程 MCP 服务暴露的工具。只有在新任务中出现mcp__chatcut__*并且至少一次只读调用成功才算运行时连接完成。因此UI 中看到插件开关已开启只能证明“安装状态正常”不能单独证明“远程工具已经可用”。三、把已存在的插件内容转换为 Codex 个人插件本次复用了 WorkBuddy 中已经存在的 ChatCut 插件内容并整理为 Codex 的个人插件目录%USERPROFILE%\plugins\chatcut\ ├─ .codex-plugin\ │ └─ plugin.json ├─ .mcp.json └─ skills\ ├─ chatcut\ ├─ asset-import\ ├─ chatcut-plugin-basics\ ├─ create-motion-graphics\ ├─ export\ └─ ...个人 marketplace 位于%USERPROFILE%\.agents\plugins\marketplace.json插件清单使用版本0.2.16并声明{ name: chatcut, version: 0.2.16, skills: ./skills/, mcpServers: ./.mcp.json }完成结构转换后先使用 Codex 的插件验证脚本检查清单而不是立刻宣告安装成功。验证通过只代表文件结构合规后面仍需验证远程连接。四、关键兼容性问题必须显式声明 HTTP 类型最初的.mcp.json与 WorkBuddy 中的配置一致包含远程 URL、OAuth resource 和自定义 header但没有显式声明传输类型。WorkBuddy 可以识别这份配置Codex 中则出现了一个很有迷惑性的现象插件页面显示已安装并启用1 个 MCP 服务器和 16 个技能均能显示新任务却长期停留在初始化阶段没有任何回复。对比 Codex 已安装的其他远程 MCP 插件配置后发现缺少type: http修正后的配置如下{ mcpServers: { chatcut: { type: http, http_headers: { x-chatcut-mcp-surface: codex }, oauth_resource: https://api.chatcut.io/api/external-mcp/mcp, url: https://api.chatcut.io/api/external-mcp/mcp } } }这里的经验是不同 Agent 宿主对 MCP 配置的默认推断能力可能不同。迁移远程 MCP 插件时不要假设缺省传输类型在所有宿主中都能正常工作。五、为什么修改后必须重启并新建任务本次同时修正了插件源目录和 Codex 已安装缓存中的.mcp.json随后完全退出并重新打开 Codex。重启之后仍需创建全新任务因为任务的工具列表是在任务启动时捕获的。已经打开的旧任务不会因为插件刚安装或配置刚修复就自动获得新的mcp__chatcut__*工具。这也与 ChatCut 官方安装指南的要求一致完成安装、登录和验证后必须创建并切换到第一条新的编辑任务。六、不要只数工具还要执行一次无副作用验证最终验证分为两层。第一层工具发现在新任务中扫描到52 个 mcp__chatcut__* 工具工具覆盖的主要类别包括项目、时间线、轨道、标记、模板和媒体池管理时间线元素编辑、拆分、字幕、转录和脚本清理素材导入、上传、下载、库存素材搜索Motion Graphics、Shader、设计风格和字体AI 视频、配音、音乐、音效和人声分离时间线帧与素材帧检查、进度跟踪导出、渲染跟踪和格式转换Web 内容采集、编辑器链接和结构化追问。第二层真实只读调用仅仅发现 52 个工具仍不够。随后调用了只读的list_projects第一次返回 HTTP 502立即重试后成功返回 1 个现有项目没有创建、打开或修改任何视频项目。这说明插件工具注册成功MCP 传输已经打通当前授权状态可用第一次 502 更像临时网关波动而不是 OAuth 或配置失败。排查远程 MCP 时应把“一次 502”和“持续配置失败”区分开。若工具已加载且重试后只读调用成功就不应继续反复修改认证配置。七、建议采用的验证清单以后迁移类似个人插件可以按下面的顺序检查插件目录中存在.codex-plugin/plugin.json清单中的skills、mcpServers路径真实存在远程 MCP 明确声明type: http插件验证脚本通过Codex 插件页面显示已安装、已启用修改 MCP 配置后完全重启 Codex创建全新任务不在安装任务中测试精确统计mcp__插件名__*工具数量选择一个无副作用的只读工具做真实调用对偶发 502 做有限重试不暴露令牌也不直接执行写操作。八、最终结果本次 Windows 本地适配最终达到以下状态ChatCut 个人插件版本0.2.16Codex UI1 个 MCP 服务器、16 个技能新任务发现 52 个 ChatCut MCP 工具认证已有会话可用无需再次 OAuth真实验证list_projects只读调用成功安全边界验证过程未修改任何项目。从结果看这不是简单地把 WorkBuddy 配置复制到 Codex而是完成了一次宿主兼容性适配补齐 Codex 所需的 HTTP 传输声明并通过“新任务工具发现 只读调用”证明运行时确实可用。参考资料ChatCut Agent Plugin 官方仓库ChatCut ChatGPT/Codex 插件安装指南ChatCut AI Agent 插件入口OpenAIBuild pluginsOpenAICodex use cases建议标签Codex、MCP、ChatCut、Windows、AI视频编辑、插件适配