第 06 章

Agent Plugins

把"规则 + 工具 + 能力"打包成一个可分发、可迁移、可共享的单元

一个 Plugin 就是一整套工作流——写一次，装到哪都生效

重复造轮子

你已经在第 04、05 章调好了 Skill 和 MCP，但它们是"散装"的

换项目全得重配

你在 A 项目调好了 3 个 MCP server、2 个 Skill、一段 AGENTS.md 规则。换到 B 项目，要把这些逐个再抄一遍——能不能打包带走？

没法分发给队友

你写了一套"提交前自动 lint + 生成 commit message"的工作流，想让团队所有人都用上。但现在只能口口相传、手动复制文件。

从别的工具搬过来

你之前用 Cursor、Claude Code，攒了一堆规则和工具配置。来到 Codex，难道要手动逐条重写？

本章解决这三件事：用 Plugin 把能力打包分发，用 marketplace 让团队开箱即用，用 /import 从其它工具一键迁移。

开始之前

适合谁

已读完前 4 章，会写 Skill、会配 MCP 的读者
想在多个项目间复用同一套配置的开发者
需要把团队工作流标准化、分发给成员的负责人

读完你应该能

解释 Plugin 是什么、和 Skill / MCP 的关系
从零写出一个可用的 Plugin 并验证它生效
用 marketplace 机制分发 Plugin 给团队
用 /import 从其它工具迁移设置

本章先不讲

Skill 的写法细节（第 04 章）
MCP server 的 stdio/HTTP 配置（第 05 章）
Subagents 编排（第 07 章）

版本要求：Plugin 体系于 2026-03-26 发布（随 Codex CLI 更新推出，对应 rust-v* 版本系列）。/import 对 Cursor / Claude Code 的迁移支持在 0.145.0（2026-07-21）扩展。请先 codex --version 确认为较新版本。

什么是 Plugin

一句话：Plugin 是一个打包了"Skill + MCP + App"的可分发单元

定义

Plugin 是一个带 manifest（.codex-plugin/plugin.json） 的目录，里面可以装 Skills、MCP server 配置、App 集成——一个包，多种东西。

白话

如果说 Skill 是一把螺丝刀，MCP 是接的一根电线，那 Plugin 就是一个工具箱——打开它，里面螺丝刀、电线、说明书全有，直接拎着走。

比喻卸甲：这个"工具箱"只是帮你建立直观印象。在 Codex 内部，Plugin 是一组被 .codex-plugin/plugin.json 索引的文本文件，安装时被 Codex 解析注册——它不是二进制，而是一组带清单的配置。

三者怎么分

Plugin / Skill / MCP 的边界，一张表说清

概念	本质	粒度	能否独立分发
Skill	一段可触发的方法论（SKILL.md）	单一能力	可，但通常作为 Plugin 的一部分
MCP	一个外部工具进程（server）	单一工具连接	不直接，靠 .mcp.json 声明
Plugin	打包上述内容的容器	一个完整工作流	是，这正是它的设计目的

记忆口诀：Skill 是"会做的事"，MCP 是"接的工具"，Plugin 是"打包送人的整套"。Plugin 可以同时包含前两者——它是前两章内容的容器和载体。

目录结构

一个 Plugin 就是一个自包含的目录，manifest 在 .codex-plugin/ 子目录里

my-plugin/
├── .codex-plugin/
│   └── plugin.json     ← manifest（必需）：Plugin 的"身份证"
├── skills/             ← 可选：打包的 Skills
│   └── lint-fix/
│       └── SKILL.md
├── .mcp.json           ← 可选：MCP server 配置
├── .app.json           ← 可选：App / 连接器映射
└── assets/             ← 可选：图标、logo、截图

必需 vs 可选

只有 .codex-plugin/plugin.json 是必需的——它是 Plugin 的身份证。其余文件按需添加：skills/、.mcp.json、.app.json 都可单独或缺省。

和 Skill 目录的区别

