Codex 插件加载失败解决方法

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 -print

2. 检查 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 build

3. 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 --help

marketplace 相关问题还要注意网络环境。有些插件安装过程中需要拉 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/node"

5. 看日志，不要只看界面提示

界面上的“加载失败”通常太粗。排查插件开发问题，日志更重要。可以先用调试模式启动：

CODEX_LOG_LEVEL=debug codex

或者查看本地日志目录：

ls -lt ~/.codex/logs
tail -n 200 ~/.codex/logs/codex.log

常见错误可以这样判断：

• invalid plugin manifest：优先检查 plugin.json 格式、字段类型、逗号和路径。
• entry file not found：检查 main 指向的文件是否存在，是否忘记构建。
• unsupported engine：Codex 版本低于插件要求，升级 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_LEVEL=debug codex

另外，开发阶段不要频繁改插件名。Codex 缓存、marketplace 索引和本地插件目录都可能用 name 做标识，名字来回改很容易出现“旧插件还在、新插件不加载”的错觉。需要改名时，最好同步清理旧目录和缓存。

总结

Codex 插件加载失败不要先怀疑插件机制本身，先从最容易出错的地方查：目录根位置是否正确，plugin.json 是否合法，main 文件是否存在，marketplace 缓存是否刷新，MCP server 能不能单独跑起来。日志里通常已经给了方向，只要按目录、清单、缓存、依赖、日志这个顺序排查，问题会收敛得很快。