Codex CLI 플러그인 확인 방법: codex plugin list로 설치 전 목록 처음 읽는 법
TL;DR
Codex 플러그인은 Skills나 Connectors 같은 기능을 묶은 재사용 가능한 패키지입니다. 설치부터 시작하지 말고 운영체제 셸에서
codex plugin list --json
으로 현재 설정이 보여 주는
installed
와
available
배열을 먼저 확인하세요. 빈 배열도 현재 환경의 정상 결과일 수 있습니다.
목록 조회는 설치나 권한 승인이 아닙니다. 플러그인을 실제로 설치한 뒤에는 새 Codex 세션에서 기능을 확인해야 합니다.
핵심 3줄 요약
핵심 1
codex plugin --help
로 명령이 설치본에 있는지 확인한 뒤
codex plugin list --json
을 실행합니다.
핵심 2
installed
는 설치된 항목,
available
은 현재 구성에서 발견 가능한 후보입니다. 빈 배열을 오류나 전체 플러그인 부재로 단정하지 않습니다.
핵심 3
설치·활성화·새 세션 적용·외부 서비스 인증은 서로 다른 단계입니다. 첫 점검은 목록과 필드 확인에서 끝냅니다.
이 글에서 다룰 내용
- Codex 플러그인의 뜻과 지원 표면
- 설치 전에 목록부터 읽어야 하는 이유
-
installed와available배열을 확인하는 5단계 - 설치, 활성화, 새 세션, 외부 서비스 권한의 경계
왜 설치보다 목록 확인이 먼저일까
플러그인 이름만 보고 곧바로 설치하면 현재 Codex가 어떤 marketplace를 보는지 놓치기 쉽습니다. 같은 항목이 이미 설치됐는지 확인하기 어렵습니다. 외부 서비스 연결이 필요한지도 놓칠 수 있습니다.
첫 행동을 목록 조회로 한정하면 로컬 설정을 바꾸지 않고 현재 상태를 기록할 수 있습니다.
목록에 항목이 보이는 것만으로 사용 준비가 끝난 것은 아닙니다. 반대로 배열이 비었다고 플러그인 기능이 없는 것도 아닙니다.
codex plugin list
결과는 현재 계정과 설정된 marketplace snapshot의 범위를 반영합니다.
Codex 플러그인이란
OpenAI 공식 문서에서 플러그인은 ChatGPT와 Codex의 기능을 재사용 가능한 workflow로 묶은 패키지입니다. 하나의 플러그인에는 Skills와 Connectors 중 하나 또는 둘 다 들어갈 수 있습니다. MCP server·browser extension·hook·scheduled task template이 포함될 수도 있습니다.
Codex CLI에는 Codex 환경용 plugin browser가 있습니다. 공식 문서는 IDE extension은 플러그인을 지원하지 않는다고 구분합니다. 따라서 이 글의 명령을 IDE 확장 기능의 설정 경로로 일반화하면 안 됩니다.
언제 이 확인 흐름이 맞을까
새 플러그인을 설치하기 전에 현재 상태를 기록하거나 여러 환경의 구성을 비교할 때 맞습니다. 문제 해결에 들어가기 전
installed
와
available
의 실제 값을 남기는 용도로도 쓸 수 있습니다.
이 흐름은 플러그인을 설치하거나 제거하지 않습니다. marketplace 추가·플러그인 설치·외부 서비스 로그인·hook 신뢰·운영 저장소 실행은 각각 별도 검토와 승인이 필요한 다음 단계입니다.
시작 전에 준비할 것
비민감 빈 폴더나 공개 예제 폴더에서 운영체제 셸을 엽니다. 고객 저장소·운영 자격증명·내부 자료가 있는 폴더는 첫 목록 점검에 필요하지 않습니다.
현재 설치본을 기록합니다. 이 글의 확인 환경은
codex-cli 0.144.6
입니다. 공식 문서에 모든 계정에 공통인 최소 버전 조건은 적혀 있지 않으므로 현재 설치본의 도움말과 결과를 우선합니다.
1단계: plugin 하위 명령을 확인합니다
운영체제 셸에서
codex plugin --help
를 실행합니다. 현재 설치본에서는
add
·
list
·
marketplace
·
remove
가 표시됐습니다.
list
가 보이지 않으면 기억에 의존해 다음 명령을 실행하지 말고 현재 도움말과 공식 문서를 다시 대조합니다.
codex plugin list --help
에서는
--json
·
--available
·
--marketplace
옵션을 확인할 수 있습니다. 첫 점검은 변경 작업이 없는
list
만 사용합니다.
2단계: JSON 목록을 읽기 전용으로 가져옵니다
다음 명령을 실행합니다.
codex plugin list --json
현재
codex-cli 0.144.6
확인에서는
installed
와
available
이 모두 빈 배열로 반환됐고 종료 코드는 0이었습니다. 실행 전후
~/.codex/config.toml
의 크기·수정 시각·SHA-256이 같았습니다. 이는 이번 확인에서 목록 명령이 설정을 바꾸지 않았다는 로컬 증거입니다.
이 관찰을 모든 환경의 결과로 일반화하지 마세요. 계정·marketplace 설정·조직 정책에 따라 배열 내용은 달라질 수 있습니다.
3단계: installed와 available을 구분합니다
installed
배열은 현재 설치된 플러그인 항목을 담습니다.
available
배열은 현재 명령이 보여 주는 설치 가능 후보를 담습니다. 설치되지 않은 marketplace 항목까지 JSON에 포함하려면 공식 help에 나온
--available
옵션을 별도로 검토할 수 있습니다.
항목이 있으면 실제로 반환된 필드를 기록합니다. 확인할 값은
pluginId
·
name
·
marketplaceName
·
version
·
installed
·
enabled
·
source
·
installPolicy
·
authPolicy
입니다. 모든 항목에 모든 필드가 있다고 가정하지 마세요.
보이지 않는 값은
확인 필요
로 남깁니다.
4단계: marketplace 범위를 따로 확인합니다
목록이 비어 있으면 오류라고 결론 내리기 전에 현재 Codex가 고려하는 marketplace 범위를 확인합니다. 이때도 변경 명령이 아닌
codex plugin marketplace list --json
만 사용합니다.
이번 확인 환경에서는
marketplaces
가 빈 배열이었습니다.
available
이 비어 있는 결과와 함께 읽을 수 있습니다. 다만 네트워크 장애나 계정 전체의 플러그인 부재를 증명하지는 않습니다.
명령이 반환한 범위만 기록합니다.
5단계: 설치와 권한 검토를 다음 승인으로 넘깁니다
공식 문서는
codex plugin add
와 plugin browser의 설치 기능을 별도 동작으로 설명합니다. 플러그인을 설치한 뒤 bundled Skills나 tools를 쓰려면 새 chat 또는 CLI session을 시작해야 합니다.
플러그인이 외부 서비스 Connector나 MCP server를 포함하면 추가 설정이나 인증이 필요할 수 있습니다. Codex host에서 실행되는 동작에는 sandbox와 approval policy가 적용됩니다. 외부 서비스 연결에는 해당 서비스의 인증과 접근 통제가 따로 적용됩니다.
목록에 보인다는 사실은 이 권한을 승인했다는 뜻이 아닙니다.
복사해서 쓰는 점검 프롬프트
목표: Codex plugin 목록에서 설치 상태와 다음 검토 항목을 분리합니다.
허용 입력: codex --version, codex plugin --help, codex plugin list --json의 비민감 출력만 사용합니다.
제외 입력: API key, OAuth token, 고객 데이터, 내부 저장소 내용, 현재 폴더 밖 파일은 사용하지 않습니다.
출력 형식: installed와 available을 나누고, 각 항목의 실제 필드, 누락 필드, 확인 필요 항목, 다음 승인 작업을 표로 정리합니다.
완료 기준: 출력의 모든 값이 제공된 JSON 위치와 대조되고, 빈 배열도 그대로 기록되어야 합니다.
추정 금지: 보이지 않은 플러그인, 버전, publisher, 권한, 호환성, 설치 성공을 만들지 않습니다.
승인 지점: 사람이 공식 설명과 권한 범위를 확인하기 전에는 add, remove, marketplace 변경, 로그인, 외부 전송을 실행하지 않습니다.
실전 인사이트: 빈 배열도 기준점이 됩니다
첫 점검의 성공 기준은 플러그인을 하나 찾는 것이 아닙니다. 설치본이
plugin list
를 인식하는지 확인하세요. 어떤 JSON 배열을 반환하는지 기록하세요.
조회 전후 설정이 그대로인지도 확인하면 충분합니다.
이 기준점이 있으면 marketplace를 추가하거나 플러그인을 설치한 뒤 무엇이 달라졌는지 비교할 수 있습니다. 변경 전 상태가 없으면 새 항목·활성화 상태·권한 요청의 원인을 한꺼번에 추적하기 어렵습니다.
주의할 점
-
codex plugin list는 운영체제 셸에서 실행합니다./plugins는 Codex TUI 입력창에서 여는 별도 plugin browser입니다. -
--available은 설치되지 않은 marketplace 후보를 JSON에 포함하는 옵션입니다. 설치 명령이 아닙니다. - 빈
installed나available배열을 오류, 네트워크 정상, 전체 플러그인 부재로 단정하지 않습니다. - 플러그인 설치 후 bundled Skills나 tools를 사용하려면 공식 문서에 따라 새 session을 시작합니다.
- 외부 서비스 연결은 별도 인증과 접근 통제를 사용합니다. plugin 목록 조회나 설치가 권한 검토를 대신하지 않습니다.
- hook이 포함된 플러그인은 활성화 전에 동작과 신뢰 범위를 따로 검토합니다.
자주 묻는 질문
codex plugin list --json
결과가 비어 있으면 실패인가요?
아닙니다. 종료 코드와 JSON 구조를 먼저 확인합니다. 빈 배열은 현재 계정과 설정된 marketplace 범위에서 관찰된 결과일 수 있습니다.
플러그인이 세상에 없거나 네트워크가 정상이라는 뜻으로 넓히지 않습니다.
available
에 보이면 바로 사용할 수 있나요?
아닙니다.
available
은 발견 가능한 후보입니다. 설치, 활성화, 새 session, Connector나 MCP server의 추가 설정과 인증은 별도 단계입니다.
/plugins
와
codex plugin list
는 같은 명령인가요?
아닙니다.
/plugins
는 Codex TUI에서 plugin browser를 여는 slash action입니다.
codex plugin list
는 운영체제 셸에서 목록을 출력합니다.
이 글은 설치 없이 읽기 전용 결과를 남기는 shell command를 다룹니다.
플러그인을 설치하면 외부 서비스 권한도 자동으로 승인되나요?
그렇게 볼 수 없습니다. 공식 문서는 외부 서비스 연결이 해당 서비스의 인증과 접근 통제를 사용한다고 설명합니다. 설치와 실제 연결 권한을 나눠 확인하세요.
출처
- OpenAI Plugins 공식 문서 — 플러그인 구성, Codex CLI plugin browser, IDE extension 제외, 새 session, sandbox·외부 서비스 권한 경계를 확인했습니다.
- OpenAI Developer Commands 공식 문서 —
codex plugin,plugin list --json,installed·available배열과 반환 필드를 확인했습니다.
마무리
Codex 플러그인은 설치본 도움말 확인 →
codex plugin list --json
실행 →
installed
·
available
분리 → marketplace 범위 확인 → 설치와 권한 검토를 다음 승인으로 넘기기 순서로 시작합니다. 첫 실행에서는 설정을 바꾸지 않고 현재 상태를 남기는 것만으로 충분합니다. 목록에 없는 값은 추정하지 말고 공식 문서와 실제 JSON을 다시 대조하세요.
