插件管理

开始之前

工作区管理员可以从 GitHub 导入插件市场，并使其中的插件与仓库保持同步。插件市场是一个 JSON 目录，其中列出了要导入的插件。

本页介绍工作区的导入与同步。要通过云端受管配置或系统 config.toml 直接 在本地客户端上配置市场，请参阅 配置插件市场和默认设置。 要为特定项目启用或禁用插件，请参阅为仓库启用或禁用 插件。

请使用能够读取插件市场仓库及其引用的任何其他仓库的 GitHub 账户。支持公开和私有 GitHub 仓库。导入前，请完成 GitHub 组织针对仓库访问所要求的所有审批。

导入前请检查仓库内容。新插件最初的安装策略为 Available，并在安装时进行身份验证。新插件市场默认启用每日自动同步。导入会处理所有有效条目，后续同步会自动添加仓库中的任何新插件。

配置插件市场同步

1. 打开 Admin > Plugins，然后选择 Add > Import marketplace。
2. 在 Source 中输入仓库 URL，例如 https://github.com/example/team-plugins。请仅使用仓库 URL，不要使用分支或文件夹 URL。
3. 如果插件市场位于子目录中，请在 Path 中输入该目录。例如，对于 team-tools/.agents/plugins/marketplace.json，请使用 team-tools。如果位于仓库根目录，请将 Path 留空。不要输入清单文件名。
4. 可选择输入 Branch, tag, or commit。将其留空可使用仓库的默认分支。使用分支可以接收后续提交；固定的提交则会停留在该修订版本。
5. 选择 Import marketplace，并在出现提示时授权 GitHub 访问。对于非常大的插件市场，首次导入最长可能需要一小时。后续的每日同步通常只需几分钟。
6. 查看 Import results，然后打开每个已导入的插件，配置其安装策略和任何必需的应用。

若要立即请求更新而不等待每日同步，请在 Admin > Plugins > Marketplaces 下打开该插件市场，然后选择 Sync now。

支持的格式

所选目录必须包含以下文件之一：

在插件市场中，条目可以引用使用 .codex-plugin/plugin.json 的原生插件、Claude 兼容插件、Agent Plugins 1.0 软件包或受支持的技能软件包。

对于 Codex 插件市场，请为同一仓库中的插件使用本地路径：

{
  "name": "team-plugins",
  "interface": {
    "displayName": "Team plugins"
  },
  "plugins": [
    {
      "name": "team-tools",
      "source": {
        "source": "local",
        "path": "./plugins/team-tools"
      }
    }
  ]
}

该路径相对于所选插件市场根目录，而不是相对于 .agents/plugins/。

Claude 兼容插件市场可以为每个本地插件使用路径字符串：

{
  "name": "team-plugins",
  "plugins": [
    {
      "name": "team-tools",
      "source": "./plugins/team-tools"
    }
  ]
}

Codex 插件市场条目还支持使用 source: "url" 引用位于 GitHub 仓库根目录的插件，以及使用 source: "git-subdir" 引用位于 GitHub 子目录中的插件。例如：

{
  "name": "team-tools",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/example/team-tools.git",
    "path": "./plugins/team-tools",
    "ref": "main"
  }
}

Git 源可以选择一个 ref 或完整的 40 字符提交 sha。用于授权的 GitHub 账户必须能够读取每个被引用的仓库。工作区导入目前仅支持 GitHub 仓库。

配置工作区访问权限

GitHub 导入和同步不会应用仓库中的安装或身份验证策略，包括 AVAILABLE、INSTALLED_BY_DEFAULT、NOT_AVAILABLE、ON_INSTALL 和 ON_USE。工作区管理员需要为每个插件配置这些设置。同步更新或将现有插件转为由 GitHub 管理时，会保留其工作区策略。

使用 Installation policy 为每个符合条件的角色选择 Available 或 Installed。必需的应用也必须启用，并且成员必须有权访问所连接的服务。导入插件不会授予应用访问权限，也不会连接成员的账户。有关角色、应用和操作控制，请参阅插件控制。

将现有插件转为由 GitHub 管理

将 pluginId 添加到现有插件的插件市场条目中：

