本文面向想创建和分发 Codex Plugin 的开发者，覆盖从零开始的插件开发流程：用 $plugin-creator Skill 自动生成脚手架、手动构建插件目录结构、编写 plugin.json manifest、配置本地 marketplace 测试，以及打包和分发的相关注意事项。

构建 Codex Plugin

如果你只是想使用现有插件，见 Plugins。如果你只是在单个项目或个人工作流里用 Skill，不需要打包成插件——插件适合需要跨团队分发、或者要把 Skill + App + MCP 打包在一起的场景。

---

用 $plugin-creator 快速创建

最快的方式是使用内置的 $plugin-creator Skill：在 Codex 里输入 $plugin-creator 触发，它会自动生成 .codex-plugin/plugin.json manifest，并且可以同时生成用于本地测试的 marketplace 配置文件。

如果你已经有了插件目录，也可以用 $plugin-creator 来把它接入本地 marketplace。

---

构建本地 Marketplace（插件目录）

Marketplace 是一个 JSON 格式的插件目录，用于向 Codex 暴露一组插件。$plugin-creator 可以为单个插件生成一个 marketplace，也可以手动维护，持续添加条目来构建团队或个人的插件集合。

Codex 插件目录中，每个 marketplace 作为独立的来源显示。常用位置：

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

在 plugins[] 下每个插件一个条目，source.path 用 ./ 前缀相对于 marketplace 文件所在目录指向插件目录，interface.displayName 是在 Codex 插件目录里显示的名称。修改后重启 Codex 即可生效。

---

手动创建插件

第一步：创建目录和 manifest

mkdir -p my-first-plugin/.codex-plugin

my-first-plugin/.codex-plugin/plugin.json：

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "可复用的问候工作流",
  "skills": "./skills/"
}

name 使用 kebab-case 且保持稳定，Codex 用它作为插件标识符和组件命名空间。

第二步：创建 Skill

mkdir -p my-first-plugin/skills/hello

my-first-plugin/skills/hello/SKILL.md：

---
name: hello
description: 用友好的方式问候用户。
---

用热情的方式问候用户，并询问如何提供帮助。

第三步：添加到 marketplace

用 $plugin-creator 生成 marketplace，或者按下面的方式手动配置。

---

本地安装插件

仓库级 marketplace（团队共用）

Step 1：把插件目录复制到 $REPO_ROOT/plugins/my-plugin：

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

Step 2：创建 $REPO_ROOT/.agents/plugins/marketplace.json：

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

Step 3：重启 Codex，插件出现在插件目录里。

个人 marketplace

步骤类似，把插件放在 ~/.codex/plugins/my-plugin，marketplace 文件放在 ~/.agents/plugins/marketplace.json。

---

Marketplace metadata 格式

{
  "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 标识 marketplace
• interface.displayName 是在 Codex 里显示的 marketplace 标题
• source.path 相对于 marketplace 文件所在目录，必须用 ./ 开头
• 每个插件条目必须包含 policy.installation、policy.authentication 和 category

---

插件目录结构

my-plugin/
├── .codex-plugin/
│   └── plugin.json          # 必需：插件 manifest
├── skills/
│   └── my-skill/
│       └── SKILL.md         # 可选：Skill 指令
├── .app.json                # 可选：App/连接器映射
├── .mcp.json                # 可选：MCP Server 配置
└── assets/                  # 可选：图标、Logo、截图

只有 plugin.json 放在 .codex-plugin/ 里，其他文件（skills/、assets/、.mcp.json、.app.json）放在插件根目录。

---

完整 Manifest 示例

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "打包可复用 Skill 和 App 集成。",
  "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",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "可复用 Skill 和 App",
    "longDescription": "把 Skill 和 App 集成打包在一起分发。",
    "developerName": "Your team",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
    "websiteURL": "https://example.com",
    "privacyPolicyURL": "https://example.com/privacy",
    "termsOfServiceURL": "https://example.com/terms",
    "defaultPrompt": [
      "用 My Plugin 总结新的 CRM 笔记",
      "用 My Plugin 整理新的客户跟进"
    ],
    "brandColor": "#10A37F",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "screenshots": ["./assets/screenshot-1.png"]
  }
}

主要 manifest 字段

插件标识：name（kebab-case，保持稳定）、version、description

发布者信息：author、homepage、repository、license、keywords

组件指向：

• skills：指向 Skill 目录
• mcpServers：指向 .mcp.json 文件
• apps：指向 .app.json 文件

安装界面（interface）：

• displayName/shortDescription/longDescription：展示文案
• developerName/category/capabilities：发布者和能力元数据
• defaultPrompt：在插件目录里显示的快速启动提示
• composerIcon/logo/screenshots：视觉素材

路径规则：所有 manifest 路径相对于插件根目录，必须以 ./ 开头。

---

发布到官方插件目录

官方插件目录的自助发布功能即将推出。

---

常见问题

Q: 什么时候该用 Skill，什么时候该打包成 Plugin？

A: 如果你在单个仓库里自己用，直接用项目级 Skill（放 .codex/skills/ 或者 AGENTS.md）就够了。打包成 Plugin 适合以下场景：需要跨多个仓库使用、需要捆绑 App 集成或 MCP 配置、或者想分享给团队/发布给外部用户。

Q: Plugin manifest 里的 name 可以改吗？

A: 开发迭代阶段可以，但一旦发布或分发给他人后尽量不要改。Codex 用 name 作为插件标识符，改名会导致已安装的插件被识别为新插件。

Q: .mcp.json 里需要写什么？

A: 格式和 ~/.codex/config.toml 里的 [mcp_servers] 表相同，把 MCP Server 的配置写在这里，安装插件时 Codex 会自动加载。具体字段见 MCP 配置。