如果您已经构建了插件,希望让更多人使用,可以将它发布到插件目录,方便用户在 ChatGPT 和 Codex 中发现并使用。插件可以包含 MCP 连接、技能,或同时包含两者。
将构建好的插件包以 ZIP 文件的形式上传,解决自动检查发现的问题,然后提交审核。审核通过后,您可以自行决定何时发布。
首次发布后,系统会自动检测 MCP 服务器的变更,符合条件的更新通过自动检查后就会上线。更新服务器无需上传新的插件 ZIP 文件,也无需逐次发布更新。如果更改了插件元数据或技能,仍需上传新的 ZIP 文件。
提交前,请按照插件打包指南准备插件包,并阅读插件准则。您也可以使用插件目录中的 Plugin Creator 准备提交材料。

插件概览。 在“插件”页面发起提交,跟踪发布状态、审核进度和 MCP 设置状态。
提交远程 MCP 服务器时,请选择包含 MCP,并提供稳定且可公开访问的 HTTPS 端点。如果您的插件运行本地 MCP 服务器,或必须在桌面端执行,请参阅提交仅限桌面端使用的插件。
1. 上传插件 ZIP 文件
确认权限和发布身份
选择插件所属的组织和项目。组织所有者可以提交插件。其他成员需要 Apps Management Write 权限,所有者可以通过组织角色授予此权限。
在组织设置中完成个人或企业验证,即可以您本人或公司的名义发布插件。
创建草稿
如果您的插件使用 MCP 服务器,请在首次上传的 ZIP 文件中包含该服务器的配置。目前不支持向现有的纯技能插件添加 MCP 服务器。
- 打开插件页面,选择上传新插件或现有插件。
- 选择已通过验证的开发者身份。插件目录会显示与该身份关联的名称。
- 选择上传插件,然后选择您的 ZIP 文件。
- 验证通过后,系统会打开插件详情页,显示新草稿。
如果验证失败,请修正系统报告的插件包错误并重新上传。不要将私密凭据或密钥放入 ZIP 文件。
2. 查看检查结果并解决问题
上传 ZIP 文件后,插件详情页会显示自动检查的进度和结果,方便您在提交审核前解决问题。元数据与技能显示上传的插件包版本,MCP 服务器显示已连接的服务器和扫描到的工具。两者分开显示,因为更改插件包需要上传新的 ZIP 文件,而系统可以直接连接您的服务器检查托管工具的变更。
检查元数据
- 打开元数据与技能。页面会自动显示最近上传的版本。
- 等待元数据检查完成,然后在问题中查看检查发现的问题。
- 选择复制问题,以便在开发过程中使用这些检查结果。
- 修正插件包中受影响的字段,然后选择上传插件以修复问题,上传修正后的 ZIP 文件并查看新的检查结果。
提示: 您可以让 Codex 或 ChatGPT 检查插件包和复制的检查结果,解释问题,并建议如何修正元数据或技能。

元数据检查结果。 查看所选插件包版本的检查结果,并上传修正后的 ZIP 文件。
此处的插件包详情为只读。请参照插件包字段参考在源插件包中编辑。公开 URL 必须可以访问,且其指明的发布者必须与提交时的发布者一致。
检查技能
如果插件包包含技能,请在元数据与技能中查看检查结果。打开具体问题,查看涉及哪项技能以及需要修改的内容,然后更新该技能的指令或配套文件,上传修正后的 ZIP 文件。查看更新后的检查结果。所有必需的技能扫描都必须成功完成,才能提交审核。
连接并扫描 MCP 服务器
插件包可以声明多个 MCP 服务器,但每个插件只能连接一个 MCP 服务器。首次连接该服务器时,请完成以下设置。如果连接出现问题,请使用重新连接。如果工具有变更,请参阅扫描最新变更。
- 打开 MCP 服务器,选择要连接的服务器。
- 选择连接,打开连接 MCP 服务器面板。
- 核对 MCP 服务器 URL、身份验证及相关设置。
- 按照门户中的提示完成域名验证质询,然后连接服务器,并在需要时完成身份验证。
- 等待自动工具扫描完成,然后检查扫描到的工具。打开问题查看检查结果。
- 修复连接问题或扫描发现的服务器端问题,然后根据情况选择重新连接或重新扫描,并查看新的结果。

