构建插件 (Build plugins)

创建、测试和分发 Codex 插件。学习使用 $plugin-creator 快速搭建插件，构建自定义插件市场，以及手动创建和安装插件。

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

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

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

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

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

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 可以在测试时暴露单个插件，然后随着你添加更多插件，逐渐发展为更大的精选目录。

从 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 来源有效。

要检查、刷新或移除已配置的 marketplaces：

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，以及它解析出的根路径，包括本地默认 marketplaces 和已配置的 marketplace 快照。

手动创建插件

从一个打包一个 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/"
}

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

在 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 集成或 marketplace 元数据。

手动安装本地插件

根据谁应该能够访问该插件或精选列表，使用仓库 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，并验证插件是否出现。

在 ~/.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 会相对于 marketplace 根目录解析 source.path，而不是相对于 .agents/plugins/ 文件夹解析。文件格式请参见 Marketplace 元数据。

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

与你的 workspace 共享本地插件

创建插件并将其添加到 Codex 后，你可以从 Codex app 将其共享给 ChatGPT workspace 的其他成员。

在 Codex app 中打开 Plugins。
前往 Created by you，并打开插件详情页。
选择 Share。
添加 workspace 成员或 workspace 组，或复制分享链接。
选择谁有访问权限，然后发送邀请或链接。

被你共享的人可以在插件目录中的 Shared with you 下找到该插件。将本地插件共享给你的 workspace 不会将它发布到公共 Plugin Directory。共享插件会保留在你的 workspace 和组织边界内；未登录该 workspace 的账户无法访问它。当一个团队或角色应共享相同插件访问权限时，请使用 groups。当你希望通过仓库或 CLI 分发时，请使用 marketplace；当你希望选定的队友从 Codex app 安装插件时，请使用 workspace sharing。

Workspace 管理员可以通过在 requirements.toml 中添加 features.plugin_sharing = false，从 cloud-managed requirements 禁用插件共享：

features.plugin_sharing = false

Marketplace 元数据

如果你维护一个仓库 marketplace，请在 $REPO_ROOT/.agents/plugins/marketplace.json 中定义它。对于个人 marketplace，请使用 ~/.agents/plugins/marketplace.json。marketplace 文件控制 Codex 面向目录中的插件排序和安装策略。它可以在你测试时表示一个插件，也可以表示你希望 Codex 在一个 marketplace 名称下共同展示的精选插件列表。在将插件添加到 marketplace 之前，请确保它的 version、publisher 元数据和安装界面文案已经准备好让其他开发者看到。

{
  "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 根目录，以 ./ 开头，并保持在该根目录内部。
对于本地条目，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 条目的来源，它会跳过该插件条目，而不是让整个 marketplace 失败。

Codex 如何使用 marketplaces

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

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

驱动官方 Plugin Directory 的精选 marketplace
$REPO_ROOT/.agents/plugins/marketplace.json 下的仓库 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 中存储每个插件的开启或关闭状态。

打包和分发插件

插件结构

每个插件都有一个 manifest，位于 .codex-plugin/plugin.json。它也可以包含 skills/ 目录、用于生命周期 hooks 的 hooks/ 目录、指向一个或多个 apps 或 connectors 的 .app.json 文件、配置 MCP servers 的 .mcp.json 文件，以及用于在受支持界面中展示插件的 assets。

Directorymy-plugin/
- Directory.codex-plugin/
  - plugin.json 必需：插件 manifest
- Directoryskills/
  - Directorymy-skill/
    SKILL.md 可选：skill instructions
- Directoryhooks/
  - hooks.json 可选：生命周期 hooks
- .app.json 可选：app 或 connector mappings
- .mcp.json 可选：MCP server configuration
- Directoryassets/ 可选：icons、logos、screenshots
  - …

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

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

标识插件。
指向打包的组件，例如 skills、apps、MCP servers 或 hooks。
提供安装界面元数据，例如 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 是必需入口点。其他 manifest 字段是可选的，但已发布插件通常会使用它们。

Manifest 字段

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

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

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

displayName、shortDescription 和 longDescription 控制标题和描述性文案。
developerName、category 和 capabilities 添加 publisher 和 capability 元数据。
websiteURL、privacyPolicyURL 和 termsOfServiceURL 提供外部链接。
defaultPrompt、brandColor、composerIcon、logo 和 screenshots 控制 starter prompts 和视觉展示。

路径规则

保持 manifest 路径相对于插件根目录，并以 ./ 开头。
尽可能将视觉 assets，例如 composerIcon、logo 和 screenshots，存放在 ./assets/ 下。
使用 skills 表示打包的 skill 文件夹，使用 apps 表示 .app.json，使用 mcpServers 表示 .mcp.json，使用 hooks 表示生命周期 hooks。
启用的插件可以在 skills、MCP servers 和 apps 旁包含生命周期 hooks。
如果你的插件将 hooks 存储在 ./hooks/hooks.json，则不需要在 .codex-plugin/plugin.json 中添加 hooks 条目；Codex 会自动检查该默认文件。

打包的 MCP servers 和生命周期 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 配置中启用或禁用打包的 MCP server，并调整工具审批策略，而无需编辑插件。对插件范围的 MCP server 策略使用 plugins.<plugin>.mcp_servers.<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 可以在用户、项目和 managed hooks 旁加载来自插件的生命周期 hooks。

安装或启用插件不会自动信任它的 hooks。插件打包的 hooks 是非 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。manifest 字段可以是单个路径、路径数组、内联 hooks 对象，或内联 hooks 对象数组。

{
  "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。有关受支持事件、输入、输出、信任审查和当前限制，请参见 Hooks。

发布官方公共插件

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

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

Concepts

App 桌面应用

IDE 扩展

CLI

Web 云端

集成

Codex Security

Plugins 插件

Skills 技能

Enterprise

构建插件 (Build plugins)

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

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

从 CLI 添加 marketplace

手动创建插件

手动安装本地插件

与你的 workspace 共享本地插件

Marketplace 元数据

Codex 如何使用 marketplaces

打包和分发插件

插件结构

Manifest 字段

路径规则

打包的 MCP servers 和生命周期 hooks

发布官方公共插件

开始入门

使用 Codex

配置

管理

自动化

学习

发布

构建插件 (Build plugins)

使用 @plugin-creator 创建插件

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

从 CLI 添加 marketplace

手动创建插件

手动安装本地插件

与你的 workspace 共享本地插件

Marketplace 元数据

Codex 如何使用 marketplaces

打包和分发插件

插件结构

Manifest 字段

路径规则

打包的 MCP servers 和生命周期 hooks

发布官方公共插件

开始入门

使用 Codex

配置

管理

自动化

学习

发布

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