코덱스(Codex) 사용법, 설치부터 요청 문장 쓰는 법까지

장바구니 금액 계산 함수의 버그를 고치는 같은 작업을 코덱스(Codex) CLI에 세 가지 문장으로 3번씩 맡겼더니, 세 방식 모두 3/3으로 테스트를 통과했습니다. 차이는 걸린 시간과 토큰에서 났어요. 고칠 파일과 확인 방법까지 적은 요청이 중앙값 19.7초로 가장 짧았습니다. 이 작은 작업에서는 고칠 파일과 확인 명령을 적은 요청의 시간·토큰 중앙값이 가장 낮았습니다. 첫 요청에 이 항목들을 넣는 출발점으로 참고할 수 있습니다.

Codex 사용법 3단계

Codex CLI 공식 문서의 시작 순서는 설치, 로그인, 첫 작업 요청입니다. 프로젝트 폴더에서 codex를 실행하고, 처음 실행할 때 Sign in with ChatGPT나 다른 로그인 방법을 고릅니다. 그다음 하고 싶은 일을 말로 적으면 됩니다. 이 측정 결과를 보면 첫 요청에 고칠 파일과 확인 명령을 함께 적는 것부터 시도해 보는 편이 좋습니다.

함께 읽을 글

• 클로드 코드(Claude Code) vs Codex, 같은 버그 수정을 맡겨 보니
• 코덱스(Codex) 설치 방법, npm과 설치 스크립트 비교
• 올라마(Ollama) 사용법, 맥 설치부터 코덱스 연결까지 직접 해 보니

Codex CLI 사용법, 설치와 첫 실행

macOS·Linux에서는 설치 스크립트로 설치합니다.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows에서는 새 PowerShell 창에서 Windows용 설치 스크립트를 실행합니다.

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

npm이나 Homebrew로도 설치할 수 있습니다.

npm install -g @openai/codex

brew install --cask codex

설치한 뒤 프로젝트 폴더에서 codex를 실행하면 대화형으로 쓸 수 있습니다. 스크립트나 반복 작업에서는 codex exec로 호출합니다. API 키로도 쓸 수 있지만 추가 설정이 필요합니다(openai/codex 저장소 참고).

세 가지 요청 방식의 결과

작업은 작은 Node.js 프로젝트였습니다. src/cart.js에 금액 계산 함수가 있고, test/cart.test.js의 테스트 6개가 정률 쿠폰의 원 단위 버림, 0원 아래로 내려가지 않는 정액 쿠폰, 5만 원부터 무료인 배송비, 할인 뒤 금액으로 정하는 배송비, 빈 장바구니 0원을 확인합니다. 결과는 3회 중앙값이에요.

성공률은 같았으니, 이 작업에서는 시간과 토큰을 보면 됩니다. 그렇다면 원인을 먼저 정리하게 하면 더 느려질까요? 이 측정에서는 원인 정리 요청이 24.1초로 한 줄 요청의 23.8초와 거의 같았고, 계산값으로도 1.0배였습니다.

도식출처: 코딩 작업 실측

출력 토큰도 걸린 시간과 같은 순서였어요. 파일·확인 방법까지 적은 요청이 528로 가장 적었고, 원인 정리 요청은 684로 가장 많았습니다. 한 줄 요청은 그 사이인 652였죠.

도식출처: 코딩 작업 실측

입력 토큰에서는 차이가 더 뚜렷했습니다. 한 줄 요청은 79,291이었고 나머지 두 방식은 59,658과 59,906으로, 계산값으로는 둘 다 한 줄 요청의 0.8배였어요. 입력 토큰에는 캐시 읽기가 포함되며, 중앙값 기준 캐시 읽기는 한 줄 요청이 67,584, 파일·확인 방법 요청이 53,376, 원인 정리 요청이 53,504였습니다.

도식출처: 코딩 작업 실측

회차마다 결과가 얼마나 달랐을까요?

중앙값만 보면 놓치는 부분이 있습니다. 파일·확인 방법 요청은 2회차에서 29.7초가 걸려 세 방식의 모든 회차 중 가장 길었어요. 원인 정리 요청은 2회차만 입력 토큰이 46,335로 낮았고, 이때 도구 호출은 5번, 추론 토큰은 10이었습니다.

한 줄 요청은 세 회차의 시간이 23.7초, 23.8초, 24.2초로 고르게 나왔습니다. 그래서 한 번 실행한 결과로 어느 방식이 빠르다고 판단하면 틀릴 수 있어요.

이런 차이는 왜 생겼을까요?

한 줄 요청은 입력 토큰과 도구 호출 수가 둘 다 가장 많았습니다. 그런데 도구 호출이 늘어서 입력 토큰이 늘었는지, 다른 이유가 있는지는 이 측정만으로는 가를 수 없습니다. 기록에는 그 원인이 적혀 있지 않거든요.

직접 확인하고 싶다면 codex exec --json으로 실행해 보세요. 출력되는 turn.completed 이벤트의 usage에서 input_tokens, cached_input_tokens, output_tokens, reasoning_output_tokens를 볼 수 있습니다. 같은 요청을 여러 번 실행해 회차마다 도구 호출 흐름이 어떻게 다른지 비교하면, 자기 프로젝트에서는 어떤지 알 수 있어요.

Codex CLI 사용법: 설치부터 첫 요청까지

측정 결과를 자기 프로젝트에 적용하려면 먼저 CLI가 있어야겠죠. Codex CLI 공식 문서의 순서는 다음과 같습니다.

1. 운영체제에 맞는 방법으로 설치합니다. macOS·Linux는 단독 설치 스크립트를 쓰고, 업데이트도 같은 명령으로 합니다.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows는 새 PowerShell 창에서 실행합니다.

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

