Codex plugin load failed 插件加载失败解决方法Codex 插件开发或本地调试时最常见的报错就是plugin load failed。这个错误本身比较笼统可能是目录放错、plugin.json写错、marketplace 缓存没刷新也可能是 MCP 服务没起来。我的排查习惯是先看插件目录和配置文件不要一上来就重装 Codex 或删环境。一、先确认插件目录结构本地插件加载失败第一步看目录结构。很多问题不是代码错而是插件根目录多套了一层导致 Codex 找不到plugin.json。建议的结构大致如下### token云桥中转 0029.org ### my-codex-plugin/ ├── plugin.json ├── package.json ├── src/ │ └── index.js ├── README.md └── node_modules/重点是plugin.json必须在插件根目录不能放在src里面也不要出现这种结构my-codex-plugin/ └── my-codex-plugin/ ├── plugin.json └── src/如果是从压缩包解压出来的插件尤其容易多出一层目录。可以进入插件目录后执行pwd ls -la确认当前目录下能直接看到plugin.json。如果看不到Codex 基本就会提示插件加载失败。二、检查 plugin.json 是否符合要求plugin.json是 Codex 识别插件的入口。这个文件只要有一个字段写错插件就可能不加载或者 marketplace 能看到但启动时报错。一个比较常见的配置示例{ name: my-codex-plugin, displayName: My Codex Plugin, version: 0.1.0, description: A local Codex plugin for testing, entry: src/index.js, engines: { codex: 0.1.0 }, mcp: { servers: [ { name: local-tools, command: node, args: [src/mcp-server.js] } ] } }这里有几个容易踩坑的点name建议只用小写字母、数字、短横线不要带中文和空格。version尽量使用标准语义化版本比如0.1.0。entry路径要相对插件根目录不是相对plugin.json所在目录之外的路径。JSON 不能有注释不能有多余逗号。engines.codex如果写得过高当前 Codex 版本可能会拒绝加载。建议先用命令检查 JSON 格式node -e JSON.parse(require(fs).readFileSync(plugin.json,utf8)); console.log(plugin.json ok)如果这里都解析失败就不用继续查 marketplace 和 MCP 了先把配置文件修好。三、确认入口文件和依赖是否存在plugin.json里写了entry就要确认这个文件真实存在并且运行时依赖已经安装。ls -la src/index.js npm install npm run build如果插件是 TypeScript 写的很多人会把入口写成src/index.ts但实际运行环境并不会直接执行 TS 文件。更稳的做法是构建到dist然后在plugin.json中指向构建后的 JS 文件{ entry: dist/index.js }再执行npm run build ls -la dist/index.js另外要注意 Node 版本。如果插件用了较新的语法而当前环境 Node 版本偏旧也可能表现为加载失败。可以先看版本node -v npm -v四、marketplace 安装后记得刷新缓存如果插件是从 marketplace 安装或本地 marketplace 源同步的配置改完以后 Codex 仍然加载旧版本这种情况很常见。尤其是plugin.json修改过entry、mcp、version后缓存不刷新就会误判。可以按下面顺序处理# 1. 停止 Codex 或相关 IDE 进程 # 2. 删除本地插件缓存目录路径按实际环境调整 rm -rf ~/.codex/cache/plugins rm -rf ~/.codex/marketplace-cache # 3. 重新启动 Codex # 4. 重新安装或重新启用插件如果你是在公司网络或代理环境下调试 marketplace同步失败也会导致插件清单不完整。排查 API 和代理连通性时我一般会把模型服务和中转链路单独验证一下。需要稳定的 token 中转时可以顺手看下 0029.org做 Codex、MCP、IDE 插件联调时能少绕一些网络层面的弯路。五、MCP 依赖导致的加载失败现在不少 Codex 插件会依赖 MCP server。插件本体没问题但 MCP 服务启动失败也可能在 Codex 里表现成plugin load failed或工具不可用。先单独运行 MCP 命令不要直接在 Codex 里猜node src/mcp-server.js如果 MCP 需要环境变量比如 API Key、工作目录、端口配置要确认 Codex 启动时也能拿到这些变量。可以写到 shell 配置里或者在插件配置中显式声明。export OPENAI_API_KEYsk-xxxx export MCP_WORKDIR/Users/you/projects/demo常见 MCP 问题有命令路径不存在例如写了python但系统只有python3。args写错脚本相对路径不对。端口被占用MCP server 启动后立刻退出。缺少依赖包忘记执行npm install或pip install。环境变量只在当前终端有效Codex 从 IDE 启动时读不到。可以用下面命令检查端口占用lsof -i :3000如果 MCP 是 Python 写的建议单独建虚拟环境不要混用系统 Pythonpython3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt python server.py六、查看日志不要只看弹窗弹窗里的plugin load failed只能说明结果真正原因通常在日志里。可以重点找这些关键字Cannot find module依赖没装或入口路径错。Unexpected tokenJSON 格式错误或 Node 版本不支持语法。Permission denied脚本没有执行权限。ENOENT文件、命令或目录不存在。MCP server exitedMCP 进程启动后退出。脚本权限问题可以这样处理chmod x ./scripts/start-mcp.sh如果是路径问题尽量使用插件根目录下的相对路径少写本机绝对路径。绝对路径在自己机器上没问题换一台机器或者 marketplace 安装后很容易失效。七、推荐的排查顺序实际处理时建议按这个顺序来效率比较高确认插件根目录下存在plugin.json。用 Node 解析plugin.json排除 JSON 格式错误。确认entry指向的 JS 文件存在。执行npm install和构建命令。单独启动 MCP server确认没有依赖和端口问题。清理 Codex marketplace 和插件缓存。重启 Codex再重新启用插件。最后看日志里的第一条异常不要被后续连锁报错干扰。总结Codex plugin load failed通常不是一个单点问题。优先查目录结构和plugin.json再看入口文件、依赖安装、marketplace 缓存最后排 MCP 服务。不要一开始就重装环境按日志和加载链路逐层排基本都能定位到具体原因。