插件可以包含技能、MCP 配置,也可以同时包含两者。您可以将插件文件加载到自己的环境中,也可以将 ZIP 文件上传到 OpenAI 托管的环境。
此插件将文档搜索技能与 OpenAI 文档 MCP 服务器结合使用。它需要访问网络,无需凭据,也不依赖本地服务器。
docs-helper/
├── .codex-plugin/plugin.json
├── .mcp.json
└── skills/docs-search/SKILL.md
在 .codex-plugin/plugin.json 中声明技能目录和 MCP 配置。
1234567{
"name": "docs-helper",
"version": "1.0.0",
"description": "Find answers in OpenAI developer documentation.",
"skills": "./skills/",
"mcpServers": "./.mcp.json"
}
路径相对于插件根目录解析。路径必须以 ./ 开头,不能指向插件目录之外,也不能包含 .. 路径段。完整的清单格式请参阅打包插件。
将服务器添加到 .mcp.json。此文件采用插件专用格式,与 agent.tools 的格式不同。
12345678{
"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 的插件根目录。
1
2
3
4
5
6
7
8
9
10
11
12
13
14import 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);
1
2
3
4
5
6
7
8
9
10
11
12
13from 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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import (
"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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22import 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());
1
2
3
4
5
6
7
8
9
10
11
12require "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 配置。
在 environment.plugins 中为每个插件提供一个 ZIP 文件。每个 ZIP 文件必须包含一个插件文件夹,且该文件夹内必须有 .codex-plugin/plugin.json。请求中的名称和描述必须与清单中的内容一致。
下面的辅助函数会打包您的文件夹并创建会话。请传入您的 API 客户端和 docs-helper 的路径。OpenAI 会自动解压并注册插件。
Go 示例程序使用 OpenAI SDK 和 Go 标准库提供的 ZIP 功能。程序会创建一个临时示例插件,上传后删除该插件的本地目录。要上传自己的插件,请调用 uploadPlugin 并传入插件目录。创建压缩包时,程序会拒绝符号链接和其他非常规文件。
Ruby 辅助函数依赖 openai 和 rubyzip 两个 gem 包。请先用 gem install openai rubyzip 安装这两个包,并设置 OPENAI_API_KEY,然后再创建客户端。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37import 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(),
},
}
],
},
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110package main
import (
"archive/zip"
"bytes"
"context"
"encoding/base64"
"encoding/json"
"fmt"
"github.com/openai/openai-go/v3"
"io"
"io/fs"
"log"
"os"
"path/filepath"
"time"
)
func uploadPlugin(ctx context.Context, client *openai.Client, directory string) (*openai.AgentSession, error) {
directory, err := filepath.Abs(directory)
if err != nil {
return nil, err
}
data, err := os.ReadFile(filepath.Join(directory, ".codex-plugin/plugin.json"))
if err != nil {
return nil, err
}
var manifest struct {
Name string `json:"name"`
Description string `json:"description"`
}
if err := json.Unmarshal(data, &manifest); err != nil {
return nil, err
}
if manifest.Name == "" || manifest.Description == "" {
return nil, fmt.Errorf("plugin manifest requires name and description")
}
var buffer bytes.Buffer
archive := zip.NewWriter(&buffer)
err = filepath.WalkDir(directory, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
if entry.IsDir() {
return nil
}
if !entry.Type().IsRegular() {
return fmt.Errorf("plugin archive requires regular files: %s", path)
}
relative, err := filepath.Rel(directory, path)
if err != nil {
return err
}
member, err := archive.Create(filepath.ToSlash(filepath.Join(filepath.Base(directory), relative)))
if err != nil {
return err
}
file, err := os.Open(path)
if err != nil {
return err
}
defer file.Close()
_, err = io.Copy(member, file)
return err
})
closeErr := archive.Close()
if err != nil {
return nil, err
}
if closeErr != nil {
return nil, closeErr
}
return client.Beta.Agents.Sessions.New(ctx, openai.BetaAgentSessionNewParams{Agent: openai.BetaAgentSessionNewParamsAgent{Model: openai.String("gpt-6-astra")}, Environment: openai.EnvironmentParamUnion{OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{Plugins: []openai.HostedPluginParam{{Name: manifest.Name, Description: manifest.Description, Source: openai.InlineCapabilitySourceParam{Data: base64.StdEncoding.EncodeToString(buffer.Bytes())}}}}}})
}
func run() error {
temporary, err := os.MkdirTemp("", "docs-plugin-")
if err != nil {
return err
}
defer os.RemoveAll(temporary)
directory := filepath.Join(temporary, "docs-helper")
files := map[string]string{
".codex-plugin/plugin.json": `{"name":"docs-helper","version":"1.0.0","description":"Find answers in OpenAI developer documentation.","skills":"./skills/","mcpServers":"./.mcp.json"}`,
".mcp.json": `{"mcpServers":{"openai_docs":{"type":"http","url":"https://developers.openai.com/mcp"}}}`,
"skills/docs-search/SKILL.md": "---\nname: docs-search\ndescription: Find answers in OpenAI developer documentation.\n---\n\nUse the openai_docs MCP server to find relevant documentation.\nAnswer the question and link to the sources you used.\n",
}
for name, content := range files {
path := filepath.Join(directory, name)
if err := os.MkdirAll(filepath.Dir(path), 0700); err != nil {
return err
}
if err := os.WriteFile(path, []byte(content), 0600); err != nil {
return err
}
}
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
client := openai.NewClient()
session, err := uploadPlugin(ctx, &client, directory)
if err != nil {
return err
}
fmt.Println(session.ID)
return nil
}
func main() {
if err := run(); err != nil {
log.Fatal(err)
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40require "openai"
require "json"
require "base64"
require "tmpdir"
require "fileutils"
require "zip"
def upload_plugin(client, plugin_directory)
plugin_directory = File.expand_path(plugin_directory)
manifest = JSON.parse(File.read(File.join(plugin_directory, ".codex-plugin/plugin.json")))
Dir.mktmpdir do |temporary|
archive = File.join(temporary, "plugin.zip")
Zip::File.open(archive, create: true) do |zip|
Dir.glob("**/*", File::FNM_DOTMATCH, base: plugin_directory).sort.each do |relative|
source = File.join(plugin_directory, relative)
next unless File.file?(source)
zip.add(File.join(File.basename(plugin_directory), relative), source)
end
end
client.beta.agents.sessions.create(
agent: { model: "gpt-6-astra" },
environment: {
type: :openai_hosted,
plugins: [
{
type: :inline,
name: manifest.fetch("name"),
description: manifest.fetch("description"),
source: {
type: :base64,
media_type: "application/zip",
data: Base64.strict_encode64(File.binread(archive))
}
}
]
}
)
end
end
使用插件列表创建环境模板。在后续会话中,将 environment.environment_template_id 设置为已保存的模板 ID。
省略 environment.plugins 即可继承模板中的插件列表。如果提供新的列表,它就会替换模板中的列表。每个会话都有独立的环境,由该会话的根智能体及其子智能体共享。
本示例无需身份验证。对于插件使用的其他 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 连接故障排查。测试完成后,请删除测试会话并停止运行自托管的计算资源。