让你的Tweak向Codex提供MCP工具通过Codex清单注册MCP Server的完整实践【免费下载链接】codex-plusplusCodex tweak system for the Codex desktop app项目地址: https://gitcode.com/gh_mirrors/co/codex-plusplus这是一份面向新手的完整实践指南通过 Codex 的 Tweak 清单manifest中的mcp字段注册 MCP Server让你的 Tweak 自动向 Codex 桌面应用提供 MCP 工具——无需手动编辑 Codex 配置同步、冲突处理、清理全部自动完成。一、这个功能解决什么问题MCPModel Context Protocol是一种让 AI 调用外部工具的标准协议。Codex 通过~/.codex/config.toml里的mcp_servers配置加载 MCP 工具但传统做法需要你手动编辑这个文件——改错了还会影响整个 Codex 环境。从 Codex 0.1.2 版本起见 0.1.2 发布说明Tweak 只需在清单里声明一个mcp字段Codex 主进程就会帮你完成配置同步。整个链路如下manifest.json 的 mcp 字段 ↓ Codex 主进程自动扫描 ~/.codex/config.toml受管配置块 ↓ Codex 启动 MCP Server ↓ 对话中直接调用你提供的 MCP 工具二、核心概念清单里的 mcp 字段一个会提供 MCP 工具的 Tweak和普通 Tweak 的唯一区别就是 manifest.json 里多了一个可选的mcp字段{ id: com.you.my-tweak, name: My Tweak, version: 0.1.0, githubRepo: you/my-tweak, description: 给 Codex 加上我的工具。, mcp: { command: node, args: [mcp-server.js], env: { MY_FLAG: 1 } } }mcp字段只有三个属性类型定义见 TweakMcpServer字段必填说明command✅启动 MCP Server 的命令如node、pythonargs❌启动参数Tweak 目录下存在的相对路径会自动转成绝对路径env❌传给 Server 的环境变量值必须全部是字符串三、动手实践三步注册你的 MCP Server第 1 步准备 Tweak 目录一个 Tweak 就是一个包含manifest.json和入口脚本的文件夹放到各平台的 Tweak 目录详见 编写 Tweak 官方指南macOS~/Library/Application Support/codex-plusplus/tweaks/Linux~/.local/share/codex-plusplus/tweaks/Windows%APPDATA%/codex-plusplus/tweaks/推荐结构my-tweak/ ├── manifest.json ├── index.js # Tweak 入口UI 逻辑可参考官方指南的最小示例 └── mcp-server.js # 你的 MCP Server任意通过 stdio 协议实现的进程第 2 步写入 mcp 清单在manifest.json中加入上面第二节展示的mcp字段。如果 Server 脚本叫mcp-server.jsargs直接写文件名即可Codex 会自动解析成绝对路径例如.../tweaks/my-tweak/mcp-server.js。第 3 步放置 Server 并重新加载mcp-server.js可以是任何语言的实现只要能通过 stdin/stdout 讲 MCP 协议即可。然后把 Tweak 放入目录后在 Codex 窗口按Cmd/CtrlR重新加载或重启应用打开Settings → Tweaks确认 Tweak 已加载MCP 配置即已同步完成。四、Codex 的同步机制三个贴心设计Codex 在加载 Tweak 时调用 syncMcpServersFromEnabledTweaks 扫描已启用的 Tweak由 syncManagedMcpServers 把声明写进config.toml中一个带标记的受管块# BEGIN CODEX MANAGED MCP SERVERS [mcp_servers.my-tweak] command node args [/path/to/tweaks/my-tweak/mcp-server.js] env { MY_FLAG 1 } # END CODEX MANAGED MCP SERVERS服务名自动生成由 Tweak 的id派生——去掉co.bennett.前缀、特殊字符替换为连字符并转小写。例如co.bennett.native-widgets→native-widgetscom.example.my-widget→com-example-my-widget推导规则见 mcpServerNameFromTweakId 及其测试用例。名称冲突时自动追加-2、-3。绝不覆盖你的手动配置如果你在config.toml里已手动定义了同名 ServerCodex 会跳过该 Tweak 只在日志中提示保留你的配置不动。卸载即清理禁用或移除 Tweak 后Codex 只删除受管块内的条目块外内容原样保留该行为有完整回归测试保障。五、Tweak 商店中的真实例子商店的 index.json 收录了两个真实使用mcp字段的 TweakProject Home项目看板让 Codex 通过 MCP 管理任务和 Windows Computer UseWindows 桌面自动化。它们的清单都只有极简的mcp: { command: node, args: [mcp-server.js] }——这正是你写自己 Tweak 时可以直接套用的形态。六、快速排错清单如果 MCP Server 没有出现在 Codex 里按顺序自查command是非空字符串且是系统里可用的可执行程序args里的相对路径文件确实存在于Tweak 目录内env的值是否全部为字符串Tweak 是否处于启用状态只有启用的 Tweak 会同步 MCP 配置Tweak 清单是否通过了校验SDK 的校验逻辑会检查mcp.command必填、mcp.args为字符串数组、mcp.env为字符串对象现象可能原因Tweak 未出现在 Tweaks 列表manifest.json缺少必填字段或格式错误对照字段说明表修正声明了mcp却未被同步command为空或args/env类型不合法会被静默跳过用validateTweakManifest检查日志显示 skipped ... already configured by user你手动配置了同名 ServerCodex 主动让位怀疑配置没生效查看 Codex 主进程日志log/main.log中 synced Codex MCP config 记录七、总结通过 Codex 清单注册 MCP Server 的完整流程可以浓缩为一句话写一个带mcp字段的manifest.json放入 Tweak 目录重载 Codex。服务命名、路径解析、与手动配置的冲突处理、卸载清理都由 mcp-sync.ts 自动完成。现在你可以开始动手让你的第一个 Tweak 为 Codex 提供专属 MCP 工具了 【免费下载链接】codex-plusplusCodex tweak system for the Codex desktop app项目地址: https://gitcode.com/gh_mirrors/co/codex-plusplus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考