MCP 连接和域名验证。 连接服务器并完成域名验证,然后检查扫描到的工具。
对于已获批准的本地 MCP 插件,请选择仅包含技能,并按照仅限桌面端使用的插件提交说明操作。
在您填写表单期间,门户会将提交内容保存为草稿。
如果连接或扫描失败,请检查端点是否可用以及身份验证是否正常,然后重新连接或重新扫描。提交前,请解决完成 MCP 设置中列出的问题,并修复连接故障。有关 MCP 服务器 URL、身份验证、工具元数据和用户界面的要求,请参阅插件准则。
配置提交所需的身份验证
门户会从插件包的 mcp.json 中读取高级身份验证设置。请参照 MCP 身份验证参考配置身份验证方法、OAuth 客户端注册方式、端点和权限范围。连接面板会显示这些设置,但不提供高级 OAuth 设置编辑器。
要更改配置,请更新 mcp.json,选择上传新版本,并在连接前检查 MCP 服务器中保存的设置。如果客户端已经注册,凭据可能无法更改。请检查已保存的连接,以确认上传后实际使用的客户端。
对于 OAuth,请选择您的提供商支持的注册方式:
| 注册方式 | 需要提供的内容 |
|---|---|
已注册的客户端(provided) |
在 mcp.json 中声明客户端 ID 和令牌端点身份验证方法。需要时,在门户中输入客户端密钥。 |
动态客户端注册(dcr) |
通过自动发现或 registrationUrl 覆盖设置提供注册端点。不要在插件包中包含客户端凭据。 |
客户端标识符元数据文档(cimd) |
配置 CIMD 首选项。运行时可以根据注册策略回退到 DCR。 |
如果使用已注册的客户端:
- 在 OAuth 提供商处注册连接流程使用的回调 URL。
- 打开 MCP 服务器,选择您的服务器,然后选择连接。
- 如果客户端需要密钥,请输入 OAuth 客户端密钥。对于自行提供的 OAuth 客户端,除非
tokenEndpointAuthMethod为"none",否则会显示此字段。 - 如有需要,完成域名验证,然后选择连接,并为用于连接和扫描服务器的账号授权。
- 等待扫描完成,解决检查发现的连接或工具问题。
不要将客户端密钥放入 mcp.json,清单不接受 clientSecret。客户端密钥用于验证您的 OAuth 应用。请勿将其与账号密码、访问令牌或审核人员的登录凭据混淆。
如果通过 OAuth 自动发现无法获取所需端点,请将 authorizationUrl 和 tokenUrl 的覆盖设置添加到 mcp.json 中。确保客户端 ID、令牌端点身份验证方法、权限范围和回调 URL 与提供商的配置一致。
身份验证限制
门户的连接表单支持无身份验证、OAuth,以及无身份验证与 OAuth 混合使用的访问方式。虽然清单模式接受 API 密钥身份验证,但门户不提供 API 密钥连接流程,也没有用于输入 Bearer 令牌的字段。此限制同样适用于通过 Basic 身份验证或自定义请求头声明 API 密钥的情况。仅上传 API 密钥声明无法完成 MCP 设置。如果您的插件必须使用这种身份验证方法,请联系 OpenAI。
不要在服务器的 headers 中嵌入令牌来绕过此限制。提交到公开目录时,系统会拒绝非空的服务器请求头。不要将受保护的服务器配置为 type: "none"。
对于自行提供的 OAuth 客户端,模式接受 private_key_jwt,但仅设置该值并不能配置签名密钥。本门户指南未提供签名密钥的设置步骤。如果要使用这种方法提交,请先向 OpenAI 确认所需配置。
域名验证详情
验证域名时,请在门户显示的 URL 上以纯文本形式提供与门户所示内容完全一致的质询令牌:
https://<challenge-base-host>/.well-known/openai-apps-challenge
响应中只能包含该令牌的原文,不要返回 JSON 或令牌列表。质询使用的基准地址必须是 MCP 主机名或符合条件的父域名对应的 HTTPS 源,路径会被忽略。如果其他插件已使用同一质询 URL,请使用允许的父域名源或不同的主机名,不要替换其他插件的令牌。如果两种方式都不可行,请联系支持团队。
3. 提交审核
查看自动检查结果后,请补全审核团队测试插件所需的信息,并提交所选草稿。您必须先完成必需的设置并解决验证错误。其他自动检查发现的问题可以一并提交给审核团队评估。
补全审核信息
包含 MCP 连接的插件需要提供审核信息,以便审核团队测试集成。您可以将正向和反向测试用例、演示视频 URL 和发行说明写入 plugin.json,以便随 ZIP 文件一起导入。请参阅审核和发布字段参考及完整元数据示例。插件目录中的 Plugin Creator 可以帮助您准备这些信息。请在审核详情中单独输入审核人员的凭据。请准备以下材料:
- 审核人员凭据(需要登录时提供)。 提供专用测试账号、登录 URL、工作空间或租户详情,以及登录说明。使用示例数据,不要提供真实用户的账号。账号必须具备运行测试用例所需的权限和数据,并且应能立即使用,无需 MFA 审批、电子邮件或短信验证码、免密登录链接,也无需访问专用网络。
- 五个正向测试用例。 每个用例应包含场景、用户提示词、预期调用的工具和预期结果。提交前,请使用测试账号运行每个用例。
- 三个反向测试用例。 提供插件不应执行操作的提示词或场景,说明插件不应完成请求的原因,以及预期的拒绝答复、澄清问题或安全的替代处理方式。
- 演示视频。 演示测试用例和插件功能,并提供可访问的录像 URL。
- 发行说明。 简要说明提交的插件包版本及其变更内容。
在元数据与技能中,打开审核信息 → 审核详情,核对导入的材料并输入审核人员凭据。填写所有可编辑字段,然后选择保存详情。对于标记为由插件 ZIP 文件管理的字段,请在插件包中添加或修改信息,再重新上传。您也可以在插件包元数据中指定插件在哪些国家/地区可用,并提供翻译。若已提供,请核对导入的设置。有关支持的字段及其导入规则,请参阅自动提供提交和审核信息。

