Open Interpreter 插件系统深度指南：用 Skills、MCP Server 与 Hooks 构建可复用的扩展包

2026-09-06 18:33:14作者：裘旻烁

Plugins（插件）是 Open Interpreter 中用于打包复用扩展的容器机制，它把技能（Skills）、MCP Server 定义、Hooks 以及相关扩展配置捆绑为一个整体，随插件一起安装、共享与卸载。本文以 docs/plugins.md 为线索，结合仓库内 codex-rs（Rust 核心实现）中插件装载、清单校验、市场（Marketplace）管理的真实源码与测试，完整讲解插件是什么、如何开启实验特性、目录形态与 plugin.json 清单如何编写、市场如何运作，以及信任与沙箱边界如何兜底。读完你将掌握在 Open Interpreter 中创建、打包、校验、安装与分发一个插件的最小闭环。

插件（Plugins）要解决什么问题

插件是对"一组应该一起迁移的扩展"的封装。文档给出的定义非常直白：一个插件可以包含 skills、MCP server 定义、hooks，以及其他需要同时移动的配置（见 docs/plugins.md）。

在一个开放的 Agent 生态里，扩展经常以零散形式存在：一个技能散落在 ~/.agents/skills，一个 MCP 配置埋在某个项目的 .mcp.json，一段 hooks 逻辑贴在某份 config 里。这样既难以复用，也难以分享给他人。插件的价值在于把上述三类扩展以及图标、简介等展示性元数据收进一个带版本、带作者、带市场策略的独立单元：

Skills：Agent 按需加载的可执行技能（含说明与脚本）；
MCP servers：外部工具/能力接入点（mcpServers）；
Hooks：Agent 生命周期上的钩子逻辑；
其他配置：如 app 集成清单、附带脚本与静态资源等。

插件系统目前是实验性功能，可能需要显式开启（见下文"开启实验性插件功能"），因此把它当作扩展的"正式打包格式"之前，先确认你的运行版本与开关状态。

开启实验性插件功能

插件的启用方式是配置文件中的 [features] 表，文档给出的最小开启片段是：

[features]
plugins = true

features 在仓库的配置模型中是以"特性名 → 布尔值"映射存在的。在 codex-rs/config/src/thread_config.rs 的配置分层测试里可以看到，无论是 SessionThreadConfig 还是 UserThreadConfig，features 都表示为键值映射，而会话（session）层配置在测试数据中即以 plugins 键默认 false 的形式出现，串行化为 TOML 后即表现为：

[features]
plugins = false

也就是说默认关闭、需显式开启在数据模型层面是有支撑的：features 只是一张"特性名到开关"的表，plugins 这条记录默认取 false，只有配置为 plugins = true 才生效。由于插件处于实验期且可能默认禁用，请在首次使用前确认你的 launcher/CLI 版本对该特性开关的解释方式（以当前发布版本的文档为准）。

插件目录形态（Plugin Shape）

一个插件在磁盘上是一个目录，文档给出的标准骨架如下：

my-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
├── mcp/
└── hooks/

要点拆解：

.codex-plugin/plugin.json 是必选的清单文件，描述插件本身以及随包携带的各扩展点；目录必须保留、不可删除（仓库内置的插件创建技能也把"保留 .codex-plugin/plugin.json"列为硬性行为，见 plugin-creator/SKILL.md）。
skills/、mcp/、hooks/ 是三个常见的可选伴随目录/文件，分别承载技能、MCP 服务定义与钩子。
从仓库 codex-rs/core-plugins 的实现来看，插件整体走的是"清单（manifest）→ 归档/解析 → 装载（loader）→ 激活（activation）→ 运行"的管线：目录下既有 manifest.rs（清单解析）、plugin_bundle_archive.rs（插件包归档）、checkout.rs（检出）、activation.rs（激活）、loader.rs（装载）等模块，也包含 local_paths.rs 负责定位本地插件与个人市场文件的路径约定。

plugin.json 清单：字段与 interface

清单文件是插件的身份证。仓库在 plugin-creator 技能附带的 plugin-json 样例规范中给出了权威样例，下面是核心结构（字段均来自该规范，URL 为示意占位值）：

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://example.com/author"
  },
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./skills/",
  "hooks": "./hooks.json",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "interface": {
    "displayName": "Plugin Display Name",
    "shortDescription": "Short description for subtitle",
    "category": "Productivity",
    "capabilities": ["Interactive", "Write"],
    "defaultPrompt": [
      "Summarize my inbox and draft replies for me.",
      "Find open bugs and turn them into Linear tickets."
    ],
    "brandColor": "#3B82F6",
    "logo": "./assets/logo.png"
  }
}

