构建插件

本页面向 plugin authors。如果你想在 Codex 中浏览、安装和使用 plugins，请参见 Plugins 。如果你仍在迭代一个 repo 或个人 workflow，请先从 local skill 开始。当你希望跨团队共享 workflow、打包 app integrations 或 MCP config、封装 lifecycle hooks，或发布稳定 package 时，再构建 plugin。

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

It scaffolds the 必需 .codex-plugin/plugin.json manifest 和 can also 生成 a local marketplace entry for testing。如果 you already have a plugin folder, you can still 使用 @plugin-creator 到 wire it into a local marketplace.

Marketplace 是 plugins 的 JSON catalog。@plugin-creator 可以为单个 plugin 生成 marketplace，你也可以持续向同一个 marketplace 添加 entries，为 repo、team 或个人 workflow 构建 curated list。

In Codex, each marketplace appears as a selectable source in the plugin directory。使用 $REPO_ROOT/.agents/plugins/marketplace.json for a repo-scoped 列出 或 ~/.agents/plugins/marketplace.json for a personal 列出。添加 one entry per plugin under plugins[], point each source.path at the plugin folder 使用 a ./-prefixed path relative 到 the marketplace root, 和 设置 interface.displayName 到 the label you want Codex 到 显示 in the marketplace picker。Then restart Codex。After that, 打开 the plugin directory, 选择 your marketplace, 和 browse 或 安装 the plugins in that curated 列出.

You don’t need a separate marketplace per plugin。One marketplace can expose a single plugin while you are testing, then grow into a larger curated catalog as you 添加 more plugins.

使用 codex plugin marketplace add when you want Codex to install and track a marketplace source for you instead of editing config.toml by hand.

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 sources can be GitHub shorthand (owner/repo 或 owner/repo@ref), HTTP 或 HTTPS Git URLs, SSH Git URLs, 或 local marketplace root directories。使用 --ref 到 pin a Git ref, 和 repeat --sparse PATH 到 使用 a sparse checkout for Git-backed marketplace repos。--sparse is valid only for Git marketplace sources.

To inspect, refresh, 或 移除 configured 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 prints each marketplace Codex is considering and the root path it resolves from, including local default marketplaces and configured marketplace snapshots.

启动 使用 a minimal plugin that packages one skill.

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/"
}

使用 a stable plugin name in kebab-case。Codex uses it as the plugin identifier 和 component namespace.

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.

From there, you can 添加 MCP config, app integrations, 或 marketplace metadata as needed.

使用 a repo marketplace 或 a personal marketplace, depending on who should be able 到 access the plugin 或 curated 列出.

添加 a marketplace file at $REPO_ROOT/.agents/plugins/marketplace.json 和 store your plugins under $REPO_ROOT/plugins/.

Repo marketplace example

Step 1：复制 the plugin folder into $REPO_ROOT/plugins/my-plugin.

mkdir -p ./plugins
cp -R /absolute/path/to/my-plugin ./plugins/my-plugin

Step 2：添加 或 update $REPO_ROOT/.agents/plugins/marketplace.json so that source.path points 到 that plugin directory 使用 a ./-prefixed relative path:

