Codex Plugins 插件机制与本地安装教程

Codex Plugins 插件机制与本地安装教程

关键词： Codex Plugins、OpenAI 插件系统、Codex plugin.json、Codex 本地插件安装、marketplace 插件目录、Codex skills、MCP 插件、AI 工作流插件化

在这里插入图片描述

📌 这篇内容基于 OpenAI Codex 官方 Plugins 文档整理，重点从“能实际用起来”的角度解释：插件是什么、怎么安装、本地怎么跑通，以及 plugin.json 的结构到底在干什么。

一、Codex Plugins 是什么（先建立正确认知）

Codex Plugins 本质不是“浏览器插件”或“IDE 扩展”，而是一个更偏工程化的概念：

一套可复用的 AI 工作流打包方案（Workflow Bundle）

可以把它理解成：

• 一套 prompt + 规则 + 工具调用方式的封装
• 可跨项目安装复用
• 类似“npm 包”，但内容是 AI 工作流能力

一个插件通常可以包含：

• Skills：具体任务执行规则（核心）
• Apps：外部应用集成（可选）
• MCP servers：外部工具/上下文服务（可选）

二、官方插件目录长什么样

官方文档里的插件目录更像一个“能力市场”：

插件目录

它不是简单列表，而是：

Codex 能力的可安装集合（类似工作流商店）

三、6 个关键结论（建议先记住）

1. Codex Plugin = 可安装的 AI 工作流包
2. 一个插件 = skills +（apps + MCP）组合
3. CLI / UI 都可以安装插件
4. 小需求先写 skill，不一定要做 plugin
5. 需要跨项目复用时才升级为 plugin
6. 官方公共插件发布能力仍在逐步开放

四、普通用户怎么使用插件

1）在 Codex App 中安装

官方提供插件目录入口，可以直接安装：

• 选择插件
• 一键启用
• 自动加载 skills / 工具配置

这一步的意义是：

不需要手写 prompt 体系，直接用别人封装好的工作流

2）CLI 方式使用插件

在命令行中：

codex
/plugins

界面效果如下：

CLI插件界面

说明一点：

Codex 插件体系是 CLI + GUI 双入口的，而不是只服务网页端

五、本地插件怎么创建（核心重点）

方式1：使用 @plugin-creator（推荐）

官方推荐方式是：

@plugin-creator

它可以自动帮你生成：

• plugin.json
• 本地插件结构
• marketplace 配置（用于测试）

效果：

plugin creator

方式2：手动创建（理解结构用）

一个最小插件结构如下：

my-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   └── demo-skill/
│       └── SKILL.md

六、plugin.json 是什么（核心配置）

最简版本：

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "一个可复用工作流插件",
  "skills": "./skills/"
}

常见字段解释：

七、marketplace 是什么（容易误解点）

很多人会误以为 marketplace 是“插件商店”，实际上：

marketplace = 插件索引 JSON 文件

Codex 通过它来加载插件列表。

1）Repo marketplace（仓库级）

适用于项目内插件：

$REPO_ROOT/.agents/plugins/marketplace.json

插件目录：

$REPO_ROOT/plugins/my-plugin

示例结构：

{
  "name": "local-repo",
  "interface": {
    "displayName": "项目插件集"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

2）Personal marketplace（个人级）

适用于跨项目复用：

~/.agents/plugins/marketplace.json

插件目录：

~/.codex/plugins/my-plugin

八、插件缓存机制（理解安装过程）

Codex 安装后会缓存插件：

~/.codex/plugins/cache/$MARKETPLACE/$PLUGIN/$VERSION/

本地插件版本通常是：

local

启用状态记录在：

~/.codex/config.toml

九、完整插件目录结构

一个标准插件通常如下：

my-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── .app.json
├── .mcp.json
└── assets/
    ├── icon.png
    └── logo.png

关键点：

• .codex-plugin/ 是入口
• skills 是核心逻辑
• mcp/app 是扩展能力
• assets 是展示资源

十、什么时候需要做 plugin

✔ 适合做 plugin：

• 多项目复用同一套工作流
• 需要团队统一能力
• skills + MCP + 工具链组合使用

✔ 不适合：

• 单项目临时逻辑
• 还在试验阶段
• 只需要一个 prompt

十一、最小可运行路径（建议流程）

一个比较稳的实践路径：

1. 先写 SKILL.md
2. 在当前项目验证效果
3. 再封装 plugin.json
4. 加入 marketplace
5. 最后扩展 MCP / Apps

十二、官方当前状态

根据文档：

• 插件目录：已存在
• 本地插件：支持完整
• marketplace：支持本地
• 公共发布：仍在推进中（coming soon）

总结

Codex Plugins 本质上是在做一件事：

把 AI 使用方式从“写 prompt”升级为“安装工作流能力包”

它更接近：

• npm（代码依赖）
• docker image（环境封装）
• workflow engine（流程封装）

三者的结合体。

如果后面要进一步落地，通常会延伸到两个方向：

• MCP 服务体系（工具扩展）
• skills 工程化拆分（类似微服务）

如果你需要，我可以再补一篇更偏实战的：

• 👉「Codex Plugin 从0到1完整开发示例（含 MCP 接入）」