插件可以打包技能、MCP 配置，或同时包含两者。您可以将插件文件加载到自己的环境中，也可以将 ZIP 文件上传到 OpenAI 托管的环境。
打包插件
此插件将文档搜索技能与 OpenAI 文档 MCP 结合使用。它需要网络访问权限，但不需要凭据或本地服务器依赖项。
docs-helper/
├── .codex-plugin/plugin.json
├── .mcp.json
└── skills/docs-search/SKILL.md在 .codex-plugin/plugin.json 中声明技能目录和 MCP 配置：
{
"name": "docs-helper",
"version": "1.0.0",
"description": "Find answers in OpenAI developer documentation.",
"skills": "./skills/",
"mcpServers": "./.mcp.json"
}路径以插件根目录为基准进行解析，必须以 ./ 开头，指向插件内部，且不能包含 .. 路径段。完整的清单格式请参阅打包插件。
将服务器添加到 .mcp.json。此文件使用插件格式，与 agent.tools 的格式不同：
{
"mcpServers": {
"openai_docs": {
"type": "http",
"url": "https://developers.openai.com/mcp"
}
}
}将指令添加到 skills/docs-search/SKILL.md：
---
name: docs-search
description: Find answers in OpenAI developer documentation.
---
Use the openai_docs MCP server to find relevant documentation.
Answer the question and link to the sources you used.在自托管沙盒中注册插件
将插件复制到 /workspace/plugins/docs-helper，并将该绝对路径添加到 environment.capability_directories。请选择包含 .codex-plugin/plugin.json 的插件根目录。
import OpenAI from "openai";
const client = new OpenAI();
const result = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
},
environment: {
type: "self_hosted",
workspace_directory: "/workspace",
capability_directories: ["/workspace/plugins/docs-helper"],
},
});
console.log(result.id);在智能体使用插件之前，先连接执行器。允许环境访问 https://developers.openai.com/mcp。
如果有多个插件，请列出每个插件的根目录。指定父目录可以发现嵌套的技能，但不会加载每个子插件的 MCP 配置。
将插件上传到 OpenAI 托管的沙盒
在 environment.plugins 中为每个插件提供一个 ZIP 文件。每个 ZIP 文件必须包含一个插件文件夹，且该文件夹内必须有 .codex-plugin/plugin.json。请求中的名称和描述必须与清单一致。
此辅助函数会打包您的文件夹并创建会话。请传入您的 API 客户端和 docs-helper 的路径。OpenAI 会自动解压并注册插件。
import base64
import json
import shutil
from pathlib import Path
from tempfile import TemporaryDirectory
def upload_plugin(client, plugin_directory):
plugin_directory = Path(plugin_directory).resolve()
manifest = json.loads((plugin_directory / ".codex-plugin/plugin.json").read_text())
with TemporaryDirectory() as temporary:
archive = shutil.make_archive(
str(Path(temporary) / "plugin"),
"zip",
root_dir=plugin_directory.parent,
base_dir=plugin_directory.name,
)
return client.beta.agents.sessions.create(
agent={"model": "gpt-6-astra"},
environment={
"type": "openai_hosted",
"plugins": [
{
"type": "inline",
"name": manifest["name"],
"description": manifest["description"],
"source": {
"type": "base64",
"media_type": "application/zip",
"data": base64.b64encode(
Path(archive).read_bytes()
).decode(),
},
}
],
},
)复用托管插件配置
使用插件列表创建环境模板。在后续会话中，将 environment.environment_template_id 设置为已保存的模板 ID。
省略 environment.plugins 即可继承模板的插件列表。提供列表则会替换模板中的列表。每个会话都有自己的环境，根智能体及其子智能体共享该环境。
配置 MCP 服务器身份验证
此示例不需要身份验证。对于其他插件 MCP 服务器：
- HTTP：
bearer_token_env_var读取环境变量，并将其值作为 Bearer Token 发送。其他http_headers值均按字面值使用；不支持env_http_headers。 - Stdio：
env_vars列出要传递给服务器进程的环境变量。请在环境中安装可执行文件及其依赖项。如果cwd是相对路径，则以插件根目录为基准进行解析。
不要在插件文件和压缩包中存放密钥等机密信息。插件 MCP 连接从会话环境中发起。有关凭据的使用边界，请参阅 MCP 身份验证。
对于托管的 stdio MCP，请省略网络策略或将其设置为 enabled。这些连接不支持 disabled 和 restricted 网络策略。
测试插件
发送一条普通会话消息，要求使用该技能：
Use docs-search to explain how to stream Responses API output. Include links to the documentation.
检查该轮交互是否已完成，以及其已保存的条目是否包含一次成功的 openai_docs 调用。回答应遵循技能中的指令并引用文档。对于仅包含技能的插件，请对照指令检查其输出；不要求进行 MCP 调用。
更改插件文件或模板后，请创建新会话。现有会话不会重新加载工具。如果出现连接错误，请参阅 MCP 故障排除。完成后，请删除测试会话并停止自托管计算资源。