构建插件 – Codex

本页面面向插件开发者。如果您只想在 Codex 中浏览、安装和使用插件，请参阅插件。如果您仍处于单个仓库或个人工作流的迭代阶段，请从本地技能（Skill）开始。当您需要跨团队共享该工作流、捆绑应用集成或 MCP 配置、封装生命周期钩子，或发布稳定包时，请构建一个插件。

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

如需最快速地进行设置，请使用内置的 @plugin-creator 技能。

它会为您构建所需的 .codex-plugin/plugin.json 清单文件，并可以生成一个用于测试的本地市场条目。如果您已经拥有一个插件文件夹，仍然可以使用 @plugin-creator 将其挂载到本地市场中。

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

“市场”（Marketplace）是一个插件的 JSON 目录。@plugin-creator 可以为单个插件生成一个市场文件，您可以持续向该市场添加条目，从而为仓库、团队或个人工作流构建属于您自己的精选插件列表。

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

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

通过 CLI 添加市场

当您希望 Codex 为您安装并跟踪市场来源，而不是手动编辑 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

市场来源可以是 GitHub 缩写（owner/repo 或 owner/repo@ref）、HTTP 或 HTTPS Git URL、SSH Git URL，或本地市场根目录。使用 --ref 来指定 Git 引用，多次使用 --sparse PATH 可以对基于 Git 的市场仓库进行稀疏检出。--sparse 仅适用于 Git 市场来源。

查看、刷新或移除已配置的市场

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 当前考虑的每个市场及其解析的根路径，包括本地默认市场和已配置的市场快照。

手动创建插件

从一个封装了单个技能的最小化插件开始。

创建一个包含 .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-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 生成市场，或者按照构建您自己的精选插件列表手动将插件挂载到 Codex 中。

在此之后，您可以根据需要添加 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 并确认插件显示。

市场文件指向插件的位置，因此上述目录仅为示例，而非硬性要求。Codex 解析 source.path 时是相对于市场根目录的，而不是相对于 .agents/plugins/ 文件夹。关于文件格式，请参阅市场元数据。

修改插件后，更新市场条目所指向的插件目录，并重启 Codex，以便本地安装能读取到新文件。

创建插件并将其添加到 Codex 后，您可以从 Codex 应用中将其分享给您 ChatGPT 工作区的其他成员。

在 Codex 应用中打开插件。
转到由您创建并打开插件详情页。
选择共享。
添加工作区成员或复制共享链接。
选择谁有权访问，然后发送邀请或链接。

您共享的对象可以在插件目录的与您共享中找到该插件。与工作区共享本地插件并不会将其发布到公共插件目录。共享的插件仅保留在您的工作区和组织边界内；未登录该工作区的账户无法访问。当您需要进行仓库或 CLI 分发时，请使用市场；当您希望特定队友从 Codex 应用安装插件时，请使用工作区共享。

工作区管理员可以通过在 requirements.toml 中添加 plugin_sharing = false 来禁用云管理需求中的插件共享功能。

plugin_sharing = false

市场元数据

如果您维护一个仓库市场，请在 $REPO_ROOT/.agents/plugins/marketplace.json 中进行定义。对于个人市场，请使用 ~/.agents/plugins/marketplace.json。市场文件控制着 Codex 面向的目录中插件的排序和安装策略。它可以代表测试阶段的一个插件，也可以是您希望 Codex 在同一个市场名称下显示的精选插件列表。在将插件添加到市场之前，请确保其 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 来标识市场。
使用 interface.displayName 来设置 Codex 中显示的市场标题。
在 plugins 下为每个插件添加一个对象，以构建 Codex 将在该市场标题下显示的精选列表。
将每个插件条目的 source.path 指向您希望 Codex 加载的插件目录。对于仓库安装，通常位于 ./plugins/ 下。对于个人安装，常见模式是 ./.codex/plugins/<plugin-name>。
保持 source.path 相对于市场根目录，以 ./ 开头，并确保其位于根目录下。
对于本地条目，source 也可以是一个简单的字符串路径，如 "./plugins/my-plugin"。
务必在每个插件条目上包含 policy.installation、policy.authentication 和 category。
使用 policy.installation 的值，如 AVAILABLE（可用）、INSTALLED_BY_DEFAULT（默认安装）或 NOT_AVAILABLE（不可用）。
使用 policy.authentication 来决定认证是在安装时进行，还是在首次使用时进行。

