Codex CLI 0.146 에이전트 플러그인 (Agent Plugins): 매니페스트를 마이그레이션하고 안전하게 게시하세요

빠른 답변

OpenAI는 2026년 7월 29일에 Codex CLI 0.146.0을 출시했습니다. 이번 릴리스에는 에이전트 플러그인 (Agent Plugins) 매니페스트 지원이 추가되었고, 워크스페이스 플러그인 게시 기능이 공개되었으며, 마켓플레이스 (marketplace) 호환성이 확장되었습니다. 안전한 배포(rollout)는 단순히 "업그레이드 후 게시"하는 것이 아닙니다:

1. 워크플로우를 하나의 스킬 (skill)로 유지할지, 아니면 설치 가능한 플러그인 (plugin)으로 만들지 결정합니다.
2. 하나의 매니페스트 권한 (manifest authority)을 선택하고, Codex 전용 오버레이 (overlay)가 있다면 문서화합니다.
3. 새로운 Codex 세션에서 로컬 마켓플레이스 (local marketplace)를 통해 패키지를 테스트합니다.
4. 서버가 해당 기능을 명시적으로 보고할 때만 워크스페이스 (workspace)에 게시합니다.
5. 설치, 스킬 발견 (skill discovery), MCP 인증 (authentication), 훅 (hooks), 커넥터 액션 (connector actions), 샌드박스 정책 (sandbox policy), 그리고 롤백 (rollback)을 각각 별도로 검증합니다.

가장 중요한 경계는 패키지 가용성이 커넥터 액세스 (connector access)나 런타임 권한 (runtime permission)을 부여하지 않는다는 점입니다. 플러그인의 MCP 서버, 외부 ID, 쓰기 액션 또는 로컬 명령이 여전히 사용할 수 없는 상태더라도 플러그인은 올바르게 설치될 수 있으며, 이러한 분리는 안전을 위한 기능입니다.

대상 사용자

이 가이드는 Codex 스킬, MCP 서버, 또는 개인 폴더에서 반복 가능한 패키지로 이동해야 하는 팀 워크플로우를 유지 관리하는 개발자를 위한 것입니다. 특히 동일한 기능이 모든 사용자에게 동일한 외부 권한을 부여하지 않으면서도 Codex 및 ChatGPT 지원 환경 전체에서 작동해야 할 때 유용합니다.

하나의 집중된 워크플로우가 이미 스킬 (skill)로서 작동하고 있다면, 설치, 공유 또는 서버 기반 도구로 인해 실제 패키징 요구 사항이 발생할 때까지는 그대로 유지하십시오. AI 코딩 샌드박스 체크리스트는 여전히 권위 있는 기준입니다: 배포한다고 해서 워크플로우가 읽기, 실행 또는 게시할 수 있는 권한이 확장되지는 않습니다.

Codex CLI 0.146에서 변경된 사항

공식 변경 로그(changelog)는 0.146.0 버전에서 여러 플러그인 변경 사항을 그룹화하여 설명합니다. 이제 Codex는 Agent Plugins 1.0 스키마(schema)를 사용하는 루트 plugin.json을 인식할 수 있으며, 휴대 가능한 메타데이터(portable metadata)와 skills/ 및 mcp.json을 매핑할 수 있습니다. 또한 com.openai 확장을 통해 Codex 전용 앱(apps), 훅(hooks) 및 인터페이스 설정을 적용할 수 있습니다. 레거시(legacy) 방식인 .codex-plugin/plugin.json은 폴백 오버레이(fallback overlay) 역할을 수행할 수 있습니다.

구현 단계에서는 지원되지 않는 Agent Plugins 스키마 버전을 의도적으로 거부합니다. 또한 휴대 가능한 스킬(skill) 탐색을 직계 자식 폴더로 제한하며, 플러그인 루트 외부로 해결되는 경로는 제외합니다. 이러한 규칙은 경로 레이아웃과 스키마 버전을 단순한 미적 관례가 아닌 릴리스 게이트(release gates)로 만듭니다.

워크스페이스 게시(Workspace publishing)는 별도의 권한 게이트(capability-gated)로 관리됩니다. 앱 서버(app-server)는 null 허용 가능한 canPublishToWorkspace 메타데이터를 반환할 수 있으며, 클라이언트는 해당 권한이 없거나 사용할 수 없는 경우 '실패 시 차단(fail closed)' 방식으로 동작해야 합니다. 보이는 워크스페이스 이름, 성공적인 개인 설치, 또는 관리자 역할로부터 권한을 추론하지 마십시오.

