OpenAI Codex 中文教程
联系我 goolvyouyou@gmail.com

构建插件

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

本页面面向插件作者。如果你只是想浏览、安装和使用插件，请先看插件。如果你仍然只是在单个仓库或个人工作流里迭代，一个本地技能往往就足够了。只有当你希望把这个工作流分享给团队、把应用集成、MCP 配置或生命周期 hooks 一起打包，或发布成稳定的可安装包时，再考虑做成插件。

使用 @plugin-creator 创建插件

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

Codex 中的 plugin-creator 技能

它会自动生成必须的 .codex-plugin/plugin.json 清单文件，也可以顺手生成一个本地插件市场条目，方便你立即测试。如果你已经有一个插件目录，也可以继续用 @plugin-creator 把它接到本地插件市场中。

如何调用 plugin-creator 技能

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

插件市场清单（marketplace）是一个描述插件列表的 JSON 目录。@plugin-creator 可以先为单个插件生成一份 marketplace，之后你可以持续往同一个 marketplace 中追加条目，形成一个面向仓库、团队或个人工作流的精选插件列表。

在 Codex 中，每份 marketplace 都会作为插件目录里的一个可选来源出现。

  • 仓库级 marketplace：$REPO_ROOT/.agents/plugins/marketplace.json
  • 个人级 marketplace：~/.agents/plugins/marketplace.json

使用时，在 plugins[] 下为每个插件添加一条记录，把 source.path 指向插件目录，并使用相对于 marketplace 根目录的 ./ 前缀路径。interface.displayName 则控制 Codex 在插件市场选择器中显示的名称。完成后重启 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；对 Git-backed marketplace 仓库，可以重复传入 --sparse PATH 来使用 sparse checkout。--sparse 只适用于 Git marketplace 来源。

如需刷新或移除已经配置的 marketplace：

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

手动创建插件

你可以从一个只打包单个技能的最小插件开始。

  1. 创建插件目录，并在 .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/"
}

name 建议使用稳定的 kebab-case。Codex 会把它作为插件标识符和组件命名空间。

  1. 在 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.
  1. 把这个插件加入某个插件市场清单。你可以用 @plugin-creator 自动生成，也可以按下文的精选插件列表方式手动接入。

之后，你可以再按需加入 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，确认插件已经出现在插件目录中。

marketplace 文件决定的是“插件从哪里加载”，所以上述目录只是示例，并不是固定要求。Codex 会把 source.path 解释为相对于 marketplace 根目录的路径，而不是相对于 .agents/plugins/ 目录的路径。更多格式细节，请参见插件市场元数据。

修改本地插件后，请同步更新 marketplace 指向的插件目录，并重启 Codex，让本地安装副本能够加载新文件。

与工作区共享本地插件

创建插件并添加到 Codex 后，你可以在 Codex App 中把它分享给 ChatGPT 工作区的其他成员。

  1. 在 Codex App 中打开 Plugins（插件）。
  2. 进入 Created by you（由你创建），并打开插件详情页。
  3. 选择 Share（共享）。
  4. 添加工作区成员，或复制共享链接。
  5. 选择谁可以访问，然后发送邀请或链接。

被分享的人可以在插件目录的 Shared with you（与你共享） 下找到该插件。把本地插件分享给工作区，不等于把它发布到公开 Plugin Directory。共享插件会留在你的工作区和组织边界内；未登录该工作区的账号无法访问。若你希望通过仓库或 CLI 分发，请使用 marketplace；若你希望让选定队友从 Codex App 安装插件，请使用工作区共享。

工作区管理员可以在 cloud-managed requirements 中加入 plugin_sharing = false，禁用插件共享：

plugin_sharing = false

插件市场元数据

如果你维护仓库级 marketplace，请使用 $REPO_ROOT/.agents/plugins/marketplace.json；如果是个人级 marketplace，请使用 ~/.agents/plugins/marketplace.json。marketplace 文件控制的是 Codex 中的插件排序和安装策略。它既可以只描述一个测试中的插件，也可以描述一整组你希望一起展示的精选插件。在把插件加入 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 下为每个插件添加一个对象，构成这份精选目录。
  • 让每个插件条目的 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-backed 插件来源。当插件位于仓库根目录时使用 "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 selector。如果 Codex 无法解析某个 marketplace 条目的 source，它会跳过该插件条目，而不是让整个 marketplace 加载失败。

Codex 如何使用插件市场

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

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

  • 官方 Plugin Directory 背后的精选 marketplace
  • 仓库级 marketplace：$REPO_ROOT/.agents/plugins/marketplace.json
  • legacy-compatible marketplace：$REPO_ROOT/.claude-plugin/marketplace.json
  • 个人级 marketplace：~/.agents/plugins/marketplace.json

只要插件通过 marketplace 暴露出来，Codex 就可以安装它。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.json、指向 MCP 服务端的 .mcp.json，以及用于展示插件的资源文件。

my-plugin/
├── .codex-plugin/
│   └── plugin.json          # 必需：插件清单文件
├── skills/
│   └── my-skill/
│       └── SKILL.md         # 可选：技能指令
├── hooks/
│   └── hooks.json           # 可选：生命周期 hooks
├── .app.json                # 可选：app 或 connector 映射
├── .mcp.json                # 可选：MCP server 配置
└── assets/                  # 可选：图标、logo、截图

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

已发布插件通常会使用比最小脚手架示例更完整的 manifest。manifest 主要承担三项职责：

  • 标识插件本身
  • 指向它打包的技能、应用、MCP 服务端或 hooks
  • 提供安装界面所需的描述、图标和法务链接等元数据

下面是一份完整的 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 字段

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

  • 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 控制启动提示和视觉呈现

路径规则

  • 让 manifest 中的路径都保持相对于插件根目录，并使用 ./ 开头。
  • composerIcon、logo 和 screenshots 这类视觉资源，尽量统一放到 ./assets/ 下。
  • skills 应指向打包技能的目录，apps 应指向 .app.json，mcpServers 应指向 .mcp.json，hooks 应指向生命周期 hooks。
  • 本版本中 plugin hooks 默认关闭；除非设置 [features].plugin_hooks = true，否则打包在插件中的 hooks 不会运行。
  • 启用 plugin hooks 后，如果省略 hooks，Codex 会在存在时使用默认的 ./hooks/hooks.json 文件。

打包 MCP server 与生命周期 hooks

mcpServers 可以指向一个 .mcp.json 文件。该文件既可以直接包含 server 映射，也可以用 mcp_servers 对象包一层。

直接 server 映射：

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

带 mcp_servers 包装的映射：

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

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

[features]
plugin_hooks = true

默认的 plugin 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 路径规则：以 ./ 开头，相对于插件根目录解析，并且必须留在插件根目录内。

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

Plugin hooks 使用和普通 hooks 相同的事件 schema。支持的事件、输入、输出、信任审核和当前限制，请参见 Hooks。

发布官方公共插件

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

官方公共插件的自助发布与管理能力也即将推出。