OpenAI Codex 사용법: CLI 설치부터 버그 수정·테스트·코드 리뷰까지

코드 한 조각을 생성하는 것과 기존 개발 프로젝트를 수정하는 것은 다르다. 원인을 찾고, 파일을 변경하고, 테스트와 diff로 결과를 검증하는 작업 흐름이 필요하다. OpenAI Codex는 이러한 과정을 개발 환경에서 수행하도록 설계된 코딩 에이전트다.

이번 글에서는 Codex CLI 설치부터 Python 버그 재현, AGENTS.md 규칙 설정, 코드 수정 요청, 테스트와 리뷰까지 살펴본다.

Codex 실습 순서를 표현한 자체 제작 개념도다. 실제 실행 화면은 아니다.

문서 확인: 2026년 11월 4일. Python 예제는 Python 3.13.5로 별도 검증했으며, 초기 테스트 4개 중 3개 실패·참고 수정안 적용 후 4개 통과했다. Codex 에이전트 실행 자체는 검증하지 않았다.

1. Codex는 일반적인 AI 채팅과 어떻게 다른가?

일반적인 AI 채팅은 제공한 코드나 설명을 바탕으로 분석과 코드 생성을 수행한다. Codex는 권한을 부여한 작업 공간에서 실제 프로젝트 파일을 읽고 수정하며 개발 명령을 실행할 수 있다.

구분	일반적인 AI 채팅	Codex
코드 분석	제공한 코드 중심	접근할 수 있는 저장소 탐색
파일 수정	코드 제안	실제 파일 수정 가능
테스트	명령어 안내	테스트 도구 실행 가능
결과 검토	사용자가 별도로 적용	작업 로그와 변경 diff 확인
실행 환경	주로 대화	CLI, IDE, 데스크톱, 클라우드

Codex가 항상 올바르게 수정한다는 의미는 아니다. 따라서 에이전트가 무엇을 바꿀 수 있는지와 어떻게 검증할 것인지를 미리 정해 두는 것이 좋다.

2. Codex 실행 환경과 설치 방법

Codex는 CLI, IDE 확장 프로그램, 데스크톱 앱의 Codex 모드 및 Codex Cloud에서 사용할 수 있다. 터미널에서 명령어·파일 변경을 직접 확인하고 싶다면 CLI가 적합하고, 편집기 안에서 작업하려면 IDE 확장 프로그램이 편리하다.

Codex Cloud는 별도 환경에서 저장소 기반 작업을 수행하는 방식으로, 클라우드 접근 권한과 환경 구성이 필요하다. Codex 자체는 Free·Go를 포함한 ChatGPT 요금제에 제공되지만 사용량 제한은 다르며, Codex Cloud는 Free·Go에 포함되지 않는다. 공식 요금제별 사용 안내

2.1. 사전 준비

이번 예제에는 Git, Python 3와 ChatGPT 계정이 필요하다. npm 방식으로 설치한다면 Node.js 및 npm도 준비한다. 실습 명령은 macOS·Linux·WSL2의 셸을 기준으로 한다.

2.2. CLI 설치

npm 설치:

macOS 또는 Linux 독립형 설치:

Windows PowerShell 독립형 설치:

설치 스크립트는 실행 전에 확인하는 것이 좋다. 조직 내부 개발 환경이라면 패키지 설치 정책을 우선한다. 위 명령은 Codex 공식 GitHub 저장소에 안내되어 있다.

프로젝트 디렉터리에서 시작한다.

처음 실행한다면 안내에 따라 ChatGPT로 로그인한다. API 키로 인증하는 방법도 있지만 API 결제와 ChatGPT 구독 사용량은 구분해야 한다.

대화형 화면에서 살펴볼 명령은 다음과 같다.

명령	용도
`/status`	현재 작업 세션 상태 확인
`/model`	모델 선택
`/permissions`	파일·명령 실행에 대한 승인 정책 확인
`/diff`	Git 변경 내역 확인
`/review`	코드 리뷰 요청
`/help`	사용 가능한 명령 확인

이 명령들은 일반 셸이 아닌 Codex 대화형 입력창에서 사용한다. 버전별 옵션은 공식 CLI 명령 참조를 확인한다.

3. 실습: 실패하는 Python 테스트 준비하기

이번 실습에서는 재시도 대기 시간을 계산하는 지수 백오프(Exponential Backoff) 함수를 다룬다. 실제 네트워크 요청은 수행하지 않는다.

시도 횟수	예상 대기 시간
1	0.5초
2	1.0초
3	2.0초
4	4.0초
그 이후	최대 8.0초

시도 횟수는 1부터 시작한다. 0 이하의 값이 전달되면 ValueError가 발생해야 한다.

새 프로젝트를 만든다.

3.1. 오류가 있는 구현

retry.py 파일을 작성한다.

문제는 attempt가 1부터 시작하는데 지수 계산에 그대로 사용된다는 점이다. 그래서 첫 번째 대기 시간이 0.5초가 아니라 1.0초가 된다. 또한 0 이하의 시도 횟수를 검사하지 않는다.

3.2. 테스트 코드

test_retry.py에 다음 코드를 저장한다.

테스트 과정에서 생성되는 캐시 파일이 Git 변경 목록을 어지럽히지 않도록 .gitignore도 만든다.

테스트를 실행한다.

Python 3.13.5에서 이 초기 예제를 별도로 실행한 결과, 네 개 테스트 중 세 개가 실패했다. 첫 시도, 두 번째 시도, 0 이하의 시도 횟수 검사가 실패했고 최대 대기 시간 검사는 통과했다. 이 실패 상태가 수정 작업의 기준점이다.

4. `AGENTS.md`로 프로젝트 규칙 정하기

Codex는 저장소의 AGENTS.md 파일에서 프로젝트별 지침을 읽는다. 파일 수정 범위, 테스트 명령, 의존성 정책을 적어 두면 매 요청마다 반복 설명하는 일을 줄일 수 있다.

루트에 AGENTS.md 파일을 생성한다.

이는 에이전트에게 제공하는 작업 지침이지 운영체제 수준 보안 장치는 아니다. 실제 네트워크·파일 접근은 샌드박스와 승인 정책으로 제한해야 한다. AGENTS.md 공식 문서

초기 파일을 기록한다.

이 커밋에는 의도적으로 실패하는 테스트가 포함된다. 실습 시작점을 보존하기 위한 것이다. Git 작성자 설정이 없는 경우 먼저 구성한다.

5. Codex에 수정 작업 요청하기

다시 프로젝트 디렉터리에서 codex를 실행하고 아래 요청을 입력한다.

"버그를 수정해 줘"라는 한 줄 요청보다 수정 범위와 완료 조건을 명시하는 편이 결과를 검토하기 좋다. 환경과 권한이 허용되면 Codex는 파일을 분석하고 수정한 뒤 테스트를 실행할 수 있다. 다만 이 글은 해당 Codex 세션을 직접 실행한 기록이 아니므로 실제 결과는 작업 로그에서 확인해야 한다.