第 04 章的 Skill 目录里只有 SKILL.md。Plugin 目录多了 .codex-plugin/plugin.json 作为 manifest——有没有这个 manifest，是 Plugin 和裸 Skill 的分界线。

注意路径：manifest 不是放在根目录的 plugin.json，而是放在 .codex-plugin/plugin.json。点前缀目录容易被忽略，别漏掉。

Manifest 详解

.codex-plugin/plugin.json 决定 Plugin 如何被发现、加载、展示

{
  "name": "my-commit-helper",
  "version": "1.0.0",
  "description": "提交前自动 lint 修复 + 生成规范 commit message",
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
  "interface": {
    "displayName": "Commit Helper",
    "shortDescription": "lint + 提交规范一站式"
  }
}

字段	必需	作用
`name`	是	Plugin 的唯一标识，用 kebab-case（如 my-plugin）。Codex 用它做组件命名空间
`version`	建议	语义化版本，市场分发和升级时区分新旧
`description`	建议	一句话说明用途，展示在插件目录里
`skills`	否	指向 skills 目录（字符串如 `"./skills/"`）或数组
`mcpServers`	否	指向一个 `.mcp.json`，声明依赖的 MCP server
`apps`	否	指向一个 `.app.json`，声明依赖的 app / 连接器映射
`interface`	否	控制安装界面如何展示（displayName、capabilities 等）

最小可用：只要一个 .codex-plugin/plugin.json 带 name 字段，就是个合法 Plugin。其余字段按你要打包的内容逐步添加。

从零造一个 Plugin（1/3）

场景：把"提交前自动 lint + 生成 commit message"打包成团队可用的 Plugin

有两种方式起步——用内置脚手架，或手动建目录。

# 方式 A（推荐）：用内置 skill 脚手架自动生成
$ codex
> $plugin-creator
# 它会交互式问你名称、描述，自动生成 .codex-plugin/plugin.json
# 还能顺便生成一个本地 marketplace 条目用于测试

# 方式 B：手动建目录
$ mkdir -p my-commit-helper/.codex-plugin
$ mkdir -p my-commit-helper/skills/lint-fix

// my-commit-helper/.codex-plugin/plugin.json
{
  "name": "my-commit-helper",
  "version": "1.0.0",
  "description": "提交前自动 lint 修复，并生成规范 commit message",
  "skills": "./skills/",
  "mcpServers": "./.mcp.json"
}

为什么推荐 $plugin-creator：它不只生成 manifest，还会帮你搭好本地 marketplace 条目（后面讲为什么这很关键）。

从零造一个 Plugin（2/3）

第二步：填充 Skills 和 MCP 配置——用的就是前两章的格式

// skills/lint-fix/SKILL.md —— 复用第 04 章的写法
---
name: lint-fix
description: 提交前运行 lint 并自动修复。当用户说
 "提交""commit""帮我修 lint 错误"时触发。
---
# Lint 自动修复
1. 运行 `npm run lint -- --fix`
2. 汇报修复了哪些文件
3. 若有无法自动修复的，逐条列出原因