市场控制着 Codex 从哪里加载插件。如果您的插件位于示例目录之外，本地 source.path 可以指向其他位置。市场文件可以存在于您开发插件的仓库中，也可以存在于单独的市场仓库中，并且一个市场文件可以指向一个或多个插件。

市场条目也可以指向基于 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 无法解析市场条目的来源，它会跳过该插件条目，而不是导致整个市场加载失败。

Codex 如何使用市场

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

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

支持官方插件目录的精选市场
位于 $REPO_ROOT/.agents/plugins/marketplace.json 的仓库市场
位于 $REPO_ROOT/.claude-plugin/marketplace.json 的兼容遗留版本的市场
位于 ~/.agents/plugins/marketplace.json 的个人市场

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

您可以单独启用或禁用每个插件。Codex 将每个插件的开启或关闭状态存储在 ~/.codex/config.toml 中。

打包与分发插件

插件结构

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

my-plugin/
- .codex-plugin/
  
  plugin.json 必需：插件清单
- skills/
  
  my-skill/
  
  SKILL.md 可选：技能指令
- hooks/
  
  hooks.json 可选：生命周期钩子
- .app.json 可选：应用或连接器映射
- .mcp.json 可选：MCP 服务器配置
- assets/ 可选：图标、标志、截图

只有 plugin.json 应放置在 .codex-plugin/ 中。请将 skills/、hooks/、assets/、.mcp.json 和 .app.json 保持在插件根目录下。

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

标识插件。
指向捆绑的组件，如技能、应用、MCP 服务器或钩子。
提供安装界面的元数据，如描述、图标和法律链接。

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

{
  "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/ 下。
使用 skills 指向捆绑的技能文件夹，apps 指向 .app.json，mcpServers 指向 .mcp.json，hooks 指向生命周期钩子。
启用的插件可以在技能、MCP 服务器和应用之外包含生命周期钩子。
如果您的插件将钩子存储在 ./hooks/hooks.json，则无需在 .codex-plugin/plugin.json 中设置 hooks 条目；Codex 会自动检查该默认文件。

捆绑的 MCP 服务器和生命周期钩子

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

直接服务器映射

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

包装后的服务器映射

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

安装后，用户无需编辑插件，即可在 Codex 配置中启用或禁用捆绑的 MCP 服务器，并调整工具批准策略。使用 plugins.<plugin>.mcp_servers.<server> 进行插件级 MCP 服务器策略设置。

[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 可以加载插件中的生命周期钩子，并与用户、项目和受管钩子一并使用。

安装或启用插件并不会自动信任其钩子。插件捆绑的钩子是非托管钩子，因此在用户审核并信任当前钩子定义之前，Codex 会跳过它们。

默认插件钩子文件是 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。该清单字段可以是单个路径、路径数组、内联钩子对象或内联钩子对象数组。

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

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

插件钩子命令会接收 Codex 特有的环境变量 PLUGIN_ROOT 和 PLUGIN_DATA。PLUGIN_ROOT 指向已安装插件的根目录，PLUGIN_DATA 指向插件的可写数据目录。Codex 还会设置 CLAUDE_PLUGIN_ROOT 和 CLAUDE_PLUGIN_DATA 以实现与现有插件钩子的兼容性。

插件钩子使用与常规钩子相同的事件架构。请参阅钩子了解支持的事件、输入、输出、信任审查及当前限制。

发布官方公共插件

将插件添加到官方插件目录的功能即将推出。

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

推荐

开始使用

核心概念

Agents SDK

工具

运行与扩展

评估

实时与音频

模型优化

专用模型

上线

遗留 API

资源

开始使用

使用 Codex

配置

管理

自动化

学习

发布版本