플러그인에는 스킬과 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 문제 해결을 참고하세요. 테스트를 마치면 테스트 세션을 삭제하고 자체 호스팅 컴퓨팅 리소스를 중지하세요.