AI translation, not an official translation. Refer to the original for technical details.

完整的文档索引，请参阅 llms.txt。在页面 URL 后追加 .md 即可获取文档页面的 Markdown 版本。

插件可以打包技能、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);

from openai import OpenAI

client = OpenAI()

result = client.beta.agents.sessions.create(
    agent={"model": "gpt-6-astra"},
    environment={
        "type": "self_hosted",
        "workspace_directory": "/workspace",
        "capability_directories": ["/workspace/plugins/docs-helper"],
    },
)
print(result.id)

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		Agent: openai.BetaAgentSessionNewParamsAgent{Model: openai.String("gpt-6-astra")},
		Environment: openai.EnvironmentParamUnion{
			OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{
				WorkspaceDirectory:    "/workspace",
				CapabilityDirectories: []string{"/workspace/plugins/docs-helper"},
			},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result.ID)

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import java.util.List;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(SessionCreateParams.Agent.builder().model("gpt-6-astra").build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .capabilityDirectories(List.of("/workspace/plugins/docs-helper"))
                        .build())
                .build());
System.out.println(result.id());

require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent: { model: "gpt-6-astra" },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
    capability_directories: ["/workspace/plugins/docs-helper"]
  }
)
puts 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 网络策略。

测试插件

发送一条请求使用技能的普通会话消息：

使用 docs-search 解释如何流式传输 Responses API 输出。请包含文档链接。

检查该轮次是否已完成，以及其已保存项目中是否包含对 openai_docs 的成功调用。答案应遵循技能的说明并引用文档。对于仅含技能的插件，对照说明检查其输出；不需要 MCP 调用。

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