이 문서는 Codex 워크플로우의 재사용성을 높이기 위한 installable bundle인 'Plugins'에 대해 자세히 설명합니다. Plugin은 스킬(workflows를 설명하는 prompt), optional app integrations, MCP server configurations와 같은 다양한 구성 요소를 포함할 수 있으며, 추후 더 많은 구성 요소가 추가될 예정입니다.

Plugins의 정의 및 구성 요소
Plugins은 Codex Agent가 점진적으로 발견할 수 있는 스킬, 앱 통합(connector mapping), 그리고 원격 도구나 공유 context를 제공하는 MCP servers를 한데 묶어 패키징합니다. 이는 프로젝트나 팀 간에 동일한 설정을 쉽게 공유하고 재사용할 수 있도록 돕습니다.

Plugins 사용 및 설치 방법
Plugins은 Codex 앱 내의 디렉토리에서 OpenAI가 큐레이션한 것을 찾아 사용하거나, CLI(codex /plugins 명령어)를 통해 접근할 수 있습니다.
로컬 Plugin을 빠르게 설정하려면 내장된 @plugin-creator skill을 사용하여 필요한 .codex-plugin/plugin.json manifest를 scaffolding할 수 있습니다. 이는 테스트를 위한 로컬 marketplace entry도 생성할 수 있습니다. 이미 다른 ecosystem이나 자체 구축한 Plugin이 있다면, @plugin-creator를 통해 로컬 marketplace에 추가할 수 있습니다.

수동으로 로컬 Plugin을 설치하는 방법은 두 가지 marketplace 유형에 따라 나뉩니다:

1. Repo Marketplace: __INLINE_FORMULA_0__REPO_ROOT/plugins/에 복사합니다. marketplace.json 파일 내에서 Plugin entry의 source.path는 Plugin 디렉토리를 ./-prefixed relative path로 가리켜야 합니다 (예: "./plugins/my-plugin").
2. Personal Marketplace: ~/.agents/plugins/marketplace.json 파일을 추가하고, Plugin 폴더를 ~/.codex/plugins/에 복사합니다. Repo Marketplace와 마찬가지로 source.path를 해당 디렉토리로 설정합니다.

두 경우 모두 Codex를 재시작하여 Plugin이 표시되는지 확인해야 합니다. marketplace.json은 Plugin의 위치를 가리키므로, source.path는 marketplace root에 상대적으로 해석됩니다.

Marketplace Metadata
Marketplace 파일(repo의 경우 $REPO_ROOT/.agents/plugins/marketplace.json, personal의 경우 ~/.agents/plugins/marketplace.json)은 Codex 내 Plugin 카탈로그의 정렬 및 설치 정책을 제어합니다. 주요 필드는 다음과 같습니다:

• name: Marketplace를 식별하는 최상위 필드.
• interface.displayName: Codex에 표시되는 Marketplace 제목.
• plugins: Plugin 목록을 포함하는 배열. 각 Plugin entry는 다음을 포함합니다:
  • name: Plugin의 이름.
  • source.source: "local"과 같은 소스 유형.
  • source.path: Plugin 디렉토리를 가리키는 경로로, Marketplace root에 상대적이며 ./로 시작해야 합니다.
  • policy.installation: Plugin 설치 정책 (AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE 등).
  • policy.authentication: 인증이 설치 시 (ON_INSTALL) 또는 첫 사용 시 발생하는지 결정.
  • category: Plugin의 카테고리 (예: "Productivity").

Plugin 변경 시, marketplace entry가 가리키는 Plugin 디렉토리를 업데이트하고 Codex를 재시작해야 변경 사항이 적용됩니다.

Codex의 Marketplace 활용 방식
Plugin marketplace는 Codex가 읽고 설치할 수 있는 JSON 형태의 Plugin 카탈로그입니다. Codex는 공식 Plugin Directory, $REPO_ROOT/.agents/plugins/marketplace.json의 repo marketplace, 그리고 ~/.agents/plugins/marketplace.json의 personal marketplace에서 marketplace 파일을 읽을 수 있습니다.
Codex는 Plugin을 ~/.codex/plugins/cache/__INLINE_FORMULA_1__PLUGIN_NAME/__INLINE_FORMULA_2__VERSION은 'local'로 설정되며, 설치된 복사본은 해당 cache 경로에서 로드됩니다. 각 Plugin은 개별적으로 활성화 또는 비활성화할 수 있으며, 이 상태는 ~/.codex/config.toml에 저장됩니다.

