本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/plugins/build

构建插件

为 Codex 创建、测试并分发插件

本页面面向插件作者。如果你想在 Codex 中浏览、安装和使用插件，请参见 Plugins。如果你仍在围绕一个仓库或一个个人工作流进行迭代，请先从本地 skill 开始。当你想要在团队间共享该工作流、打包应用集成或 MCP 配置、封装生命周期 hook，或发布一个稳定包时，再构建插件。

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

如需最快完成设置，请使用内置的 $plugin-creator skill。

Codex 中的 plugin-creator skill

它会为你生成必需的 .codex-plugin/plugin.json 清单文件，也可以生成一个用于测试的本地 marketplace 条目。如果你已经有一个插件文件夹，仍然可以使用 $plugin-creator 将其接入本地 marketplace。

如何调用 plugin-creator skill

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

marketplace 是一个插件的 JSON 目录。$plugin-creator 可以为单个插件生成一个 marketplace，你也可以持续向同一个 marketplace 添加条目，以便为某个仓库、团队或个人工作流构建你自己的精选列表。

在 Codex 中，每个 marketplace 都会作为插件目录中的一个可选来源出现。仓库范围的列表使用 $REPO_ROOT/.agents/plugins/marketplace.json，个人列表使用 ~/.agents/plugins/marketplace.json。在 plugins[] 下为每个插件添加一个条目，将每个 source.path 指向插件文件夹，并使用相对于 marketplace 根目录且带有 ./ 前缀的路径，同时将 interface.displayName 设置为你希望 Codex 在 marketplace 选择器中显示的标签。然后重启 Codex。之后，打开插件目录，选择你的 marketplace，并浏览或安装该精选列表中的插件。

你不需要为每个插件单独创建一个 marketplace。一个 marketplace 可以在测试期间只暴露单个插件，然后随着你添加更多插件，扩展成一个更大的精选目录。

插件目录中的自定义本地 marketplace

从 CLI 添加 marketplace

当你希望由 Codex 为你安装并跟踪 marketplace 来源，而不是手动编辑 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 来源可以是 GitHub 简写（owner/repo 或 owner/repo@ref）、HTTP 或 HTTPS Git URL、SSH Git URL，或本地 marketplace 根目录。使用 --ref 固定某个 Git ref，并重复使用 --sparse PATH 以对基于 Git 的 marketplace 仓库启用 sparse checkout。--sparse 仅适用于 Git marketplace 来源。

要刷新或移除已配置的 marketplace：

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

手动创建插件

从一个打包了单个 skill 的最小插件开始。

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

使用稳定的 kebab-case 形式的插件 name。Codex 会将其用作插件标识符和组件命名空间。

在 skills//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 配置、应用集成或 marketplace 元数据。

手动安装本地插件

根据谁应当能够访问该插件或精选列表，使用仓库 marketplace 或个人 marketplace。

Workspace

在 $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 并确认该插件已出现。

Global

在 ~/.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 根目录，而不是相对于 .agents/plugins/ 文件夹。文件格式请参见 Marketplace metadata。

在你更改插件后，更新你的 marketplace 条目所指向的插件目录，并重启 Codex，以便本地安装获取新文件。

Marketplace metadata

如果你维护的是仓库 marketplace，请在 $REPO_ROOT/.agents/plugins/marketplace.json 中定义它。对于个人 marketplace，请使用 ~/.agents/plugins/marketplace.json。marketplace 文件控制 Codex 可见目录中的插件顺序和安装策略。它可以在你测试期间只表示一个插件，也可以表示一个你希望 Codex 在同一个 marketplace 名称下共同展示的精选插件列表。在你将插件添加到 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 下为每个插件添加一个对象，以构建一个由 Codex 在该 marketplace 标题下展示的精选列表。
将每个插件条目的 source.path 指向你希望 Codex 加载的插件目录。对于仓库安装，该目录通常位于 ./plugins/ 下。对于个人安装，常见模式是 ./.codex/plugins/。
保持 source.path 相对于 marketplace 根目录，以 ./ 开头，并确保它位于该根目录内。
对于本地条目，source 也可以是一个普通字符串路径，例如 "./plugins/my-plugin"。
始终在每个插件条目上包含 policy.installation、policy.authentication 和 category。
使用 policy.installation 值，例如 AVAILABLE、INSTALLED_BY_DEFAULT 或 NOT_AVAILABLE。
使用 policy.authentication 来决定认证发生在安装时还是首次使用时。

