构建自己的插件

这篇面向 plugin 作者。

如果你只是想在 Codex 中浏览、安装和使用 plugins，请看 Plugins。

如果你还在某个 repo 或个人工作流中迭代，先从本地 skill 开始。

当你想跨团队共享工作流、打包 app integrations 或 MCP config，或发布稳定包时，再构建 plugin。

用 $plugin-creator 创建插件

最快 setup 方式，是使用内置 $plugin-creator skill。

截图：

• light mode：https://developers.openai.com/images/codex/plugins/plugin-creator.png
• dark mode：https://developers.openai.com/images/codex/plugins/plugin-creator-dark.png

它会 scaffold required .codex-plugin/plugin.json manifest，也可以生成用于测试的 local marketplace entry。

如果你已经有 plugin folder，仍然可以使用 $plugin-creator 把它接入 local marketplace。

invoke 截图：

• light mode：https://developers.openai.com/images/codex/plugins/plugin-creator-invoke.png
• dark mode：https://developers.openai.com/images/codex/plugins/plugin-creator-invoke-dark.png

构建自己的精选插件清单

marketplace 是一个 plugin JSON catalog。

$plugin-creator 可以为单个 plugin 生成 marketplace；你也可以持续向同一个 marketplace 添加 entries，为 repo、team 或 personal workflow 构建 curated list。

在 Codex 中，每个 marketplace 都会作为 plugin directory 中可选择的 source 出现。

路径建议：

• repo-scoped list：$REPO_ROOT/.agents/plugins/marketplace.json
• personal list：~/.agents/plugins/marketplace.json

做法：

1. 在 plugins[] 下为每个 plugin 添加一个 entry。
2. 让每个 source.path 指向 plugin folder。
3. source.path 使用相对 marketplace root 的路径，并以 ./ 开头。
4. 设置 interface.displayName，作为 Codex 在 marketplace picker 中展示的 label。
5. restart Codex。
6. 打开 plugin directory，选择你的 marketplace，然后 browse 或 install curated list 中的 plugins。

不需要为每个 plugin 单独创建 marketplace。一个 marketplace 可以在测试时只暴露一个 plugin，之后随着你添加更多 plugins，逐步变成更大的 curated catalog。

截图：

• light mode：https://developers.openai.com/images/codex/plugins/codex-local-plugin-light.png
• dark mode：https://developers.openai.com/images/codex/plugins/codex-local-plugin.png

从 CLI 添加 marketplace

如果你希望 Codex 为你 install 和 track marketplace source，而不是手动编辑 config.toml，使用 codex plugin marketplace add。

codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-root

marketplace sources 可以是：

• GitHub shorthand，例如 owner/repo 或 owner/repo@ref。
• HTTP 或 HTTPS Git URLs。
• SSH Git URLs。
• local marketplace root directories。

使用 --ref 可以 pin Git ref。

对 Git-backed marketplace repos，可以重复使用 --sparse PATH 进行 sparse checkout。--sparse 只适用于 Git marketplace sources。

刷新或移除 configured marketplaces：

codex plugin marketplace upgrade
codex plugin marketplace upgrade marketplace-name
codex plugin marketplace remove marketplace-name

手动创建 plugin

先从一个只打包一个 skill 的 minimal plugin 开始。

1. 创建 plugin folder，并在 .codex-plugin/plugin.json 放 manifest。

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

使用 stable plugin name，格式为 kebab-case。Codex 会把它作为 plugin identifier 和 component namespace。

2. 在 skills/<skill-name>/SKILL.md 下添加 skill。

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.

3. 把 plugin 添加到 marketplace。可以使用 $plugin-creator 生成，也可以按照 Build Your Own Curated Plugin List 手动接入 Codex。

之后，你可以按需要添加 MCP config、app integrations 或 marketplace metadata。

手动安装本地 plugin

根据谁需要访问该 plugin 或 curated list，选择 repo marketplace 或 personal marketplace。

