Codex CLI의 플러그인 시스템이 빠르게 자리를 잡아가고 있습니다. /plugins 명령어를 통해 이제 마켓플레이스별로 플러그인을 탐색하고, 설치하고, 실행하거나 중단할 수 있게 되었죠. 많은 팀이 내부 도구 체인을 재사용 가능한 Codex 플러그인으로 패키징하고 있습니다. 하지만 공식 마켓플레이스의 셀프 서비스 등록은 현재 '심사제' 단계입니다. 개발자는 매니페스트 구조와 로컬 디버깅 방법을 이해하고, 심사 과정을 거쳐야만 비로소 사용자가 플러그인을 사용할 수 있게 됩니다. 이 글에서는 제로 베이스에서 구축하고, 로컬 테스트를 거쳐 Git 마켓플레이스에 배포하고, 공식 심사를 통과하기까지의 전체 과정을 실무 순서대로 정리하고, 자주 실수하는 부분들을 짚어보겠습니다.
Codex 플러그인은 무엇으로 구성되나요?
Codex 플러그인은 본질적으로 여러 기능을 설치 및 배포 가능한 단위로 패키징한 것입니다. OpenAI 공식 문서에 따르면, 플러그인은 스킬(재사용 가능한 작업 지침), MCP 기반 앱(외부 도구 서비스 연결), 수명 주기 훅, 그리고 선택 사항인 브라우저 확장 프로그램 및 주기적 작업 템플릿을 포함할 수 있습니다. 이러한 구성 요소가 모두 반드시 존재해야 하는 것은 아니며, 스킬만 포함된 가벼운 플러그인도 정상적으로 설치하고 사용할 수 있습니다.
각 구성 요소의 역할 범위를 이해하는 것이 올바른 매니페스트를 작성하는 전제 조건입니다. 아래 표는 Codex 플러그인 디렉터리에 있는 4가지 핵심 구성 요소의 저장 경로와 역할을 정리한 것입니다.
| 구성 요소 | 저장 경로 | 역할 | 필수 여부 |
|---|---|---|---|
| plugin.json | .codex-plugin/plugin.json |
플러그인 식별 및 메타 정보 | 필수 |
| skills | skills/<skill-name>/SKILL.md |
재사용 가능한 작업 지침 정의 | 선택 |
| MCP servers | .mcp.json |
외부 도구 서비스 연결 설정 | 선택 |
| hooks | hooks/hooks.json |
수명 주기 훅 명령어 선언 | 선택 |
참고로, 플러그인이 단순히 팀 내부에서 재사용하는 SKILL.md 파일이라면 복잡한 매니페스트 과정을 거칠 필요가 없습니다. 파일을 .agents/skills/ 디렉터리에 직접 넣으면 Codex가 자동으로 감지하므로 플러그인 목록이 필요 없습니다. 이는 많은 팀이 '내부 스크립트'에서 '정식 플러그인'으로 넘어가는 과정에서 거치는 일반적인 중간 단계입니다.
플러그인의 기능적 범위는 생각보다 훨씬 넓습니다. 가장 흔히 사용되는 스킬과 MCP 기반 앱 외에도, 공식 문서에서는 브라우저 확장 프로그램에 필요한 기능 선언과 재사용 가능한 주기적 작업 템플릿을 포함할 수 있다고 명시합니다. 이는 플러그인이 '사용자가 직접 트리거하는' 대화형 요청뿐만 아니라 '주기적으로 백그라운드에서 실행되는' 자동화 시나리오까지 처리할 수 있음을 의미합니다. 어떤 구성 요소를 하나의 플러그인으로 묶을지 선택하는 것은 설치 경험과 유지보수 비용 사이의 균형을 맞추는 과정입니다. 구성 요소가 많을수록 플러그인 기능은 완벽해지지만, 심사 자료와 테스트 케이스도 함께 늘어납니다. 제출하기 전에 목표 사용자가 정말로 필요로 하는 기능이 무엇인지 먼저 고민하고, 모든 구성 요소를 하나의 패키지에 무작정 넣지 않는 것이 좋습니다.
plugin.json으로 시작하기: 플러그인 매니페스트 파일 상세 가이드
plugin.json은 플러그인의 신분증과 같습니다. Codex가 이 플러그인을 어떻게 인식하고, 로드하며, 표시할지 결정하죠. 최소한으로 필요한 설정은 다음 세 가지 필드뿐입니다.
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "재사용 가능한 인사말 워크플로우",
"skills": "./skills/"
}
name 필드는 변경되지 않는 kebab-case 형식을 사용하는 것이 좋습니다. 나중에 버전을 업데이트하더라도 이 식별자를 바꾸면 안 됩니다. 바꾸게 되면 마켓에서 동일한 플러그인의 업데이트로 인식하지 못하기 때문이죠. version은 시맨틱 버전(Semantic Versioning) 규칙을 따르며, 마켓은 이 필드를 보고 사용자에게 업데이트 알림을 보낼지 결정합니다. 매니페스트에서 참조하는 모든 경로는 반드시 플러그인 루트 디렉토리를 기준으로 하며 ./로 시작해야 하고, 루트 디렉토리 밖으로 나갈 수 없습니다.
세 가지 기본 필드 외에도 skills는 여러 스킬 디렉토리를 배열로 지정할 수 있으며, hooks, mcpServers, apps 필드는 각각 hooks/hooks.json, .mcp.json, .app.json 설정 파일을 가리킵니다. 이렇게 "파일을 가리키는 필드" 구조를 사용하면 매니페스트 자체는 간결하게 유지되고, 구체적인 스킬 설명이나 도구 설정은 별도 파일에서 관리할 수 있어 여러 명이 동시에 작업할 때 충돌을 방지할 수 있습니다.
공식 마켓플레이스에 플러그인을 제출할 계획이라면, 전시용 메타데이터를 추가해야 합니다. 아래 표는 배포 시 작성해야 할 핵심 필드입니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| author / repository | 문자열 | 플러그인 출처, 인증된 신원과 일치 권장 |
| interface.displayName | 문자열 | 마켓 목록에 표시될 플러그인 이름 |
| interface.category | 문자열 | 플러그인 카테고리, 사용자 탐색 경로에 영향 |
| interface.capabilities | 배열 | 플러그인이 가진 기능 태그 선언 |
| mcpServers / apps / hooks | 객체 | 각 컴포넌트의 설정 파일 경로 |
매니페스트 작성 시 가장 흔한 실수는 경로 참조 오류입니다. skills 필드에 절대 경로를 적거나 ./를 빠뜨리는 경우죠. 로컬에서는 잘 작동해도 제출 시 무효한 매니페스트로 판정될 수 있습니다. 제출 전에는 깨끗한 디렉토리에서 플러그인 저장소를 다시 클론하여 실제 설치 환경과 유사하게 전체 테스트를 진행하는 것을 추천합니다.
로컬 스캐폴딩 및 디버깅: 플러그인 바로 실행하기
매니페스트를 처음부터 직접 작성하는 것은 비효율적입니다. 공식적으로 제공하는 $plugin-creator 스킬을 사용하여 Codex CLI에서 대화형으로 스캐폴딩을 생성해 보세요.
codex "$plugin-creator 스캐폴드를 사용하여 infra-monitor라는 플러그인을 생성해줘"
이 명령어를 사용하면 매니페스트, 예제 스킬, 로컬 마켓 항목이 자동으로 생성되어 번거로운 디렉토리 구조 작업을 생략할 수 있습니다. 생성 후에는 원격 저장소에 배포할 필요 없이 바로 로컬 환경에서 설치 및 테스트가 가능합니다.
로컬 디버깅 단계에서 플러그인 내 스킬이 여러 대규모 언어 모델을 호출하여 비교 테스트를 수행해야 한다면, 통합 API 게이트웨이를 사용해 환경 설정 전환 비용을 크게 줄일 수 있습니다. MCP 서버 기능을 검증할 때 보통 base_url을 APIYI(apiyi.com)에서 제공하는 API 중계 서비스로 설정합니다. 하나의 API 키로 여러 모델을 호출할 수 있어, 동일한 플러그인 로직에서 각 모델의 성능 차이를 쉽게 비교할 수 있습니다.
from openai import OpenAI
client = OpenAI(
api_key="your-apiyi-key", # APIYI 키 입력
base_url="https://api.apiyi.com/v1"
)
🎯 디버깅 팁: Codex 플러그인 개발 중에는 다양한 모델에서 MCP 서버의 응답 품질을 반복적으로 테스트해야 합니다. APIYI(apiyi.com) 플랫폼을 통해 여러 모델 호출을 통합 관리하면 각 모델마다 키를 발급받거나 호출 로직을 유지보수할 필요가 없어, 플러그인 자체 기능 완성에 더 집중할 수 있습니다.
수동으로 로컬 마켓 항목을 만드는 것 외에도 ~/.agents/plugins/marketplace.json(개인용) 또는 저장소 루트의 .agents/plugins/marketplace.json(팀용)에 로컬 플러그인 경로를 선언할 수 있습니다. source 필드를 local로 설정하면 로컬 디렉토리를 가리키게 되어, 원격 푸시 없이도 설치 검증을 완료할 수 있습니다.
만약 플러그인에 ChatGPT 개발자 모드와 연동해야 하는 MCP 기반 앱이 포함되어 있다면, 공식적으로 제공하는 또 다른 경로가 있습니다. ChatGPT 설정에서 개발자 모드를 켜고 MCP 기반 앱을 생성하여 앱 ID를 받은 뒤, $plugin-creator를 통해 해당 ID를 연결하세요. 그러면 실제 대화 환경에서 플러그인과 앱 간의 데이터 흐름을 검증할 수 있습니다. 이 단계는 순수 로컬 CLI 디버깅보다 실제 배포 후 환경과 훨씬 비슷하므로, 제출 전 최소 한 번은 전체 과정을 거쳐보는 것을 권장합니다.
Git 마켓플레이스 등록 및 팀 내 배포
플러그인이 로컬에서 정상적으로 검증되었다면, 팀 내 배포를 위해 굳이 공식 심사를 기다릴 필요는 없습니다. Git 저장소를 활용해 마켓플레이스 소스를 구성하는 것만으로 충분하거든요. Codex CLI는 이를 위한 전용 마켓플레이스 관리 명령어를 제공합니다.
| 명령어 | 용도 |
|---|---|
codex plugin marketplace add owner/repo |
GitHub 저장소를 마켓플레이스 소스로 추가 |
codex plugin marketplace add owner/repo --ref v2.1.0 |
특정 브랜치나 태그를 고정하여 단계적 배포 제어 |
codex plugin marketplace list |
추가된 마켓플레이스 목록 확인 |
codex plugin marketplace upgrade |
마켓플레이스 업데이트 가져오기 |
codex plugin marketplace remove |
마켓플레이스 소스 제거 |
저장소 규모가 큰 팀이라면 --sparse .agents/plugins 옵션을 사용해 보세요. 전체 저장소를 복제하지 않고 플러그인 관련 디렉터리만 가져올 수 있어 설치 속도가 훨씬 빨라집니다. 이런 Git 마켓플레이스 방식은 기업 내부 툴체인에 아주 적합합니다. 공개 심사 과정을 거칠 필요 없이, 새로운 태그를 푸시하고 팀원들이 upgrade 명령어만 한 번 실행하면 바로 동기화되니까요.
실무적인 관점에서 Git 마켓플레이스 방식에는 숨겨진 장점이 하나 더 있습니다. 바로 플러그인의 업데이트 주기와 팀 내부의 배포 주기를 분리할 수 있다는 점이죠. 비즈니스 코드는 하루에도 여러 번 병합될 수 있지만, 대화형 툴체인의 일부인 플러그인은 업데이트가 너무 잦으면 사용자의 인지 모델을 방해할 수 있습니다. 플러그인 버전과 태그를 고정된 배포 주기(예: 1~2주 단위)에 맞춰 관리하는 것을 추천합니다. 이렇게 하면 기능 개선 속도는 유지하면서도 팀원들이 새로운 상호작용 방식에 자주 적응해야 하는 번거로움을 줄일 수 있습니다.
공식 Marketplace 제출 및 심사 전체 프로세스
공식 Marketplace의 셀프 등록 기능은 아직 완전히 개방되지 않았습니다. OpenAI 문서에는 해당 기능이 "곧 출시 예정"이라고 명시되어 있으며, 현재 일반 사용자를 위한 공식 제출은 플러그인 제출 포털을 통한 수동 심사 프로세스를 거쳐야 합니다. 제출 전에는 신원 확인이 필수입니다. 개인 개발자는 '개인 인증(individual verification)'을, 기업 명의로 배포하려면 '기업 인증(business verification)'을 완료해야 하며, 심사 담당자가 제출한 서류와 실제 배포 주체가 일치하는지 확인합니다.
공식 제출을 위해 준비해야 할 자료 목록은 다음과 같습니다.
| 자료 분류 | 구체적인 요구사항 |
|---|---|
| 플러그인 기본 정보 | 이름, 설명, 로고, 카테고리, 관련 URL |
| MCP 서버 | 공용 도메인, CSP 정책, 인증 설정 |
| 데모 계정 | MFA나 이메일 2차 인증 없이 바로 로그인 가능해야 함 |
| 테스트 케이스 | 성공 시나리오 5개 + 실패 시나리오 3개 |
| 도구 주석 | readOnlyHint, openWorldHint, destructiveHint가 실제 동작과 일치해야 함 |
제출 과정은 Info(공개 목록 정보), MCP(서버 및 인증 설정), Skills(최종 스킬 패키지 업로드), Prompts(시작 프롬프트 예시), Testing(테스트 케이스), Global(사용 가능 국가 및 지역) 등 여러 섹션으로 나뉘며, 마지막으로 Submit 섹션에서 배포 관련 설명을 작성하고 정책 동의를 완료하면 됩니다. 심사가 통과되면 개발자가 포털에서 직접 배포 시점을 선택할 수 있으며, 이후 플러그인은 ChatGPT와 Codex의 통합 플러그인 디렉터리에 나타나게 됩니다.
플러그인에 MCP 기반 앱이 포함되어 있다면 도메인 소유권 인증을 추가로 진행해야 합니다. MCP 서버가 배포된 도메인과 플러그인에서 선언한 도메인이 일치하는지 확인하기 위해서죠. 심사 팀은 도구의 결과값에 불필요한 개인정보나 API 키 정보가 포함되어 있는지 집중적으로 검사합니다. 이 부분은 심사에서 반려된 후 수정하기보다, 도구 출력 형식을 설계할 때 미리 방지하는 것이 좋습니다.
버전 관리 및 흔히 겪는 문제들
플러그인을 출시한 후, 버전 관리의 세부 사항은 사용자의 업데이트 경험에 직접적인 영향을 미칩니다. 마켓플레이스는 version 필드를 통해 업데이트 여부를 판단하므로, 시맨틱 버전 관리(Semantic Versioning) 규칙을 엄격히 준수하는 것이 중요합니다. 버그 수정은 패치 버전, 새로운 기능 추가는 마이너 버전, 그리고 하위 호환성이 깨지는 변경 사항은 메이저 버전을 올리는 식이죠.
설치된 플러그인은 로컬 경로인 ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/에 캐시됩니다. "플러그인을 업데이트했는데 동작이 그대로예요"와 같은 문제를 해결할 때는 코드 로직을 다시 디버깅하기 전에 캐시가 새 버전으로 갱신되었는지 확인하는 것이 문제의 원인을 훨씬 빠르게 파악하는 방법입니다. 기업 환경에서는 requirements.toml에 의한 강제 화이트리스트 정책을 마주할 수 있습니다. MCP 서버는 이름과 신원이 모두 일치해야 하며, 하나라도 다르면 서비스가 별도의 오류 메시지 없이 조용히 비활성화됩니다. 이런 문제는 운영 환경에 배포하기 전 테스트 환경에서 정책 구성을 먼저 검증해 보시길 권장합니다.
다음 표는 개발자들이 자주 겪는 문제와 대응 방안을 정리한 것입니다.
| 흔한 문제 | 대응 방안 |
|---|---|
| manifest 경로를 절대 경로로 작성 | ./로 시작하는 상대 경로로 통일 |
| 암시적 호출로 의도치 않은 플러그인 실행 | @plugin-name을 사용하여 플러그인 명시 |
| 업데이트 후 동작 미반영 | 로컬 플러그인 캐시 디렉토리가 갱신되었는지 확인 |
| 기업 정책 하에서 MCP가 조용히 비활성화됨 | requirements.toml의 이름과 신원 일치 여부 확인 |
공식 심사를 제출하기 전에 서드파티 도구인 codex-plugin-scanner를 한 번 실행해 보는 것을 추천합니다. 이 도구는 설치 가능성, 유지보수 상태, MCP 보안성, 배포 출처 등의 차원에서 플러그인 점수를 매겨줍니다. 특히 기업 고객에게 배포할 플러그인이라면, 심사에서 반려당하는 것보다 미리 문제를 발견하는 것이 시간을 훨씬 아끼는 길입니다.
또 하나 간과하기 쉬운 디테일은 명시적 호출과 암시적 발견의 차이입니다. Codex는 플러그인을 명시하지 않으면 문맥에 따라 가장 관련성 높은 기술을 자동으로 매칭합니다. 만약 동일한 작업 공간에 기능이 비슷한 플러그인이 여러 개 설치되어 있다면, 암시적 매칭이 의도하지 않은 플러그인을 선택할 수 있습니다. 특히 팀이 공유하는 작업 공간에서는 @plugin-name을 사용하여 명시적으로 선언하는 습관을 들이면, 이른바 "플러그인 간 충돌" 문제를 해결하는 비용을 줄일 수 있습니다.
Codex 플러그인 개발 FAQ
플러그인과 개별 SKILL.md 파일은 어떤 차이가 있나요?
SKILL.md는 플러그인의 구성 요소 중 하나입니다. 단독으로 사용할 때는 manifest가 필요 없으며, .agents/skills/ 디렉토리에 넣기만 하면 자동으로 발견됩니다. 반면 플러그인은 skills, MCP 서버, 훅(hooks) 등 여러 구성 요소를 신원 식별이 가능하고 버전 관리가 용이한 하나의 단위로 묶은 것이라, 공식적인 배포와 업데이트 추적이 필요한 경우에 적합합니다.
개발 단계에서 여러 모델 계정을 비교 테스트하려면 어떻게 해야 하나요?
이는 모델 선택이나 프롬프트 튜닝이 포함된 플러그인 개발 시 자주 겪는 현실적인 문제입니다. 모델 제조사마다 일일이 계정을 만들고 API 키를 관리하는 대신, APIYI(apiyi.com)와 같은 통합 게이트웨이를 사용해 보세요. 하나의 키로 주요 모델들을 호출하여 A/B 테스트를 수행할 수 있어, 계정 관리보다는 플러그인 로직 자체에 디버깅 역량을 집중할 수 있습니다.
Git 마켓 배포와 공식 Marketplace 등록을 병행할 수 있나요?
네, 가능합니다. 많은 팀이 먼저 Git 마켓을 통해 내부 검증과 소규모 배포를 진행한 뒤, 안정성이 확인되면 공식 제출 절차를 밟습니다. 두 배포 방식은 서로 충돌하지 않으며, manifest 구조도 동일하게 사용됩니다.
플러그인 심사는 보통 얼마나 걸리나요?
공식 문서에는 고정된 기한이 명시되어 있지 않으며, 현재 심사 프로세스가 지속적으로 구축 및 확장 중이라는 점만 안내되어 있습니다. 또한 긴급 처리도 지원하지 않습니다. 심사 기간을 프로젝트 일정의 불확실한 변수로 고려하고, 제출 전 자료를 한 번에 완벽하게 준비하여 보완 요청으로 인한 왕복 시간을 줄이는 것이 가장 실질적인 출시 단축 방법입니다.
마무리하며
Codex 플러그인 개발의 핵심적인 어려움은 사실 코드 자체보다는 manifest 규격 요구사항을 이해하고 심사 절차를 위한 자료를 준비하는 데 있습니다. 이러한 세부 사항들은 생각보다 복잡하지 않지만, 경로 표기 방식이나 필드 누락 하나 때문에 반려되어 처음부터 다시 작업해야 하는 경우가 많습니다. '로컬 스캐폴드 검증 → Git 마켓 소규모 배포 → 공식 심사 제출' 순서로 진행하시길 권장하며, 각 단계마다 실제 환경에서의 테스트 시간을 충분히 확보하세요. 만약 개발 중인 플러그인이 여러 모델 호출을 포함하거나 테스트 모델을 자주 변경해야 한다면, APIYI(apiyi.com)에서 제공하는 통합 API 중계 서비스를 활용해 보세요. 환경 구축 시간을 크게 단축하여 플러그인 자체의 완성도를 높이는 데 더 집중할 수 있을 것입니다.