가장 작은 패키지 형태를 선택하세요

스킬 전용 플러그인의 경우, OpenAI의 빌더 문서(builder documentation)는 .codex-plugin/plugin.json과 직계 자식 스킬 폴더를 포함하는 최소한의 패키지를 보여줍니다:

release-review/
├── .codex-plugin/
│   └── plugin.json
...

Codex 0.146.0은 휴대 가능한 루트 Agent Plugins 매니페스트(manifest)도 이해합니다. 두 개의 독립적인 신뢰할 수 있는 원천(sources of truth)을 생성하지 마십시오. 어떤 매니페스트가 권위(authoritative)를 갖는지, 어떤 필드가 휴대 가능한지, 그리고 어떤 Codex 전용 동작이 com.openai 또는 폴백 오버레이에서 오는지 기록하십시오.

마이그레이션 워크플로우 (Migration workflow)

1. 권한 및 권위 인벤토리 조사 (Inventory capability and authority)

모든 스킬 (skill), 스크립트 (script), MCP 도구 (tool), 커넥터 (connector), 훅 (hook), UI 리소스 (UI resource), 예약된 템플릿 (scheduled template), 그리고 외부 쓰기 작업 (external write action)을 나열하십시오. 각 항목에 대해 입력 (input), 출력 (output), 인증 신원 (authentication identity), 파일 시스템 또는 네트워크 도달 범위 (filesystem or network reach), 그리고 롤백 방법 (rollback method)을 기록하십시오.

2. 패키지 경계 정규화 (Normalize the package boundary)

스킬을 구성된 스킬 디렉토리의 직접적인 자식으로 유지하십시오. 중첩된 탐색 (nested discovery), 심볼릭 링크 탈출 (symlink escapes), 선언되지 않은 실행 파일 (undeclared executables), 비밀 정보 (secrets), 생성된 빌드 출력물 (generated build output), 그리고 플러그인 루트 외부의 경로를 거부하십시오. 패키지를 복사하거나 게시하기 전에 스키마 버전 (schema version)을 검증하십시오.

3. 이식 가능한 동작과 Codex 전용 동작의 분리 (Separate portable and Codex-only behavior)

이식 가능한 메타데이터 (metadata), 스킬, 그리고 MCP 설정은 에이전트 플러그인 (Agent Plugins) 패키지에 속합니다. Codex만이 이해할 수 있는 앱 (apps), 훅 (hooks), 또는 인터페이스 설정은 명시적인 Codex 경계가 필요합니다. 검토자는 Codex 확장 기능을 제거했을 때 무엇이 남을지 예측할 수 있어야 합니다.

4. 로컬 마켓플레이스를 통한 테스트 (Test through a local marketplace)

로컬 마켓플레이스 (local marketplace)에서 패키지를 설치하고, 세부 정보를 검사하며, 활성화한 후 새로운 Codex 세션을 시작하십시오. 설치된 스킬과 도구는 새로운 세션을 위해 로드됩니다. 이미 실행 중인 세션은 신뢰할 수 있는 수락 증거가 아닙니다.

하나의 긍정 사례 (positive case), 하나의 인증 누락 사례 (missing-auth case), 하나의 작업 거부 사례 (denied-action case), 그리고 하나의 삭제/재설치 사례 (uninstall/reinstall case)를 실행하십시오. 플러그인이 MCP를 사용하는 경우, 단순히 성공적인 연결 화면을 수락하기보다는 도구 스키마 (tool schemas)와 외부 서비스 신원 (external service identity)을 모두 확인하십시오.

5. 워크스페이스 게시 게이트키핑 (Gate workspace publication)

canPublishToWorkspace가 명시적으로 사용 가능한 경우에만 워크스페이스 게시를 표시하거나 사용하십시오. null, 누락된 메타데이터, API 오류, 또는 오래된 카탈로그 (stale catalogs)는 "허용되지 않음"으로 취급하십시오. 권한이나 정책이 해결되지 않은 동안에는 개인 마켓플레이스 (personal marketplace)를 안전한 대체 수단으로 유지하십시오.

6. 권한 체인 재확인 (Recheck the permission chain)

워크스페이스 플러그인 가용성, 번들링된 스킬, 커넥터 액세스 (connector access), 커넥터 작업 (connector actions), 소스 시스템 권한 부여 (source-system authorization), 그리고 런타임 샌드박스 정책 (runtime sandbox policy)은 서로 별개의 제어 항목입니다. 읽기 작업 (read actions)부터 시작하십시오. 범위 (scopes), 확인 동작 (confirmation behavior), 외부 영향 (external effects), 그리고 복구 (recovery)를 검토한 후에만 쓰기 (writes)를 추가하십시오.

