20. Plugins插件开发

插件 vs 技能

上一章学的 Skill 是「编写格式」—你把一套工作流写成 SKILL.md，Codex 按需调用。但它默认只在你自己机器、你自己仓库里转。想给团队用怎么办？

Plugin 是「分发格式」—把 Skills、MCP 配置、App 集成和生命周期 Hook 打成一个能整体装卸、一键安装的套装包。

打个比方：Skill 是你自己手写的一份操作手册，放在你工位上；Plugin 是把这份手册连同工具箱一起打包，贴上标签发到公司内网，同事点一下就全套到手。

维度	散装 Skill（本地自用）	Plugin（插件）
最适合	单仓库自用、个人工作流	跨团队共享、打包多种组件
打包什么	通常就一个 skill	skills + MCP + App + Hook
怎么共享	手动复制文件	通过市场或工作区分享，一键安装
能不能版本化	不强调	有 version 字段，按版本发布

插件能打包什么

一个插件可以包含三类组件：

组件	是什么	装进来后怎么用
Skills	可复用的工作流指令	描述任务时自动选用，或用 @ 显式点名
Apps	连接 GitHub、Slack 等外部服务的通道	装时或首次用时按提示授权
MCP servers	给 Codex 接更多工具的服务	可能需要额外配置或认证
Hooks	生命周期钩子	默认不被信任，需审阅后才运行

插件目录结构

每个插件必须在 .codex-plugin/plugin.json 中提供清单文件，其他组件按需放在插件根目录下：

my-plugin/
├── .codex-plugin/
│   └── plugin.json          # 必需：插件清单
├── skills/
│   └── my-skill/
│       └── SKILL.md         # 可选：技能指令
├── hooks/
│   └── hooks.json           # 可选：生命周期钩子
├── .app.json                # 可选：App 或连接器映射
├── .mcp.json                # 可选：MCP server 配置
└── assets/                  # 可选：图标、截图等素材

清单文件 plugin.json

最小清单只需要几个字段：

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow",
  "skills": "./skills/"
}

name 建议用 kebab-case（小写加连字符），它是插件的标识符和组件命名空间。

发布级插件通常用更完整的清单：

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Bundle reusable skills and connectors.",
  "author": {
    "name": "Your team",
    "email": "team@example.com"
  },
  "homepage": "https://example.com/plugins/my-plugin",
  "license": "MIT",
  "keywords": ["research", "crm"],
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "hooks": "./hooks/hooks.json",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "Reusable skills and connectors",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
    "brandColor": "#10A37F",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png"
  }
}

清单字段说明

字段	说明
name / version / description	标识插件
author / homepage / license / keywords	发布者与发现元数据
skills	指向打包技能的目录，以 ./ 开头
mcpServers	指向 .mcp.json 文件
apps	指向 .app.json 文件
hooks	指向生命周期钩子文件（用默认路径 ./hooks/hooks.json 可省略此字段）
interface	控制安装界面的展示信息

路径规则

• 所有路径相对于插件根目录，以 ./ 开头
• 视觉资源统一放 ./assets/ 下
• 如果 hooks 放在 ./hooks/hooks.json，清单里不用写 hooks 字段，Codex 自动检查

用 @plugin-creator 创建插件

最快的方式是使用内置的 @plugin-creator（CLI 中用 $plugin-creator）技能：

@plugin-creator create a plugin for my workflow.
Include a personal marketplace entry so I can test it locally.

它会自动生成必需的 .codex-plugin/plugin.json 清单文件，还能顺手生成一个本地插件市场条目，方便你立即测试。已有插件目录也能用它接到本地市场中。

插件市场

插件市场（Marketplace）是一个描述插件列表的 JSON 目录。ChatGPT 桌面 App 会把它作为 Plugins Directory 里的一个可选来源。

市场文件位置

类型	位置
仓库级	$REPO_ROOT/.agents/plugins/marketplace.json
个人级	~/.agents/plugins/marketplace.json

市场文件格式

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

source.path 相对于插件市场根目录，以 ./ 开头。policy.installation 常见值包括 AVAILABLE、INSTALLED_BY_DEFAULT 和 NOT_AVAILABLE。

从 Git 仓库添加市场

也可以指向基于 Git 的插件来源：

