TRAE-AI编程
OpenAI 插件
插件可打包技能、MCP配置或两者。可把文件放入自有环境，也可上传ZIP到OpenAI托管环境。
打包插件
此插件把文档搜索技能与官方文档MCP组合，需要网络，不需要凭证或本地服务器依赖：
来源示例 1（text）：
docs-helper/
├── .codex-plugin/plugin.json
├── .mcp.json
└── skills/docs-search/SKILL.md
在 .codex-plugin/plugin.json 声明技能目录及MCP配置：
来源示例 2（json）：
程序文字说明27：在OpenAI开发者文档中查找答案。
{
"name": "docs-helper",
"version": "1.0.0",
"description": "Find answers in OpenAI developer documentation.",
"skills": "./skills/",
"mcpServers": "./.mcp.json"
}
路径从插件根目录解析，必须以 ./ 开头、留在插件内、不含 ..。完整格式见打包插件。
将服务器加入 .mcp.json，注意插件格式与 agent.tools 不同：
来源示例 3（json）：
{
"mcpServers": {
"openai_docs": {
"type": "http",
"url": "https://developers.openai.com/mcp"
}
}
}
把技能指令写入 skills/docs-search/SKILL.md：
来源示例 4（markdown）：
沿用程序文字说明27。
本例中文译文：技能清单：name为docs-search；description意为“在OpenAI开发者文档中查找答案”。正文指令：使用openai_docs MCP服务器查找相关文档，回答问题并链接到实际使用的来源。
---
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 的插件根目录：
来源示例 5（javascript）：
// [中文] 示例 5：在自托管沙箱注册插件。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
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);来源示例 6（python）：
## [中文] 示例 6：在自托管沙箱注册插件。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
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)来源示例 7（go）：
// [中文] 示例 7：在自托管沙箱注册插件。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
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)来源示例 8（java）：
// [中文] 示例 8：在自托管沙箱注册插件。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
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());来源示例 9（ruby）：
## [中文] 示例 9：在自托管沙箱注册插件。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
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配置。
向托管沙箱上传插件
environment.plugins 每插件提供一个ZIP，压缩包必须只含一个插件文件夹，其内有 .codex-plugin/plugin.json。请求中的名称和描述必须与清单一致。
以下函数接收API客户端及 docs-helper 路径，打包文件夹并创建会话，OpenAI自动解压和注册：
来源示例 10（python）：
## [中文] 示例 10：向托管沙箱上传插件。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
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。 - stdio：
env_vars列出传给服务器进程的环境变量名，先在环境安装程序及依赖。相对cwd从插件根目录解析。
秘密不写入插件文件或压缩包。插件MCP从会话环境发起连接，凭证边界见 MCP认证。
托管stdio MCP需省略网络策略或设 enabled，不支持 disabled、restricted。
测试插件
发送要求使用技能的普通会话消息：
使用docs-search说明如何流式接收Responses API输出，并附文档链接。
确认轮次完成，保存项目包含成功的 openai_docs 调用，答案符合技能指令并引用文档。纯技能插件只检查输出是否符合指令，无需MCP调用。
更多建议：