OpenAI Codex 这页解决的是“如何把一个可复用的 workflow 做成插件并分发出去”。适合要把 skills、app integrations、MCP 配置或 lifecycle hooks 打包成稳定插件的作者；可用 @plugin-creator 快速生成 .codex-plugin/plugin.json，也可以用 marketplace JSON、codex plugin marketplace add 或手动目录结构完成接入。

OpenAI Codex 插件创建与发布

这页面向插件作者。
如果你只是想浏览、安装和使用 Codex 插件，请看 Plugins。如果你还在一个 repo 或个人 workflow 里反复迭代，先用 local skill。只有当你要在团队间共享 workflow、打包 app integrations 或 MCP 配置、封装 lifecycle hooks，或者发布一个稳定包时，再把它做成插件。

用 `@plugin-creator` 创建插件

最快的方式是直接使用内置的 @plugin-creator skill。

它会生成必需的 .codex-plugin/plugin.json manifest，也可以同时生成一个本地 marketplace 条目用于测试。即使你已经有插件文件夹，也仍然可以用 @plugin-creator 把它接入 local marketplace。

自定义一份插件列表

marketplace 本质上是一个插件 JSON catalog。@plugin-creator 可以先为单个插件生成 marketplace，之后你还能继续往同一个 marketplace 里追加条目，把它扩展成一个适合 repo、团队或个人 workflow 的精选列表。

在 Codex 里，每个 marketplace 都会作为 plugin directory 中可选的来源出现。仓库级列表使用 $REPO_ROOT/.agents/plugins/marketplace.json，个人列表使用 ~/.agents/plugins/marketplace.json。在 plugins[] 下为每个插件添加一个条目，把每个 source.path 指向插件文件夹，路径要以 ./ 开头，并且相对 marketplace root。然后重启 Codex。接着打开 plugin directory，选择对应 marketplace，就能浏览或安装这个精选列表里的插件。

不需要给每个插件单独建一个 marketplace。你可以先让一个 marketplace 只暴露一个插件做测试，之后再随着插件数量增加，把它扩展成更大的精选目录。

用 CLI 添加 marketplace

当你希望 Codex 自动安装并追踪某个 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 source 可以是 GitHub 简写（owner/repo 或 owner/repo@ref）、HTTP/HTTPS Git URL、SSH Git URL，或者本地 marketplace root 目录。用 --ref 锁定 Git ref；对 Git-backed marketplace repo 可以重复使用 --sparse PATH 做 sparse checkout。--sparse 只对 Git marketplace source 有效。

要查看、刷新或移除已配置的 marketplace，使用下面命令：

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

codex plugin marketplace list 会打印 Codex 正在考虑的每个 marketplace 及其解析出来的 root path，包括本地默认 marketplace 和已配置的 marketplace snapshots。

手动创建插件

从一个最小插件开始，它只打包一个 skill。

创建插件文件夹，并在 .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/"
}

插件 name 建议使用稳定的 kebab-case。Codex 会把它当作插件标识符和 component namespace。

在 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.

把插件加入 marketplace。可以用 @plugin-creator 自动生成，也可以按照自定义一份插件列表的方式手动接入 Codex。

之后你还可以按需补充 MCP 配置、app integrations，或者 marketplace metadata。

手动安装本地插件

根据是希望仓库内成员访问，还是仅限个人使用，选择 repo marketplace 或 personal marketplace。

仓库 marketplace 接入步骤

在 $REPO_ROOT/.agents/plugins/marketplace.json 增加 marketplace 文件，并把插件放在 $REPO_ROOT/plugins/ 下。

仓库 marketplace 示例

步骤 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，确认插件已经出现。

个人 marketplace 接入步骤

在 ~/.agents/plugins/marketplace.json 增加 marketplace 文件，并把插件放在 ~/.codex/plugins/ 下。

个人 marketplace 示例

步骤 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 root，而不是相对于 .agents/plugins/ 目录。文件格式见 Marketplace metadata。

修改插件之后，要更新 marketplace entry 指向的插件目录，并重启 Codex，这样本地安装才会加载新文件。

把本地插件分享给工作区

创建插件并添加到 Codex 之后，可以从 Codex app 把它分享给 ChatGPT workspace 的其他成员。

打开 Codex app 中的 Plugins。
进入 Created by you，打开插件详情页。
选择 Share。
添加 workspace 成员，或复制分享链接。
选择访问范围，然后发送邀请或链接。

