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_KEY="sk-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 写的，建议单独建虚拟环境，不要混用系统 Python：

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python server.py

六、查看日志，不要只看弹窗

弹窗里的 plugin load failed 只能说明结果，真正原因通常在日志里。可以重点找这些关键字：

• Cannot find module：依赖没装或入口路径错。
• Unexpected token：JSON 格式错误或 Node 版本不支持语法。
• Permission denied：脚本没有执行权限。
• ENOENT：文件、命令或目录不存在。
• MCP server exited：MCP 进程启动后退出。

脚本权限问题可以这样处理：

chmod +x ./scripts/start-mcp.sh

如果是路径问题，尽量使用插件根目录下的相对路径，少写本机绝对路径。绝对路径在自己机器上没问题，换一台机器或者 marketplace 安装后很容易失效。

七、推荐的排查顺序

实际处理时建议按这个顺序来，效率比较高：

1. 确认插件根目录下存在 plugin.json。
2. 用 Node 解析 plugin.json，排除 JSON 格式错误。
3. 确认 entry 指向的 JS 文件存在。
4. 执行 npm install 和构建命令。
5. 单独启动 MCP server，确认没有依赖和端口问题。
6. 清理 Codex marketplace 和插件缓存。
7. 重启 Codex，再重新启用插件。
8. 最后看日志里的第一条异常，不要被后续连锁报错干扰。

总结

Codex plugin load failed 通常不是一个单点问题。优先查目录结构和 plugin.json，再看入口文件、依赖安装、marketplace 缓存，最后排 MCP 服务。不要一开始就重装环境，按日志和加载链路逐层排，基本都能定位到具体原因。