顶层字段速览

字段	类型	含义与约束
`name`	string	插件标识，kebab-case、不含空格，与插件目录名一致，同时作为清单名与组件命名空间
`version`	string	语义化版本号，校验要求为严格 semver
`description`	string	简短用途说明
`author`	object	发布者身份，含 `name`、`email`、`url`
`homepage` / `repository`	string	文档/源码地址
`license`	string	许可证标识，如 `MIT`、`Apache-2.0`
`keywords`	array	搜索与发现标签
`skills`	string	技能目录/文件的相对路径
`hooks`	string	Hook 配置路径（注意：见下方"字段兼容性提示"）
`mcpServers`	string 或 object	MCP 配置路径；或以对象内联声明 MCP server
`apps`	string	App 集成清单路径
`interface`	object	展示层的 UX/UI 元数据

其中 mcpServers 有两种合法写法：既可以指向伴随文件：

{
  "mcpServers": "./.mcp.json"
}

也可以直接在 plugin.json 内联对象：

{
  "mcpServers": {
    "counter": {
      "type": "http",
      "url": "https://example.com/counter/mcp"
    }
  }
}

interface 展示元数据

interface 控制插件在界面上的呈现：displayName 是用户可见标题；shortDescription/longDescription 分别用于紧凑视图与详情页；category 归类；capabilities 声明能力清单；defaultPrompt 是出现在 composer 中的起始提示语，规范约束最多 3 条（超出部分被忽略）、每条不超过 128 字符（更长被截断），并建议控制在 50 字符左右以利于 UI 展示；brandColor 提供卡片主题色；logo、logoDark 与 screenshots 分别指向插件根下的品牌与截图资源，截图须为 ./assets/ 下的 PNG。

路径约定与校验规则

路径值应以 ./ 开头并相对于插件根目录；
skills、hooks、字符串形式的 mcpServers 是对默认组件发现的补充，不会取代默认发现；
校验器（validate）与工作区内插件的摄取 schema 对齐，清单必须提供真实的 name、version、description、author.name 及必需的 interface 字段；
websiteURL、privacyPolicyURL、termsOfServiceURL 若存在必须是绝对 https:// URL；
apps 只有确实存在 .app.json 时才应写入 plugin.json；
创建插件的技能刻意不让清单包含被校验器拒绝的字段（如 hooks），同时要求不得在清单中遗留 [TODO: ...] 占位符——因为最终校验会把这些占位符当作前检错误拒绝。

字段兼容性提示：原文档把 hooks 列为插件可携带的扩展点之一，但当前仓库内置样例技能的校验注记明确写到"校验器会拒绝诸如 hooks 这类尚未支持的清单字段，因此脚手架不会把它们写入生成的 plugin.json"。实操中请以你所用版本的摄取/校验 schema 为准：钩子可以作为目录扩展存在，但写入清单清单字段前先跑校验（方法见下文实战小节）。

扩展点：Skills、MCP 与 Hooks 如何被插件组织

插件里三个核心扩展点的职责边界，在原文档骨架与源码实现中可以互相印证：

Skills：是随包携带的、可被 Agent 调用执行的技能。仓库中插件对技能的装载与 filesystem 权威控制，可参考 codex-rs/ext/skills 下的 loader/executor 相关实现与测试（如 executor_file_system_authority.rs），它们约束了技能脚本运行时的文件系统权限边界。
MCP Servers：插件通过 mcpServers 声明外部能力接入。codex-rs/ext/mcp 提供了面向插件的 MCP 执行器（见 executor_plugin_mcp.rs 与 ext/mcp/src/executor_plugin），证明"插件自带的 MCP server 会被拉起并执行"，这也是为什么信任章节会特别强调 MCP server 属于会运行代码的部分。
Hooks：挂接在 Agent 流程上的钩子。插件携带的 hooks 与全局 hooks 一样会经过常规的 trust、sandbox 与 approval 控制（详见后文"信任模型"）。