审核详情。 检查从 ZIP 文件导入的测试用例和配套材料,并单独输入审核人员的私密凭据。
凭据不会包含在公开发布的插件包中。请保留测试账号和示例数据,以供后续审核使用。如果凭据或登录步骤有变更,请在草稿中更新详情并重新提交。
如果插件使用 iframe,请逐一说明每个嵌入页面的功能、需要嵌入该页面的原因,以及谁控制该页面所在的域名。技术细节请参阅 iframe 要求。
提交插件前,请在多种不同场景下充分测试插件的 MCP 服务器、工具以及用户界面(如有)。
提交草稿
选择草稿,点击提交审核,并完成必需的政策合规声明。提交后,可在“插件”页面的审核状态下跟踪进度。审核团队会通过电子邮件发送反馈。

提交审核。 确认必需的声明,然后提交所选草稿以供审核。
每个插件同一时间只能有一个版本接受审核。要替换正在审核的插件包,请等待审核结果,或先取消审核再上传。如果插件包未通过审核,请根据反馈修正后提交新的 ZIP 文件。
如果审核团队拒绝了您的提交,请查看通知邮件中的原因。如需申诉,请回复该邮件,说明为何应重新考虑审核决定。
4. 发布已通过审核的插件
插件通过审核后,您可以决定何时开放使用。打开已通过审核的插件包版本,选择发布插件。发布更新时,新版本会替换之前的插件包版本。
更新已发布的插件
要更新元数据、资源文件或随包提供的技能,请向现有插件上传新的 ZIP 文件。系统会创建一个新的插件包版本,单独对其进行检查和审核。托管工具的变更通过 MCP 扫描单独处理,无需上传插件包。
如果您之前通过旧版提交表单提交了插件,可以先将现有插件下载为 ZIP 文件。打开插件,选择已发布的插件包版本,然后选择下载发行版 ZIP 文件(位于 … 菜单中)。如果您已经在本地维护插件包,也可以直接使用本地源文件。
- 更新插件包内容和版本号,然后创建完整的 ZIP 文件,包含您打算保留的所有组件。
- 打开现有插件,选择上传插件以进行更改。
- 在元数据与技能中确认所选插件包版本。查看新的自动检查结果,解决必须修复的问题。
- 完成适用的审核步骤,然后发布已通过审核的插件包版本。
添加或移除技能时,请继续使用同一个插件。如果需要更改现有 MCP 服务器的 URL,请联系支持团队。当前更新流程不支持更改 URL。
更新 MCP 服务器
首次发布后,OpenAI 会每天扫描您托管的 MCP 服务器。符合条件的更新通过自动检查后即可使用,无需创建新的插件包版本或单独执行发布操作。部署服务器变更后,您也可以立即请求扫描。
扫描最新变更
- 将变更部署到 MCP 服务器。
- 打开现有插件,选择 MCP 服务器,然后选择已连接的服务器。
- 在问题下选择重新扫描。
- 等待扫描完成,查看检查结果并确认工具是否可用。

MCP 扫描概览。 更改服务器后重新扫描,然后检查扫描结果以及各个工具的可用状态。
如果另一次扫描正在进行、申诉正在处理中,或插件不符合扫描条件,重新扫描功能可能不可用。
查找并解决工具问题
- 打开问题,选择受影响的工具。
- 阅读发现的问题,并在暂缓上线的更新中查看此次检查评估的元数据。当前生效的定义显示正在使用的元数据。
- 选择复制问题,以便在开发过程中使用这些检查结果。
- 修正服务器上的工具元数据或实现,然后部署变更。
- 返回问题,选择重新扫描,并查看更新后的结果。
提示: 您可以让 Codex 或 ChatGPT 检查 MCP 服务器和复制的错误信息,解释问题并提出修复建议。
系统会分别评估每项工具变更。某项变更被标记为有问题,不一定会阻止其他符合条件的工具更新上线。新工具通过审核后才可用。现有工具的更新暂缓上线时,工具会继续使用之前通过审核的元数据。移除工具的操作会在扫描后生效。
在更新后的元数据上线前,请确保 MCP 服务器与当前已通过审核的工具模式兼容。
对自动检查结果提出申诉
如果自动审核提示工具注解存在问题,您可以提交申诉,并在申诉中说明情况或提供补充信息。
如果您认为某项工具检查结果有误,请选择申诉,说明审核团队应重新考虑该结果的原因。审核团队会一并评估此次扫描中暂缓上线的所有工具变更。如果检查发现的问题确实存在,通常在服务器上修正后重新扫描会更快。

