codex-plugin-cc는 Claude Code 안에서 로컬 Codex를 호출해 코드 리뷰나 작업 위임을 실행하는, OpenAI가 관리하는 플러그인이다. 설치 출처는 OpenAI의 openai/codex-plugin-cc 저장소다. 다만 여기서 “공식”은 OpenAI가 이 저장소를 관리한다는 뜻이다. Anthropic 공식 마켓플레이스에 기본 포함돼 있다거나 모든 Claude Code 버전과 운영체제에서 호환성을 보증한다는 의미는 아니다.
현재 공식 문서의 설정 순서는 네 명령으로 제시된다. 그러나 실행 전에는 저장소 주소, Node.js와 Codex 인증, 조직의 플러그인 정책을 확인해야 한다. 설치 후 첫 명령은 파일 변경을 맡기는 위임보다 문서상 읽기 전용인 /codex:review가 적합하다. 연결 대상과 결과 반환, 인증·사용량 오류, 실제 파일 변경 여부를 먼저 확인할 수 있기 때문이다.
설치 전 체크: 출처·런타임·사용량
OpenAI README의 현재 요구사항은 다음 두 가지를 명시한다.
- Node.js 18.18 이상
- Free를 포함한 ChatGPT 구독 또는 OpenAI API 키
다만 이 조건을 충족한다고 설치와 인증이 반드시 성공하는 것은 아니다. 사용 중인 Claude Code 버전, 조직의 workspace 정책, 네트워크, npm 환경, Codex 인증 상태가 결과에 영향을 줄 수 있다. 공개 README에는 정확한 최소 Claude Code 버전이 적혀 있지 않으므로, 특정 버전에서 된다고 단정하기보다 실제 환경에서 플러그인 명령 지원 여부를 확인해야 한다.
또 하나 중요한 점은 비용과 사용량이다. 플러그인에서 Codex를 호출하면 Codex 사용량 한도에 반영된다. 현재 Codex 가격 안내는 여러 ChatGPT 플랜 또는 API 키 사용 경로를 제시하지만, 독자의 지역·계정·조직 정책·남은 한도와 최종 결제액까지 알려 주지는 않는다. 설치 전 자신의 OpenAI 계정과 workspace 정책에서 접근 가능 여부와 사용량을 별도로 확인해야 한다.
| 확인 항목 | 확인할 내용 | 통과 기준 |
|---|---|---|
| 저장소 | 주소가 openai/codex-plugin-cc인지 | 소유자가 openai로 표시됨 |
| Node.js | node --version 결과 | 18.18 이상 |
| Codex 인증 | ChatGPT 계정 또는 API 키 사용 경로 | 로컬 Codex가 사용할 인증 수단이 준비됨 |
| Claude Code | /plugin 명령과 플러그인 기능 | 현재 설치에서 명령이 인식됨 |
| 조직 정책 | 외부 마켓플레이스와 플러그인 허용 여부 | workspace 관리 정책에 위배되지 않음 |
| 사용량 | Codex 플랜·API 사용 조건과 남은 한도 | 예상 작업을 실행할 수 있다고 판단됨 |
공식 문서 기준 설치 명령 4개
Claude Code에서 아래 명령을 한 줄씩 실행한다. 마켓플레이스 등록과 플러그인 설치는 서로 다른 단계다.
text/plugin marketplace add openai/codex-plugin-cc /plugin install codex@openai-codex /reload-plugins /codex:setup
이 순서는 2026년 8월 15일에 확인한 OpenAI 저장소의 설치 안내에 나온 경로다. Anthropic의 플러그인 탐색 문서도 마켓플레이스 소스 추가와 개별 플러그인 설치를 별도 작업으로 설명하며, 설치 후 즉시 반영이 필요할 때 /reload-plugins를 사용할 수 있다고 안내한다.
각 단계에서 확인할 것은 다음과 같다.
/plugin marketplace add는 OpenAI 저장소를 마켓플레이스 소스로 등록한다. 주소를 직접 확인하고 비슷한 이름의 제3자 소스로 바꾸지 않는다./plugin install은 등록한 소스에서codex@openai-codex를 설치한다. 소스 등록만으로 플러그인이 설치된 것은 아니다./reload-plugins는 Claude Code를 완전히 다시 시작하지 않고 새 플러그인을 불러온다./codex:setup은 Codex 연결을 설정하는 단계다. 인증이나 로컬 런타임 문제가 나타나면 성공한 것으로 간주하지 말고 아래 확인 지점으로 이동한다.
소스 등록과 플러그인 설치는 별도 단계다. 마지막에는 /codex:setup 결과와 로컬 Codex 인증 상태를 함께 확인한다.
이 글을 작성하는 과정에서는 실제 마켓플레이스 변경이나 설치·로그인을 실행하지 않았다. 따라서 위 명령은 공식 문서의 현재 계약을 전달하는 것이며, 특정 운영체제나 Claude Code 버전에서 재현된 성공 결과를 뜻하지 않는다.
플러그인은 로컬 Codex 환경을 그대로 쓴다
플러그인이 Claude Code와 Codex 사이에 별도의 실행 환경을 새로 만드는 것은 아니다. OpenAI의 Codex 통합 설명에 따르면 플러그인은 로컬 Codex app server를 감싸고, 전역으로 설치된 Codex CLI를 사용한다. 기존 로컬 인증, 현재 저장소 checkout, 머신 환경과 Codex 설정도 그대로 재사용한다.
이 구조에는 두 가지 실무적 의미가 있다.
- 로컬 Codex가 인증되지 않았거나 설정이 잘못됐다면 플러그인이 그 문제를 우회해 주지 않는다.
- 현재 저장소와 머신 권한을 사용하므로, 플러그인 명령의 권한 범위를 이해하지 않고 작업을 넘기면 예상보다 넓은 변경이 생길 수 있다.
Anthropic 역시 플러그인과 마켓플레이스를 사용자의 권한으로 코드를 실행할 수 있는 고신뢰 구성요소로 취급하라고 경고한다. 저장소 소유자만 보고 자동으로 안전하다고 결론 내리기보다, 추가하려는 소스와 실행할 명령을 확인한 뒤 조직 정책에 맞는지 판단해야 한다.
첫 실행은 읽기 전용 리뷰로 확인한다
설치 직후에는 변경 작업보다 /codex:review로 시작하는 편이 안전 경계를 확인하기 좋다. 현재 README는 /codex:review와 /codex:adversarial-review를 읽기 전용 리뷰 동작으로 설명한다.
예를 들어 Claude Code에서 현재 변경사항을 점검하려면 다음과 같이 요청할 수 있다.
text/codex:review 현재 변경사항에서 오류 가능성과 누락된 테스트를 검토해 줘
더 공격적인 반례 탐색이 필요하다면 다음 명령을 선택할 수 있다.
text/codex:adversarial-review 이 변경이 실패할 수 있는 경계 조건을 찾아 줘
읽기 전용이라는 설명은 이 두 리뷰 동작에 적용된다. 플러그인의 모든 명령이 읽기 전용이라는 뜻은 아니다. 리뷰 결과를 받은 뒤에는 다음을 확인한다.
- Codex가 의도한 저장소와 변경사항을 보고 있는가
- 결과가 Claude Code 세션으로 정상 반환되는가
- 인증 또는 사용량 오류가 발생하지 않는가
- 리뷰가 파일을 변경하지 않았는가
이 네 가지가 확인되면 연결과 기본 경계를 이해한 상태에서 다음 작업을 선택할 수 있다. 리뷰 품질이나 속도가 항상 향상된다고 보장할 근거는 없으므로, 첫 결과를 실제 코드와 테스트에 대조해 판단해야 한다.
리뷰와 작업 위임은 권한이 다르다
/codex:review 계열은 현재 문서상 읽기 전용이지만, rescue·transfer 계열은 Codex에 작업을 위임하거나 세션을 넘기는 흐름이다. 작업 내용에 따라 저장소 파일을 수정할 수 있으므로 같은 안전 수준으로 취급하면 안 된다.
| 목적 | 현재 문서의 명령 | 권한 판단 |
|---|---|---|
| 일반 코드 리뷰 | /codex:review | 문서상 읽기 전용 |
| 반례 중심 리뷰 | /codex:adversarial-review | 문서상 읽기 전용 |
| 막힌 작업 구조 요청 | /codex:rescue | 위임 범위와 변경 가능성을 먼저 확인 |
| 진행 중 작업 인계 | /codex:transfer | 저장소 변경을 포함할 수 있다고 보고 범위를 제한 |
| 백그라운드 작업 확인 | /codex:status | 실행 중 작업의 상태 확인 |
| 완료 결과 가져오기 | /codex:result | 결과와 실제 변경사항을 함께 검토 |
| 백그라운드 작업 중단 | /codex:cancel | 불필요하거나 범위를 벗어난 작업을 중단 |
리뷰 명령의 읽기 전용 경계가 모든 위임 명령으로 확장되는 것은 아니다. 위임 전에는 수정 범위와 금지 작업을 명시한다.
작업을 위임할 때는 “이 문제를 해결해 줘”보다 대상과 허용 범위를 명시하는 편이 낫다. 예를 들어 읽어도 되는 디렉터리, 수정 가능한 파일, 실행 가능한 테스트, 금지할 배포·로그인·외부 쓰기를 프롬프트에 적는다. 반환 후에는 설명만 믿지 말고 Git diff와 테스트 결과를 직접 확인한다.
명령이 동작하지 않을 때 확인할 순서
설치 실패를 곧바로 플러그인 결함으로 단정하면 원인을 찾기 어렵다. 증상별로 가장 가까운 경계부터 확인한다.
/plugin 또는 설치 명령이 인식되지 않는다
현재 Claude Code에서 플러그인 시스템을 사용할 수 있는지 확인한다. 공개된 OpenAI README에는 codex-plugin-cc의 정확한 최소 Claude Code 버전이 없으므로, 버전 번호를 추측하지 말고 현재 Claude Code 문서와 업데이트 상태를 대조한다. 조직 관리 환경이라면 외부 마켓플레이스 등록이 차단됐는지도 확인한다.
설치했지만 /codex:* 명령이 보이지 않는다
마켓플레이스만 추가하고 개별 플러그인 설치를 생략하지 않았는지 확인한다. 설치가 끝났다면 /reload-plugins를 실행하고, 설치된 플러그인 목록에서 codex@openai-codex의 출처를 다시 확인한다.
/codex:setup에서 인증 또는 런타임 오류가 난다
플러그인은 로컬 Codex CLI와 기존 인증·설정을 재사용한다. 로컬 Codex의 인증 상태, Node.js 버전, API 키 또는 ChatGPT 계정 경로, 네트워크와 custom provider 설정을 확인한다. 플러그인이 별도 인증 통로를 제공한다고 가정하면 안 된다.
백그라운드 작업이 끝나지 않는다
/codex:status로 상태를 보고, 완료됐다면 /codex:result로 결과를 가져온다. 작업이 불필요해졌거나 범위를 벗어났다면 /codex:cancel로 중단한다. 실제 파일 변경이 있었다면 결과 메시지와 별도로 diff를 검토한다.
운영체제, Claude Code 버전, workspace 정책, 인증 상태와 custom provider 조합별 동작은 이 글에서 재현하지 않았다. 오류를 보고할 때는 비밀값을 제외한 환경 정보와 정확한 명령, 오류 메시지를 함께 남겨야 다른 조건과 구분할 수 있다.
review gate는 편리함보다 사용량 경계를 먼저 본다
선택 기능인 review gate는 Claude의 작업 뒤에 Codex 검토를 이어 붙일 수 있지만, 무조건 켜 두는 자동 안전장치로 보면 곤란하다. OpenAI README의 경고에 따르면 이 기능은 Claude와 Codex 사이에 긴 반복을 만들고 사용량 한도를 빠르게 소모할 수 있다.
따라서 review gate는 다음 조건에서만 고려한다.
- 세션을 사람이 계속 모니터링할 수 있다.
- 어떤 변경을 검토할지 범위가 좁고 명확하다.
- Claude와 Codex 양쪽 사용량을 감당할 수 있는지 확인했다.
- 반복이 길어질 때 중단할 기준을 정했다.
소요 시간이나 사용량을 하나의 숫자로 예측할 수는 없다. 모델, 문맥, 작업 복잡도와 발견되는 문제에 따라 달라지기 때문이다. 계정별 남은 한도와 Claude Code 비용까지 합친 총비용도 공개 문서만으로는 계산할 수 없다.
안전한 첫 실행을 위한 최종 순서
codex-plugin-cc를 사용할지 결정하는 데 필요한 핵심은 “Claude Code에서 Codex를 쓸 수 있다”는 기능 설명보다 어디에서 실행되고 어떤 권한으로 무엇을 맡기는지다.
처음 시작한다면 다음 순서를 지키면 된다.
- GitHub 주소와 소유자가
openai/codex-plugin-cc인지 확인한다. - Node.js 18.18 이상, 로컬 Codex 인증 수단, workspace 정책과 사용량을 점검한다.
- 공식 문서의 네 명령으로 마켓플레이스 추가·설치·reload·setup을 구분해 실행한다.
/codex:review로 읽기 전용 흐름을 먼저 확인한다.- 파일 변경이 필요한 작업만 범위를 명시해 rescue 또는 transfer 계열에 맡긴다.
- 모든 결과는 Git diff와 실제 테스트로 검증한다.
이 경로는 모든 환경에서의 성공을 보증하지 않는다. 대신 설치가 막혔을 때 어느 경계를 확인해야 하는지, 리뷰와 작업 위임 사이에서 권한이 어떻게 달라지는지, 그리고 계정·지역·조직별로 무엇을 직접 확인해야 하는지를 분명하게 만든다.
