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

把 AI 使用方式从“写 prompt”升级为“安装工作流能力包”npm（代码依赖）docker image（环境封装）workflow engine（流程封装）三者的结合体。MCP 服务体系（工具扩展）skills 工程化拆分（类似微服务）👉「Codex Plugin 从0到1完整开发示例（含 MCP 接入）」

weixin_41961749

506人浏览 · 2026-05-08 18:51:40

weixin_41961749 · 2026-05-08 18:51:40 发布

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 个关键结论（建议先记住）

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

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

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/"
}

常见字段解释：

字段	作用
name	插件唯一标识
version	版本控制
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

关键点：