如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

外掛程式

將技能與 MCP 設定打包,以便在不同工作階段中使用。

外掛程式可以包含技能、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 疑難排解。測試完成後,請刪除測試用的工作階段,並停止自行託管的運算資源。