在仓库的集成测试里，这三个扩展点在插件维度都有覆盖：如 codex-rs/core/tests/suite/plugins.rs、codex-rs/core/tests/suite/skills_extension.rs 与 codex-rs/core/tests/suite/hooks.rs，可作为"插件与技能/hooks 扩展联动"的实现证据。

市场（Marketplaces）：插件从哪来、如何被分发

原文档提醒：Codex 兼容的插件市场命令可能存在于底层工具中；而在公开的 Open Interpreter launcher 中，应优先使用已安装或本地插件（即当前版本文档化的来源）。两者并不矛盾——市场是插件发现/安装的上游机制，而具体 launcher 对市场的支持程度取决于发布版本。

从仓库证据看，市场机制在实现与 CLI 层都真实存在：

CLI 侧存在插件子命令族与市场添加命令：相关测试见 codex-rs/cli/tests/plugin_cli.rs 与 codex-rs/cli/tests/marketplace_add.rs。仓库内置创建插件技能给出的安装命令形如 codex plugin marketplace add <path-to-marketplace-root>（见 plugin-creator/SKILL.md），用于显式配置非默认市场。
服务端（app-server）围绕插件提供了成套 v2 API 测试：安装、卸载、列表、详情、搜索、市场添加与分享，分别见 plugin_install.rs、plugin_uninstall.rs、plugin_list.rs、plugin_read.rs、plugin_search.rs、marketplace_add.rs 与 plugin_share.rs。
市场管理相关源码集中在 codex-rs/core-plugins，包含 marketplace.rs、marketplace_add.rs、marketplace_remove.rs、marketplace_policy.rs、marketplace_upgrade.rs、search.rs、share.rs 等模块；市场策略（谁能装、何时鉴权）由 marketplace_policy 单独建模。

marketplace.json 的形态

市场本身也是一个 JSON 文件。按仓库创建插件技能约定的默认位置：

个人市场：~/.agents/plugins/marketplace.json；
仓库/团队市场：<repo-root>/.agents/plugins/marketplace.json（Windows 下使用用户配置目录下的等价路径）。

marketplace.json 根结构为一个 name + 可选 interface + 有序 plugins[]：

