如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

插件

将技能和 MCP 配置打包,以便在多个会话中使用。

插件可以包含技能、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.
---

使用 openai_docs MCP 服务器查找相关文档。
回答问题,并附上所参考资料的链接。

在自托管沙盒中注册插件

将插件复制到 /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 令牌发送。http_headers 中的其他值按字面值使用。不支持 env_http_headers。
  • 标准输入输出: env_vars 列出要传递给服务器进程的环境变量。请在环境中安装可执行文件及其依赖项。如果 cwd 是相对路径,则以插件根目录为基准解析。

请勿将密钥等敏感信息存入插件文件或压缩包。插件从会话环境中发起 MCP 连接。有关凭据的使用范围,请参阅 MCP 身份验证。

在托管环境中通过标准输入输出连接 MCP 服务器时,请省略网络策略或将其设置为 enabled。此类连接不支持 disabled 和 restricted 网络策略。

测试插件

在会话中发送一条普通消息,要求智能体使用该技能。

请使用 docs-search 说明如何以流式方式接收 Responses API 的输出,并附上相关文档的链接。

确认该轮对话已完成,并检查该轮对话已保存的条目中是否有成功调用 openai_docs 的记录。回答应遵循技能指令并引用相关文档。如果插件仅包含技能,请对照指令检查输出,无需调用 MCP。

修改插件文件或模板后,请创建新会话。现有会话不会重新加载工具。如果出现连接错误,请参阅 MCP 连接故障排查。测试完成后,请删除测试会话并停止运行自托管的计算资源。