MCP 申诉。 说明审核团队应重新考虑自动检查结果的原因。
申诉期间,MCP 自动更新会暂停。如需更改,请选择撤回申诉,更新服务器,然后重新扫描。申诉仅涵盖暂缓上线的工具变更,不涉及插件包变更、身份验证或服务器共享指令。
如需排查问题,请参阅提交错误。联系支持团队时,请提供您的插件 ID。
自动提供提交和审核信息
您可以在插件清单中写入目录展示信息、审核材料和发布详情,以便在上传 ZIP 文件时自动填入。以下参考说明了支持的字段、上传时如何应用这些字段,并给出了每种插件包格式的示例。
目前无法提交包含应用引用(apps / .app.json)或生命周期钩子的插件 ZIP 包。请在 MCP 配置中声明 MCP 服务器 URL,并在控制台完成设置。
提交到公开目录前,请移除生命周期钩子。如果插件依赖生命周期钩子,请以用户可以在 Codex 桌面端手动安装的方式分发插件。
完整元数据示例
以下示例使用不同格式描述同一个笔记插件。请复制与您的插件包格式对应的清单,然后将发布者信息、URL、工具名称、审核用例、翻译和可用国家/地区替换为实际值。这些示例用例尚未在真实服务上运行。
请包含清单引用的文件:
skills/get-started/SKILL.md,其 YAML 文件头中必须包含有效的 name 和 description 字段。assets/下的四个图标文件。- 仅配置一个名为 notes 的远程 MCP 服务器。对于 Agent Plugins,在
mcp.json中配置;对于 Codex,在.mcp.json中配置。请使用下方对应的配置。
请提供您自己的演示和审核附件 URL,并确保审核人员可以访问。example.com 链接仅用于展示格式,不能作为实际提交材料。如果插件仅包含技能,请省略 review 和 MCP 配置,并从 Codex 清单中省略 mcpServers。
对于 Agent Plugins 示例,请使用以下配套的 mcp.json:
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"notes": {
"type": "streamable-http",
"url": "https://example.com/mcp"
}
}
}
对于 Codex 示例,请将以下内容保存为插件根目录下的 .mcp.json。此格式省略了 Agent Plugins 模式:
{
"mcpServers": {
"notes": {
"url": "https://example.com/mcp"
}
}
}
Agent Plugins 格式
将以下完整清单保存为插件根目录下的 plugin.json:
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "acme-notes",
"version": "1.0.0",
"description": "Search and summarize notes from your Acme workspace.",
"author": {
"name": "Acme",
"email": "support@example.com",
"url": "https://example.com"
},
"homepage": "https://example.com/notes",
"repository": "https://github.com/example/acme-notes",
"license": "MIT",
"keywords": ["notes", "search", "productivity"],
"extensions": {
"com.openai": {
"interface": {
"displayName": "Acme Notes",
"shortDescription": "Find and summarize your notes",
"longDescription": "Search notes in your Acme workspace, open matching notes, and summarize decisions with links to the source. Acme Notes only accesses notes available to your connected account.",
"developerName": "Acme",
"category": "Productivity",
"capabilities": ["Search notes", "Read notes"],
"websiteURL": "https://example.com/notes",
"supportURL": "https://example.com/support",
"privacyPolicyURL": "https://example.com/privacy",
"termsOfServiceURL": "https://example.com/terms",
"defaultPrompt": [
"Find my notes about the launch.",
"Summarize the decisions in my launch notes.",
"Open the project kickoff notes."
],
"brandColor": "#2357C6",
"brandColorDark": "#8CB4FF",
"composerIcon": "./assets/icon.png",
"composerIconDark": "./assets/icon-dark.png",
"logo": "./assets/logo.png",
"logoDark": "./assets/logo-dark.png"
},
"onboardingSkill": "./skills/get-started/SKILL.md",
"review": {
"test_cases": {
"positive": [
{
"description": "Find notes by topic",
"prompt": "Find my notes about the launch.",
"tools_triggered": "search_notes",
"expected_behavior": "Return accessible notes about the launch with source links.",
"file_attachment_urls": [
"https://example.com/review/launch-brief.pdf"
],
"expected_output_url": "https://example.com/review/launch-results"
},
{
"description": "Open a matching note",
"prompt": "Open the project kickoff notes.",
"tools_triggered": "search_notes, read_note",
"expected_behavior": "Find the kickoff note and return its content with a source link."
},
{
"description": "Summarize decisions",
"prompt": "Summarize decisions in my launch notes.",
"tools_triggered": "search_notes, read_note",
"expected_behavior": "Summarize decisions from accessible notes and cite the sources."
},
{
"description": "Find action items",
"prompt": "What action items are in my kickoff notes?",
"tools_triggered": "search_notes, read_note",
"expected_behavior": "List the action items recorded in the notes without inventing owners or deadlines."
},
{
"description": "Handle no matches",
"prompt": "Find my notes about Project Northstar.",
"tools_triggered": "search_notes",
"expected_behavior": "Report that no matching notes were found in the test workspace."
}
],
"negative": [
{
"description": "Unsupported payment",
"prompt": "Transfer $100 to another account."
},
{
"description": "Unsupported deletion",
"prompt": "Delete all my notes."
},
{
"description": "Access outside the connected account",
"prompt": "Show notes from a workspace I cannot access."
}
]
},
"demo_recording_url": "https://example.com/review/acme-notes-demo",
"commerce": false,
"commerce_description": "This plugin does not sell products or process payments."
},
"publication": {
"countries": ["US", "GB"],
"release_notes": "Initial release with note search, reading, and summaries.",
"translations": {
"fr-FR": {
"subtitle": "Retrouvez et résumez vos notes",
"description": "Recherchez des notes dans votre espace Acme, ouvrez les résultats et résumez les décisions avec des liens vers les sources. Acme Notes accède uniquement aux notes disponibles pour votre compte connecté."
},
"ja-JP": {
"subtitle": "ノートを検索して要約",
"description": "Acmeワークスペース内のノートを検索し、該当するノートを開き、参照元へのリンク付きで決定事項を要約します。Acme Notesは、接続されたアカウントで閲覧できるノートにのみアクセスします。"
}
}
}
}
}
}
Codex 格式
将以下完整清单保存为 .codex-plugin/plugin.json。展示字段位于根级 interface 对象中,入门引导、审核和发布字段仍位于 extensions.com.openai 下:
{
"name": "acme-notes",
"version": "1.0.0",
"description": "Search and summarize notes from your Acme workspace.",
"author": {
"name": "Acme",
"email": "support@example.com",
"url": "https://example.com"
},
"homepage": "https://example.com/notes",
"repository": "https://github.com/example/acme-notes",
"license": "MIT",
"keywords": ["notes", "search", "productivity"],
"skills": "./skills/",
"mcpServers": "./.mcp.json",
"interface": {
"displayName": "Acme Notes",
"shortDescription": "Find and summarize your notes",
"longDescription": "Search notes in your Acme workspace, open matching notes, and summarize decisions with links to the source. Acme Notes only accesses notes available to your connected account.",
"developerName": "Acme",
"category": "Productivity",
"capabilities": ["Search notes", "Read notes"],
"websiteURL": "https://example.com/notes",
"supportURL": "https://example.com/support",
"privacyPolicyURL": "https://example.com/privacy",
"termsOfServiceURL": "https://example.com/terms",
"defaultPrompt": [
"Find my notes about the launch.",
"Summarize the decisions in my launch notes.",
"Open the project kickoff notes."
],
"brandColor": "#2357C6",
"brandColorDark": "#8CB4FF",
"composerIcon": "./assets/icon.png",
"composerIconDark": "./assets/icon-dark.png",
"logo": "./assets/logo.png",
"logoDark": "./assets/logo-dark.png"
},
"extensions": {
"com.openai": {
"onboardingSkill": "./skills/get-started/SKILL.md",
"review": {
"test_cases": {
"positive": [
{
"description": "Find notes by topic",
"prompt": "Find my notes about the launch.",
"tools_triggered": "search_notes",
"expected_behavior": "Return accessible notes about the launch with source links.",
"file_attachment_urls": [
"https://example.com/review/launch-brief.pdf"
],
"expected_output_url": "https://example.com/review/launch-results"
},
{
"description": "Open a matching note",
"prompt": "Open the project kickoff notes.",
"tools_triggered": "search_notes, read_note",
"expected_behavior": "Find the kickoff note and return its content with a source link."
},
{
"description": "Summarize decisions",
"prompt": "Summarize decisions in my launch notes.",
"tools_triggered": "search_notes, read_note",
"expected_behavior": "Summarize decisions from accessible notes and cite the sources."
},
{
"description": "Find action items",
"prompt": "What action items are in my kickoff notes?",
"tools_triggered": "search_notes, read_note",
"expected_behavior": "List the action items recorded in the notes without inventing owners or deadlines."
},
{
"description": "Handle no matches",
"prompt": "Find my notes about Project Northstar.",
"tools_triggered": "search_notes",
"expected_behavior": "Report that no matching notes were found in the test workspace."
}
],
"negative": [
{
"description": "Unsupported payment",
"prompt": "Transfer $100 to another account."
},
{
"description": "Unsupported deletion",
"prompt": "Delete all my notes."
},
{
"description": "Access outside the connected account",
"prompt": "Show notes from a workspace I cannot access."
}
]
},
"demo_recording_url": "https://example.com/review/acme-notes-demo",
"commerce": false,
"commerce_description": "This plugin does not sell products or process payments."
},
"publication": {
"countries": ["US", "GB"],
"release_notes": "Initial release with note search, reading, and summaries.",
"translations": {
"fr-FR": {
"subtitle": "Retrouvez et résumez vos notes",
"description": "Recherchez des notes dans votre espace Acme, ouvrez les résultats et résumez les décisions avec des liens vers les sources. Acme Notes accède uniquement aux notes disponibles pour votre compte connecté."
},
"ja-JP": {
"subtitle": "ノートを検索して要約",
"description": "Acmeワークスペース内のノートを検索し、該当するノートを開き、参照元へのリンク付きで決定事項を要約します。Acme Notesは、接続されたアカウントで閲覧できるノートにのみアクセスします。"
}
}
}
}
}
}
请选择与插件包格式对应的字段位置:
| 元数据 | Agent Plugins:根目录下的 plugin.json | Codex:.codex-plugin/plugin.json |
|---|---|---|
| 插件包标识和发布者 | 根级字段 | 根级字段 |
| 目录展示文本、链接、提示词和图片 | extensions.com.openai.interface |
interface |
| 入门技能 | extensions.com.openai.onboardingSkill | extensions.com.openai.onboardingSkill |
| 审核和发布详情 | extensions.com.openai.review 和 extensions.com.openai.publication | extensions.com.openai.review 和 extensions.com.openai.publication |
对于 Agent Plugins 包,请将 OpenAI 专用设置放在 plugin.json 的 extensions.com.openai 下。如果该对象存在,OpenAI 会忽略 .codex-plugin/plugin.json 中的设置,不会合并这两个文件。如果该对象不存在,OpenAI 会从 .codex-plugin/plugin.json 读取这些设置。插件包标识仍取自根目录下的 plugin.json,技能取自 skills/,MCP 服务器配置取自 mcp.json。
您可以参照完整元数据示例开始配置。如果开发者控制台提示缺少隐私政策 URL、支持页面 URL 或应用图标,请查阅字段参考,找到对应的清单字段。
清单字段
“要求”列分别说明插件包格式和提交审核的要求。审核详情在 ZIP 文件中为可选项,但提交前必须备齐所需材料。
插件包标识和组件
以下字段描述插件包本身。两种格式都应将这些字段放在清单根级,表中指定为 OpenAI 扩展字段的除外。
| 字段 | 要求 | 值和用途 |
|---|---|---|
$schema |
Agent Plugins 必填,Codex 省略 | 可移植格式必须使用 https://agent-plugins.org/schemas/1.0.0/plugin.schema.json 。独立的 Codex 兼容清单应省略此字段。 |
name |
必填 | 必须提供稳定的标识符,最多 64 个字符。准备提交的插件包标识符只能使用小写字母、数字和单个连字符。请将标识符与显示名称分开设置。 |
version |
Codex 必填,可移植模式可选 | 发行版本号,例如 1.0.0。可移植模式允许省略,但提交和更新时请明确指定语义化版本号。Codex 格式必须提供版本号。 |
description |
Codex 必填,Agent Plugins 可选 | 插件包简介,最多 4000 个字符。可移植模式可选,Codex 格式必填。 |
author |
Codex 必填,Agent Plugins 可选 | 发布者对象,包含 name,以及可选的 email 和 HTTPS url。可移植模式允许省略该对象,Codex 格式要求提供 author.name。名称最多 120 个字符,电子邮件地址最多 320 个字符,URL 最多 2048 个字符。 |
homepage |
可选 | 可选的 HTTPS 项目主页 URL,最多 2048 个字符。目录条目的 interface.websiteURL 需单独设置。 |
repository |
可选 | 可选的源代码仓库 URL。 |
license |
可选 | 可选的许可证标识符,例如 MIT。 |
keywords |
可选 | 可选的搜索关键词数组,方便用户发现插件。 |
extensions |
可选 | 按命名空间分组的设置。请将 OpenAI 专用设置放在 com.openai 下。 |
skills |
适用于包含技能的 Codex 插件包 | 仅限 Codex:包含技能的目录相对路径或路径数组,例如 "./skills/"。可移植插件包会自动从 skills/ 发现技能。 |
mcpServers |
适用于包含 MCP 服务器的 Codex 插件包 | 仅限 Codex:使用 "./.mcp.json" 指向随包提供的 MCP 服务器配置。可移植插件包会自动发现根目录下的 mcp.json。 |
对于可移植插件包,请将以下附加设置放在 extensions.com.openai 内。对于 Codex 兼容清单,请将其放在根级:
| 字段 | 要求 | 值和用途 |
|---|---|---|
interface |
Codex 必填,Agent Plugins 可选 | 目录展示元数据中介绍的展示对象。Codex 格式必须包含此对象。可移植插件包可以从根级元数据生成基本展示文本。 |
id |
可选 | 托管插件目录使用的可选标识符。如果已分配标识符,请保留原值。上传 ZIP 文件时使用控制台中的插件标识。 |
可移植插件包始终从 skills/ 发现技能,从 mcp.json 发现 MCP 服务器。内联扩展或兼容性覆盖配置中的 skills 或 mcpServers 声明不能替换、禁用或增加这些组件。这些声明仅适用于根目录中没有可识别的可移植清单的插件包。
目录展示元数据
对于 Agent Plugins 格式,请将以下字段放在 extensions.com.openai.interface 中。对于 Codex 格式,请放在 interface 中。此处列出的是提交到公开目录时的限制。上传插件包时,系统可以接受较长的草稿文本。上传成功并不表示目录条目已满足提交要求。
| 字段 | 要求 | 类型 | 值和提交限制 |
|---|---|---|---|
displayName |
必填 | 字符串 | 向用户显示的名称,必填,最多 30 个字符。 |
shortDescription |
必填 | 字符串 | 随名称显示的副标题,必填,最多 30 个字符。 |
longDescription |
必填 | 字符串 | 说明插件支持的任务、适用人群和使用限制,必填,最多 4000 个字符。 |
developerName |
必填 | 字符串 | 发布者名称,必填,最多 80 个字符。系统会根据您选择的已验证开发者身份自动设置目录中显示的发布者名称。 |
category |
必填 | 字符串 | 必须填写控制台中的类别名称,例如 Productivity 或 Developer Tools。 |
capabilities |
Codex 必填,Agent Plugins 可选 | 字符串数组 | 功能标签,最多 20 个,每个最多 120 个字符。Codex 格式必填,没有标签时请使用 []。 |
websiteURL |
MCP 审核必填 | 字符串 | HTTPS 产品网站 URL,最多 1024 个字符。 |
supportURL |
MCP 审核必填 | 字符串 | HTTPS 客户支持页面 URL,最多 1024 个字符。 |
privacyPolicyURL |
MCP 审核必填 | 字符串 | HTTPS 隐私政策 URL,最多 1024 个字符。 |
termsOfServiceURL |
MCP 审核必填 | 字符串 | HTTPS 服务条款 URL,最多 1024 个字符。 |
defaultPrompt |
可选 | 字符串或字符串数组 | 最多三个起始提示词,每个最多 128 个字符。提示词不能重复,也不要包含对应用的 @提及。有多个提示词时请使用数组。 |
brandColor |
可选 | 字符串 | 浅色主题颜色,格式为 #RRGGBB,与白色的对比度至少为 2:1。 |
brandColorDark |
可选 | 字符串 | 深色主题颜色,格式为 #RRGGBB,与 #212121 的对比度至少为 2:1。如果仅提供 brandColor,系统会据此生成深色主题颜色。 |
composerIcon |
Codex 必填 | 字符串 | 编辑器中使用的图标的相对路径。 |
composerIconDark |
可选 | 字符串 | 该图标深色主题版本的相对路径,可选。 |
logo |
Codex 必填,提交时必须提供主图标 | 字符串 | 目录条目主图标的相对路径。 |
logoDark |
可选 | 字符串 | 主图标深色主题版本的相对路径,可选。 |
如果关联的 MCP 应用需要接受公开发布审核,必须提供全部四个目录展示 URL:websiteURL、supportURL、privacyPolicyURL 和 termsOfServiceURL。请使用不含嵌入凭据的 HTTPS URL。纯技能插件的元数据验证不要求提供全部四个 URL。插件包的 homepage 和 author.url 不会自动填入这些目录展示字段。
图标
准备分发插件包时,请包含 logo 和 composerIcon。Codex 插件包验证要求两者齐全。可移植插件包即使没有这两个字段也能上传,但控制台要求在提交前提供应用主图标。深色主题版本为可选项。如果出现“需要应用图标”警告,请添加 logo 及其对应的图片文件,或在控制台中提供图标。
请使用以 ./ 开头、相对于插件根目录的路径,并包含所有引用的文件。支持的图片格式为 PNG、JPEG、WebP 和 SVG,每个文件最多 5 MiB。图标和徽标必须为正方形,尺寸至少为 48 × 48 像素。位图的宽和高均不能超过 4096 像素。对于 SVG 图标,请以数值明确指定相等的宽和高,或提供至少为 48 × 48 的正方形 viewBox。
配置入门引导、审核和发布信息
两种格式都应将这些对象直接放在 extensions.com.openai 下。在可移植格式中,它们与 interface 同级。不要将它们嵌套在 interface 内。
可选的 onboardingSkill 为用户提供安装后可以运行的设置流程。有关清单示例、路径规则,以及设置流程如何使用新的或现有的对话,请参阅添加入门技能。
| 字段 | 要求 | 类型 | 值和用途 |
|---|---|---|---|
onboardingSkill |
可选 | 字符串 | 插件包内某项技能的 SKILL.md 文件的相对路径,例如 ./skills/get-started/SKILL.md。路径必须指向包内已有的技能。 |
review.test_cases.positive |
ZIP 中可选,首次 MCP 审核需要五个用例 | 对象数组 | 仅包含一个 MCP 服务器的插件的正向审核用例。请使用下表中的用例字段。 |
review.test_cases.negative |
ZIP 中可选,首次 MCP 审核需要三个用例 | 对象数组 | 该服务器的反向审核用例。 |
review.demo_recording_url |
ZIP 中可选,MCP 审核必填 | 字符串 | 审核人员可以访问的演示视频 URL。 |
review.commerce |
可选 | 布尔值 | 指明应用是否支持商业交易。填写此声明不等于接受法律条款。 |
review.commerce_description |
可选 | 字符串 | 说明应用如何处理商业交易。 |
publication.countries |
可选 | 字符串数组 | 指定插件在哪些国家/地区可用的允许列表,使用系统可识别的大写国家/地区代码,例如 US 和 GB。省略该字段可保留现有范围,使用 [] 可移除国家/地区限制。此设置在插件发布时生效,也适用于纯技能插件。 |
publication.release_notes |
可选 | 字符串 | 描述此版本变更的发行说明。 |
publication.translations |
可选 | 对象或 null | 可选的映射,将语言区域键对应到翻译后的目录展示文本。请参阅翻译目录展示文本。 |
publication.translations.<locale>.subtitle |
可选 | 字符串或 null | 翻译后的副标题,可选,最多 30 个字符。 |
publication.translations.<locale>.description |
可选 | 字符串或 null | 翻译后的描述,可选,最多 4000 个字符。 |
review.test_cases.positive 或 review.test_cases.negative 中的每个对象描述一个测试用例:
| 字段 | 要求 | 类型 | 值和用途 |
|---|---|---|---|
description |
必填 | 字符串 | 必须说明要检查的行为。正向用例的描述不得超过 4000 个字符。 |
prompt |
必填 | 字符串 | 必须提供审核人员可以试用的用户提示词。 |
tools_triggered |
正向用例必填 | 字符串 | 预期调用的工具名称。提交时,正向用例必须提供此字段。 |
expected_behavior |
正向用例必填 | 字符串 | 可观察到的预期结果。提交时,正向用例必须提供此字段。 |
file_attachment_urls |
可选 | 字符串数组 | 用例所用文件的链接,可选。 |
expected_output_url |
可选 | 字符串 | 预期结果示例的链接,可选。例如,可提供参考文档,供审核人员与实际输出比对。 |
首次提交 MCP 应用审核时,必须恰好提供五个正向用例和三个反向用例。上传时系统接受不完整的列表,请在提交审核前补齐。如果包含多个 MCP 服务器,请在 MCP 配置中分别为每台服务器声明用例。插件级 review.test_cases 要求恰好有一台服务器,不能与服务器级用例声明同时使用。纯技能插件无需提供 MCP 应用审核用例或演示录像。
导入的测试用例在控制台中为只读。如需修改,请编辑插件包并重新上传。省略 test_cases 或将其设为 null,会保留现有用例。test_cases: {} 会清空两个列表。后续上传时省略用例,也不会恢复在控制台中编辑用例的功能。
对于审核信息中的标量字段和 release_notes,省略字段或将其设为 null 会保留已保存的值,空字符串则会清空文本。提交审核时,系统会重新应用插件包中明确指定的值。如果要使用在控制台中编辑的值,请从插件包中移除相应的标量字段声明。共享审核字段适用于插件自身的 MCP 应用草稿。纯技能插件的发行说明会保留在插件包中,不会触发应用审核。
请将 commerce 和 commerce_description 放在 review 中,不要放在 publication 中。不要在插件包中包含凭据或给审核人员的说明:ZIP 元数据不接受 test_credentials 和 reviewer_instructions。请通过控制台的安全表单输入审核人员所需的访问信息。
翻译目录展示文本
在两种格式中,都可以在 extensions.com.openai.publication 下添加 translations 对象,提供翻译后的副标题和描述。请使用非空的语言区域键,例如 fr-FR 或 ja-JP。每个语言区域对应的对象可以包含 subtitle、description 或两者。任一字段都可以省略或设为 null。您也可以省略 translations 或将其设为 null。
基础目录展示字段中应保留英文文本。无需提供 en-US 翻译,导入程序也不会自动生成该翻译。
翻译后的副标题必须为单行,最多 30 个字符。翻译后的描述可以包含 \n 换行符,最多 4000 个字符。提供的文本不能只包含空白字符,且必须使用受支持的文本字符。系统会拒绝制表符和其他不受支持的控制字符。字符数限制按文本原样计算,包括开头和结尾的空格。
系统会在导入时验证翻译,并将其保留在上传的插件包中。编辑元数据后,翻译也会保留。目前,导入翻译不会改变插件目录中显示的文本,也不会改变目录条目 API 响应中的文本。