Plugin 提交错误
Plugin 提交错误
查找并修复提交到公开目录的 Plugin 校验错误，覆盖最终提交、ZIP 结构、manifest、MCP 工具、Skills、App 引用、图片、资产与安全扫描要求。
Plugin 提交错误#
Codex 中文站说明： 本页围绕“Plugin 提交错误”重新补充了中文使用场景和验证重点。界面名称可能随 Codex 版本更新，请以当前客户端为准。
查找并修复提交到公开目录的 Plugin 校验错误
提交到公开目录的 Plugin 需要满足比工作区内安装更严格的标准。目录提交既要通过通用 package 检查，也要通过目录字段、评审材料、MCP 工具、skills、资产和图片的额外检查。本参考还包含 App 引用等通用 package 检查；这些错误也可能出现在提交门户之外。
请根据提交时返回的错误代码查找对应要求。错误会阻止提交；警告不会阻止提交，但继续前应逐项检查。
非空值不能只包含空白字符。受支持文本不包括控制字符、Unicode 行分隔符或段落分隔符，以及不受支持的不可见格式字符。HTTPS URL 必须包含 host，且不得嵌入凭据或不受支持的字符。
最终目录提交#
Package 即使通过上传校验，仍可能在最终目录提交时失败。最终提交会使用更严格的目录字段限制，并检查 MCP 配置、skill 扫描、测试用例和政策声明。
| 字段 | 最终提交规则 |
|---|---|
| Package name | 必填；最多 64 个字符。以 ASCII 字母或数字开头，只能使用 ASCII 字母、数字、_ 和 -。 |
| Version | 必填；使用最长 64 个字符的语义版本。 |
| Display name | 必填；单行；最多 30 个字符。 |
| Short description | 必填；单行；最多 30 个字符。 |
| Long description | 必填；最多 4,000 个字符；允许换行。 |
| Developer name | 必填；单行；最多 80 个字符。 |
| Category | 必填；从目录与 interface 错误列出的分类中选择。 |
| Capabilities | 最多 20 项。每项不能为空，必须为单行，且最多 120 个字符。 |
| Starter prompts | 最多 3 条。每条不能为空；经过 Unicode 和空白规范化后必须唯一；必须为单行、最多 128 个字符，且不得包含 App @mention。 |
| URLs | MCP-backed 提交必填；skills-only 提交可选。Website、support、privacy policy 和 terms URL 必须使用 HTTPS，且最多 1,024 个字符。 |
| Brand colors | 可选的六位十六进制颜色。浅色与白色的对比度至少为 2:1；深色与 #212121 的对比度至少为 2:1。 |
每个 Plugin 提交还必须满足：
- 每个随附 skill 都通过安全扫描；扫描最多可能需要 2 小时。
- 使用已验证的开发者或企业身份，并完成全部必需的政策声明。
MCP-backed Plugin 的最终提交还必须满足：
- Website、support、privacy policy 和 terms URL 符合上述规则。
- 提供 demo recording URL，展示各受支持平台上的主要用例和工具。
- 恰好提供五个正向测试、三个负向测试以及 release notes。
- 使用生产环境 HTTPS MCP server URL，完成域名验证，并通过最新的工具扫描。
- 每个 MCP tool 都明确设置
readOnlyHint、openWorldHint和destructiveHint，并为每个值提供理由。 - Server 使用 OAuth 时，提供可供评审人员直接使用的演示凭据。
- 只有 MCP server 提供自定义 UI 时才能上传截图。每个 starter prompt 对应一张 PNG 或 JPEG；图片必须恰好 706 像素宽、400–860 像素高。
最终元数据错误#
以下错误名中的 subtitle 指 short description，description 指 long description。
| 名称 | 要求 |
|---|---|
submission_display_name_required | Display name 必填、不得为空，且必须为单行。 |
submission_display_name_too_long | Display name 最多 30 个字符。 |
submission_display_name_character_unsupported | Display name 必须使用受支持文本并保持单行。 |
submission_subtitle_required | Short description 必填、不得为空，且必须为单行。 |
submission_subtitle_too_long | Short description 最多 30 个字符。 |
submission_subtitle_character_unsupported | Short description 必须使用受支持文本并保持单行。 |
submission_description_required | Long description 必填且不得为空；允许换行。 |
submission_description_too_long | Long description 最多 4,000 个字符。 |
submission_description_character_unsupported | Long description 必须使用受支持文本；允许换行。 |
submission_developer_name_required | Developer name 必填、不得为空，且必须为单行。 |
submission_developer_name_too_long | Developer name 最多 80 个字符。 |
submission_developer_name_character_unsupported | Developer name 必须使用受支持文本并保持单行。 |
plugin_capability_invalid | 每项 capability 必须非空、使用受支持文本、保持单行，且最多 120 个字符。 |
plugin_default_prompt_mention | Starter prompt 不得包含 App @mention。 |
plugin_default_prompt_duplicate | Starter prompt 经过 Unicode 和空白规范化后必须唯一。 |
MCP 与评审错误#
以下错误适用于 MCP-backed 提交。
| 名称 | 要求 |
|---|---|
annotations_required | 每个 MCP tool 都必须准确设置 readOnlyHint、openWorldHint 和 destructiveHint。 |
justification_required | 每项 MCP tool annotation 都必须说明其只读、开放世界或破坏性行为的理由。 |
scan_required | 必须对生产环境 MCP server 完成成功且最新的工具扫描。 |
domain_verification_required | 必须在 MCP host 或允许的父 host 上，把精确验证 token 托管在生成的 /.well-known/openai-apps-challenge URL，并通过 Verify Domain。 |
frame_domain_explanation_required | 对工具扫描报告的每个外部 frame domain，都必须说明 UI 为何需要它以及它提供什么内容。 |
screenshots_not_allowed | 只有当前 MCP 工具扫描报告了 UI output template 时才允许截图。 |
Archive 错误#
Skills-only ZIP 上传错误与警告#
Skills only 上传可以包含 Plugin manifest 和随附 skills。更新时修改 package name 会阻止提交；其它发现需要确认。
| 名称 | 要求 |
|---|---|
plugin_name_mismatch | 更新中的 package name 必须与现有 Plugin name 一致。 |
plugin_version_unchanged | 新发布必须使用不同的 manifest version；复用已发布版本需要确认。 |
mcp_configuration_excluded | Skills-only ZIP 不得包含 mcpServers 或 .mcp.json；MCP-backed Plugin 必须使用 With MCP。 |
app_configuration_excluded | Skills-only ZIP 不得包含 apps 或 .app.json；含 App 内容的 Plugin 必须使用 With MCP。 |
screenshot_configuration_excluded | Skills-only ZIP 不得包含 interface.screenshots；截图要求使用 With MCP 且提供自定义 UI。 |
claude_format_normalized | 门户会把 .claude-plugin/plugin.json 转换为 .codex-plugin/plugin.json，补充缺失的 interface 默认值并规范化文本字段。 |
manifest_normalized | 门户会把规范化后的 manifest 保存为 .codex-plugin/plugin.json；字段发生变化时需要确认。 |
developer_name_defaulted | author.name 与 interface.developerName 必须一致；否则确认后，两者都会使用选中的已验证身份。 |
ZIP 结构与限制错误#
| 名称 | 要求 |
|---|---|
archive_empty | Archive 不得为空。 |
archive_too_large | 压缩 ZIP 不得超过 100 MB。 |
archive_format_not_zip | Archive 必须是有效且未损坏的 ZIP 文件。 |
archive_member_path_empty | Archive 条目路径不得为空。 |
archive_member_path_has_outer_whitespace | Archive 条目路径首尾不得包含空白。 |
archive_member_path_has_backslash | Archive 条目路径必须使用 /，不能使用反斜杠。 |
archive_member_path_absolute | Archive 条目路径必须相对于 archive 根目录。 |
archive_member_path_has_empty_segment | Archive 条目路径不得包含空段。 |
archive_member_path_has_parent_segment | Archive 条目路径不得包含 .. 段。 |
archive_member_path_too_deep | Archive 条目路径连同文件名在内最多包含 20 段。 |
archive_member_path_too_long | Archive 条目路径必须在支持的路径长度限制内。 |
archive_member_path_normalization_collision | 大小写和 Unicode 规范化后，各 archive 条目路径仍必须唯一。 |
archive_member_type_unsupported | Archive 条目必须是普通文件或目录。 |
archive_member_too_large | 单个 archive 条目不得超过 100 MiB。 |
archive_member_path_duplicate | Archive 条目路径必须唯一。 |
archive_member_path_type_conflict | 同一路径不能既是文件又是目录，也不能同时包含另一 archive 条目。 |
archive_too_many_entries | Archive 最多包含 5,000 个条目。 |
archive_uncompressed_too_large | 解压后的 archive 不得超过 512 MiB。 |
archive_member_unreadable | 每个 archive 条目都必须可读、不得加密，并使用受支持的压缩方式。 |
Plugin 根目录错误#
| 名称 | 要求 |
|---|---|
plugin_root_missing | 所选路径必须存在，并且是包含 Plugin 的目录。 |
archive_plugin_files_missing | Skills-only ZIP 必须包含受支持的 Plugin manifest，以及至少一个有效的 skills/。 |
plugin_root_ambiguous | ZIP 必须恰好包含一个 Plugin 根目录；它可以位于 archive 根目录，也可以位于唯一的顶层目录中。 |
plugin_root_has_siblings | 如果 ZIP 使用顶层 Plugin 目录，该目录旁不得存在其它文件。 |
Plugin manifest 错误#
| 名称 | 要求 |
|---|---|
plugin_manifest_missing | ZIP 根目录或唯一顶层目录中必须包含 .codex-plugin/plugin.json、.agent-plugin/plugin.json 或 .claude-plugin/plugin.json。 |
plugin_manifest_not_file | Plugin manifest 必须是普通 JSON 文件。 |
plugin_manifest_unreadable | Plugin manifest 必须是可读的 UTF-8 文本。 |
plugin_manifest_json_malformed | Plugin manifest 必须包含有效 JSON；语法错误会附带行号。 |
plugin_manifest_root_not_object | Plugin manifest 顶层必须是 JSON object。 |
codex_manifest_parent_not_directory | .codex-plugin 必须是目录。 |
codex_manifest_path_not_file | .codex-plugin/plugin.json 必须是普通 JSON 文件。 |
plugin_id_wrong_type | 如提供 id，它必须是字符串。 |
plugin_id_empty | 如提供 id，它不得为空。 |
plugin_name_missing | name 必填。 |
plugin_name_wrong_type | name 必须是字符串。 |
plugin_name_empty | name 不得为空。 |
plugin_name_too_long | name 最多 64 个字符。 |
plugin_name_format | name 必须以 ASCII 字母或数字开头，只能包含 ASCII 字母、数字、_ 或 -。 |
plugin_version_missing | version 必填。 |
plugin_version_wrong_type | version 必须是字符串。 |
plugin_version_empty | version 必须是非空语义版本，例如 1.0.0。 |
plugin_version_not_semver | version 必须使用语义版本，例如 1.0.0。 |
plugin_version_too_long | version 最多 64 个字符。 |
plugin_description_missing | description 必填。 |
plugin_description_wrong_type | description 必须是字符串。 |
plugin_description_empty | description 不得为空。 |
plugin_description_too_long | description 最多 1,024 个字符。 |
plugin_description_character_unsupported | description 必须使用受支持文本；允许换行。 |
plugin_developer_missing | author.name 必填；interface.developerName 也必填，并会单独报告。 |
plugin_author_wrong_type | author 必须是 object。 |
plugin_author_name_wrong_type | author.name 必须是字符串。 |
plugin_author_name_empty | author.name 不得为空。 |
plugin_author_name_too_long | author.name 最多 120 个字符。 |
plugin_author_name_character_unsupported | author.name 必须使用受支持文本。 |
plugin_author_email_wrong_type | 如提供 author.email，它必须是字符串。 |
plugin_author_email_empty | 如提供 author.email，它不得为空。 |
plugin_author_email_too_long | author.email 最多 320 个字符。 |
plugin_author_email_character_unsupported | author.email 必须使用受支持文本。 |
plugin_author_url_wrong_type | 如提供 author.url，它必须是字符串。 |
plugin_author_url_empty | 如提供 author.url，它不得为空。 |
plugin_author_url_not_https | author.url 必须是 HTTPS URL。 |
plugin_author_url_has_credentials | author.url 不得包含凭据。 |
plugin_author_url_too_long | author.url 最多 2,048 个字符。 |
plugin_author_url_character_unsupported | author.url 必须使用受支持文本。 |
目录与 interface 错误#
Plugin manifest 的 interface object 定义向用户展示的公开目录信息。它位于 .codex-plugin/plugin.json，使用 displayName、shortDescription 等字段：
json
{
"interface": {
"displayName": "Example Plugin",
"shortDescription": "Summarize documents",
"longDescription": "Summarize and organize documents.",
"developerName": "Example",
"category": "Productivity",
"capabilities": ["Summarize documents"]
}
}四个目录 URL（website、privacy policy、terms 和 support）对 skills-only Plugin 可选，对 MCP-backed Plugin 必填。Package 校验时最长 2,048 个字符；最终目录提交时最长 1,024 个字符。
| 名称 | 要求 |
|---|---|
plugin_interface_wrong_type | Plugin manifest 的 interface 字段必须是 JSON object。 |
plugin_display_name_wrong_type | interface.displayName 必须是字符串。 |
plugin_display_name_empty | interface.displayName 必填且不得为空。 |
plugin_display_name_too_long | Package 校验时 interface.displayName 最多 80 个字符；最终目录提交时最多 30 个。 |
plugin_display_name_character_unsupported | interface.displayName 必须使用受支持文本。 |
plugin_short_description_missing | interface.shortDescription 必填且必须为单行；package 校验时最多 240 个字符，最终目录提交时最多 30 个。 |
plugin_short_description_wrong_type | interface.shortDescription 必须是字符串。 |
plugin_short_description_empty | interface.shortDescription 不得为空。 |
plugin_short_description_too_long | Package 校验时 interface.shortDescription 最多 240 个字符；最终目录提交时最多 30 个。 |
plugin_short_description_character_unsupported | interface.shortDescription 必须使用受支持文本。 |
plugin_long_description_wrong_type | interface.longDescription 必须是字符串。 |
plugin_long_description_empty | interface.longDescription 必填且不得为空。 |
plugin_long_description_too_long | interface.longDescription 最多 4,000 个字符。 |
plugin_long_description_character_unsupported | interface.longDescription 必须使用受支持文本；允许换行。 |
plugin_developer_name_wrong_type | interface.developerName 必须是字符串。 |
plugin_developer_name_empty | interface.developerName 必填且不得为空。 |
plugin_developer_name_too_long | Package 校验时 interface.developerName 最多 120 个字符；最终目录提交时最多 80 个。 |
plugin_developer_name_character_unsupported | interface.developerName 必须使用受支持文本。 |
plugin_category_wrong_type | interface.category 必须是字符串。 |
plugin_category_empty | 如提供 interface.category，它不得为空；省略时使用 Other。 |
plugin_category_unknown | interface.category 必须是 Productivity、Creativity、Developer Tools、Business & Operations、Data & Analytics、Communication、Education & Research、Security、Finance、Healthcare、Travel、Entertainment 或 Other。 |
plugin_category_character_unsupported | interface.category 必须使用受支持文本。 |
plugin_capabilities_wrong_type | interface.capabilities 必须是字符串列表。 |
plugin_capabilities_too_many | interface.capabilities 最多包含 20 项。 |
plugin_capability_wrong_type | interface.capabilities 的每一项都必须是字符串。 |
plugin_capability_empty | 如提供 interface.capabilities 条目，它不得为空。 |
plugin_capability_too_long | interface.capabilities 的每一项最多 120 个字符。 |
plugin_capability_character_unsupported | interface.capabilities 的每一项都必须使用受支持文本。 |
plugin_website_url_wrong_type | 如提供 interface.websiteURL，它必须是字符串。 |
plugin_website_url_empty | 如提供 interface.websiteURL，它不得为空。 |
plugin_website_url_format | interface.websiteURL 必须是 HTTPS URL。 |
plugin_website_url_too_long | interface.websiteURL 必须符合目录 URL 长度限制。 |
plugin_privacy_policy_url_wrong_type | 如提供 interface.privacyPolicyURL，它必须是字符串。 |
plugin_privacy_policy_url_empty | 如提供 interface.privacyPolicyURL，它不得为空。 |
plugin_privacy_policy_url_format | interface.privacyPolicyURL 必须是 HTTPS URL。 |
plugin_privacy_policy_url_too_long | interface.privacyPolicyURL 必须符合目录 URL 长度限制。 |
plugin_terms_of_service_url_wrong_type | 如提供 interface.termsOfServiceURL，它必须是字符串。 |
plugin_terms_of_service_url_empty | 如提供 interface.termsOfServiceURL，它不得为空。 |
plugin_terms_of_service_url_format | interface.termsOfServiceURL 必须是 HTTPS URL。 |
plugin_terms_of_service_url_too_long | interface.termsOfServiceURL 必须符合目录 URL 长度限制。 |
plugin_support_url_wrong_type | 如提供 interface.supportURL，它必须是字符串。 |
plugin_support_url_empty | 如提供 interface.supportURL，它不得为空。 |
plugin_support_url_format | interface.supportURL 必须是 HTTPS URL。 |
plugin_support_url_too_long | interface.supportURL 必须符合目录 URL 长度限制。 |
plugin_homepage_wrong_type | 如提供 homepage，它必须是字符串。 |
plugin_homepage_empty | 如提供 homepage，它不得为空。 |
plugin_homepage_format | homepage 必须是 HTTPS URL。 |
plugin_homepage_too_long | homepage 最多 2,048 个字符。 |
plugin_brand_color_wrong_type | 如提供 interface.brandColor，它必须是字符串。 |
plugin_brand_color_empty | 如提供 interface.brandColor，它不得为空。 |
plugin_brand_color_format | interface.brandColor 必须是六位十六进制颜色，例如 #1ABCFE。 |
plugin_brand_color_dark_wrong_type | 如提供 interface.brandColorDark，它必须是字符串。 |
plugin_brand_color_dark_empty | 如提供 interface.brandColorDark，它不得为空。 |
plugin_brand_color_dark_format | interface.brandColorDark 必须是六位十六进制颜色，例如 #1ABCFE。 |
plugin_brand_color_contrast | interface.brandColor 与白色的对比度至少为 2:1。 |
plugin_brand_color_dark_contrast | interface.brandColorDark 与 #212121 的对比度至少为 2:1。 |
plugin_default_prompt_wrong_type | interface.defaultPrompt 必须是字符串或字符串列表。 |
plugin_default_prompt_too_many | interface.defaultPrompt 最多包含三条 prompt。 |
plugin_default_prompt_entry_wrong_type | interface.defaultPrompt 的每一项都必须是字符串。 |
plugin_default_prompt_empty | 如提供 interface.defaultPrompt 条目，它不得为空。 |
plugin_default_prompt_too_long | Package 校验时每条 interface.defaultPrompt 最多 512 个字符；最终目录提交时最多 128 个。 |
plugin_default_prompt_character_unsupported | 每条 interface.defaultPrompt 都必须使用受支持文本并保持单行。 |
Plugin 内容错误#
| 名称 | 要求 |
|---|---|
plugin_skills_path_wrong_type | skills 必须是指向根 skills/ 目录的字符串路径。 |
plugin_skills_path_empty | 如提供 skills，它必须是指向根 skills/ 目录的非空路径。 |
plugin_skills_path_unsupported | skills 必须解析到根 skills/ 目录。 |
plugin_skills_directory_missing | 已声明的根 skills/ 目录必须存在。 |
plugin_skills_path_not_directory | 已声明的根 skills/ 必须是目录。 |
plugin_apps_path_wrong_type | apps 必须是指向根 .app.json 的字符串路径。 |
plugin_apps_path_empty | 如提供 apps，它必须是指向根 .app.json 的非空路径。 |
plugin_apps_path_unsupported | apps 必须解析到根 .app.json。 |
plugin_apps_file_missing | 已声明的根 .app.json 文件必须存在。 |
plugin_apps_path_not_file | 已声明的根 .app.json 必须是普通文件。 |
plugin_runtime_surface_missing | Skills-only ZIP 必须包含至少一个有效的 skills/；App 和 MCP 引用不能满足此要求。 |
Skill 错误#
| 名称 | 要求 |
|---|---|
skill_manifest_missing | Skill 必须包含 SKILL.md。 |
skill_bundle_too_large | 每个压缩后的 skill bundle 必须在错误信息给出的 MiB 限制内。 |
skill_directory_hidden | Skill 目录名不得以 . 开头。 |
skill_manifest_nested | 每个 skill 目录都必须是 skills/ 的直接子目录。 |
skill_manifest_not_regular_file | SKILL.md 必须是普通文件。 |
skill_manifest_unreadable | SKILL.md 必须可读。 |
skill_manifest_invalid_utf8 | SKILL.md 必须包含有效 UTF-8。 |
skill_frontmatter_missing | SKILL.md 必须以位于 --- 行之间的 YAML front matter 开头。 |
skill_frontmatter_unclosed | SKILL.md 的 YAML front matter 必须以 --- 结束。 |
skill_frontmatter_yaml_malformed | SKILL.md front matter 必须包含有效 YAML。 |
skill_frontmatter_wrong_type | SKILL.md front matter 必须是 YAML mapping。 |
skill_name_missing | name 必填且不得为空。 |
skill_name_wrong_type | name 必须是字符串。 |
skill_name_empty | name 不得为空。 |
skill_name_character_unsupported | Skill front matter 的 name 必须使用受支持文本。 |
skill_description_missing | description 必填且不得为空。 |
skill_description_wrong_type | description 必须是字符串。 |
skill_description_empty | description 不得为空。 |
skill_description_too_long | description 最多 1,024 个字符。 |
skill_description_character_unsupported | Skill front matter 的 description 必须使用受支持文本。 |
skill_body_empty | Skill 指令不得为空。 |
skill_identity_too_long | 合并后的 Plugin 与 skill 名称（plugin-name:skill-name）最多 64 个字符。 |
skill_identity_duplicate | 每个 skill 的 name 在 Plugin 内必须唯一。 |
Skill 智能体元数据错误#
随附 skill 可以在 skills/ 中定义自己的 interface。它控制 skill 向用户展示的方式，与 Plugin manifest 的 interface 相互独立。Skill interface 字段使用 snake_case：
yaml
interface:
display_name: "Summarize documents"
short_description: "Summarize a document"
icon_small: "./assets/icon.png"
default_prompt: "Summarize the selected document."| 名称 | 要求 |
|---|---|
skill_agent_not_regular_file | agents/openai.yaml 必须是普通文件。 |
skill_agent_unreadable | agents/openai.yaml 必须可读。 |
skill_agent_invalid_utf8 | agents/openai.yaml 必须包含有效 UTF-8。 |
skill_agent_yaml_malformed | agents/openai.yaml 必须包含有效 YAML。 |
skill_agent_top_level_wrong_type | agents/openai.yaml 顶层必须是 YAML mapping。 |
skill_agent_interface_missing | 如果包含 agents/openai.yaml，其中的 interface 必填。 |
skill_agent_interface_wrong_type | agents/openai.yaml 中的 interface 必须是 YAML mapping。 |
skill_agent_display_name_missing | interface.display_name 必填且不得为空。 |
skill_agent_display_name_wrong_type | interface.display_name 必须是字符串。 |
skill_agent_display_name_empty | interface.display_name 不得为空。 |
skill_agent_short_description_missing | interface.short_description 必填且不得为空。 |
skill_agent_short_description_wrong_type | interface.short_description 必须是字符串。 |
skill_agent_short_description_empty | interface.short_description 不得为空。 |
skill_agent_icon_small_wrong_type | 如提供 interface.icon_small，它必须是非空相对文件路径。 |
skill_agent_icon_small_empty | interface.icon_small 必须是非空相对文件路径，例如 assets/icon.png。 |
skill_agent_icon_large_wrong_type | 如提供 interface.icon_large，它必须是非空相对文件路径。 |
skill_agent_icon_large_empty | interface.icon_large 必须是非空相对文件路径，例如 assets/icon.png。 |
skill_agent_brand_color_wrong_type | 如提供 interface.brand_color，它必须是字符串。 |
skill_agent_brand_color_empty | 如提供 interface.brand_color，它必须是非空六位十六进制颜色，例如 #1ABCFE。 |
skill_agent_brand_color_format | interface.brand_color 必须是六位十六进制颜色，例如 #1ABCFE。 |
skill_agent_default_prompt_wrong_type | 如提供 interface.default_prompt，它必须是字符串。 |
skill_agent_default_prompt_empty | 如提供 interface.default_prompt，它不得为空。 |
skill_agent_policy_wrong_type | 如提供 policy，它必须是 YAML mapping。 |
skill_agent_allow_implicit_invocation_wrong_type | policy 只能包含 products 和 allow_implicit_invocation。products 必须包含 CHAT、CODEX 或两者；allow_implicit_invocation 必须是 true 或 false。 |
skill_agent_dependencies_wrong_type | dependencies 必须是 YAML mapping；只支持 tools。 |
skill_agent_dependency_unsupported | agents/openai.yaml 只支持 dependencies.tools。 |
资产路径错误#
| 名称 | 要求 |
|---|---|
declared_asset_path_wrong_type | 指定的资产字段必须是文件路径字符串。 |
declared_asset_path_empty | 指定的资产字段不得为空。 |
declared_asset_path_has_outer_whitespace | 指定的资产字段首尾不得包含空白。 |
declared_asset_path_has_control_character | 指定的资产字段不得包含 U+0000–U+001F 或 U+007F 字符。 |
branding_asset_path_missing_root_prefix | 指定的资产字段必须以 ./ 开头。 |
declared_asset_path_unsafe | 指定的资产字段必须是 Plugin 内的相对路径，不得包含绝对路径、drive 前缀或 .. 遍历段。 |
declared_asset_path_outside_package | 指定的资产字段必须引用 Plugin 内的文件。 |
declared_asset_file_missing | 指定的资产字段引用了不存在的文件。 |
declared_asset_not_regular_file | 指定的资产字段必须引用普通文件，不能是目录或特殊文件。 |
图片错误#
目录品牌图片必须使用受支持的文件类型，并符合下列大小与尺寸限制。这些规则适用于 package 内的品牌资产；starter prompt 截图使用上文单独列出的门户限制。
| 名称 | 要求 |
|---|---|
plugin_logo_path_missing | interface.logo 必填，且必须引用正方形图片。 |
plugin_composer_icon_path_missing | interface.composerIcon 必填，且必须引用正方形图片。 |
image_file_unreadable | 图片文件必须可读。 |
image_file_too_large | 图片不得超过 5 MiB。 |
image_file_format_unsupported | 图片文件名必须以 .png、.jpg、.jpeg、.webp 或 .svg 结尾。 |
raster_image_decode_failed | 栅格图片必须是可安全解码的 PNG、JPEG 或 WebP 文件。 |
raster_image_extension_content_mismatch | 图片扩展名必须与检测到的图片格式一致。 |
raster_image_not_square | 图片必须为正方形。 |
raster_image_dimensions_too_small | 图片尺寸至少为 48×48 像素。 |
raster_image_dimensions_too_large | 图片尺寸不得超过 4,096×4,096 像素。 |
svg_xml_malformed | SVG 必须包含有效的 UTF-8 XML。 |
svg_root_element_invalid | SVG 根元素必须是 |
svg_dimensions_missing | SVG 必须定义数值 viewBox，或数值 width 和 height。 |
svg_dimensions_not_numeric | SVG 尺寸必须是数值，不得包含单位或百分比。 |
svg_dimensions_not_positive | SVG 宽高必须是正的有限数值。 |
svg_dimensions_not_square | SVG 尺寸必须为正方形。 |
svg_dimensions_too_small | SVG 尺寸至少为 48×48 像素。 |
App 引用错误#
Plugin 引用 App 时，通用 package 检查会校验 .app.json。提交门户不会发布对现有 ChatGPT App 的引用：Skills only 上传会移除 .app.json；MCP-backed 提交必须使用 With MCP，并直接提交 MCP server。
对于本地或工作区 package，顶层 apps object 会把每个 App alias 映射到一个 App 条目。
| 名称 | 要求 |
|---|---|
app_manifest_unreadable | .app.json 必须是可读的 UTF-8 文本。 |
app_manifest_json_malformed | .app.json 在报告的行附近包含格式错误的 JSON。 |
app_manifest_wrong_type | .app.json 顶层必须是 JSON object。 |
app_entries_missing | apps 必填。 |
app_entries_wrong_type | apps 必须是 object。 |
app_entry_wrong_type | 每个 App 条目都必须是 object。 |
app_id_missing | 每个 App 条目的 id 都必填。 |
app_id_wrong_type | 每个 App 条目的 id 都必须是字符串。 |
app_id_format | 每个 App 条目的 id 必须以 asdk_app_、connector_ 或 templated_apps_ 开头，随后是字母或数字，其余字符只能是字母、数字、_ 或 -。 |
app_entry_optional_wrong_type | 如提供 App 条目的 optional，它必须是 true 或 false。 |
app_entry_required_wrong_type | 如提供 App 条目的 required，它必须是 true 或 false。 |
app_not_eligible | 对本地或工作区 package，每个引用的 App 都必须是已发布的公开 Codex App、可用 connector 或已发布 App template。目录提交必须使用 With MCP 并直接提交 MCP server。 |
Package 警告#
这些警告表示校验会忽略或规范化某些 package 内容。它们不会阻止提交，但应确认提交后的 Plugin 仍包含预期文件和设置。
| 名称 | 要求 |
|---|---|
duplicate_app_reference | .app.json 中每个 App ID 应只引用一次；重复引用会被视为一个 App。 |
undeclared_app_manifest_ignored | 只有 Plugin manifest 的 apps 字段设为 ./.app.json 时，才会导入根目录 .app.json。 |
undeclared_mcp_manifest_ignored | 只有 Plugin manifest 的 mcpServers 字段设为 ./.mcp.json 时，才会导入根目录 .mcp.json。 |
skill_file_ignored | 直接位于 skills/ 下的文件不会作为 skill 导入；每个 skill 都必须位于包含 SKILL.md 的目录中。 |
skill_symlink_ignored | 直接位于 skills/ 下的符号链接不会作为 skill 导入；每个 skill 都必须是包含 SKILL.md 的真实目录。 |
skill_frontmatter_adjusted | 导入时会去除外侧空白并折叠内部空白，以规范化 skill 的 name 和 description。 |
skill_metadata_ignored | Skill interface 设置必须使用 agents/openai.yaml 中的 interface mapping；SKILL.md 的 metadata 不会配置 interface。 |
后续步骤#
解决全部校验错误后，返回提交 Plugin完成提交。
本站实践建议#
使用“Plugin 提交错误”扩展 Codex 时，只启用当前任务需要的能力，并检查其可访问的数据与可执行操作。团队共享前应先完成权限和失败场景测试。
Codex API 与国内使用#
在实践“Plugin 提交错误”相关功能时，如需为 Codex 配置 OpenAI-compatible API，可以前往 APIBest 获取 API Key。第三方服务的模型映射、价格、额度和数据处理方式以 APIBest 当前说明为准。