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/<skill>/SKILL.md`。
`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/<skill>/SKILL.md`；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/<skill>/agents/openai.yaml 中定义自己的 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>`。
`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 当前说明为准。

Plugin 提交错误 ​

最终目录提交 ​

最终元数据错误 ​

MCP 与评审错误 ​

Archive 错误 ​

Skills-only ZIP 上传错误与警告 ​

ZIP 结构与限制错误 ​

Plugin 根目录错误 ​

Plugin manifest 错误 ​

目录与 interface 错误 ​

Plugin 内容错误 ​

Skill 错误 ​

Skill 智能体元数据错误 ​

资产路径错误 ​

图片错误 ​

App 引用错误 ​

Package 警告 ​

后续步骤 ​

本站实践建议 ​

Codex API 与国内使用 ​