Codex插件加载失败的根本原因是plugin.json字段不合规：必须严格满足required字段、语义化version、合法name格式、显式声明skills路径、正确配置assets和mcpServers相对路径。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你想让 Codex 在本地加载一个自己写的插件，但 plugin.json 总是报错、不被识别、或者装上去没图标没技能——根本原因往往就藏在 plugin.json 的字段写法里。这个文件不是随便填几个键值对就能跑起来的 JSON，它必须严格匹配 Codex CLI 的解析规则，少一个 required 字段、多一个非法 key、路径写错斜杠方向，插件就会静默失败。
确认插件根目录和基础结构
在终端中进入你准备存放插件的目录，比如 ~/plugins/my-first-plugin；【必须确保该目录下没有 package.json 或 node_modules】，否则 Codex CLI 会误判为 npm 包而跳过扫描。
创建 .codex-plugin 子目录：mkdir -p .codex-plugin
在这个子目录里新建 plugin.json 文件：touch .codex-plugin/plugin.json
plugin.json 必填字段与格式规范
打开 .codex-plugin/plugin.json，用 VS Code 或其他纯文本编辑器粘贴以下最小合法结构：
{
"name": "my-first-plugin",
"description": "A minimal working plugin",
"version": "0.1.0",
"author": {"name": "You"},
"license": "MIT"
}
注意：name 字段只能含小写字母、数字、连字符（-），不能有空格或下划线；【version 必须是语义化版本格式 x.y.z，写成 0.1 或 1 不会被接受】。
保存后，在终端运行 codex plugins list，如果看到 my-first-plugin 出现在列表中且状态为 “enabled”，说明 plugin.json 基础结构已通过校验。
添加技能入口：skills 路径必须显式声明
如果你的插件包含技能（即 skills/**/SKILL.md），必须在 plugin.json 中显式声明 skills 字段，不能依赖默认路径。
方法一：单个技能目录
在 plugin.json 的根对象里追加一行： "skills": ["skills/"]
方法二：多个技能目录
写成数组形式："skills": ["skills/", "extra-skills/"]
【Codex 不会自动扫描 skills/ 目录，不写 skills 字段 = 技能完全不可见】。即使 SKILL.md 文件存在且格式正确，也不会被加载。
图标与资产路径配置
第一步：把 icon.png 放到插件根目录（不是 .codex-plugin 下）
第二步：在 plugin.json 中添加 assets 字段：
"assets": { "icon": "icon.png" }
第三步：确保 icon.png 是 128×128 像素、PNG 格式、无透明通道（部分 macOS 渲染器对 alpha 通道支持不稳定）
这一步操作起来很简单，直接把文件拖进去就行。但如果你用 Sketch 或 Figma 导出带透明底的 PNG，图标在 Codex App 里可能显示为全黑或空白。
关联 MCP Server 的正确写法
第一步：在插件根目录创建 .mcp.json 文件
第二步：确保 .mcp.json 内容是合法 JSON 对象，至少含 name 和 endpoint 字段，例如：
{ "name": "my-mcp", "endpoint": "http://localhost:8080" }
第三步：回到 plugin.json，在根对象中添加字段：
"mcpServers": ".mcp.json"
【mcpServers 字段值必须是相对插件根目录的路径字符串，不能是数组，不能带前导 ./】。写成 "./.mcp.json" 或 ["./.mcp.json"] 都会导致 MCP 服务注册失败。
