Codex plugin load failed 插件加载失败解决方法-CSDN博客

odex 出现 plugin load failed，通常不是 Codex 本身坏了，而是插件目录、plugin.json、marketplace 配置、MCP 服务或网络鉴权有一处没有被正确加载。下面按最常见原因逐步排查。

一、先确认插件是否被 Codex 识别

在终端执行：

codex --version
codex plugin marketplace list

如果 marketplace 列表里没有你的插件来源，说明 Codex 还没有读到插件市场配置。可以刷新一次：

codex plugin marketplace upgrade

修改插件文件、marketplace 文件后，建议重启 Codex。Codex 本地插件通常会安装到缓存目录，改了源文件但没有刷新或重启，很容易出现“明明改了但还是加载失败”的情况。

二、检查插件目录结构

一个标准 Codex 插件至少需要这个结构：

my-plugin/
  .codex-plugin/
    plugin.json
  skills/
    my-skill/
      SKILL.md

注意：只有 plugin.json 放在 .codex-plugin/ 目录里，skills/、hooks/、.mcp.json、.app.json、assets/ 都应该放在插件根目录。

最小可用的 plugin.json 示例：

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My Codex plugin",
  "skills": "./skills/"
}

常见错误包括：

把 skills/ 放进了 .codex-plugin/
plugin.json 文件名写错
name 使用了空格、中文或特殊字符
skills 路径没有使用 ./ 开头
插件目录被移动后，marketplace 里的路径没有同步更新

三、检查 marketplace.json 配置

如果是本地插件，常见 marketplace 文件位置有两个：

项目级：$REPO_ROOT/.agents/plugins/marketplace.json
个人级：~/.agents/plugins/marketplace.json

示例配置：

{
  "name": "local-plugins",
  "interface": {
    "displayName": "Local Plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

重点检查 source.path。它必须是相对于 marketplace 根目录的路径，并且通常要以 ./ 开头。如果路径写成绝对路径、写错层级，Codex 可能会跳过该插件或显示加载失败。

四、验证 JSON 是否有效

很多 plugin load failed 是 JSON 格式问题导致的，例如多了尾逗号、少了引号、注释写进 JSON。

可以执行：

node -e "JSON.parse(require('fs').readFileSync('.codex-plugin/plugin.json','utf8')); console.log('plugin.json OK')"

如果 marketplace 也需要检查：

node -e "JSON.parse(require('fs').readFileSync('.agents/plugins/marketplace.json','utf8')); console.log('marketplace.json OK')"

五、检查 Skill 文件头

如果插件包含 Skill，SKILL.md 顶部建议包含 front matter：

---
name: my-skill
description: Use this skill for a specific Codex workflow.
---

这里写技能说明。

常见错误：

--- 没有成对出现
name 为空
description 太模糊或格式异常
文件编码异常

六、MCP 插件加载失败的排查

如果插件里配置了 MCP，通常会有：

{
  "mcpServers": "./.mcp.json"
}

.mcp.json 示例：

{
  "docs": {
    "command": "docs-mcp",
    "args": ["--stdio"]
  }
}

需要确认：

command 在当前系统 PATH 中可执行
Node、Python 或对应运行时已安装
MCP 服务能单独启动
Windows 下路径不要混用错误的斜杠和转义字符
企业网络或代理没有拦截服务请求

如果 MCP 依赖外部 API，经常出现连接超时、鉴权失败、请求失败等问题。这种情况下可以考虑使用稳定的 API 中转方案，例如 token云桥中转站：api.0029.org。配置时一般需要把插件或 MCP 服务里的 base_url / api_base 指向中转地址，并使用对应的 API Key。建议使用专用 Key、控制额度，并确认 HTTPS、日志和隐私策略，避免把主账号密钥直接暴露给不可信环境。

七、检查 Codex 配置优先级

Codex 配置可能来自多个位置：

用户配置：~/.codex/config.toml
项目配置：.codex/config.toml

如果项目没有被信任，项目级 .codex/ 配置可能不会加载。遇到插件启用状态异常、MCP 配置不生效时，可以先检查 ~/.codex/config.toml 中是否有插件相关配置被关闭。

八、清理缓存后重新安装

如果确认插件结构没问题，但 Codex 仍然加载旧版本，可以尝试：

codex plugin marketplace upgrade

然后重启 Codex。

如果是本地插件，建议修改版本号：

{
  "name": "my-plugin",
  "version": "1.0.1"
}

版本号不变时，某些缓存场景下容易继续加载旧文件。

九、快速修复清单

确认 codex --version 是最新版本
确认 .codex-plugin/plugin.json 存在
确认 plugin.json 是合法 JSON
确认 skills、hooks、mcpServers 路径以 ./ 开头
确认 marketplace 的 source.path 指向正确插件目录
执行 codex plugin marketplace list 查看来源
执行 codex plugin marketplace upgrade 刷新
重启 Codex
如果涉及 API/MCP，检查网络、代理、Key 和 Base URL

总结

Codex plugin load failed 的核心排查思路是：先看 Codex 有没有读到 marketplace，再看插件目录结构，再看 plugin.json 和路径规则，最后排查 MCP、网络和 API 鉴权。大多数问题都能通过修正路径、刷新 marketplace、重启 Codex 解决。涉及外部 API 时，可以使用 token云桥中转站 api.0029.org 这类中转服务改善连接与统一配置，但要注意密钥安全和服务合规。