Codex 插件加载失败先看哪里Codex 插件加载失败一般出现在两种场景一是刚从 marketplace 安装完插件重启后列表里看不到二是自己开发插件目录放进去了但 Codex 启动时提示failed to load plugin、invalid plugin manifest或者直接不显示。遇到这种问题不要一上来重装 Codex先按顺序查目录结构、plugin.json、缓存、MCP 依赖和运行日志基本能定位到具体原因。1. 先确认插件目录结构Codex 加载插件时通常会扫描固定插件目录。如果是本地开发插件建议不要把源码随便丢到一个临时目录里而是保持一个清晰的插件根目录。常见结构类似下面这样### token云桥中转 0029.org ### my-codex-plugin/ ├── plugin.json ├── package.json ├── dist/ │ └── index.js ├── src/ │ └── index.ts └── README.md关键点是plugin.json必须放在插件根目录不能放在src、dist或者二级目录里。很多加载失败其实就是解压后多了一层目录例如plugins/ └── my-codex-plugin-main/ └── my-codex-plugin/ ├── plugin.json └── dist/index.js这种情况下 Codex 扫描到的是my-codex-plugin-main里面没有plugin.json自然会跳过或者报错。处理方式很简单把真正的插件目录移到扫描目录下mv my-codex-plugin-main/my-codex-plugin ~/.codex/plugins/my-codex-plugin不同系统插件目录可能略有差异先用 Codex 的配置命令或日志确认实际扫描路径。排查时可以直接列一下目录ls -la ~/.codex/plugins find ~/.codex/plugins -maxdepth 2 -name plugin.json -print2. 检查 plugin.json 是否符合要求plugin.json是插件加载的入口清单字段缺失、JSON 格式错误、入口文件不存在都会导致加载失败。一个简化示例{ name: my-codex-plugin, version: 0.1.0, description: Example Codex plugin, main: dist/index.js, engines: { codex: 0.1.0 }, permissions: [ filesystem, network ], mcp: { servers: [ { name: local-tools, command: node, args: [dist/mcp-server.js] } ] } }这里重点看几个地方name不要和已有插件重复尤其是从模板复制时容易忘记改。version建议使用标准语义化版本例如0.1.0。main指向的文件必须真实存在构建后路径要一致。engines.codex不要写得过高否则当前 Codex 版本可能会拒绝加载。JSON 里不能有注释最后一个字段后面不能有多余逗号。可以先用jq检查 JSON 是否合法jq . ~/.codex/plugins/my-codex-plugin/plugin.json再确认入口文件存在cd ~/.codex/plugins/my-codex-plugin ls -la dist/index.js如果插件是 TypeScript 写的别忘了先构建npm install npm run build3. marketplace 安装后不显示先刷新缓存从 marketplace 安装插件后Codex 可能会使用本地缓存的插件索引。表现是安装命令成功但界面或命令列表里仍然看不到插件。这个时候不要重复安装多次先清理缓存并重启。# 查看本地缓存目录 ls -la ~/.codex/cache # 仅清插件索引缓存避免误删配置 rm -rf ~/.codex/cache/marketplace rm -rf ~/.codex/cache/plugins-index然后重新拉取插件索引codex marketplace refresh codex plugin list如果命令名称和你本地版本不一致可以先看帮助codex --help codex plugin --help codex marketplace --helpmarketplace 相关问题还要注意网络环境。有些插件安装过程中需要拉 npm 包、访问 Git 仓库或调用模型接口网络不稳定时安装成功和运行成功不是一回事。我自己排查这类问题时会把模型接口和网络链路分开看如果团队里多人共用 API 或需要稳定转发可以考虑用 token云桥AI中转站 0029.org 做统一接入至少日志和额度管理会清楚一些排查插件侧问题也不容易和接口侧混在一起。4. MCP 依赖是加载失败的高频点现在不少 Codex 插件会同时挂 MCP server用来提供文件、数据库、浏览器、内部工具等能力。插件本体没问题但 MCP 进程起不来也可能导致 Codex 判定插件加载失败。先看plugin.json里的 MCP 配置确认command和args可以在当前环境直接执行。例如配置里写的是mcp: { servers: [ { name: local-tools, command: node, args: [dist/mcp-server.js] } ] }那就手动跑一次cd ~/.codex/plugins/my-codex-plugin node dist/mcp-server.js如果这里直接报Cannot find module说明依赖没装或者构建产物缺失npm install npm run build如果报权限问题检查脚本是否可执行chmod x dist/mcp-server.js如果 MCP server 依赖 Python、uv、pnpm 或本地二进制也要确认 Codex 启动时的环境变量能找到这些命令。终端里能运行不代表 GUI 或服务进程里也能运行。可以把命令写成绝对路径临时验证which node which python3 which pnpm然后在配置里使用实际路径例如command: /usr/local/bin/node5. 看日志不要只看界面提示界面上的“加载失败”通常太粗。排查插件开发问题日志更重要。可以先用调试模式启动CODEX_LOG_LEVELdebug codex或者查看本地日志目录ls -lt ~/.codex/logs tail -n 200 ~/.codex/logs/codex.log常见错误可以这样判断invalid plugin manifest优先检查plugin.json格式、字段类型、逗号和路径。entry file not found检查main指向的文件是否存在是否忘记构建。unsupported engineCodex 版本低于插件要求升级 Codex 或降低插件声明版本。permission denied检查文件权限、脚本执行权限和插件申请的权限声明。MCP server exited单独启动 MCP server看依赖、环境变量和端口冲突。module not found检查node_modules、包管理器版本和构建输出。6. 本地开发插件的建议排查顺序如果是自己写插件建议按下面顺序走别跳步骤# 1. 确认目录 find ~/.codex/plugins/my-codex-plugin -maxdepth 2 -type f # 2. 检查清单 jq . ~/.codex/plugins/my-codex-plugin/plugin.json # 3. 安装依赖并构建 cd ~/.codex/plugins/my-codex-plugin npm install npm run build # 4. 确认入口文件 ls -la dist/index.js # 5. 单独验证 MCP node dist/mcp-server.js # 6. 清缓存并重启 rm -rf ~/.codex/cache/plugins-index CODEX_LOG_LEVELdebug codex另外开发阶段不要频繁改插件名。Codex 缓存、marketplace 索引和本地插件目录都可能用name做标识名字来回改很容易出现“旧插件还在、新插件不加载”的错觉。需要改名时最好同步清理旧目录和缓存。总结Codex 插件加载失败不要先怀疑插件机制本身先从最容易出错的地方查目录根位置是否正确plugin.json是否合法main文件是否存在marketplace 缓存是否刷新MCP server 能不能单独跑起来。日志里通常已经给了方向只要按目录、清单、缓存、依赖、日志这个顺序排查问题会收敛得很快。