外掛程式可以包含技能、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 權杖傳送。其他http_headers的值會按原樣傳送。不支援env_http_headers。 - Stdio:
env_vars列出要傳給伺服器程序的環境變數。請在環境中安裝可執行檔及其相依套件。若cwd是相對路徑,則以外掛程式根目錄為基準解析。
請勿將機密資料存放在外掛程式檔案或封存檔中。外掛程式會從工作階段的環境建立 MCP 連線。關於憑證的使用範圍,請參閱 MCP 驗證。
對於託管環境中使用 stdio 的 MCP 伺服器,請省略網路政策或將其設為 enabled。這類連線不支援 disabled 和 restricted 網路政策。
測試外掛程式
在工作階段中傳送一則一般訊息,要求智慧體使用該技能:
請使用 docs-search 說明如何以串流方式接收 Responses API 的輸出,並附上相關文件的連結。
確認該回合已完成,且該回合的已儲存項目中有成功呼叫 openai_docs 的紀錄。回答應遵循技能的指示並引用文件。如果外掛程式只包含技能,請確認輸出符合技能的指示,無須呼叫 MCP。
變更外掛程式檔案或範本後,請建立新的工作階段。現有工作階段不會重新載入工具。如果發生連線錯誤,請參閱 MCP 疑難排解。測試完成後,請刪除測試用的工作階段,並停止自行託管的運算資源。