{
  "name": "personal",
  "interface": {
    "displayName": "Personal"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": {
        "source": "local",
        "path": "./plugins/plugin-name"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

市场条目字段要点（依据 plugin-json-spec.md）：

plugins[] 的顺序即渲染顺序，新条目默认追加在末尾；
每个条目的 source 描述来源：source 取值 local（本地工作流），path 相对市场根目录，统一为 ./plugins/<plugin-name>（对个人市场即解析到 ~/plugins/<plugin-name>）；
policy.installation 允许值：NOT_AVAILABLE、AVAILABLE、INSTALLED_BY_DEFAULT，新建条目默认 AVAILABLE；
policy.authentication 允许值：ON_INSTALL、ON_USE，新建条目默认 ON_INSTALL；
policy.products 属于可选覆盖项，仅在明确需要产品级门控（product gating）时才写；
每个条目必须包含 policy.installation、policy.authentication 与 category 三者，缺一不可；
displayName 属于市场根的 interface 对象，不要写到单个插件条目上；
平台会默认"个人市场即 ~/.agents/plugins/marketplace.json"，codex plugin marketplace add 只用于显式配置非默认市场；非默认市场在告诉用户从它重装前必须先完成该市场的 add 安装。

信任模型与安全边界

原文档在"Trust"一节给出了插件系统最关键的提醒：启用插件前必须先审查其内容。这是因为插件携带的可运行部分至少有三类会执行代码的载体：

hooks：挂到 Agent 流程上运行；
MCP servers：作为服务进程被拉起并处理工具调用；
skill 脚本：由 Agent 依据技能说明执行。

这三类执行都经由常规的 trust、sandbox 与 approval 控制，而不是脱离现有安全体系的特权通道。换言之，插件不会让你绕过已有的权限系统，但也意味着恶意插件一旦通过审批就会获得对应权限，所以"审什么"比"要不要审"更重要：

装插件前，检查它的 plugin.json（名称、作者、来源）与各扩展点引用的脚本内容；
对从市场安装的插件，留意条目里的 policy 与 category 信息，判断其安装策略与鉴权时机；
运行边界仍由你当前的执行策略与沙箱决定。Open Interpreter 的执行策略与沙箱能力分别有独立文档可衔接查阅：docs/execpolicy.md（执行策略/审批预设）与 docs/sandbox.md（沙箱隔离）。从源码结构看，插件激活后的实际脚本/MCP 执行同样落入这些通用的执行策略与沙箱通道，插件装载结果（是否加载、有无失败）由 plugin/src/load_outcome.rs 之类的模型承载。

实战：用仓库内置 plugin-creator 技能创建并校验一个插件

仓库自带一个名为 plugin-creator 的样例技能（codex-rs/skills/src/assets/samples/plugin-creator/SKILL.md），用于在 Codex/Open Interpreter 中创建、扩展与更新本地插件。它完整展示了插件从脚手架到市场登记的标准工作流，是官方文档之外的权威实操蓝本。

1. 初始化脚手架

在技能根目录（含 SKILL.md 的目录）下运行：

# 插件名会被规范化为小写 hyphen-case，且不超过 64 字符；
# 生成的目录名与 plugin.json 中的 name 永远一致。
python3 scripts/create_basic_plugin.py <plugin-name>

默认在 ~/plugins/<plugin-name> 下创建插件根，且总会生成 .codex-plugin/plugin.json，并用校验 schema 认可的默认值填充清单。目录与命名的规范化规则为：My Plugin → my-plugin；下划线、空格与标点转为 -；连续连字符折叠；结果统一小写。

2. 按需补充伴随结构

可用 --with-* 开关一次性生成配套目录：

python3 scripts/create_basic_plugin.py my-plugin \
  --path <parent-plugin-directory> \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps

支持的可选结构包括 skills/、hooks/、scripts/、assets/、.mcp.json 与 .app.json。注意约束：只有实际创建了对应伴随文件时，plugin.json 里才写 apps / mcpServers；且清单不要写入校验器不支持的字段（含 hooks）。

3. 登记进市场

默认写入个人市场文件 ~/.agents/plugins/marketplace.json，并把插件条目（含 policy.installation: "AVAILABLE"、policy.authentication: "ON_INSTALL"、category）追加进 plugins[]：

python3 scripts/create_basic_plugin.py my-plugin --with-marketplace

若默认的 personal 市场名已被占用，可指定新的市场文件名（这是 --marketplace-name 的唯一合理场景）：

python3 scripts/create_basic_plugin.py my-plugin \
  --with-marketplace \
  --marketplace-name team-local

只有当用户明确要求仓库/团队级目的地时，才把 --path 指向仓库插件目录、--marketplace-path 指向 <repo-root>/.agents/plugins/marketplace.json，并随后对该非默认市场执行 codex plugin marketplace add 完成安装登记。

4. 校验与迭代

交付前必须运行校验脚本（它会拒绝遗留 [TODO: ...] 占位符、非严格 semver 版本号、缺失的必需字段等）：

python3 scripts/validate_plugin.py <plugin-path>

开发期对已有本地插件的迭代，不建议手工编辑市场文件，而是沿用脚手架流程并更新 cachebuster 后重新安装：

python3 scripts/update_plugin_cachebuster.py <plugin-path>

技能同时强调：校验通过后如需在 Codex App 中查看/分享插件，应输出 codex://plugins/<plugin-name>?marketplacePath=<absolute marketplace.json path> 形式的深链（分享模式追加 &mode=share），路径需要 URL 编码，且不要自行附加 pluginName/hostId 参数。

小结

插件的设计意图十分清晰：把"技能 + MCP server + hooks + 元数据"这些本会散落各处的扩展收敛成一个带清单、可版本化、可进市场、可审计的统一包，同时不创建新的特权通道——装载后的每一段可执行内容（hook、MCP server、技能脚本）依然走 Open Interpreter 既有的信任、沙箱与审批体系。这也正是原文档"Trust"章节反复强调先审查再启用的原因。

想继续深入，可以沿仓库路径按需查看：

文档基准：docs/plugins.md；
清单与市场的权威样例：plugin-json-spec.md；
插件装载与生命周期实现：codex-rs/core-plugins/src（loader、manifest、activation、marketplace、store 等模块）；
插件安装/卸载/搜索的 API 级行为验证：app-server v2 插件测试；
插件特性开关的配置模型：thread_config.rs；
与插件执行边界衔接的通用控制：docs/execpolicy.md、docs/sandbox.md。