플러그인

플러그인 (Plugins)

플러그인은 스킬, MCP 구성, 또는 둘 다를 패키징해요. 자체 환경에 파일을 로드하거나 OpenAI 호스팅 환경에 ZIP을 업로드할 수 있어요.

출처: 문서

본문

플러그인 패키징하기 (Package the plugin)

이 플러그인은 문서 검색 스킬과 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.

자체 호스팅 샌드박스에서 플러그인 등록하기 (Register plugins in a self-hosted sandbox)

플러그인을 /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);

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)

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)

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());

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 구성을 로드하지는 않아요.

OpenAI 호스팅 샌드박스에 플러그인 업로드하기 (Upload plugins to an OpenAI-hosted sandbox)

environment.plugins에 플러그인당 ZIP을 하나씩 제공하세요. 각 ZIP 안에는 .codex-plugin/plugin.json이 들어 있는 플러그인 폴더가 하나 있어야 해요. 요청의 name과 description은 매니페스트와 일치해야 해요.

이 헬퍼는 폴더를 패키징하고 세션을 만들어요. 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(),
                        },
                    }
                ],
            },
        )

호스팅 플러그인 설정 재사용하기 (Reuse a hosted plugin setup)

플러그인 목록으로 환경 템플릿을 만들고 나중 세션에는 environment.environment_template_id를 저장한 템플릿 ID로 설정하세요.

environment.plugins를 생략하면 템플릿의 플러그인 목록을 상속받아요. 목록을 제공하면 그걸로 대체돼요. 각 세션은 자체 환경을 가지며, 루트 에이전트와 그 서브에이전트가 그 환경을 공유해요.

MCP 서버 인증하기 (Authenticate MCP servers)

이 예시는 인증이 필요 없어요. 다른 플러그인 MCP 서버에서는:

• HTTP: bearer_token_env_var는 환경 변수를 읽어 그 값을 베어러 토큰으로 보내요. 다른 http_headers 값은 리터럴이고, env_http_headers는 지원되지 않아요.
• Stdio: env_vars는 서버 프로세스에 전달할 환경 변수를 나열해요. 실행 파일과 의존성을 환경에 설치하세요. 상대 cwd는 플러그인 루트에서 해석돼요.

시크릿을 플러그인 파일과 아카이브에 넣지 마세요. 플러그인 MCP 연결은 세션의 환경에서 실행돼요. 자격 증명 경계는 MCP 인증을 참고하세요.

호스팅 stdio MCP에서는 네트워크 정책을 생략하거나 enabled로 설정하세요. 이 연결에는 disabled와 restricted 네트워크 정책이 지원되지 않아요.

플러그인 테스트하기 (Test a plugin)

스킬을 요청하는 일반 세션 메시지를 보내세요:

Use docs-search to explain how to stream Responses API output. Include links to the documentation.

턴이 완료됐는지, 그리고 그 저장된 아이템에 openai_docs에 대한 성공적인 호출이 포함됐는지 확인하세요. 답은 스킬의 지시사항을 따라야 하고 문서를 인용해야 해요. 스킬 전용 플러그인이라면 출력을 지시사항과 비교해 확인하세요. MCP 호출은 필요하지 않아요.

플러그인 파일이나 템플릿을 바꾼 뒤에는 새 세션을 만드세요. 기존 세션은 도구를 다시 로드하지 않아요. 연결 오류는 MCP 문제 해결을 참고하세요. 작업이 끝나면 테스트 세션을 삭제하고 자체 호스팅 컴퓨팅을 중지하세요.

더 알아보기 (Learn more)

• MCP 연결 가이드에서 연결과 인증을 확인하세요.
• Vaults 가이드에서 자격 증명을 안전하게 관리하는 방법을 확인하세요.