{
  "name": "team-tools",
  "pluginId": "plugin_0123456789abcdef0123456789abcdef",
  "source": {
    "source": "local",
    "path": "./plugins/team-tools"
  }
}

从 Admin > Plugins 打开该插件，并复制其 URL 中 /admin/plugins/ 后面的 ID。在插件市场条目中，将 pluginId 与 name 和 source 放在同一级。现有插件必须位于同一工作区中。

这会将已上传或以其他方式处于未管理状态的工作区插件转为由 GitHub 管理。该插件会保留其 ID、共享设置和工作区策略。后续更新将来自 GitHub；无法再通过上传归档文件替换该托管插件。已由其他 GitHub 源管理的插件无法通过此方式接管。

仅限桌面端的插件

任何在 mcp.json 或 .mcp.json 中声明 MCP server的已导入插件都会标记为 Desktop only，并且仅可在 ChatGPT 桌面应用中使用。这包括使用远程 HTTPS URL 的服务器。相同限制也适用于其他受支持的 MCP 配置形式，例如内联服务器声明。

使用 .app.json 引用现有应用

在插件根目录中添加 .app.json。文件名包含开头的点；不支持不带点的 app.json。

{
  "apps": {
    "team-tools": {
      "id": "asdk_app_example",
      "required": true
    }
  }
}

将 asdk_app_example 替换为现有应用的 ID。受支持的应用 ID 以 asdk_app_、connector_ 或 templated_apps_ 开头。请使用应用 ID，而不是 plugin_... ID。例如，包含 plugin_asdk_app_example 的插件 URL 表示应用 asdk_app_example。

键 team-tools 用于命名此文件中的引用。当插件依赖该应用时，请将 required 设置为 true。你可以添加更多条目以引用其他现有应用。

对于原生插件，请在 .codex-plugin/plugin.json 中将 apps 设置为 ./.app.json。以下是此示例的完整清单：

{
  "name": "team-tools",
  "version": "1.0.0",
  "description": "Use the team's approved tools.",
  "author": {
    "name": "Example team"
  },
  "apps": "./.app.json",
  "interface": {
    "displayName": "Team tools",
    "shortDescription": "Use approved team tools",
    "longDescription": "Connect to the team's existing app.",
    "developerName": "Example team",
    "category": "Productivity",
    "capabilities": ["Read"]
  }
}

请按以下布局放置文件：

team-plugins/
├── .agents/plugins/marketplace.json
└── plugins/team-tools/
    ├── .codex-plugin/plugin.json
    └── .app.json

该引用不会创建应用或授予权限。管理员必须向预期角色开放该应用，成员则必须完成任何必需的身份验证。现有的应用权限、操作控制和服务访问权限仍然适用。

使插件保持最新

新插件市场每天检查更新。打开 Admin > Plugins > Marketplaces，选择该插件市场，然后选择 Sync now，即可立即请求更新而不等待自动同步。

同步可以添加新的插件市场条目并更新现有插件。合并仓库变更之前请先进行检查，因为自动同步会导入任何新插件。

同步后，请查看状态和已保存的报告。Completed — N errors 表示此次同步已完成，但有些插件无法处理。如果现有插件的更新无效，系统会保留其上一个可用版本。在 GitHub 中修复报告的问题，然后选择 Sync now 重试。

从仓库中移除条目不会删除其已导入的工作区副本。它会被标记为 No longer in source。在 ChatGPT 中删除插件市场会删除从中导入的所有插件。

重新连接或更改 GitHub 访问权限

若要重新连接 GitHub 访问权限，请先确认用于导入的 GitHub 账户仍有权访问该仓库及其引用的任何仓库。然后，最初导入该插件市场的管理员应在 ChatGPT 中打开 GitHub 插件并重新连接自己的账户，因为插件市场同步使用该管理员的 GitHub 连接。

若要转移给新所有者，新的工作区管理员应打开 Admin > Plugins > Add > Import marketplace，并使用相同的 Source、Path 和 Branch, tag, or commit 值导入同一插件市场。后续同步将使用其 GitHub 连接。

不要仅为了重新连接或更改所有权而删除插件市场：删除插件市场也会移除从中导入的插件。