被分享的人会在 plugin directory 的 Shared with you 下找到这个插件。把本地插件分享给 workspace，不会把它发布到 public Plugin Directory。被分享的插件只会留在你的 workspace 和 organization 边界内；未登录该 workspace 的账号无法访问。需要 repo 或 CLI 分发时用 marketplace；需要指定队友从 Codex app 安装时，用 workspace sharing。

如果 workspace admin 需要禁用插件分享，可以在 cloud-managed requirements 里添加 plugin_sharing = false：

plugin_sharing = false

Marketplace metadata

如果你维护的是 repo marketplace，请在 $REPO_ROOT/.agents/plugins/marketplace.json 里定义它。个人 marketplace 使用 ~/.agents/plugins/marketplace.json。marketplace 文件控制 Codex-facing catalog 里的插件排序和安装策略。它可以只代表一个正在测试的插件，也可以代表一个精选列表，让 Codex 在同一个 marketplace 名下统一展示。把插件加入 marketplace 之前，先确认它的 version、publisher metadata 和 install-surface 文案已经准备好，其他开发者会看到这些内容。

{
  "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 下为每个插件添加一个对象，Codex 会把它们作为这个 marketplace 下的精选列表展示。
把每个插件条目的 source.path 指向你希望 Codex 读取的插件目录。仓库安装通常放在 ./plugins/，个人安装常见做法是 ./.codex/plugins/<plugin-name>。
source.path 要相对于 marketplace root，必须以 ./ 开头，而且要保持在这个 root 内。
对于本地条目，source 也可以直接写成字符串路径，例如 "./plugins/my-plugin"。
每个插件条目都要包含 policy.installation、policy.authentication 和 category。
policy.installation 可以使用 AVAILABLE、INSTALLED_BY_DEFAULT 或 NOT_AVAILABLE。
policy.authentication 用来决定认证是在安装时完成，还是在首次使用时完成。

marketplace 决定 Codex 从哪里加载插件。本地 source.path 也可以指向别处，只要你的插件不在前面这些示例目录里即可。marketplace 文件可以放在你开发插件的 repo 中，也可以放在单独的 marketplace repo 中；一个 marketplace 文件既可以指向一个插件，也可以指向多个插件。

marketplace 条目也可以指向 Git-backed plugin source。插件位于仓库根目录时，用 "source": "url"；插件位于子目录时，用 "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 条目可以使用 ref 或 sha 选择器。如果 Codex 无法解析某个 marketplace entry 的 source，它会跳过该插件条目，而不是让整个 marketplace 失败。

Codex 如何使用 marketplace

plugin marketplace 是一个 Codex 可读取和安装的插件 JSON catalog。

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

官方 Plugin Directory 使用的 curated marketplace
$REPO_ROOT/.agents/plugins/marketplace.json 的 repo marketplace
$REPO_ROOT/.claude-plugin/marketplace.json 的 legacy-compatible marketplace
~/.agents/plugins/marketplace.json 的 personal marketplace

你可以安装 marketplace 暴露的任意插件。Codex 会把插件安装到 ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/。对于 local 插件，$VERSION 是 local，Codex 会从这个 cache path 加载已安装副本，而不是直接读取 marketplace entry。

你可以分别启用或禁用每个插件。Codex 会把每个插件的 on/off 状态保存在 ~/.codex/config.toml。

打包和分发插件

插件结构

每个插件都需要在 .codex-plugin/plugin.json 里有一个 manifest。它还可以包含 skills/ 目录、用于 lifecycle hooks 的 hooks/ 目录、指向一个或多个 app 或 connector 的 .app.json 文件、用于配置 MCP servers 的 .mcp.json 文件，以及用于在支持的界面中展示插件的 assets。

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

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

正式发布的插件通常会使用比 quick-start scaffold 更完整的 manifest。manifest 有三个作用：

标识插件。
指向打包好的组件，比如 skills、apps、MCP servers 或 hooks。
提供 install-surface metadata，比如描述、图标和法律链接。

下面是一个完整的 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 是必需入口。其他 manifest 字段是可选的，但已发布插件通常都会用到。

Manifest 字段

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

name、version 和 description 用于识别插件。
author、homepage、repository、license 和 keywords 提供 publisher 和 discovery metadata。
skills、mcpServers、apps 和 hooks 指向相对插件根目录的打包组件。
interface 控制安装界面如何展示插件。

用 interface 对象配置 install-surface metadata：

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

路径规则

manifest 里的路径必须相对于插件根目录，并且以 ./ 开头。
尽量把 composerIcon、logo 和 screenshots 等视觉资源放在 ./assets/ 下。
skills 用于打包 skill 文件夹，apps 用于 .app.json，mcpServers 用于 .mcp.json，hooks 用于 lifecycle hooks。
已启用的插件可以同时包含 lifecycle hooks、skills、MCP servers 和 apps。
如果插件把 hooks 放在 ./hooks/hooks.json，你不需要在 .codex-plugin/plugin.json 里再写 hooks 字段；Codex 会自动检查这个默认文件。

打包 MCP servers 与 lifecycle hooks

mcpServers 可以指向一个 .mcp.json 文件，该文件既可以是直接的 server map，也可以是包了一层的 mcp_servers 对象。

直接 server map：

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

包了一层的 server map：

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

安装后，用户可以在自己的 Codex 配置里单独启用或禁用某个 bundled MCP server，并调整 tool approval policy，而不必修改插件本身。使用 plugins.<plugin>.mcp_servers.<server> 为插件范围内的 MCP server 设置策略：

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

[plugins."my-plugin".mcp_servers.docs.tools.search]
approval_mode = "approve"

当插件启用后，Codex 可以把插件中的 lifecycle hooks 与用户、项目和 managed hooks 一起加载。

安装或启用插件，并不会自动信任它的 hooks。插件自带的 hooks 属于 non-managed hooks，Codex 会先跳过它们，直到用户审查并信任当前 hook 定义。

默认的插件 hook 文件是 hooks/hooks.json：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${PLUGIN_ROOT}/hooks/session_start.py",
            "statusMessage": "Loading plugin context"
          }
        ]
      }
    ]
  }
}

