OpenAI Codex 插件开发指南 | 创建、测试与分发插件

本页面面向插件作者。如果你只是想浏览、安装和使用插件，请先看插件。如果你仍然只是在单个仓库或个人工作流里迭代，一个本地技能往往就足够了。只有当你希望把这个工作流分享给团队、把应用集成或 MCP 配置一起打包，或发布成稳定的可安装包时，再考虑做成插件。

使用 `$plugin-creator` 创建插件

最快的方式是直接使用内置的 $plugin-creator 技能。

它会自动生成必须的 .codex-plugin/plugin.json 清单文件，也可以顺手生成一个本地插件市场条目，方便你立即测试。如果你已经有一个插件目录，也可以继续用 $plugin-creator 把它接到本地插件市场中。

构建你自己的精选插件列表

插件市场清单（marketplace）是一个描述插件列表的 JSON 目录。$plugin-creator 可以先为单个插件生成一份 marketplace，之后你可以持续往同一个 marketplace 中追加条目，形成一个面向仓库、团队或个人工作流的精选插件列表。

在 Codex 中，每份 marketplace 都会作为插件目录里的一个可选来源出现。

仓库级 marketplace：$REPO_ROOT/.agents/plugins/marketplace.json
个人级 marketplace：~/.agents/plugins/marketplace.json

使用时，在 plugins[] 下为每个插件添加一条记录，把 source.path 指向插件目录，并使用相对于 marketplace 根目录的 ./ 前缀路径。interface.displayName 则控制 Codex 在插件市场选择器中显示的名称。完成后重启 Codex，打开插件目录，选中该 marketplace，就可以浏览和安装这份精选列表中的插件。

你不需要为每个插件单独维护一份 marketplace。一个 marketplace 完全可以在测试阶段只暴露一个插件，之后再逐步扩展成一个更完整的精选目录。

手动创建插件

你可以从一个只打包单个技能的最小插件开始。

创建插件目录，并在 .codex-plugin/plugin.json 中放入清单文件。

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

name 建议使用稳定的 kebab-case。Codex 会把它作为插件标识符和组件命名空间。

在 skills/<skill-name>/SKILL.md 下添加一个技能。

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.

把这个插件加入某个插件市场清单。你可以用 $plugin-creator 自动生成，也可以按下文的精选插件列表方式手动接入。

之后，你可以再按需加入 MCP 配置、应用集成或插件市场元数据。

手动安装本地插件

你可以根据插件面向的范围，选择仓库级插件市场清单或个人级插件市场清单。

把插件市场清单文件放到 $REPO_ROOT/.agents/plugins/marketplace.json，并把插件目录放到 $REPO_ROOT/plugins/ 下。

仓库级示例

步骤 1：把插件复制到 $REPO_ROOT/plugins/my-plugin。

mkdir -p ./plugins
cp -R /absolute/path/to/my-plugin ./plugins/my-plugin

步骤 2：创建或更新 $REPO_ROOT/.agents/plugins/marketplace.json，让 source.path 用带 ./ 前缀的相对路径指向该插件目录：