{
  "name": "local-repo",
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Step 3：Restart Codex 和 verify that the plugin appears.

添加 a marketplace file at ~/.agents/plugins/marketplace.json 和 store your plugins under ~/.codex/plugins/.

Personal marketplace example

Step 1：复制 the plugin folder into ~/.codex/plugins/my-plugin.

mkdir -p ~/.codex/plugins
cp -R /absolute/path/to/my-plugin ~/.codex/plugins/my-plugin

Step 2：添加 或 update ~/.agents/plugins/marketplace.json so that the plugin entry’s source.path points 到 that directory.

Step 3：Restart Codex 和 verify that the plugin appears.

The marketplace file points 到 the plugin location, so those directories are examples rather than fixed requirements。Codex resolves source.path relative 到 the marketplace root, not relative 到 the .agents/plugins/ folder。See Marketplace metadata for file format.

After you change the plugin, update the plugin directory that your marketplace entry points 到 和 restart Codex so the local 安装 picks up the 新的 files.

After you create a plugin 和 添加 it 到 Codex, you can share it 使用 other members of your ChatGPT workspace 从 the Codex app.

People you share 使用 can find the plugin under Shared 使用 you in the plugin directory。Sharing a local plugin 使用 your workspace doesn’t publish it 到 the public Plugin Directory。Shared plugins stay within your workspace 和 organization boundary；accounts that aren’t signed in 到 that workspace can’t access them。使用 groups 当 a team 或 role should share the same plugin access。使用 a marketplace 当 you want repo 或 CLI distribution, 和 使用 workspace sharing 当 you want selected teammates 到 安装 a plugin 从 the Codex app.

Workspace admins can disable plugin sharing 从 cloud-managed requirements by adding features.plugin_sharing = false 到 requirements.toml:

features.plugin_sharing = false

如果 you maintain a repo marketplace, define it in $REPO_ROOT/.agents/plugins/marketplace.json。For a personal marketplace, 使用 ~/.agents/plugins/marketplace.json。A marketplace file controls plugin ordering 和 安装 policies in Codex-facing catalogs。It can represent one plugin while you are testing 或 a curated 列出 of plugins that you want Codex 到 显示 together under one marketplace name。Before you 添加 a plugin 到 a marketplace, make sure its version, publisher metadata, 和 安装-surface 复制 are ready for other developers 到 see.

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

The marketplace controls where Codex loads the plugin 从。A local source.path can point somewhere else 如果 your plugin lives outside those example directories。A marketplace file can live in the repo where you are developing the plugin 或 in a separate marketplace repo, 和 one marketplace file can point 到 one plugin 或 many.

Marketplace entries can also point at Git-backed plugin sources。使用 "source"："url" 当 the plugin lives at repository root, 或 "source"："git-subdir" 当 the plugin lives in a subdirectory:

{
  "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 entries may 使用 ref 或 sha selectors。如果 Codex can’t resolve a marketplace entry’s source, it skips that plugin entry 而不是 failing the whole marketplace.

A plugin marketplace is a JSON catalog of plugins that Codex can 读取 和 安装.

Codex can 读取 marketplace files 从:

You can 安装 any plugin exposed through a marketplace。Codex installs plugins into ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/。For local plugins, $VERSION is local, 和 Codex loads the installed 复制 从 that cache path rather than directly 从 the marketplace entry.

You can enable 或 disable each plugin individually。Codex stores each plugin’s on 或 off state in ~/.codex/config.toml.

Every plugin has a manifest at .codex-plugin/plugin.json。It can also include a skills/ directory, a hooks/ directory for lifecycle hooks, an .app.json file that points at one 或 more apps 或 connectors, an .mcp.json file that configures MCP servers, 和 assets used 到 present the plugin across 支持的 surfaces.

Only plugin.json belongs in .codex-plugin/。Keep skills/, hooks/, assets/, .mcp.json, 和 .app.json at the plugin root.

Published plugins typically 使用 a richer manifest than the minimal example that appears in quick-start scaffolds。The manifest has three jobs:

Here’s a complete manifest example:

{
  "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 is the 必需 entry point。The other manifest fields are 可选, but published plugins commonly 使用 them.

使用 the top-level fields 到 define package metadata 和 point 到 bundled components:

使用 the interface object for 安装-surface metadata:

mcpServers can point 到 an .mcp.json file that contains either a direct server map 或 a wrapped mcp_servers object.

Direct server map:

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

Wrapped server map:

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

After installation, users can enable 或 disable a bundled MCP server 和 tune tool approval policy 从 their Codex config 不使用 editing the plugin。使用 plugins.<plugin>.mcp_servers.<server> for plugin-scoped MCP server policy:

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

当 your plugin is enabled, Codex can load lifecycle hooks 从 your plugin alongside user, project, 和 managed hooks.

Installing 或 enabling a plugin doesn’t 自动 trust its hooks。Plugin-bundled hooks are non-managed hooks, so Codex skips them until the user reviews 和 trusts the 当前 hook definition.

The 默认 plugin hook file is hooks/hooks.json:

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

如果 you define hooks in .codex-plugin/plugin.json, Codex uses that manifest entry 而不是 the 默认 hooks/hooks.json。The manifest field can be a single path, an array of paths, an inline hooks object, 或 an array of inline hooks objects.

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

Hook paths follow the same manifest path rules as skills, apps, 和 mcpServers：启动 使用 ./, resolve relative 到 the plugin root, 和 stay inside the plugin root.

Plugin hook commands receive the Codex-specific environment variables PLUGIN_ROOT 和 PLUGIN_DATA。PLUGIN_ROOT points 到 the installed plugin root, 和 PLUGIN_DATA points 到 the plugin’s writable data directory。Codex also sets CLAUDE_PLUGIN_ROOT 和 CLAUDE_PLUGIN_DATA for compatibility 使用 已有 plugin hooks.

Plugin hooks 使用 the same event schema as regular hooks。See Hooks for 支持的 events, inputs, outputs, trust 检查, 和 当前 limitations.

Adding plugins 到 the official Plugin Directory is coming soon.

Self-serve plugin publishing 和 management are coming soon.