插件管理

开始之前

工作空间管理员可以从 GitHub 导入插件市场，并从代码仓库同步更新其中的插件。市场是一个 JSON 目录，列出了要导入的插件。

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

请使用能够读取市场代码仓库及其引用的所有其他代码仓库的 GitHub 账户。支持公开和私有 GitHub 代码仓库。导入前，请完成访问代码仓库所需的所有 GitHub 组织审批。

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

配置市场同步

1. 打开 管理 > 插件 ，然后选择 添加 > 导入市场。
2. 在 来源中输入代码仓库 URL，例如 https://github.com/example/team-plugins。请仅使用代码仓库 URL，不要使用分支或文件夹的 URL。
3. 如果市场位于子目录中，请在 路径中输入该目录。例如，对于 team-tools/.agents/plugins/marketplace.json，请填写 team-tools。若要使用代码仓库根目录，请将 路径 留空。不要输入清单文件名。
4. 您可以选择填写 分支、标签或提交。留空则使用代码仓库的默认分支。指定分支可接收后续提交；指定固定提交则会保持在该版本。
5. 选择 导入市场 ，并在出现提示时授予 GitHub 访问权限。对于非常大的市场，首次导入可能需要长达一小时。后续每日同步通常只需几分钟。
6. 查看 导入结果，然后逐一打开已导入的插件，配置其安装策略和所需的应用。

如果希望立即请求更新，而不等待每日同步，请在 管理 > 插件 > 市场 中打开相应市场，然后选择 立即同步。

支持的格式

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

市场中的条目可以引用包含 .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 管理时，会保留其工作空间策略。

在 安装策略 中，为每个符合条件的角色选择 可用 或 已安装 。同时必须启用所需的应用，且成员必须拥有对所连接服务的访问权限。导入插件不会授予应用访问权限，也不会连接成员的账户。有关角色、应用和操作的控制设置，请参阅插件控制。

将现有插件转为通过 GitHub 管理

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

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

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

这样可将已上传或尚未受管理的工作空间插件转为通过 GitHub 管理。插件会保留其 ID、共享设置和工作空间策略。后续更新将来自 GitHub，无法再通过上传归档文件替换受管理的插件。已经由其他 GitHub 来源管理的插件无法通过此方式接管。

仅限桌面端的插件

任何在 mcp.json 或 .mcp.json 中声明 MCP 服务器的已导入插件，都会被标记为 仅限桌面端 ，且只能在 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

该引用不会创建应用或授予权限。管理员必须允许目标角色使用该应用，成员也必须完成所需的身份验证。现有的应用权限、操作控制和服务访问限制仍然适用。

保持插件为最新版本

新市场每天检查更新。打开 管理 > 插件 > 市场，选择相应市场，然后选择 立即同步 即可请求更新，无需等待自动同步。

同步可以添加新的市场条目并更新现有插件。请在合并前审查代码仓库的更改，因为自动同步会导入所有新插件。

同步后，请查看状态和已保存的报告。 已完成，N 个错误 表示本轮同步已结束，但部分插件无法处理。如果现有插件的更新无效，系统会保留其上一个可用版本。请在 GitHub 中修复报告的问题，然后选择 立即同步 重试。

从代码仓库中移除条目不会删除其已导入工作空间的副本。该副本会被标记为 来源中已不存在。在 ChatGPT 中删除市场会删除从该市场导入的所有插件。

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

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

要 转移给新所有者，新的工作空间管理员应打开 管理 > 插件 > 添加 > 导入市场 ，使用相同的 来源、 路径和 分支、标签或提交 值导入同一市场。后续同步将使用新管理员的 GitHub 连接。

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