锡膏管理优选指南：性价比与品质并重的选择
2026/7/2 3:01:50
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/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 能不能单独跑起来。日志里通常已经给了方向，只要按目录、清单、缓存、依赖、日志这个顺序排查，问题会收敛得很快。