Hotdry.

Article

OpenAI Codex 插件架构解析：manifest 验证、应用依赖与技能编排

深入解析 OpenAI Codex 插件系统的 manifest 结构、.app.json 应用依赖机制，以及 skills、agents、hooks 的编排模式，提供可落地的插件开发参数清单。

2026-06-08ai-systems

OpenAI 近期开源的 openai/plugins 仓库揭示了 Codex 代码生成引擎的插件化扩展机制。与早期 ChatGPT 插件不同，这套架构专为 AI 编程助手设计，通过结构化的 manifest 文件系统实现能力编排。本文基于仓库中 Figma、Notion 等官方示例，拆解插件目录结构、验证规则与外部服务集成模式，为构建生产级 Codex 插件提供工程化参考。

插件目录结构：强制与可选组件

每个 Codex 插件遵循严格的目录约定，根路径为 plugins/<name>/。核心组件分为强制与可选两类：

强制组件：

  • .codex-plugin/plugin.json：插件元数据与入口定义，Codex 通过解析此文件识别插件能力边界

可选扩展面：

  • .app.json：外部应用依赖声明，用于连接 Figma、Notion 等第三方服务
  • .mcp.json：MCP（Model Context Protocol）配置，支持与外部工具的标准化通信
  • skills/：实际技能载荷目录，每个技能包含 SKILL.md、可选的 agents/、references/、assets/、scripts/
  • agents/：插件级 Agent 配置，如 agents/openai.yaml 定义 OpenAI 表面行为
  • commands/：自定义命令注册点
  • hooks.json：生命周期钩子定义，支持在特定节点注入逻辑
  • assets/：插件级图标与静态资源

以 Figma 插件为例，其完整结构展示了 "应用支撑型" 插件的典型布局：.codex-plugin/plugin.json 定义基础元数据，.app.json 指向 Figma 集成，七个独立技能（figma-implement-design、figma-code-connect 等）分别封装在 skills/ 子目录中，通过统一的 Agent 配置协调执行。

Manifest 验证机制：plugin.json 关键字段

.codex-plugin/plugin.json 作为插件的唯一标识文件，其结构直接影响 Codex 的加载行为。根据仓库中多个插件的目录结构推断，manifest 需包含以下核心字段：

身份标识字段：

  • name：插件唯一标识符，与目录名保持一致
  • version：语义化版本号，Codex 据此判断兼容性
  • description：功能描述，用于 IDE 中的插件展示

能力声明字段：

  • skills：技能列表，指向 skills/ 目录下的子模块
  • agents：Agent 配置引用，支持多表面（surface）定义
  • hooks：生命周期钩子注册表

资源依赖字段：

  • assets：图标与媒体资源路径映射
  • permissions：所需权限清单，如文件系统访问、网络请求等

验证流程上，Codex 在加载插件时执行结构校验与语义校验两阶段：结构校验确保必需文件存在且 JSON 格式合法；语义校验检查技能引用路径有效性、Agent 配置语法正确性，以及 .app.json 中声明的外部应用依赖是否已授权。

应用依赖模式：.app.json 的集成契约

.app.json 是 Codex 插件连接外部服务的桥梁文件，其设计体现了声明式集成理念。以 Figma 插件为例，.app.json 声明了与 Figma 平台的连接契约，使插件能够调用 Figma API 获取设计稿元数据、执行 Code Connect 模板生成等操作。

该文件的核心作用包括：

服务发现： 声明插件依赖的外部应用类型（如 figma、notion、netlify），Codex 据此初始化相应的客户端实例。

认证委托： 托管 OAuth 令牌或 API 密钥的引用路径，避免敏感信息硬编码在技能脚本中。实际令牌存储由 Codex 运行时管理，插件仅通过配置名引用。

能力协商： 声明所需的外部应用权限范围（如读取文件、写入评论、触发构建），用户在安装插件时一次性授权。

对于企业级部署，.app.json 支持多环境配置模式，可通过环境变量覆盖开发、测试、生产环境的端点地址，实现同一插件在不同基础设施间的无缝迁移。

Skills、Agents 与 Hooks：能力编排三层模型

Codex 插件采用分层架构实现能力解耦：

Skills 层（技能层）： 位于 skills/<skill-name>/ 目录，是插件的功能原子单元。每个技能包含：

  • SKILL.md：自然语言描述的能力契约，定义输入输出格式与边界条件
  • agents/：技能级 Agent 覆盖，可覆盖插件级默认行为
  • references/：外部知识引用，如 API 文档片段、设计规范
  • scripts/：可执行脚本，支持预 / 后处理逻辑

Agents 层（代理层）： 位于插件根目录 agents/ 或技能子目录，定义 Codex 与外部系统的交互协议。YAML 格式的 Agent 配置指定模型参数（温度、最大令牌数）、工具调用权限、以及输出格式约束。

Hooks 层（钩子层）： 通过根目录 hooks.json 定义生命周期拦截点，支持：

  • pre-load：插件加载前执行环境检查
  • pre-skill：技能调用前注入上下文变量
  • post-skill：技能执行后处理输出结果
  • on-error：异常捕获与降级策略

这种三层模型使插件开发者能够灵活组合复用技能，通过 Agent 配置调整模型行为，借助 Hooks 实现横切关注点（日志、监控、熔断）的集中管理。

可落地的插件开发参数清单

基于 OpenAI 官方插件仓库的工程实践，构建生产级 Codex 插件需关注以下参数与检查点：

目录结构检查：

  • .codex-plugin/plugin.json 存在且 JSON 格式合法
  • 插件名称与目录名一致，使用 kebab-case 命名
  • skills/ 下每个技能包含 SKILL.md 描述文件

Manifest 配置：

  • version 遵循 SemVer 规范（主版本。次版本。修订号）
  • skills 数组项与 skills/ 子目录一一对应
  • permissions 声明遵循最小权限原则

外部集成配置：

  • .app.json 中 app_type 使用受支持的集成标识符
  • API 端点支持 HTTPS 协议
  • 认证配置使用引用名而非硬编码密钥

Agent 调优参数：

  • 代码生成类技能设置 temperature: 0.1-0.3 保证确定性
  • 设计创意类技能设置 temperature: 0.7-0.9 增加多样性
  • 设置 max_tokens 上限防止资源耗尽

安全与沙箱：

  • 敏感操作（文件写入、网络请求）在 hooks.json 中配置审计日志
  • 外部 API 调用设置超时阈值（建议 30s）
  • 用户确认操作通过 UI 层显式授权

资料来源

ai-systems

内容声明：本文无广告投放、无付费植入。

如有事实性问题，欢迎发送勘误至 i@hotdrydog.com。