marketplace 控制 Codex 从哪里加载插件。如果你的插件位于这些示例目录之外，本地 source.path 也可以指向别处。marketplace 文件既可以位于你开发插件的仓库中，也可以位于单独的 marketplace 仓库中；同一个 marketplace 文件可以指向一个插件，也可以指向多个插件。

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

Codex 如何使用 marketplace

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

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

为官方 Plugin Directory 提供支持的精选 marketplace
位于 $REPO_ROOT/.agents/plugins/marketplace.json 的 repo marketplace
位于 $REPO_ROOT/.claude-plugin/marketplace.json 的兼容旧版 marketplace
位于 ~/.agents/plugins/marketplace.json 的个人 marketplace

你可以安装通过 marketplace 暴露的任何插件。Codex 将插件安装到 ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/。对于本地插件，$VERSION 为 local，并且 Codex 会从该缓存路径加载已安装的副本，而不是直接从 marketplace 条目中加载。

你可以分别启用或禁用每个插件。Codex 会将每个插件的开关状态存储在 ~/.codex/config.toml 中。

打包和分发插件

插件结构

每个插件都在 .codex-plugin/plugin.json 中有一个清单。它还可以包含一个 skills/ 目录、一个用于生命周期 hooks 的 hooks/ 目录、一个指向一个或多个 app 或 connector 的 .app.json 文件、一个配置 MCP 服务器的 .mcp.json 文件，以及用于在受支持界面中展示插件的资源文件。

只有 plugin.json 属于 .codex-plugin/。请将 skills/、hooks/、 assets/、.mcp.json 和 .app.json 保留在插件根目录中。

已发布的插件通常会使用比快速开始脚手架中最小示例更丰富的清单。该清单有三个作用：

标识插件。
指向打包的组件，例如 skills、apps、MCP 服务器或 hooks。
提供安装界面元数据，例如描述、图标和法律链接。

以下是一个完整的清单示例：

{
  "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 是必需的入口点。其他清单字段都是可选的，但已发布的插件通常会使用它们。

清单字段

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

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

使用 interface 对象来提供安装界面元数据：

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

路径规则

保持清单路径相对于插件根目录，并以 ./ 开头。
尽可能将 composerIcon、logo 和 screenshots 等视觉资源存放在 ./assets/ 下。
对打包的 skill 文件夹使用 skills，对 .app.json 使用 apps，对 .mcp.json 使用 mcpServers，对生命周期 hooks 使用 hooks。
在此版本中，插件 hooks 默认关闭；除非设置 [features].plugin_hooks = true，否则打包的 hooks 不会运行。
当插件 hooks 已启用时，如果存在默认的 ./hooks/hooks.json 文件，省略 hooks 即可使用它。

打包的 MCP 服务器和生命周期 hooks

mcpServers 可以指向一个 .mcp.json 文件，该文件包含直接服务器映射，或者包装后的 mcp_servers 对象。

直接服务器映射：

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

包装后的服务器映射：

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

安装后，用户可以从自己的 Codex 配置中启用或禁用打包的 MCP 服务器，并调整工具审批策略，而无需编辑插件。对插件作用域的 MCP 服务器策略，请使用 plugins..mcp_servers.：

[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"

在此版本中，插件 hooks 默认关闭。当 [features].plugin_hooks = true 且你的插件已启用时，Codex 可以将你插件中的生命周期 hooks 与用户、项目和托管 hooks 一起加载。

[features]
plugin_hooks = true

默认的插件 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 会使用该清单条目，而不是默认的 hooks/hooks.json。该清单字段可以是单一路径、路径数组、内联 hooks 对象，或内联 hooks 对象数组。

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

Hook 路径遵循与 skills、apps 和 mcpServers 相同的清单路径规则：以 ./ 开头、相对于插件根目录解析，并且保持在插件根目录内。

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

插件 hooks 使用与常规 hooks 相同的事件模式。支持的事件、输入、输出、信任审查和当前限制，请参见 Hooks。

发布官方公共插件

将插件添加到官方 Plugin Directory 的功能即将推出。

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

使用 $plugin-creator 创建插件​

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

从 CLI 添加 marketplace​

手动创建插件​

手动安装本地插件​

Workspace​

Global​

Marketplace metadata​

Codex 如何使用 marketplace​

打包和分发插件​

插件结构​

清单字段​

路径规则​

打包的 MCP 服务器和生命周期 hooks​

发布官方公共插件​