AgentServer/docs/adr/0018-codex-curated-plugins-playground-only.md

ADR-0018 Codex 插件（openai-curated）只在 Playground 中使用

• 状态：Accepted · 日期：2026-10-23 · 补充 ADR-0016

背景

服务账号登录 ChatGPT 后，Codex 会从 OpenAI 官方插件目录 openai-curated-remote 自动安装一批插件，例如 Google Drive、Gmail、Outlook、Teams、Pages、Sites。目录共 7700 多项，绝大多数是 ChatGPT 应用连接器。

• 连接器由 OpenAI 远程执行，使用登录账号的授权访问对应数据
• 插件还会带来技能，以及"安装插件"的建议

这些能力只适合管理员本人使用，不能开放给经 API 接入的平台（家人使用的各个前端）。

决策

• 后台目录：新增"技能与插件 › Codex · OpenAI 插件"页，只管理 openai-curated* 目录。
  • 通过 app-server 的 plugin/list、plugin/installed、plugin/read、plugin/install、plugin/uninstall 实现
  • 目录缓存 10 分钟，服务端搜索、分类筛选、分页
  • 安装后若有需要授权的应用（appsNeedingAuth），提示到 ChatGPT 中完成连接
  • 插件文件由 Codex 自己下载和存放
• 只在 Playground 开放：会话的 source = admin（在后台 Playground 中创建）且引擎为 Codex 时，对话 config 才打开 features.plugins / remote_plugin / apps 和 apps._default.enabled。
  • 以下功能仍然关闭：tool_suggest（对话中不能安装插件）、multi_agent、browser_use、computer_use、skill_mcp_dependency_install
  • 经 API Key 创建的会话始终全部关闭，后台"在 Playground 中继续"一个 API 会话也不会开放
• 插件技能：远程插件带来的技能（pluginId 非空）不在 Profile 的技能列表中出现，也不受 Profile 选择约束。开放插件的会话全部保留，其他会话全部禁用。
• 调用确认：应用连接器的调用确认以 mcpServer/elicitation/request 到达。
  • 开放插件的会话中，不需要填写内容的确认转成审批卡片，并写入审计
  • 需要填表或跳转网址的请求一律拒绝
  • 其他会话一律拒绝
• Playground 提示：Codex 会话的工具栏显示"插件已开放"。

后果

• Claude 侧不受影响（Claude 的插件机制见 ADR-0013）
• 已加载的 Codex 会话沿用创建时的配置（03 §3.4 已知限制），因此 Playground 会话与 API 会话的配置互不影响

修订（2026-10-28）：Profile 可以为 API 会话开放指定插件

有些经 API 的操作需要用到插件。Profile 增加 codexPluginIds（仅 Codex 引擎），默认为空，由管理员逐个勾选已安装的插件：

• 开放范围：勾选了插件的 Profile，会话开启 plugins、remote_plugin、apps 功能，但 apps._default.enabled = false，只逐个启用这些插件带的应用连接器（plugin/read 返回的应用 ID，缓存 10 分钟）；其他插件带来的技能照常禁用。已实测（codex 0.164）：只启用 Google Calendar 时，模型发现不了 Gmail 等其他已授权应用的工具。
• 确认：应用调用的确认（elicitation）在开放了插件的会话中转为审批卡片，与 Playground 相同；需要填表或跳转网址的请求仍然拒绝。
• Playground 仍然全部开放；未勾选插件的 Profile 与之前一样全部关闭。卸载的插件在运行时忽略。
• 勾选变化会改变线程配置，已加载的 Codex 会话会分叉以使用新配置。