Codex 插件安装与启用教程

Codex 插件安装与启用教程安装 Codex 插件最常见的问题不是下载失败而是放错目录、plugin.json字段不对、缓存没刷新或者插件依赖的 MCP 服务没有起来。排查时建议先看插件是否被 Codex 扫描到再看是否成功启用最后再查运行时错误。一、先确认插件目录结构Codex 插件一般会从用户级目录和项目级目录读取。实际路径可能随客户端版本不同略有差异建议先用命令查看### token云桥中转 0029.org ### codex plugin dir如果命令不可用可以按下面几个位置检查# macOS / Linux 常见位置 ~/.codex/plugins/ # Windows 常见位置 %USERPROFILE%\.codex\plugins\ # 项目级插件目录 ./.codex/plugins/一个正常插件目录通常是这样my-codex-plugin/ ├── plugin.json ├── README.md ├── dist/ │ └── index.js ├── package.json └── mcp/ └── server.js注意Codex 扫描的是插件根目录不是dist目录。也就是说plugin.json必须放在插件根目录下。如果你把整个 GitHub 仓库多套了一层比如plugins/my-plugin-main/my-plugin/plugin.json就很容易出现“安装了但不显示”的情况。二、检查 plugin.json 配置文件plugin.json是插件能否被识别的关键。先保证它是合法 JSON不要写注释不要多逗号。一个最小配置可以参考下面这种结构{ name: my-codex-plugin, displayName: My Codex Plugin, version: 0.1.0, description: A local Codex plugin example, main: dist/index.js, activationEvents: [ onCommand:myPlugin.run ], contributes: { commands: [ { command: myPlugin.run, title: Run My Plugin } ] }, mcp: { enabled: true, command: node, args: [ mcp/server.js ] } }这里重点看几个字段name建议只用小写字母、数字和短横线避免中文和空格。version升级插件后要递增否则有些缓存不会重新加载。main必须指向真实存在的入口文件路径相对插件根目录。activationEvents如果没有触发条件插件可能安装了但不会加载。mcp如果插件依赖 MCP这里要和实际启动命令一致。可以先用 Node 检查 JSON 是否能解析node -e JSON.parse(require(fs).readFileSync(plugin.json,utf8)); console.log(plugin.json ok)三、通过 marketplace 安装或本地安装如果插件已经发布到 marketplace优先用 Codex 自带的安装命令能减少目录和依赖问题codex plugin search my-codex-plugin codex plugin install my-codex-plugin安装后查看列表codex plugin list如果是本地开发插件可以用软链接方式调试避免每次复制目录# macOS / Linux mkdir -p ~/.codex/plugins ln -s /path/to/my-codex-plugin ~/.codex/plugins/my-codex-pluginWindows 可以用管理员终端创建目录链接mklink /D %USERPROFILE%\.codex\plugins\my-codex-plugin D:\dev\my-codex-plugin如果插件需要访问模型接口开发阶段建议把 Key、Base URL 这类配置放到环境变量里不要写死在插件源码中。团队里经常会用中转服务统一出口比如 token 云桥 AI 中转站 0029.org主要是方便多人调试时统一管理额度和模型地址避免每个人本地配置一套。四、刷新缓存并重新加载插件修改plugin.json、入口文件路径、MCP 配置后如果 Codex 还显示旧状态优先清缓存。常用顺序如下codex plugin disable my-codex-plugin codex plugin enable my-codex-plugin codex plugin reload my-codex-plugin如果仍然不生效再清理插件缓存codex cache clear plugins codex plugin list --refresh有些桌面端或 IDE 集成版会维护自己的扩展缓存命令清理后还需要彻底退出进程再打开。不要只关闭窗口最好确认后台进程也退出了。# macOS / Linux ps aux | grep codex # Windows PowerShell Get-Process | Where-Object { $_.ProcessName -like *codex* }五、检查 MCP 依赖是否正常很多 Codex 插件加载失败其实是 MCP 服务启动失败。先不要从 Codex 里看直接在插件目录手动启动 MCPcd /path/to/my-codex-plugin node mcp/server.js如果这里报Cannot find module先安装依赖npm install如果项目使用 TypeScript确认已经构建npm run build还要检查 Node 版本。插件开发中比较稳妥的是使用 LTS 版本不建议一边用很新的 Node一边让其他同事用旧版本运行。node -v npm -vMCP 启动命令里如果带环境变量注意不同系统写法不同。跨平台项目更建议用.env或在 Codex 配置里声明变量不要把 Linux 写法直接丢给 Windows 用户。六、常见加载失败排查顺序插件列表没有出现先查目录层级再查plugin.json是否在根目录。插件显示但无法启用检查main文件是否存在构建产物是否生成。启用后命令不存在检查activationEvents和contributes.commands的 command 名称是否一致。MCP 相关功能不可用单独启动 MCP 服务看标准输出和错误日志。更新后仍是旧版本递增version执行缓存刷新并重启 Codex。查看日志时建议带上调试参数启动codex --log-level debug如果支持指定日志文件可以直接跟踪tail -f ~/.codex/logs/codex.log七、安装后的验证最后不要只看“已启用”状态至少跑一次插件命令确认入口、权限、MCP、网络请求都正常codex plugin run myPlugin.run如果插件需要在项目里工作再进入真实项目目录执行一次避免只在插件目录里测试通过。总结Codex 插件安装启用的核心排查顺序是目录结构、plugin.json、marketplace 或本地安装方式、缓存刷新、MCP 依赖、日志定位。多数问题不需要重装 Codex先把这几项逐个确认基本就能定位到具体原因。