仓库级 marketplace 示例

在 $REPO_ROOT/.agents/plugins/marketplace.json 添加 marketplace file，并把 plugins 放在 $REPO_ROOT/plugins/。

Step 1：把 plugin folder 复制到 $REPO_ROOT/plugins/my-plugin。

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

Step 2：添加或更新 $REPO_ROOT/.agents/plugins/marketplace.json，让 source.path 指向 plugin directory，并使用 ./ 开头的 relative path。

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

Step 3：restart Codex，并确认 plugin 出现。

个人 marketplace 示例

在 ~/.agents/plugins/marketplace.json 添加 marketplace file，并把 plugins 放在 ~/.codex/plugins/。

Step 1：把 plugin folder 复制到 ~/.codex/plugins/my-plugin。

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

Step 2：添加或更新 ~/.agents/plugins/marketplace.json，让 plugin entry 的 source.path 指向该 directory。

Step 3：restart Codex，并确认 plugin 出现。

marketplace file 指向 plugin location，所以这些 directories 是 examples，不是固定要求。

Codex 会相对 marketplace root 解析 source.path，而不是相对 .agents/plugins/ folder。

file format 见 Marketplace Metadata。

修改 plugin 后，更新 marketplace entry 指向的 plugin directory，并 restart Codex，让 local install 读取新 files。

Marketplace 元数据

如果维护 repo marketplace，请定义：

$REPO_ROOT/.agents/plugins/marketplace.json

如果维护 personal marketplace，请使用：

~/.agents/plugins/marketplace.json

marketplace file 控制 Codex-facing catalogs 中的 plugin ordering 和 install policies。

它可以在测试时只代表一个 plugin，也可以代表一组 curated plugins，让 Codex 在同一个 marketplace name 下展示。

把 plugin 加入 marketplace 前，请确认它的 version、publisher metadata 和 install-surface copy 已经准备好给其他 developers 查看。

{
  "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"
    }
  ]
}

metadata 规则：

• 使用 top-level name 标识 marketplace。
• 使用 interface.displayName 定义 Codex 中显示的 marketplace title。
• 在 plugins 下为每个 plugin 添加一个 object，组成 Codex 在该 marketplace title 下展示的 curated list。
• 每个 plugin entry 的 source.path 指向 Codex 要加载的 plugin directory。repo installs 常见路径是 ./plugins/；personal installs 常见模式是 ./.codex/plugins/<plugin-name>。
• source.path 保持相对 marketplace root，以 ./ 开头，并保持在该 root 内部。
• 对 local entries，source 也可以是 plain string path，例如 "./plugins/my-plugin"。
• 每个 plugin entry 都要包含 policy.installation、policy.authentication 和 category。
• policy.installation 可以使用 AVAILABLE、INSTALLED_BY_DEFAULT 或 NOT_AVAILABLE。
• 使用 policy.authentication 决定 authentication 在 install 时发生，还是在 first use 时发生。

marketplace 控制 Codex 从哪里加载 plugin。

如果你的 plugin 不在示例 directories 中，local source.path 也可以指向别的位置。

marketplace file 可以位于你开发 plugin 的 repo，也可以位于单独的 marketplace repo。一个 marketplace file 可以指向一个 plugin，也可以指向多个 plugins。

marketplace entries 也可以指向 Git-backed plugin sources。

当 plugin 位于 repository root，使用 "source": "url"；当 plugin 位于 subdirectory，使用 "source": "git-subdir"。

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

Git-backed entries 可以使用 ref 或 sha selectors。

如果 Codex 无法 resolve 某个 marketplace entry 的 source，它会跳过该 plugin entry，而不是让整个 marketplace 失败。

Codex 如何使用 marketplaces

plugin marketplace 是 Codex 可以 read 和 install 的 plugins JSON catalog。

Codex 可以读取这些 marketplace files：

