OpenAI 코덱스란? 코딩 에이전트 기능부터 사용법까지 5가지 핵심 정리
터미널부터 클라우드까지, 개발자 대신 일하는 AI를 이해하는 시간
- OpenAI 코덱스는 2025년 4월 다시 등장한 AI 코딩 에이전트로, 2021년 코드 완성 모델과는 완전히 다른 제품입니다.
- 터미널(CLI)·클라우드(Web)·IDE 확장·데스크톱 앱까지 4가지 방식으로 쓸 수 있습니다.
- 모든 작업은 격리된 샌드박스 안에서 실행되어 저장소를 직접 손대지 않습니다.
- AGENTS.md 파일 하나로 코덱스에게 프로젝트 규칙을 가르칠 수 있습니다.
- ChatGPT Plus·Pro·Business 요금제에 포함되어 있어 추가 결제 없이 시작 가능합니다.
버그를 고치려고 코드를 열었는데, 손댈 파일이 열 개가 넘는다면 어떤 기분일까요.
혼자 다 처리하기엔 시간이 부족하고, 그렇다고 미룰 수도 없는 상황입니다. 바로 이럴 때 등장한 것이 OpenAI 코덱스입니다.
이 글에서는 OpenAI 코덱스가 정확히 무엇인지, 어떻게 작동하는지, 실제로 어떻게 써야 하는지를 순서대로 정리합니다. 이미 알고 있는 코파일럿이나 커서와 뭐가 다른지도 함께 비교합니다.
1. OpenAI 코덱스란 무엇인가
OpenAI 코덱스는 저장소를 직접 읽고, 코드를 수정하고, 테스트를 돌리고, 풀리퀘스트까지 여는 자율 코딩 에이전트입니다.
이름은 2021년 GPT-3 기반 코드 완성 모델에서 따왔지만, 지금의 코덱스는 그 모델과 architecturally 무관한 완전히 새로운 시스템입니다. 2023년 초기 API 모델이 단종된 뒤, 2025년 4월 전혀 다른 형태로 부활했습니다.
과거 코덱스가 한 줄씩 코드를 제안하는 자동완성이었다면, 지금 OpenAI 코덱스는 “이 기능을 구현해줘”라는 지시 하나로 여러 파일을 오가며 작업을 끝까지 완수하는 에이전트입니다.
같은 “코덱스”라는 이름 때문에 옛날 자동완성 기능을 떠올리는 분이 많습니다. 지금 검색해서 찾은 정보가 2023년 이전 자료라면 이미 낡은 내용일 가능성이 큽니다. OpenAI 코덱스를 조사할 땐 반드시 2025년 4월 이후 자료인지 날짜를 확인하세요.
2026년 기준 OpenAI 코덱스는 주간 활성 사용자 수백만 명을 넘어선 것으로 알려져 있습니다. 개발팀이 백로그에 쌓인 반복 작업(의존성 업데이트, 테스트 추가, 린트 오류 수정)을 코덱스에 맡기고, 사람은 더 중요한 설계 작업에 집중하는 구조가 자리 잡고 있습니다.
2. OpenAI 코덱스는 어떻게 작동하나: 샌드박스와 에이전트 구조
OpenAI 코덱스의 핵심은 세 가지입니다. 저장소 구조 이해, 다중 에이전트 조율, 그리고 샌드박스 격리 실행입니다.
작업을 맡기면 코덱스는 저장소를 격리된 클라우드 샌드박스에 복제합니다. 이 안에서 파일을 읽고, 수정하고, 명령어를 실행합니다. 네트워크가 기본적으로 차단되어 있어 외부로 코드가 유출될 위험이 낮습니다.
2-1. 매니저-워커 구조의 서브에이전트
코덱스는 하나의 매니저 에이전트가 여러 워커 에이전트를 동시에 지휘하는 방식으로 확장됐습니다. 큰 작업을 쪼개 병렬로 처리하면 사람이 순서대로 리뷰만 하면 되는 구조가 만들어집니다.
2-2. 테스트를 통과할 때까지 반복
초기 codex-1 모델부터 강화학습으로 훈련된 습관이 하나 있습니다. 코드를 작성한 뒤 테스트를 돌리고, 실패하면 스스로 원인을 찾아 다시 고치는 루프를 반복하는 것입니다. 사람이 “테스트 돌려봐”라고 매번 말하지 않아도 됩니다.
작업을 맡기기 전에 테스트 코드가 최소한이라도 있는 저장소인지 확인하세요. 테스트가 아예 없으면 코덱스가 “통과 기준”을 스스로 판단해야 해서 결과 품질이 들쭉날쭉해집니다.
샌드박스가 격리되어 있다고 해서 결과 코드가 항상 안전하다는 뜻은 아닙니다. 특히 결제·인증·개인정보를 다루는 코드는 병합 전 반드시 사람이 직접 리뷰해야 합니다. 블라인드 코드 품질 비교에서 코덱스는 속도와 토큰 효율을 우선하는 대신, 첫 결과물 완성도에서 추가 리뷰가 필요한 경우가 상대적으로 많다는 평가도 있습니다.
3. OpenAI 코덱스 사용법: CLI·클라우드·IDE 비교
OpenAI 코덱스는 하나의 계정으로 네 가지 표면을 오갈 수 있습니다. 상황에 맞는 표면을 고르는 게 생산성을 좌우합니다.
예를 들어 “레거시 모듈에 테스트 커버리지를 추가해줘”처럼 명확하지만 시간이 걸리는 작업은 Codex Web에 맡기고, 다른 일을 하는 동안 완료되면 알림을 받는 식으로 씁니다. 반대로 지금 당장 눈앞의 버그를 잡을 땐 CLI나 IDE 확장이 더 빠릅니다.
Codex CLI는 Rust로 재작성되면서 GitHub 스타 수만 개를 넘긴 오픈소스 프로젝트로 성장했습니다. 소스 코드를 전부 열람할 수 있어서, 승인 정책이나 에이전트 루프 동작을 팀 사정에 맞게 직접 고칠 수도 있습니다.
OpenAI 코덱스는 2021년의 자동완성 모델과 전혀 다른, 저장소를 스스로 읽고 고치는 자율 에이전트입니다. Part 2에서는 AGENTS.md 설정법과 요금제, 경쟁 도구와의 비교를 이어갑니다.
4. AGENTS.md로 OpenAI 코덱스 커스터마이징하기
OpenAI 코덱스를 처음 쓸 때 가장 많이 겪는 문제는 “우리 프로젝트 규칙을 모른다”는 점입니다. 이걸 해결하는 파일이 AGENTS.md입니다.
저장소 루트에 AGENTS.md를 두면, 코덱스는 작업을 시작하기 전에 이 파일을 먼저 읽습니다. “PR 열기 전 npm run lint를 실행하라”, “테스트는 pnpm test로 돌려라” 같은 규칙을 여기 적어두면 매번 반복해서 지시할 필요가 없습니다.
4-1. 전역 설정과 프로젝트 설정의 우선순위
코덱스는 두 단계로 지침을 읽습니다. 먼저 ~/.codex 홈 디렉터리의 전역 AGENTS.md, 그다음 저장소 루트부터 현재 작업 디렉터리까지 내려오며 각 폴더의 AGENTS.md를 순서대로 병합합니다. 하위 폴더 파일이 상위 규칙을 덮어씁니다.
예를 들어 결제 모듈처럼 특별 규칙이 필요한 폴더에는 별도로 AGENTS.override.md를 두면, 그 폴더에서 작업할 때만 다른 규칙이 적용됩니다.
AGENTS.md는 기본적으로 32KiB까지만 읽힙니다. 용량을 넘기면 나머지 지침은 경고 없이 잘려나갑니다. 규칙이 많다면 폴더별로 파일을 나누는 게 안전합니다.
많은 팀이 AGENTS.md에 코딩 스타일 같은 부수적인 내용부터 채웁니다. 실제로 효과가 큰 건 “테스트 명령어”와 “PR 열기 전 필수 체크리스트”처럼 매번 실수하기 쉬운 반복 작업입니다. 우선순위 높은 규칙을 파일 맨 위에 두는 게 핵심입니다.
5. OpenAI 코덱스 요금제와 시작하는 법
OpenAI 코덱스는 별도 상품이 아니라 ChatGPT 요금제 안에 포함되어 있습니다. Plus, Pro, Business, Edu, Enterprise 구독자라면 추가 결제 없이 바로 쓸 수 있습니다.
API를 통해 직접 연동하고 싶다면 토큰 기반 크레딧 과금 방식이 적용됩니다. 다만 작업을 실행하기 전에 예상 비용이 표시되지 않아서, 긴 세션일수록 크레딧 소모가 예상보다 커질 수 있다는 점은 감안해야 합니다.
시작 방법은 간단합니다. CLI라면 npm i -g @openai/codex 명령으로 설치한 뒤 ChatGPT 계정으로 로그인하면 됩니다. 별도 API 키 없이 구독 계정만으로 인증이 끝납니다.
처음 써본다면 API 키보다 ChatGPT 구독 계정 로그인을 추천합니다. 사용량이 요금제 한도 안에서 관리되기 때문에 갑자기 큰 비용이 청구될 걱정이 적습니다.
6. OpenAI 코덱스 vs 클로드 코드 vs 커서, 뭐가 다를까
“어떤 코딩 에이전트를 써야 하나요”라는 질문에 정답은 하나가 아닙니다. 도구마다 강점이 다릅니다.
실무에서는 이렇게 나눠 쓰는 경우가 많습니다. 기능을 새로 설계하는 탐색적 작업엔 상호작용이 빠른 도구를, 의존성 업데이트나 린트 정리처럼 명확히 정의된 백로그 작업엔 OpenAI 코덱스처럼 비동기로 맡길 수 있는 도구를 사용하는 방식입니다.
즉 하나만 골라야 하는 게 아니라, 작업 성격에 따라 도구를 바꿔가며 쓰는 것이 2026년 현재 가장 흔한 패턴입니다.
별도 무료 버전은 없지만, ChatGPT Plus 이상 요금제에 포함되어 있어 추가 결제 없이 쓸 수 있습니다. API로 직접 쓰면 토큰 단위로 별도 과금됩니다.
데이터 처리 방식은 요금제와 설정에 따라 다르므로, 민감한 코드를 연결하기 전 OpenAI의 개인정보·데이터 처리 정책을 직접 확인하는 것이 안전합니다.
다릅니다. 코파일럿은 주로 코드 자동완성과 인라인 제안에 가깝고, OpenAI 코덱스는 저장소 전체를 읽고 스스로 작업을 끝까지 처리하는 자율 에이전트에 더 가깝습니다.
쓸 수는 있지만, 결과 코드를 검증할 최소한의 지식은 필요합니다. 코드를 읽지 못한 채 그대로 병합하면 오류를 놓치기 쉽습니다.
기존 TypeScript 구현보다 실행 속도가 빠르고 배포 바이너리가 가벼워져, 터미널에서 반응 속도가 중요한 에이전트 특성에 더 잘 맞기 때문입니다.
📚 함께 보면 좋은 글
OpenAI 코덱스와 함께 비교해보면 좋은 AI 코딩 도구 가이드를 모았습니다.
🔗 공식 자료
📖 출처
OpenAI Developers 공식 문서(developers.openai.com), Wikipedia “Codex (AI agent)” 항목, Augment Code의 Codex CLI 분석 글, IntuitionLabs의 Codex 데스크톱 앱 가이드, Codegen의 Codex 리뷰, MyEngineeringPath의 Codex 가이드를 참고했습니다.
OpenAI 코덱스는 자동완성이 아니라 저장소를 스스로 읽고 고치는 자율 에이전트입니다. AGENTS.md로 규칙을 가르치고, 작업 성격에 맞는 표면(CLI·Web·IDE)을 골라 쓰면 반복 작업의 상당 부분을 맡길 수 있습니다.