{
  "name": "local-repo",
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

步骤 3：重启 Codex，确认插件已经出现在插件目录中。

把插件市场清单文件放到 ~/.agents/plugins/marketplace.json，并把插件目录放到 ~/.codex/plugins/ 下。

个人级示例

步骤 1：把插件复制到 ~/.codex/plugins/my-plugin。

mkdir -p ~/.codex/plugins
cp -R /absolute/path/to/my-plugin ~/.codex/plugins/my-plugin

步骤 2：创建或更新 ~/.agents/plugins/marketplace.json，让对应插件条目的 source.path 指向这个目录。

步骤 3：重启 Codex，确认插件已经出现在插件目录中。

marketplace 文件决定的是“插件从哪里加载”，所以上述目录只是示例，并不是固定要求。Codex 会把 source.path 解释为相对于 marketplace 根目录的路径，而不是相对于 .agents/plugins/ 目录的路径。更多格式细节，请参见插件市场元数据。

修改本地插件后，请同步更新 marketplace 指向的插件目录，并重启 Codex，让本地安装副本能够加载新文件。

插件市场元数据

如果你维护仓库级 marketplace，请使用 $REPO_ROOT/.agents/plugins/marketplace.json；如果是个人级 marketplace，请使用 ~/.agents/plugins/marketplace.json。marketplace 文件控制的是 Codex 中的插件排序和安装策略。它既可以只描述一个测试中的插件，也可以描述一整组你希望一起展示的精选插件。在把插件加入 marketplace 之前，请先确认它的 version、发布者元数据，以及安装界面的展示文案已经准备好给其他开发者看。

{
  "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"
    },
    {
      "name": "research-helper",
      "source": {
        "source": "local",
        "path": "./plugins/research-helper"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

使用顶层 name 作为 marketplace 的稳定标识。
使用 interface.displayName 作为 Codex 中显示的 marketplace 标题。
在 plugins 下为每个插件添加一个对象，构成这份精选目录。
让每个插件条目的 source.path 指向你希望 Codex 加载的插件目录。仓库级安装通常会放在 ./plugins/ 下；个人级安装常见布局则是 ./.codex/plugins/<plugin-name>。
让 source.path 保持相对于 marketplace 根目录、使用 ./ 开头，并确保路径落在该根目录之内。
每个插件条目都应包含 policy.installation、policy.authentication 和 category。
policy.installation 常见值包括 AVAILABLE、INSTALLED_BY_DEFAULT 和 NOT_AVAILABLE。
用 policy.authentication 决定认证发生在安装时还是第一次使用时。

marketplace 决定的是 Codex 从哪里加载插件。即使你的插件并不在上述示例目录里，source.path 也可以指向别的位置。一个 marketplace 文件既可以放在你正在开发插件的仓库里，也可以放在独立的 marketplace 仓库里；同一个 marketplace 文件既可以只指向一个插件，也可以同时指向多个插件。

Codex 如何使用插件市场

插件 marketplace 是 Codex 可以读取并安装的 JSON 目录。

Codex 可以从以下位置读取 marketplace 文件：

官方 Plugin Directory 背后的精选 marketplace
仓库级 marketplace：$REPO_ROOT/.agents/plugins/marketplace.json
个人级 marketplace：~/.agents/plugins/marketplace.json

只要插件通过 marketplace 暴露出来，Codex 就可以安装它。Codex 会把插件安装到：

~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/

对于本地插件，$VERSION 会是 local。Codex 运行时读取的是这份缓存副本，而不是直接从 marketplace 条目里声明的位置运行。

每个插件都可以单独启用或禁用；Codex 会把它们的开关状态保存在 ~/.codex/config.toml 中。

打包与分发插件

插件结构

每个插件都必须在 .codex-plugin/plugin.json 中提供清单文件。除此之外，它还可以包含 skills/ 目录、指向应用或连接器的 .app.json、指向 MCP 服务端的 .mcp.json，以及用于展示插件的资源文件。

my-plugin/
├── .codex-plugin/
│   └── plugin.json          # 必需：插件清单文件
├── skills/
│   └── my-skill/
│       └── SKILL.md         # 可选：技能指令
├── .app.json                # 可选：app 或 connector 映射
├── .mcp.json                # 可选：MCP server 配置
└── assets/                  # 可选：图标、logo、截图

.codex-plugin/ 目录里只应该放 plugin.json。skills/、assets/、.mcp.json 和 .app.json 都应该放在插件根目录。

已发布插件通常会使用比最小脚手架示例更完整的 manifest。manifest 主要承担三项职责：

标识插件本身
指向它打包的技能、应用或 MCP 服务端
提供安装界面所需的描述、图标和法务链接等元数据

下面是一份完整的 manifest 示例：

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Bundle reusable skills and app integrations.",
  "author": {
    "name": "Your team",
    "email": "team@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/plugins/my-plugin",
  "repository": "https://github.com/example/my-plugin",
  "license": "MIT",
  "keywords": ["research", "crm"],
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "Reusable skills and apps",
    "longDescription": "Distribute skills and app integrations together.",
    "developerName": "Your team",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
    "websiteURL": "https://example.com",
    "privacyPolicyURL": "https://example.com/privacy",
    "termsOfServiceURL": "https://example.com/terms",
    "defaultPrompt": [
      "Use My Plugin to summarize new CRM notes.",
      "Use My Plugin to triage new customer follow-ups."
    ],
    "brandColor": "#10A37F",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "screenshots": ["./assets/screenshot-1.png"]
  }
}

.codex-plugin/plugin.json 是必需的入口文件。其他清单字段都是可选的，但对正式发布的插件来说，这些字段通常都会用到。

Manifest 字段

顶层字段用于定义包元数据，并指向插件打包的组件：

name、version 和 description 用于标识插件
author、homepage、repository、license 和 keywords 提供发布者与发现相关元数据
skills、mcpServers 和 apps 指向相对于插件根目录的组件入口
interface 控制安装界面如何展示这个插件

interface 对象用于定义安装界面元数据：

displayName、shortDescription 和 longDescription 控制标题和描述文案
developerName、category 和 capabilities 提供发布者与能力信息
websiteURL、privacyPolicyURL 和 termsOfServiceURL 提供外部链接
defaultPrompt、brandColor、composerIcon、logo 和 screenshots 控制启动提示和视觉呈现

路径规则

让 manifest 中的路径都保持相对于插件根目录，并使用 ./ 开头。
composerIcon、logo 和 screenshots 这类视觉资源，尽量统一放到 ./assets/ 下。
skills 应指向打包技能的目录，apps 应指向 .app.json，mcpServers 应指向 .mcp.json。

发布官方公共插件

把插件加入官方 Plugin Directory 的能力即将推出。

官方公共插件的自助发布与管理能力也即将推出。

来源：https://developers.openai.com/codex/plugins/build

最近搜索

推荐搜索

构建插件