• official Plugin Directory 背后的 curated marketplace。
• repo marketplace：$REPO_ROOT/.agents/plugins/marketplace.json。
• Claude-style marketplace：$REPO_ROOT/.claude-plugin/marketplace.json。
• personal marketplace：~/.agents/plugins/marketplace.json。

你可以 install marketplace 中暴露的任意 plugin。

Codex 会把 plugins 安装到：

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

对于 local plugins，$VERSION 是 local。Codex 会从这个 cache path 加载 installed copy，而不是直接从 marketplace entry 加载。

你可以单独 enable 或 disable 每个 plugin。

Codex 会把每个 plugin 的 on/off state 存在 ~/.codex/config.toml。

打包和分发 plugins

Plugin 结构

每个 plugin 都有一个 manifest：

.codex-plugin/plugin.json

plugin 还可以包含：

• skills/ directory。
• 指向一个或多个 apps 或 connectors 的 .app.json file。
• 配置 MCP servers 的 .mcp.json file。
• lifecycle config。
• 用于 supported surfaces 展示 plugin 的 assets。

典型结构：

my-plugin/
  .codex-plugin/
    plugin.json              # Required: plugin manifest
  skills/
    my-skill/
      SKILL.md               # Optional: skill instructions
  .app.json                  # Optional: app or connector mappings
  .mcp.json                  # Optional: MCP server configuration
  hooks/
    hooks.json               # Optional: lifecycle configuration
  assets/                    # Optional: icons, logos, screenshots

.codex-plugin/ 中只放 plugin.json。

skills/、assets/、.mcp.json、.app.json 和 lifecycle config files 都保留在 plugin root。

published plugins 通常使用比 quick-start scaffolds 中 minimal example 更丰富的 manifest。

manifest 有三个作用：

• identify plugin。
• 指向 bundled components，例如 skills、apps 或 MCP servers。
• 提供 install-surface metadata，例如 descriptions、icons 和 legal links。

完整 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",
  "hooks": "./hooks/hooks.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 是 required entry point。

其他 manifest fields 是 optional，但 published plugins 通常会使用。

Manifest 字段

使用 top-level fields 定义 package metadata，并指向 bundled components：

• name、version、description：identify plugin。
• author、homepage、repository、license、keywords：提供 publisher 和 discovery metadata。
• skills、mcpServers、apps、hooks：指向 relative to plugin root 的 bundled components。
• interface：控制 install surfaces 如何展示 plugin。

使用 interface object 提供 install-surface metadata：

• displayName、shortDescription、longDescription：控制 title 和 descriptive copy。
• developerName、category、capabilities：添加 publisher 和 capability metadata。
• websiteURL、privacyPolicyURL、termsOfServiceURL：提供 external links。
• defaultPrompt、brandColor、composerIcon、logo、screenshots：控制 starter prompts 和 visual presentation。

路径规则

• manifest paths 保持 relative to plugin root，并以 ./ 开头。
• visual assets，例如 composerIcon、logo 和 screenshots，尽量放在 ./assets/ 下。
• skills 用于 bundled skill folders，apps 用于 .app.json，mcpServers 用于 .mcp.json，hooks 用于 lifecycle config。
• 如果 omitted hooks，但 plugin 包含 ./hooks/hooks.json，Codex 会自动加载该 default lifecycle config。

打包 MCP servers 和 lifecycle config

mcpServers 可以指向 .mcp.json file。

该 file 可以包含 direct server map，也可以包含 wrapped mcp_servers object。

Direct server map：

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

Wrapped server map：

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

hooks 可以指向：

• 一个 lifecycle JSON file。
• lifecycle JSON files array。
• inline lifecycle object。
• inline lifecycle objects array。

file paths 必须和其他 manifest paths 一样，遵循 ./-prefixed plugin-root path rules。

如果 omitted manifest field，Codex 仍会检查 ./hooks/hooks.json。

发布官方公开插件

官方 Plugin Directory 的插件添加入口尚未开放。

自助发布和管理插件的入口尚未开放。