8가지 롤아웃 게이트 (Eight rollout gates)

Qwen Code Goal verification checklist와 동일한 방식으로 릴리스 주장(release claims)을 증거와 결합하십시오. “플러그인이 카탈로그에 나타났다”는 것은 발견(discovery)을 증명할 뿐, 해당 플러그인의 워크플로 (workflow), 권한 (permissions), 또는 롤백 (rollback) 기능이 작동함을 증명하는 것은 아닙니다.

복사 가능한 롤아웃 기록 (Copyable rollout record)

plugin_rollout:
  codex_version: "0.146.0"
  purpose: "one bounded workflow"
...

이것은 운영 기록 (operating record)이며, OpenAI 매니페스트 스키마 (manifest schema)가 아닙니다.

흔한 실수 (Common mistakes)

모든 기술 (skill)을 플러그인으로 만드는 것. 패키징 (Packaging)은 설치, 버전 관리 (versioning), 권한 (permissions), 그리고 지원 (support) 작업을 추가합니다. 개인적인 워크플로 (workflow)는 공유가 필요하거나 도구 (tools)가 번들링을 정당화할 때까지 기술 (skill) 상태로 유지하십시오.

두 개의 상충하는 매니페스트 (manifests)를 유지하는 것. 휴대 가능한 매니페스트 (portable manifest)와 Codex 오버레이 (overlay)는 명시적인 우선순위 (precedence)가 필요합니다. 서로 어긋나는 중복 필드는 모호한 릴리스를 생성합니다.

설치에 사용된 세션에서 테스트하는 것. 기술 (skill) 또는 도구 (tool)의 가용성을 확인하기 전에 새로운 세션을 시작하십시오.

워크스페이스 가시성 (workspace visibility)을 게시 권한 (publish permission)과 동일하게 취급하는 것. 워크스페이스 게시 (Workspace publishing)는 해당 기능이 명시적으로 보고되지 않는 한 실패하도록 처리되어야 합니다 (fail closed).

설치를 권한 부여 (authorization)와 동일시하는 것. 커넥터 로그인 (Connector login), 소스 시스템 액세스 (source-system access), 액션 권한 (action permissions), 그리고 Codex 샌드박스 (sandbox)는 여전히 독립적으로 적용됩니다.

부작용 (side effects)을 검토하지 않고 훅 (hooks)을 배포하는 것. 훅 (Hooks)은 라이프사이클 이벤트 (lifecycle events) 전후에 실행될 수 있습니다. 엄격한 송신 허용 목록 (strict egress allowlist)에 사용되는 것과 동일한 명령, 네트워크, 그리고 비밀 정보 (secret) 검토를 적용하십시오.

FAQ

Codex CLI 0.146은 기존의 모든 플러그인을 마이그레이션(migrating)해야 합니까?

아니요. 이번 릴리스는 레거시 (legacy) .codex-plugin/plugin.json 경로를 폴백 오버레이 (fallback overlay)로 보존합니다. 휴대 가능한 에이전트 플러그인 (Agent Plugins) 호환성이 구체적인 공유 이점을 제공할 때 마이그레이션하고, 전환하기 전에 우선순위 (precedence)를 검증하십시오.

하나의 플러그인이 ChatGPT와 Codex 모두에서 작동할 수 있나요?

OpenAI는 지원되는 인터페이스 (surfaces)를 위해 하나의 범용 공개 플러그인 디렉토리를 문서화하고 있습니다. 개별 기능은 여전히 인터페이스별로 특화될 수 있으며, 모든 ChatGPT 또는 Codex 인터페이스에서 플러그인을 사용할 수 있는 것은 아닙니다.

설치된 플러그인이 외부 서비스에 자동으로 기록할 수 있나요?

단순히 설치되었다는 이유만으로는 불가능합니다. 커넥터 액세스 (Connector access), 액션 제어 (action controls), 소스 시스템 권한 부여 (source-system authorization), 그리고 런타임 승인 정책 (runtime approval policy)은 별개로 유지됩니다.

출처

• Codex changelog: CLI 0.146.0
• Codex PR #35105: Agent Plugins manifests
• Codex PR #35254: workspace publishing capability
• OpenAI plugin architecture
• OpenAI plugin packaging guide
• Using plugins in ChatGPT and Codex
• OpenAI workspace plugin controls