npm이나 Homebrew로도 설치할 수 있어요.

npm install -g @openai/codex

brew install --cask codex

2. 프로젝트 폴더에서 codex를 실행하고, 처음 실행할 때 Sign in with ChatGPT 또는 다른 로그인 방법을 고릅니다. GitHub 저장소는 Plus, Pro, Business, Edu, Enterprise 플랜 안에서 쓰려면 ChatGPT 계정 로그인을 권하고, API 키로도 쓸 수 있지만 추가 설정이 필요하다고 안내합니다.
3. 작업 전후로 Git 체크포인트를 만들어 둡니다. 문서는 변경을 되돌릴 수 있도록 이렇게 하라고 권해요.
4. 원하는 일을 문장으로 적어 첫 작업을 시작합니다. 문서의 예시는 프로젝트 설명을 요청하는 문장입니다.

Tell me about this project

대화형과 한 번 실행은 언제 쓸까요?

저장소에서 codex를 실행하면 대화형으로 일합니다. 낯선 코드를 살피고, 변경을 계획하고, 파일을 고치고, 로컬 개발 도구를 실행하는 흐름이죠. 진행 중인 차례를 중간에 이끌 수 있고, 명령과 변경 내용을 보면서 같은 세션에서 후속 작업을 이어 갈 수 있어요. 나중에 돌아오려면 codex resume으로 최근 대화를 다시 엽니다.

반면 codex exec는 비대화형 실행입니다. 스크립트나 CI처럼 같은 작업을 되풀이하는 흐름에 맞아요. 이 글의 측정도 codex exec --json으로 했고, 아래 옵션으로 개인 설정의 영향을 껐습니다.

승인 방식과 샌드박스는 어디서 정할까요?

대화형에서는 /permissions로 정합니다. Codex가 묻지 않고 파일을 고치거나 명령을 실행해도 되는 때를 고르고, 현재 샌드박스와 쓰기 가능한 경로를 확인한 뒤 진행할 수 있어요.

혼자 제품을 만들다 보면 에이전트에게 맡긴 사이 다른 폴더까지 바뀌지 않을까 걱정되죠. 이럴 때는 측정처럼 작업 폴더에만 쓸 수 있는 범위에서 시작하고, 실행 전에 쓰기 가능한 경로부터 확인해 보는 편이 안전합니다.

그대로 따라 할 요청 문장

측정에 쓴 문장은 세 가지입니다. 먼저 한 줄 요청이에요.

장바구니 금액이 이상하게 나와요. 고쳐 주세요.

다음은 고칠 파일과 확인 방법까지 적은 요청입니다.

test/cart.test.js의 테스트가 모두 통과하도록 src/cart.js를 고쳐 주세요. 테스트 파일은 고치지 마세요. 고친 뒤 node --test로 확인해 주세요.

마지막은 원인을 먼저 정리하게 한 요청입니다.

먼저 test/cart.test.js와 src/cart.js를 읽고 무엇이 틀렸는지 목록으로 정리해 주세요. 그다음 테스트가 모두 통과하도록 src/cart.js를 고쳐 주세요. 테스트 파일은 고치지 마세요. 고친 뒤 node --test로 확인해 주세요.

처음 쓴다면 두 번째 문장의 틀을 자기 프로젝트에 맞게 바꿔 쓰는 게 좋습니다. 통과해야 할 테스트, 고칠 파일, 건드리면 안 되는 파일, 확인 명령을 한 문장씩 적는 구조예요. 고친 이유를 목록으로 받아 검토하고 싶다면 세 번째 틀이 맞고, 이 측정에서는 성공률이 같았습니다.

자주 하는 실수와 점검 목록

• 한 줄로만 시키기: 이 작업에서는 성공했지만 입력 토큰이 가장 많았습니다.
• 지킬 파일을 적지 않기: 측정은 테스트 파일이 그대로일 때만 성공으로 셌습니다. 직접 쓸 때도 테스트가 바뀌지 않았는지 따로 확인하세요.
• 한 번 실행으로 판단하기: 같은 요청도 회차에 따라 18.9초에서 29.7초까지 벌어졌습니다.
• 체크포인트 없이 시작하기: 작업 전후 Git 체크포인트가 없으면 되돌리기 어렵습니다.

맡기기 전에는 이 항목들을 확인해 보세요.

• 고칠 파일과 고치지 말 파일을 적었나요?
• 확인 명령(예: node --test)을 요청에 넣었나요?
• /permissions에서 쓰기 가능한 경로를 봤나요?
• Git 체크포인트를 만들었나요?

측정 조건과 한계

측정 환경은 darwin arm64, Node.js v22.23.1, codex-cli 0.163.0-alpha.10.2였습니다. 세 방식 모두 같은 모델(gpt-6.1-sol)과 기본 추론 강도로 실행했고, 요청 문장만 바꿨습니다. 조건마다 작업 폴더를 새 임시 폴더로 복사했고, 3번씩 번갈아 실행해 중앙값을 썼습니다. 걸린 시간은 명령을 시작해 끝날 때까지이고, 비용은 표시되지 않았어요.

사용자 설정, 규칙 파일, 플러그인, 앱 연결, 사용자 스킬을 모두 끄고 Codex에 기본으로 들어 있는 스킬만 남긴 상태였습니다. 그러니 평소 설정과 스킬을 켜고 쓴다면 숫자가 달라질 수 있습니다. 또 함수 몇 개짜리 작은 작업 하나만 잰 결과라서, 파일이 많은 큰 작업이나 다른 모델에서는 결과가 다를 수 있어요.