如果你在 .codex-plugin/plugin.json 里定义了 hooks，Codex 会优先使用那个 manifest 条目，而不是默认的 hooks/hooks.json。这个字段可以是单个路径、路径数组、inline hooks object，或者 inline hooks object 数组。

{
  "name": "repo-policy",
  "hooks": ["./hooks/session.json", "./hooks/tools.json"]
}

hook 路径遵循和 skills、apps、mcpServers 相同的 manifest 路径规则：以 ./ 开头，相对于插件根目录解析，并且必须留在插件根目录内。

插件 hook 命令可以接收 Codex 专用环境变量 PLUGIN_ROOT 和 PLUGIN_DATA。PLUGIN_ROOT 指向已安装插件根目录，PLUGIN_DATA 指向插件的可写数据目录。为了兼容已有插件 hooks，Codex 也会设置 CLAUDE_PLUGIN_ROOT 和 CLAUDE_PLUGIN_DATA。

插件 hooks 使用和常规 hooks 相同的事件 schema。支持的事件、输入、输出、trust review 和当前限制，请看 Hooks。

发布官方 public plugins

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

自助式插件发布和管理功能也即将推出。

常见问题

OpenAI Codex 插件怎么创建

最快的方法是用 @plugin-creator，它会生成 .codex-plugin/plugin.json，还可以帮你生成本地 marketplace 条目。
如果你已经有插件目录，也可以手动创建 .codex-plugin/plugin.json，再把它加进 marketplace。

OpenAI Codex 本地插件怎么安装

把插件目录复制到仓库的 ./plugins/ 或个人的 ~/.codex/plugins/，然后在对应的 ~/.agents/plugins/marketplace.json 或 $REPO_ROOT/.agents/plugins/marketplace.json 里添加 source.path。
改完后重启 Codex，插件才会从 marketplace cache 里重新加载。

Codex 插件里的 hooks 会自动信任吗

不会。安装或启用插件并不会自动信任它的 hooks。
插件自带的 hooks 属于 non-managed hooks，需要用户先审查并信任当前 hook 定义，Codex 才会执行。

OpenAI Codex 插件创建与发布 #

用 @plugin-creator 创建插件 #

自定义一份插件列表 #

用 CLI 添加 marketplace #

手动创建插件 #

手动安装本地插件 #

仓库 marketplace 接入步骤 #

个人 marketplace 接入步骤 #

把本地插件分享给工作区 #

Marketplace metadata #

Codex 如何使用 marketplace #

打包和分发插件 #

插件结构 #

Manifest 字段 #

路径规则 #

打包 MCP servers 与 lifecycle hooks #

发布官方 public plugins #

常见问题 #

OpenAI Codex 插件怎么创建 #

OpenAI Codex 本地插件怎么安装 #

Codex 插件里的 hooks 会自动信任吗 #