Plugin 생성 시점

• Local skills: 단일 repo 또는 워크플로우에 대한 반복 작업, 개인 또는 프로젝트별 동작, 재사용 가능한 패키징 전의 실험에 적합합니다.
• Plugins: 동일한 스킬 또는 앱 통합을 팀이나 프로젝트 전반에 걸쳐 사용하고자 할 때, 스킬, MCP config, 앱 통합을 하나의 installable unit으로 묶고자 할 때, 또는 팀원이나 marketplace를 위한 안정적이고 versioned된 패키지가 필요할 때 적합합니다. 워크플로우를 처음에는 로컬에서 개발하고, 공유할 준비가 되면 Plugin으로 패키징하는 것이 권장됩니다.

Plugin 구조
모든 Plugin은 .codex-plugin/plugin.json에 manifest를 가지고 있습니다. 또한 skills/ 디렉토리, 하나 이상의 앱 또는 커넥터를 가리키는 .app.json 파일, 그리고 Plugin을 표시하는 데 사용되는 assets/를 포함할 수 있습니다.

• my-plugin/ (Plugin root)
  • .codex-plugin/
    • plugin.json (Required: Plugin manifest)
  • skills/ (Optional: Skill instructions)
    • my-skill/SKILL.md
  • .app.json (Optional: App or connector mappings)
  • .mcp.json (Optional: MCP server configuration)
  • assets/ (Optional: Icons, logos, screenshots)

.codex-plugin/plugin.json은 필수 진입점이며, skills/, assets/, .mcp.json, .app.json은 Plugin root에 위치해야 합니다.

Manifest 필드
plugin.json manifest는 다음 세 가지 역할을 수행합니다: Plugin 식별, 묶인 구성 요소(스킬, 앱, MCP 서버) 참조, 설치 화면 metadata 제공.
최상위 필드는 패키지 metadata를 정의하고 묶인 구성 요소를 가리킵니다:

• name, version, description: Plugin 식별.
• author, homepage, repository, license, keywords: 게시자 및 검색 metadata.
• skills, mcpServers, apps: Plugin root에 상대적인 경로로 묶인 구성 요소를 가리킵니다.

interface 객체는 설치 화면에서 Plugin을 어떻게 표시할지 제어합니다:

• displayName, shortDescription, longDescription: 제목 및 설명 텍스트.
• developerName, category, capabilities: 게시자 및 기능 metadata.
• websiteURL, privacyPolicyURL, termsOfServiceURL: 외부 링크.
• defaultPrompt, brandColor, composerIcon, logo, screenshots: 시작 프롬프트 및 시각적 표현.

경로 규칙
Manifest 내의 모든 경로는 Plugin root에 상대적이어야 하며 ./로 시작해야 합니다. composerIcon, logo, screenshots와 같은 시각적 asset은 가능한 경우 ./assets/ 아래에 저장하는 것이 좋습니다. skills는 묶인 skill 폴더, apps는 .app.json, mcpServers는 .mcp.json을 위해 사용됩니다.

첫 Plugin 생성 예시

3. Plugin 폴더와 manifest 생성: mkdir -p my-first-plugin/.codex-plugin, my-first-plugin/.codex-plugin/plugin.json 파일에 { "name": "my-first-plugin", "version": "1.0.0", "description": "Reusable greeting workflow", "skills": "./skills/" } 내용 추가. Plugin 이름은 kebab-case를 사용하며 Codex의 identifier로 사용됩니다.
4. Skill 추가: mkdir -p my-first-plugin/skills/hello, my-first-plugin/skills/hello/SKILL.md 파일에 skill 정의 추가.

이후, "Use plugins locally" 섹션을 따라 Plugin을 Codex에 로드할 수 있으며, 필요에 따라 MCP config, 앱 통합 또는 marketplace metadata를 추가할 수 있습니다. 공식 Plugin Directory에 Plugin을 게시하는 기능은 추후 제공될 예정입니다.