外掛程式可封裝技能、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 Token 傳送。其他http_headers值會按字面使用；不支援env_http_headers。 - Stdio：
env_vars列出要傳遞給伺服器程序的環境變數。請在環境中安裝執行檔及其相依套件。若cwd為相對路徑，則以外掛程式根目錄為基準解析。
請勿將機密資訊放入外掛程式檔案或封存檔。外掛程式的 MCP 連線會從工作階段的環境發起。憑證的使用界限請參閱 MCP 身分驗證。
對於託管的 stdio MCP，請省略網路政策，或將其設為 enabled。這些連線不支援 disabled 和 restricted 網路政策。
測試外掛程式
傳送一般工作階段訊息，要求使用該技能：
Use docs-search to explain how to stream Responses API output. Include links to the documentation.
確認該回合已完成，且其已儲存項目包含對 openai_docs 的成功呼叫。回答應遵循技能的指示並引用文件。若外掛程式僅包含技能，請對照指示檢查其輸出；不需要 MCP 呼叫。
變更外掛程式檔案或範本後，請建立新的工作階段。現有工作階段不會重新載入工具。若發生連線錯誤，請參閱 MCP 疑難排解。完成後，請刪除測試工作階段並停止自行託管的運算資源。