{
  "name": "remote-helper",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/example/codex-plugins.git",
    "path": "./plugins/remote-helper",
    "ref": "main"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

手动创建和安装插件

第一步：创建插件目录和清单

mkdir -p my-first-plugin/.codex-plugin

写 my-first-plugin/.codex-plugin/plugin.json：

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow",
  "skills": "./skills/"
}

第二步：添加一个技能

mkdir -p my-first-plugin/skills/hello

写 my-first-plugin/skills/hello/SKILL.md：

---
name: hello
description: Greet the user with a friendly message.
---

Greet the user warmly and ask how you can help.

第三步：安装到本地

仓库级安装：

1. 把插件复制到 $REPO_ROOT/plugins/my-plugin
2. 创建或更新 $REPO_ROOT/.agents/plugins/marketplace.json，让 source.path 指向插件目录
3. 重启 ChatGPT 桌面 App

个人级安装：

1. 把插件复制到 ~/.codex/plugins/my-plugin
2. 创建或更新 ~/.agents/plugins/marketplace.json
3. 重启 ChatGPT 桌面 App

从 CLI 管理插件市场

CLI 提供了一组子命令来管理插件市场来源：

# 添加市场（GitHub 简写）
codex plugin marketplace add owner/repo

# 添加市场（指定分支）
codex plugin marketplace add owner/repo --ref main

# 添加市场（本地路径）
codex plugin marketplace add ./local-marketplace-root

# 查看已配置的市场
codex plugin marketplace list

# 刷新所有市场
codex plugin marketplace upgrade

# 刷新指定市场
codex plugin marketplace upgrade marketplace-name

# 移除市场
codex plugin marketplace remove marketplace-name

在会话中浏览和安装

启动 Codex 后，在对话里输入：

/plugins

会弹出插件浏览器，按市场分组。点开一个插件看详情，选 Install plugin 安装。在已安装的插件上按 Space 键可以切换启用状态。

安装后新开一个线程再让 Codex 使用插件。

调用插件

两种方式调用已安装的插件：

• 描述任务让 Codex 自己选：正常说需求，Codex 自动挑该用哪个插件
• 用 @ 点名：输入 @ 加插件名或技能名，显式调用

@my-plugin

禁用插件

不想删但暂时不用，在 ~/.codex/config.toml 里设：

[plugins."gmail@openai-curated"]
enabled = false

key 的格式是 插件名@市场名。改完重启 Codex。

与工作区共享

创建插件后，可以从 ChatGPT 桌面 App 分享给工作区成员：

1. 打开 Plugins
2. 进入 Created by you
3. 打开插件详情页，选 Share
4. 添加工作区成员或群组，或复制共享链接

打包 MCP 服务器和 Hook

MCP 服务器

.mcp.json 文件可以直接包含 server 映射：

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

安装后，用户可以在 Codex 配置中启用或禁用插件打包的 MCP server，调整工具审批策略，不需要修改插件本身：

[plugins."my-plugin".mcp_servers.docs]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["search"]

Hook

默认的插件钩子文件是 hooks/hooks.json。插件钩子命令会收到环境变量 PLUGIN_ROOT（指向已安装插件根目录）和 PLUGIN_DATA（指向插件的可写数据目录）。

小结

你想干啥	怎么做
快速创建插件	用 @plugin-creator 生成脚手架
手动创建	建 .codex-plugin/plugin.json + 组件目录
搭建插件市场	写 marketplace.json，放 .agents/plugins/ 下
CLI 管理市场	codex plugin marketplace add/list/upgrade/remove
会话里装插件	/plugins 浏览和安装
调用插件	@插件名 或描述任务让 Codex 自己选
禁用插件	config.toml 里 [plugins."名@市场"] enabled = false
分享给团队	ChatGPT App > Plugins > Share
打包 MCP/Hook	放 .mcp.json 和 hooks/hooks.json

插件的核心价值在「规模」—跨项目复用、团队共享、统一管理发版本。单条工作流自用写 Skill 就行，要给别人用、要把一堆配置打成一包、要发版本才打成插件。记住那条铁律：.codex-plugin/ 里只放 plugin.json，其他组件全摆根目录。还有，插件里的 Hook 默认不被信任，要审过才跑。

下一章讲 Hooks 钩子—怎么在 Codex 干活流程的特定时机自动跑脚本。