// .mcp.json —— 复用第 05 章的配置格式
{
  "servers": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

看到规律了吗：Plugin 的内容文件，用的就是第 04、05 章的格式——Plugin 没有发明新格式，它只是把已有的 Skills 和 MCP 装进一个带 .codex-plugin/plugin.json 的目录。

从零造一个 Plugin（3/3）

第三步：通过 marketplace 让 Codex 发现它，再安装验证

Codex 不扫描随意丢进目录的文件夹——它只从marketplace（插件清单）里发现 Plugin。你得先注册一个本地 marketplace：

// ~/.agents/plugins/marketplace.json（个人级）
// 或 .agents/plugins/marketplace.json（仓库级，团队共享）
{
  "name": "local",
  "plugins": [
    {
      "name": "my-commit-helper",
      "source": {
        "source": "local",
        "path": "./plugins/my-commit-helper"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

# 重启 Codex，打开插件目录
$ codex
> /plugins
# 在目录里找到 my-commit-helper → 选择 Install

验证闭环：装上 → 在 /plugins 里看到状态是 Installed → 提问"我们的提交规范是什么"看规则是否注入 → 说"帮我提交"看 Skill/MCP 是否触发。四步都通，这个 Plugin 才算"活了"。

运行时发生了什么

Plugin 被加载时，Codex 解析 manifest 并注册各组件

Codex 启动
  │
  ├─ 1. 读取已配置的 marketplace（~/.agents/plugins/marketplace.json
  │     和 .agents/plugins/marketplace.json）
  │
  ├─ 2. 解析每个已安装 Plugin 的 .codex-plugin/plugin.json
  │
  ├─ 3. 注册 skills 字段指向的 SKILL.md
  │     → 进入"可用 Skill 池"
  │       （仍走第 04 章的渐进式加载：先读 frontmatter，匹配才加载 body）
  │
  └─ 4. 注册 mcpServers 字段指向的 .mcp.json
        → 进入"可用工具池"
          （仍走第 05 章的机制：stdio / http，启动子进程或连接）

关键认知：Plugin 不"运行"任何东西——它只是一个装载清单。真正干活的是它装的两样东西：Skill（进匹配池）、MCP（进工具池）。Plugin 的价值在于把散件的安装原子化为一步。

插件目录与生命周期

用 /plugins 打开交互式目录，在里面浏览、安装、管理

$ codex
> /plugins
# 打开 Plugin Directory，CLI 按 marketplace 分组展示
# 顶部有 marketplace 源标签切换（如官方源、本地源等）
#   底部是 marketplace 源切换 + Add Marketplace 按钮
# 在 CLI 里可以：
#   - 浏览各 marketplace 下的 Plugin
#   - 打开 Plugin 详情 → Install plugin
#   - 对已装 Plugin 按空格键切换启用状态

安装

在目录里找到 Plugin，选择 Install plugin。Codex 把它写入 ~/.codex/plugins/，注册其中的 skills 和 MCP 工具。

启用 / 禁用（保留安装）

在 CLI 目录里对已装 Plugin按空格键切换启用状态；或在 ~/.codex/config.toml 里写 [plugins."name@source"] + enabled = false 后重启。

卸载

重新打开该 Plugin 详情，选择 Uninstall plugin。注意：卸载只移除 Plugin 包，它捆绑的 app 连接仍留在 ChatGPT 里，需另行管理。

需要凭证时：如果 Plugin 的 MCP server 需要 API key，安装时或首次使用时会提示输入，不会在安装时硬编码。

不是命令行子命令：Codex 没有 /plugin install、/plugin list 这类语法。一切通过 /plugins 打开的交互式目录完成。

Marketplace 机制

Plugin 的发现与分发，都靠 marketplace 这个 JSON 清单

什么是 marketplace

一个 JSON 文件，列出若干 Plugin 及其来源路径。Codex 启动时读取它，把列出的 Plugin 显示在插件目录里供人安装。

两个作用域

仓库级：.agents/plugins/marketplace.json + ./plugins/，提交 Git 后团队共享
个人级：~/.agents/plugins/marketplace.json + ~/.codex/plugins/，只给自己用

# 用 CLI 添加远程 marketplace（GitHub 仓库）
$ codex plugin marketplace add owner/repo
$ codex plugin marketplace add owner/repo --ref main

# 刷新 / 移除已配置的 marketplace
$ codex plugin marketplace upgrade marketplace-name
$ codex plugin marketplace remove marketplace-name

关键转变：以前是"每个人自己配 Skill + MCP"，现在是"一个人打包成 Plugin + 注册到 marketplace，整个团队 clone 后开箱即用"。

目录里的来源

/plugins 实际是两层结构：过滤标签 + marketplace 源

过滤标签（顶部）

按 marketplace 分组：CLI 按 marketplace 源分组展示 Plugin
Installed：已安装的 Plugin
官方精选：OpenAI 官方维护的 Plugin（GitHub、Slack 等）
Workspace：当前仓库级 marketplace 里的

注：具体标签名称可能因 CLI / App 版本而异，以你本地的 /plugins 界面为准。

Marketplace 源（底部）

默认官方源：OpenAI 维护的公共 Plugin 目录
用 Add Marketplace 按钮接入更多源（GitHub 仓库、团队私有源等）
也可在命令行用 codex plugin marketplace add <owner/repo> 添加

典型官方 Plugin：GitHub、Gmail、Google Drive、Slack、Linear、Notion、Figma、Sentry、Vercel 等，都在 OpenAI Curated 标签下。

安全提醒：从外部 marketplace 安装前，务必看一眼 Plugin 的 .codex-plugin/plugin.json 和 .mcp.json——它会获得哪些权限（网络、文件、token）。Plugin 能装的不只是能力，还有它的全部权限。

安装前的权限审查

Plugin = Skill + MCP，也就等于两者的权限总和

看 manifest

检查 skills（会注入可触发能力）、mcpServers（会接入外部工具）。这些字段决定了 Plugin 装上后能干什么。

看 .mcp.json

里面的 server 有没有网络访问、文件读写、敏感 token。一个恶意的 MCP server 能干的事，装它的 Plugin 也能干。

最小验证

陌生 Plugin 先配合第 09 章的 read_only 沙箱试跑，确认行为正常再放开权限。

原则：只装可信来源。Plugin 把"分散配置"变成了"一键安装"，便利性提升了，但一次错误安装的破坏面也更大。

/import 迁移

从其它工具一键搬设置过来——这是进入 Plugin 生态的另一条入口

$ codex
> /import

执行 /import 后，Codex 会引导你选择来源工具，然后迁移以下内容：

能迁移什么

settings：审批策略、模型偏好等配置
MCP servers：工具连接直接搬过来
plugins：已装的插件
sessions：历史会话记录
commands：自定义 slash 命令
project memories：项目级长期记忆

支持来源

Cursor：规则文件、MCP 配置
Claude Code：CLAUDE.md、MCP、plugins、memories

为什么放在这章：/import 搬过来的"规则 + MCP + 插件"，本质就是一堆待整理的 Plugin 原料。迁过来后，你可以再用本章的方法把它们打包成一个自己的 Plugin。

版本背景：/import 最初在 v0.140.0 引入（仅支持 Claude Code），v0.145.0（2026-07-21）扩展到 Cursor 并新增 project-scoped memories 迁移。

迁移实战

从 Claude Code 搬到 Codex 的完整流程

# 1. 确保 Claude Code 的配置还在默认位置
#    （~/.claude/ 或项目内 .claude/）

# 2. 在 Codex 里执行
$ codex
> /import
# 选择来源：Claude Code

# 3. Codex 扫描并展示可迁移项
#    [x] CLAUDE.md → 转写为 AGENTS.md
#    [x] 3 个 MCP servers
#    [x] memories (12 条)

# 4. 确认 → 自动写入 Codex 配置

常见错误 1

manifest 放错位置（不是根目录的 plugin.json）

症状

你建了个目录，在根目录放了 plugin.json，结果 /plugins 目录里根本看不到它。

原因

Codex 只认 .codex-plugin/plugin.json 这个子目录路径。根目录的 plugin.json 会被忽略——这是最常见的疏漏。

解决：manifest 必须放在 my-plugin/.codex-plugin/plugin.json。注意那个点前缀目录，它容易被漏掉。

常见错误 2

没注册 marketplace，指望"丢进目录就能被发现"

症状

你把 Plugin 文件夹复制进了 ~/.codex/plugins/，重启 Codex，但 /plugins 里看不到它。

原因

Codex 不扫描随意放置的文件夹——它只读 marketplace 清单（~/.agents/plugins/marketplace.json 或 .agents/plugins/marketplace.json）里列出的 Plugin。

解决：用 $plugin-creator 生成 marketplace 条目，或手动在 marketplace.json 里加一条 source.path 指向你的 Plugin 目录，再重启 Codex。

常见错误 3

把不该共享的 secret 提交进仓库

症状

团队 Plugin 提交进 Git 后，队友 clone 下来，MCP server 报鉴权失败——或者更糟，你的 token 泄露了。

原因

Plugin 里的 .mcp.json 直接硬编码了 token。这和第 05 章的 .mcp.json 是同一个坑，只是搬进了 Plugin。

解决：用环境变量引用（"env": { "GITHUB_TOKEN": "$GH_TOKEN" }），把 secret 留在每人本地的环境里。Plugin 仓库只放配置，不放凭证。需要凭证的 Plugin 在首次运行时弹窗提示输入。

何时该打包

Plugin 不是万能的，看场景选

场景	推荐	原因
个人一次性脚本	手写配置	打包成本 > 收益
团队多人复用	Plugin + marketplace	一份分发，人人一致
对外发布工作流	Plugin + 公开 marketplace	版本管控、可发现
跨工具迁移	/import	搬的是配置，不是包

官方建议：还在一个仓库、一条个人工作流里反复改，就先用本地 Skill。想跨团队共享、想打包 App/MCP 配置、想发稳定版本了，才上 Plugin。

速查表

功能	命令 / 位置	说明
打开插件目录	`/plugins`	交互式浏览、安装、卸载
Plugin 脚手架	`$plugin-creator`	生成 manifest + marketplace 条目
添加 marketplace	`codex plugin marketplace add <owner/repo>`	接入远程插件源
刷新 marketplace	`codex plugin marketplace upgrade`	拉取最新插件列表
仓库级 marketplace	`.agents/plugins/marketplace.json`	团队共享，提交 Git
个人级 marketplace	`~/.agents/plugins/marketplace.json`	只给自己用
从它工具迁移	`/import`	Cursor / Claude Code → Codex

动手练习

三个递进的小任务，每个都给出"做对了应该看到什么"

练习 1：最小 Plugin

用 $plugin-creator 生成一个最小 Plugin，注册到本地 marketplace。预期：执行 /plugins 后，在 Workspace 标签下能看到它。

练习 2：打包一个真实能力

把第 04 章写的某个 Skill，加 .codex-plugin/plugin.json 打包成 Plugin，通过 marketplace 安装。预期：装好后能像原来一样触发那个 Skill。

练习 3：思考题

如果你的团队有 10 个人、3 个项目，什么样的内容适合做成 Plugin 分发？什么样的留在各自的 AGENTS.md 里？

检查理解

试着不看上面，回答这几个问题

Plugin、Skill、MCP 三者的核心区别是什么？
manifest 必须放在哪个路径？为什么根目录的 plugin.json 不行？
Plugin 被加载时，它的内容各自去了哪里？
为什么光把 Plugin 文件夹丢进 ~/.codex/plugins/ 不够，还得注册 marketplace？

如果答得上来：你已经掌握了 Codex 的 Plugin 体系——把零散的规则、能力、工具，打包成可流动的整体。接下来第 07 章我们会进入 Subagents——让 Codex 分裂成多个专家并行工作。

第 06 章总结

本章要点

Plugin 是什么

打包"Skills + MCP + App"的可分发容器
标志是 .codex-plugin/plugin.json（manifest），放在点前缀子目录里
内容文件复用第 04、05 章的格式，没有发明新东西

怎么用

浏览/安装：/plugins 打开交互式目录
分发：marketplace 清单（仓库级或个人级）
脚手架：$plugin-creator 一键生成
迁移：/import 从 Cursor / Claude Code 搬配置

下一步：第 07 章 Subagents —— Plugin 让你把能力打包分发，Subagents 则让 Codex 分裂成多个专家并行工作，处理更复杂的任务。