플러그인 빌드

이 문서는 플러그인 작성자를 위한 문서입니다. Codex에서 플러그인을 찾아 설치하고 사용하려면 플러그인을 참고하십시오. 하나의 저장소나 개인 워크플로를 아직 반복 개선하는 단계라면 로컬 skill부터 시작하는 편이 좋습니다. 팀 간에 워크플로를 공유하거나, 앱 통합 및 MCP 구성을 함께 묶거나, 안정적인 패키지로 배포하려면 플러그인을 만드십시오.

`$plugin-creator`로 플러그인 만들기

가장 빠르게 시작하려면 내장 $plugin-creator skill을 사용합니다.

이 skill은 필수 .codex-plugin/plugin.json manifest를 scaffold하고, 테스트용 로컬 marketplace 항목도 생성할 수 있습니다. 이미 플러그인 폴더가 있어도 $plugin-creator를 사용해 로컬 marketplace에 연결할 수 있습니다.

나만의 큐레이션 플러그인 목록 만들기

Marketplace는 플러그인 JSON 카탈로그입니다. $plugin-creator는 단일 플러그인용 marketplace를 생성할 수 있으며, 같은 marketplace에 항목을 계속 추가해 저장소, 팀, 개인 워크플로용 큐레이션 목록을 만들 수 있습니다.

Codex에서 각 marketplace는 플러그인 디렉터리의 선택 가능한 소스로 나타납니다. 저장소 범위 목록에는 $REPO_ROOT/.agents/plugins/marketplace.json을, 개인 목록에는 ~/.agents/plugins/marketplace.json을 사용합니다. plugins[] 아래에 플러그인마다 항목 하나를 추가하고, 각 source.path는 marketplace 루트 기준 ./로 시작하는 상대 경로로 플러그인 폴더를 가리키게 하며, Codex가 marketplace picker에 표시할 라벨은 interface.displayName에 설정합니다. 그런 다음 Codex를 다시 시작하고 플러그인 디렉터리에서 해당 marketplace를 선택해 플러그인을 탐색하거나 설치합니다.

플러그인마다 별도 marketplace가 필요하지 않습니다. 테스트 중에는 하나의 marketplace가 단일 플러그인만 노출할 수 있고, 이후 더 많은 플러그인을 추가하면서 더 큰 큐레이션 카탈로그로 확장할 수 있습니다.

CLI에서 marketplace 추가

config.toml을 직접 편집하지 않고 Codex가 marketplace 소스를 설치하고 추적하게 하려면 codex plugin marketplace add를 사용합니다.

codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-root

Marketplace 소스는 GitHub 축약형(owner/repo 또는 owner/repo@ref), HTTP/HTTPS Git URL, SSH Git URL, 로컬 marketplace 루트 디렉터리를 사용할 수 있습니다. Git ref를 고정하려면 --ref를 사용하고, Git 기반 marketplace 저장소에서 sparse checkout을 쓰려면 --sparse PATH를 반복 지정합니다. --sparse는 Git marketplace 소스에서만 유효합니다.

구성된 marketplace를 새로 고치거나 제거하려면 다음 명령을 사용합니다.

codex plugin marketplace upgrade
codex plugin marketplace upgrade marketplace-name
codex plugin marketplace remove marketplace-name

플러그인 수동 생성

skill 하나를 패키징하는 최소 플러그인부터 시작합니다.

.codex-plugin/plugin.json 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/"
}

플러그인 name은 안정적인 kebab-case로 지정합니다. Codex는 이 값을 플러그인 식별자와 컴포넌트 namespace로 사용합니다.

skills/{skill-name}/SKILL.md 아래에 skill을 추가합니다.

mkdir -p my-first-plugin/skills/hello

my-first-plugin/skills/hello/SKILL.md:

---
name: hello
description: Greet the user with a friendly message.
---

Greet the user warmly and ask how you can help.

플러그인을 marketplace에 추가합니다. $plugin-creator로 marketplace를 생성하거나, 위의 큐레이션 목록 절차에 따라 Codex에 수동 연결합니다.

이후 필요에 따라 MCP 구성, 앱 통합, marketplace metadata를 추가할 수 있습니다.

로컬 플러그인 수동 설치

누가 플러그인 또는 큐레이션 목록에 접근해야 하는지에 따라 저장소 marketplace 또는 개인 marketplace를 사용합니다.

저장소 marketplace 예시

저장소에 marketplace 파일을 $REPO_ROOT/.agents/plugins/marketplace.json으로 추가하고 플러그인을 $REPO_ROOT/plugins/ 아래에 둡니다.

플러그인 폴더를 $REPO_ROOT/plugins/my-plugin으로 복사합니다.

mkdir -p ./plugins
cp -R /absolute/path/to/my-plugin ./plugins/my-plugin

$REPO_ROOT/.agents/plugins/marketplace.json을 추가하거나 갱신해 source.path가 ./로 시작하는 상대 경로로 해당 플러그인 디렉터리를 가리키게 합니다.

{
  "name": "local-repo",
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Codex를 다시 시작하고 플러그인이 표시되는지 확인합니다.

개인 marketplace 예시

개인 marketplace 파일을 ~/.agents/plugins/marketplace.json에 추가하고 플러그인은 ~/.codex/plugins/ 아래에 둡니다.

플러그인 폴더를 ~/.codex/plugins/my-plugin으로 복사합니다.

mkdir -p ~/.codex/plugins
cp -R /absolute/path/to/my-plugin ~/.codex/plugins/my-plugin

~/.agents/plugins/marketplace.json을 추가하거나 갱신해 플러그인 항목의 source.path가 해당 디렉터리를 가리키게 합니다.
Codex를 다시 시작하고 플러그인이 표시되는지 확인합니다.

Marketplace 파일은 플러그인 위치를 가리키므로 위 디렉터리는 고정 요구 사항이 아니라 예시입니다. Codex는 source.path를 .agents/plugins/ 폴더 기준이 아니라 marketplace 루트 기준으로 해석합니다. 파일 형식은 Marketplace metadata를 참고하십시오.

플러그인을 변경한 뒤에는 marketplace 항목이 가리키는 플러그인 디렉터리를 갱신하고 Codex를 다시 시작해야 로컬 설치가 새 파일을 읽습니다.

Marketplace metadata

저장소 marketplace를 유지한다면 $REPO_ROOT/.agents/plugins/marketplace.json에 정의합니다. 개인 marketplace는 ~/.agents/plugins/marketplace.json을 사용합니다. Marketplace 파일은 Codex에 표시되는 카탈로그에서 플러그인 순서와 설치 정책을 제어합니다. 테스트 중인 단일 플러그인을 나타낼 수도 있고, 하나의 marketplace 이름 아래에 함께 표시할 큐레이션 플러그인 목록을 나타낼 수도 있습니다. 플러그인을 marketplace에 추가하기 전에 version, 게시자 metadata, 설치 화면 문구가 다른 개발자에게 보여도 괜찮은 상태인지 확인하십시오.

{
  "name": "local-example-plugins",
  "interface": {
    "displayName": "Local Example Plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    },
    {
      "name": "research-helper",
      "source": {
        "source": "local",
        "path": "./plugins/research-helper"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

최상위 name은 marketplace 식별자입니다.
interface.displayName은 Codex에 표시되는 marketplace 제목입니다.
Codex가 같은 제목 아래에 보여 줄 큐레이션 목록을 만들려면 plugins 아래에 플러그인마다 객체 하나를 추가합니다.
각 플러그인 항목의 source.path는 Codex가 로드할 플러그인 디렉터리를 가리켜야 합니다. 저장소 설치에서는 보통 ./plugins/ 아래, 개인 설치에서는 ./.codex/plugins/{plugin-name} 같은 패턴을 사용합니다.
source.path는 marketplace 루트 기준 상대 경로로 유지하고, ./로 시작하며, 해당 루트 안에 있어야 합니다.
로컬 항목에서 source는 "./plugins/my-plugin" 같은 단순 문자열 경로일 수도 있습니다.
각 플러그인 항목에는 항상 policy.installation, policy.authentication, category를 포함합니다.
policy.installation 값은 AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE 등을 사용할 수 있습니다.
policy.authentication은 인증을 설치 시점에 할지 첫 사용 시점에 할지 결정합니다.

Marketplace는 Codex가 플러그인을 어디서 로드할지 제어합니다. 로컬 source.path는 플러그인이 예시 디렉터리 밖에 있을 때 다른 위치를 가리킬 수 있습니다. Marketplace 파일은 플러그인을 개발하는 저장소 또는 별도 marketplace 저장소에 둘 수 있으며, 하나의 marketplace 파일이 플러그인 하나 또는 여러 개를 가리킬 수 있습니다.

Marketplace 항목은 Git 기반 플러그인 소스도 가리킬 수 있습니다. 플러그인이 저장소 루트에 있으면 "source": "url"을, 하위 디렉터리에 있으면 "source": "git-subdir"를 사용합니다.

{
  "name": "remote-helper",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/example/codex-plugins.git",
    "path": "./plugins/remote-helper",
    "ref": "main"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

Git 기반 항목은 ref 또는 sha 선택자를 사용할 수 있습니다. Codex가 marketplace 항목의 소스를 해석할 수 없으면 전체 marketplace를 실패시키지 않고 해당 플러그인 항목만 건너뜁니다.

Codex가 marketplace를 사용하는 방식

플러그인 marketplace는 Codex가 읽고 설치할 수 있는 플러그인의 JSON 카탈로그입니다.

Codex가 읽을 수 있는 marketplace 파일 위치:

공식 Plugin Directory를 구동하는 큐레이션 marketplace
$REPO_ROOT/.agents/plugins/marketplace.json의 저장소 marketplace
$REPO_ROOT/.claude-plugin/marketplace.json의 Claude 스타일 marketplace
~/.agents/plugins/marketplace.json의 개인 marketplace

Marketplace로 노출된 플러그인은 설치할 수 있습니다. Codex는 플러그인을 ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/에 설치합니다. 로컬 플러그인의 $VERSION은 local이며, Codex는 marketplace 항목을 직접 읽는 대신 이 캐시 경로의 설치 복사본을 로드합니다.

각 플러그인은 개별적으로 활성화하거나 비활성화할 수 있습니다. Codex는 각 플러그인의 켜짐/꺼짐 상태를 ~/.codex/config.toml에 저장합니다.

플러그인 패키징 및 배포

플러그인 구조

모든 플러그인에는 .codex-plugin/plugin.json manifest가 있습니다. 선택적으로 skills/ 디렉터리, 하나 이상의 앱 또는 connector를 가리키는 .app.json, MCP 서버를 구성하는 .mcp.json, 수명주기 구성, 지원되는 표면에서 플러그인을 표시하는 데 쓰는 asset을 포함할 수 있습니다.

my-plugin/
├── .codex-plugin/
│   └── plugin.json        # 필수: 플러그인 manifest
├── skills/
│   └── my-skill/
│       └── SKILL.md       # 선택: skill 지침
├── .app.json              # 선택: 앱 또는 connector 매핑
├── .mcp.json              # 선택: MCP 서버 구성
├── hooks/
│   └── hooks.json         # 선택: 수명주기 구성
└── assets/                # 선택: 아이콘, 로고, 스크린샷

.codex-plugin/에는 plugin.json만 둡니다. skills/, assets/, .mcp.json, .app.json, 수명주기 구성 파일은 플러그인 루트에 둡니다.

게시된 플러그인은 보통 빠른 시작 scaffold에 있는 최소 예시보다 풍부한 manifest를 사용합니다. Manifest의 역할은 세 가지입니다.

플러그인을 식별합니다.
skill, app, MCP 서버 같은 bundled 컴포넌트를 가리킵니다.
설명, 아이콘, 법적 링크 같은 설치 화면 metadata를 제공합니다.

완전한 manifest 예시:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Bundle reusable skills and app integrations.",
  "author": {
    "name": "Your team",
    "email": "team@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/plugins/my-plugin",
  "repository": "https://github.com/example/my-plugin",
  "license": "MIT",
  "keywords": ["research", "crm"],
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "hooks": "./hooks/hooks.json",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "Reusable skills and apps",
    "longDescription": "Distribute skills and app integrations together.",
    "developerName": "Your team",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
    "websiteURL": "https://example.com",
    "privacyPolicyURL": "https://example.com/privacy",
    "termsOfServiceURL": "https://example.com/terms",
    "defaultPrompt": [
      "Use My Plugin to summarize new CRM notes.",
      "Use My Plugin to triage new customer follow-ups."
    ],
    "brandColor": "#10A37F",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "screenshots": ["./assets/screenshot-1.png"]
  }
}

.codex-plugin/plugin.json은 필수 진입점입니다. 다른 manifest 필드는 선택 사항이지만, 게시 플러그인에서는 흔히 사용합니다.

Manifest 필드

최상위 필드는 패키지 metadata를 정의하고 bundled 컴포넌트를 가리키는 데 사용합니다.

name, version, description: 플러그인을 식별합니다.
author, homepage, repository, license, keywords: 게시자와 검색 metadata를 제공합니다.
skills, mcpServers, apps, hooks: 플러그인 루트 기준 bundled 컴포넌트를 가리킵니다.
interface: 설치 표면에서 플러그인을 표시하는 방식을 제어합니다.

interface 객체는 설치 화면 metadata에 사용합니다.

displayName, shortDescription, longDescription: 제목과 설명 문구를 제어합니다.
developerName, category, capabilities: 게시자와 기능 metadata를 추가합니다.
websiteURL, privacyPolicyURL, termsOfServiceURL: 외부 링크를 제공합니다.
defaultPrompt, brandColor, composerIcon, logo, screenshots: 시작 프롬프트와 시각 표시를 제어합니다.

경로 규칙

Manifest 경로는 플러그인 루트 기준 상대 경로로 유지하고 ./로 시작하게 합니다.
composerIcon, logo, screenshots 같은 시각 asset은 가능하면 ./assets/ 아래에 둡니다.
bundled skill 폴더에는 skills, .app.json에는 apps, .mcp.json에는 mcpServers, 수명주기 구성에는 hooks를 사용합니다.
hooks를 생략했는데 플러그인에 ./hooks/hooks.json이 있으면 Codex가 이 기본 수명주기 구성을 자동으로 로드합니다.

Bundled MCP 서버와 수명주기 구성

mcpServers는 직접 서버 map 또는 mcp_servers 객체로 감싼 map을 담은 .mcp.json 파일을 가리킬 수 있습니다.

직접 서버 map:

{
  "docs": {
    "command": "docs-mcp",
    "args": ["--stdio"]
  }
}

감싼 서버 map:

{
  "mcp_servers": {
    "docs": {
      "command": "docs-mcp",
      "args": ["--stdio"]
    }
  }
}

hooks는 하나의 수명주기 JSON 파일, 수명주기 JSON 파일 배열, inline 수명주기 객체, inline 수명주기 객체 배열을 가리킬 수 있습니다. 파일 경로는 다른 manifest 경로와 같은 ./ 접두사 및 플러그인 루트 기준 규칙을 따라야 합니다. Manifest 필드를 생략해도 Codex는 ./hooks/hooks.json을 확인합니다.

$plugin-creator로 플러그인 만들기