목차
- GPT 5 Codex 사용법, 설치는 어디서부터 시작하나
- Codex CLI 인증은 어떻게 설정하나
- GPT-5-Codex 모델 계열은 무엇이 다른가
- Responses API로 GPT-5-Codex를 호출하는 방법
- AGENTS.md로 에이전트 태스크를 제어하는 법
- config.toml과 MCP 서버 연동 설정
- Codex CLI 실전 워크플로 구성
- GPT 5 Codex 사용법 확장 — 추가 구성 영역
GPT-5 Codex CLI 사용법을 처음 배우려는 분이라면 이 글이 도움이 될 것입니다. GPT-5 기반 Codex 모델군은 터미널 에이전트(Codex CLI)와 서버사이드 API(Responses API) 두 축으로 나뉜다. 이 글은 설치·인증·API 호출·에이전트 태스크 설정까지 gpt 5 codex 사용법의 핵심 경로를 순서대로 다룬다. 특히 GPT-5 Codex CLI 사용법을 정확히 익히고 싶은 분들께 순서대로 안내합니다.
OpenAI가 GPT-5 기반 Codex 모델군을 내놓으면서, 터미널 에이전트와 서버사이드 API 호출이라는 두 축이 동시에 열렸다. Codex CLI는 Rust 95.2%로 작성된 오픈소스(Apache-2.0)이고, GPT-5-Codex 모델은 Responses API 전용이다. 이 두 가지를 혼동하면 API 호출 에러와 비용 산정 오류가 동시에 발생한다. 아래에서 하나씩 풀어본다.
GPT 5 Codex 사용법, 설치는 어디서부터 시작하나
가장 먼저 받는 질문이 “Codex CLI를 어떻게 깔아요?”다. 답은 단순하다.
npm install -g @openai/codex
brew install --cask codexnpm 글로벌 설치와 Homebrew cask 설치 두 가지 경로가 있다. Node.js 환경이 이미 있으면 npm이 빠르고, macOS에서 GUI 데스크톱 앱까지 한 번에 쓰고 싶으면 brew cask가 편하다. 2026-04-15 기준 최신 안정 버전은 0.121.0이다.
Codex CLI는 터미널(CLI), VS Code/Cursor/Windsurf IDE 통합, 데스크톱 앱(codex app), 웹 버전(chatgpt.com/codex) 네 가지 방식으로 사용할 수 있다. 팀 상황과 작업 유형에 맞게 선택하면 된다.
설치 후 codex 명령어를 실행하면 인증 단계로 넘어간다. Codex CLI의 GitHub 저장소 README에서 설치 옵션 전체를 확인할 수 있다.
버전 확인과 업데이트
0.121.0에서 추가된 기능이 꽤 많다. 마켓플레이스 설치(GitHub URL, 로컬 디렉토리, 직접 URL 지원), TUI 프롬프트 히스토리에서 Ctrl+R 역방향 검색, MCP 및 플러그인 병렬 호출 opt-in, Realtime API 출력 모달리티 지원, bubblewrap 샌드박스 지원이 주요 변경사항이다.
| 기능 | 설명 | 언제 쓰나 |
|---|---|---|
| 마켓플레이스 설치 | GitHub URL, git URL, 로컬 디렉토리에서 플러그인 설치 | 커스텀 도구 배포 시 |
| TUI 히스토리 | Ctrl+R로 이전 프롬프트 역방향 검색 | 반복 태스크 실행 시 |
| MCP 병렬 호출 | 여러 MCP 서버 도구를 동시에 호출 | 멀티 도구 파이프라인 |
| bubblewrap 샌드박스 | 파일 시스템 격리 실행 | 신뢰 불확실 코드 실행 시 |
마켓플레이스 설치가 특히 유용하다. 이전에는 플러그인을 수동으로 배치해야 했는데, 0.121.0부터는 GitHub URL만 지정하면 자동으로 내려받아 등록된다. Codex CLI 릴리즈 노트에서 버전별 변경 이력을 확인할 수 있다.
Codex CLI 인증은 어떻게 설정하나
설치 다음에 나오는 질문이 인증이다. Codex CLI는 두 가지 인증 방식을 지원한다.
첫 번째, ‘Sign in with ChatGPT’ 옵션. codex 명령어를 실행하면 브라우저 기반 로그인 흐름이 뜬다. 이 방식을 쓰려면 ChatGPT Plus, Pro, Business, Edu, Enterprise 플랜 중 하나가 필요하다. 무료 플랜으로는 CLI 인증이 안 된다.
두 번째, API 키 방식. OPENAI_API_KEY 환경변수를 설정하거나, config에 직접 넣는다. 서버 사이드 자동화나 CI/CD 파이프라인에서는 API 키 방식이 사실상 유일한 선택이다.
개인 개발 환경에서는 ChatGPT 로그인이 간편하다. 팀 서버, GitHub Actions, 배포 파이프라인에서는 API 키를 환경변수로 주입하는 방식을 쓴다. 두 방식을 동시에 설정하면 API 키가 우선한다.
GPT-5-Codex 모델 계열은 무엇이 다른가
“그냥 GPT-5 쓰면 안 돼요? Codex 모델이 왜 따로 있나요?” — 이것도 자주 나온다.
GPT-5-Codex는 GPT-5를 에이전틱 코딩 작업에 최적화한 모델이다. 일반 GPT-5와 달리 Responses API에서만 사용 가능하며, 기저 모델 스냅샷이 정기적으로 업데이트된다. Chat Completions API에서는 이 모델을 호출할 수 없다.
GPT-5.2-Codex도 있다. 이 모델은 reasoning effort를 low·medium·high·xhigh 네 단계로 지원하며, 함수 호출(function calling), 구조화된 출력(structured output), 스트리밍, 프롬프트 캐싱을 모두 지원한다.
| 항목 | GPT-5-Codex | GPT-5.2-Codex |
|---|---|---|
| API | Responses API 전용 | Responses API 전용 |
| reasoning effort | 지원 | low·medium·high·xhigh |
| 함수 호출 | 지원 | 지원 |
| 구조화된 출력 | 지원 | 지원 |
| 스트리밍 | 지원 | 지원 |
| 스냅샷 업데이트 | 정기 | 정기 |
공식 문서에도 명시되어 있지 않다. platform.openai.com의 모델 스펙 페이지가 403으로 직접 접근 불가한 상태(2026-04-20 기준)이며, GPT-5.3-Codex 모델 스펙도 공식 확인되지 않았다. 가격 산정 시에는 OpenAI 대시보드의 실시간 usage를 확인하는 편이 안전하다.
Responses API로 GPT-5-Codex를 호출하는 방법
“기존 openai.ChatCompletion 코드를 그대로 쓰면 안 되나요?” — 안 된다. GPT-5-Codex는 Responses API 전용이다. client.responses.create()를 써야 한다. gpt 5 codex 사용법에서 가장 실질적인 부분이 이 API 호출 패턴이다.
response = client.responses.create(
model="gpt-5.4",
reasoning={"effort": "low"},
input=[{"role": "user", "content": prompt}]
)위 코드에서 주목할 점이 세 가지다.
첫째, client.responses.create() 엔드포인트. Chat Completions의 client.chat.completions.create()와 완전히 다른 경로다. SDK 버전도 Responses API를 지원하는 버전이어야 한다.
둘째, reasoning 파라미터. {"effort": "low"}처럼 추론 강도를 지정한다. reasoning.effort는 모델이 응답 전에 생성하는 추론 토큰 수를 제어하는 파라미터다. Codex 변형 모델에서는 none 값이 자동으로 변환되는데, Codex/Codex Max에서는 low로, Codex Mini에서는 medium으로 바뀐다. 즉 Codex 모델에서 추론을 완전히 끌 수는 없다.
셋째, input 필드. Chat Completions의 messages가 아니라 input이다. 구조는 유사하지만 필드 이름이 다르므로, 기존 코드를 마이그레이션할 때 단순 find-replace로는 부족하다.
reasoning effort 단계별 선택 기준
reasoning effort를 어떤 값으로 설정할지는 태스크 복잡도와 비용 트레이드오프에 달려 있다.
| effort | 추론 토큰 | 적합한 태스크 | 비용 영향 |
|---|---|---|---|
| low | 최소 | 단순 코드 포맷팅, 린트 수정 | 낮음 |
| medium | 중간 | 일반 코드 리팩토링, 버그 수정 | 중간 |
| high | 높음 | 아키텍처 설계, 복잡한 알고리즘 | 높음 |
| xhigh | 최대 | 대규모 코드베이스 분석, 멀티파일 에이전트 태스크 | 최대 |
low로 시작해서 결과 품질이 부족하면 단계를 올리는 방식이 실용적이다. xhigh는 토큰 소모가 크므로, CI/CD 자동화에 넣을 때는 비용 알림을 걸어두는 편이 좋다. OpenAI Reasoning 가이드에서 effort 파라미터의 동작 방식을 상세히 확인할 수 있다.
Responses API를 사용한 GPT-5-Codex 호출의 전체 코드 예제는 공식 문서에서 직접 검증되지 않은 상태다. 위 코드 스니펫은 공식 가이드의 reasoning 예제를 기반으로 하지만, 프로덕션 적용 전에 API 레퍼런스를 반드시 확인해야 한다.
Codex CLI가 설치되고 인증이 끝나면, 다음 질문은 “프로젝트마다 다른 지시를 어떻게 줘요?”다. 답이 AGENTS.md다.
AGENTS.md는 프로젝트별 커스텀 지시사항을 Codex에 제공하는 마크다운 파일이다. 프로젝트 루트에 놓으면 Codex CLI가 자동으로 읽는다. 파일 검색 순서가 정해져 있다:
AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.mdAGENTS.override.md가 최우선이고, 없으면 AGENTS.md, 그 다음 TEAM_GUIDE.md, 마지막으로 .agents.md 순서다. 팀 내에서 공통 가이드는 TEAM_GUIDE.md에 넣고, 개인 오버라이드는 AGENTS.override.md에 넣는 패턴이 깔끔하다.
AGENTS.md 읽기 동작 제어
두 가지 설정 키가 AGENTS.md의 읽기 동작을 제어한다.
project_doc_max_bytes— AGENTS.md 파일을 읽을 때 최대 바이트 수. 파일이 너무 크면 잘린다.project_doc_fallback_filenames— 기본 파일명 목록을 커스터마이즈한다. 조직 내부 컨벤션에 맞게 파일명을 바꿀 수 있다.
AGENTS.md 안에 넣을 내용은 자유롭지만, 실전에서 검증된 패턴은 네 가지다:
- 프로젝트의 기술 스택과 주요 디렉토리 구조 설명
- 코딩 컨벤션 (네이밍, 임포트 순서, 테스트 규칙)
- 금지 사항 (특정 라이브러리 사용 금지, 특정 패턴 금지)
- 태스크 범위 제한 (이 프로젝트에서 Codex가 건드리면 안 되는 파일)
project/
├── AGENTS.md ← Codex 기본 지시사항
├── AGENTS.override.md ← 개인 오버라이드 (gitignore 권장)
├── TEAM_GUIDE.md ← 팀 공통 가이드
├── src/
│ ├── api/
│ └── db/
└── tests/AGENTS.md에 프로젝트 컨텍스트를 구체적으로 기술할수록 Codex의 코드 수정 정확도가 높아지고, 의도와 다른 파일 수정 비율이 줄어든다. 반대로, AGENTS.md 없이 Codex를 돌리면 프로젝트 컨텍스트를 모르는 상태에서 코드를 수정하므로 결과물 품질이 들쭉날쭉해진다.
config.toml과 MCP 서버 연동 설정
“MCP 서버를 Codex에 연결하려면 어떻게 해요?” — 이 질문에 대한 답은 config.toml이다.
Codex CLI 설정 파일은 ~/.codex/config.toml에 위치한다. 프로젝트별로 다른 설정을 쓰고 싶으면 프로젝트 루트에 .codex/config.toml을 만들면 된다. 글로벌 설정을 프로젝트 설정이 오버라이드하는 구조다.
MCP 서버 연동 설정 예시는 다음과 같다.
[mcp_servers.{name}]
command = "server-executable"
supports_parallel_tool_calls = true
default_tools_approval_mode = "approve"각 필드의 의미를 짚어보면:
command— MCP 서버 실행 바이너리 경로.npx,uvx, 또는 직접 빌드한 바이너리를 지정한다.supports_parallel_tool_calls—true로 설정하면 0.121.0에서 추가된 MCP 병렬 호출이 활성화된다. 여러 도구를 동시에 호출해야 하는 파이프라인에서 속도 이점이 크다.default_tools_approval_mode—"approve"이면 도구 호출 전에 사용자 승인을 받는다. 자동화 파이프라인에서는"prompt"로 바꿀 수도 있지만, 보안 관점에서 신중한 선택이 필요하다.
환경변수와 추가 설정 키
config.toml 외에 환경변수로도 동작을 제어할 수 있다.
| 환경변수 | 역할 |
|---|---|
CODEX_SQLITE_HOME | Codex 내부 SQLite 데이터베이스 저장 경로 |
CODEX_HOME | Codex 홈 디렉토리 경로 (기본값: ~/.codex) |
CODEX_CA_CERTIFICATE | 커스텀 CA 인증서 경로 (사내 프록시 환경) |
사내 네트워크에서 프록시 뒤에 있을 때 CODEX_CA_CERTIFICATE가 필수다. 이걸 빠뜨리면 SSL 인증 에러가 나면서 API 호출이 전부 실패한다. Codex CLI 설정 문서에서 전체 설정 키 목록을 확인할 수 있다.
글로벌 `~/.codex/config.toml`에는 인증과 기본 MCP 서버를 설정하고, 프로젝트별 `.codex/config.toml`에는 해당 프로젝트 전용 MCP 서버와 approval_mode를 설정한다. `plan_mode_reasoning_effort` 같은 설정 키로 프로젝트 특성에 맞게 추론 강도도 조절할 수 있다.
“설치·인증·설정 다 했는데, 실제 작업 흐름은 어떻게 되나요?” — 여기서는 gpt 5 codex 사용법을 실전 워크플로 관점에서 정리한다.
Codex CLI의 기본 실행은 codex 명령어 하나로 시작한다. 터미널에서 실행하면 TUI(Terminal User Interface)가 뜨고, 프롬프트를 입력하면 에이전트가 작업을 수행한다. 0.121.0부터 Ctrl+R로 이전 프롬프트를 역방향 검색할 수 있어서, 반복 태스크가 훨씬 편해졌다.
IDE 통합 vs 터미널 직접 사용
VS Code, Cursor, Windsurf 같은 IDE에서 Codex를 통합해서 쓸 수도 있고, 터미널에서 직접 실행할 수도 있다. 어느 쪽이 나은지는 작업 유형에 따라 다르다.
터미널 직접 사용이 유리한 경우:
- 여러 리포지토리를 순회하면서 일괄 수정하는 배치 작업
- CI/CD 파이프라인에서 자동화 태스크 실행
- SSH로 접속한 원격 서버에서 작업
IDE 통합이 유리한 경우:
- 코드 수정 결과를 즉시 diff로 확인하고 싶을 때
- 파일 탐색과 코드 수정을 번갈아 하는 인터랙티브 작업
- 디버깅과 Codex 태스크를 병행할 때
웹 버전(chatgpt.com/codex)은 별도 설치 없이 브라우저에서 바로 쓸 수 있다는 장점이 있다. 다만 로컬 파일 시스템 접근이 제한되므로, 실제 프로젝트 코드를 에이전트에 맡기는 용도로는 CLI나 IDE 통합이 적합하다.
bubblewrap 샌드박스 활용
0.121.0에서 추가된 bubblewrap 샌드박스는 신뢰 수준이 확인되지 않은 코드를 실행할 때 유용하다. 파일 시스템을 격리해서 Codex가 지정된 디렉토리 밖의 파일을 건드리지 못하게 한다. 오픈소스 프로젝트에 Codex를 적용할 때나, 외부 기여자의 PR을 Codex로 리뷰할 때 보안 레이어로 활용할 수 있다.
bubblewrap 샌드박스 안에서는 네트워크 접근이나 특정 시스템 콜이 제한될 수 있다. 데이터베이스 연결이 필요한 통합 테스트를 Codex 에이전트에게 실행시킬 때는 샌드박스 설정을 조절하거나, 해당 태스크만 샌드박스 밖에서 실행해야 한다.
gpt 5 codex 사용법의 기본 흐름을 잡았으면, 확장 영역으로 넘어갈 차례다.
Codex CLI에 MCP 서버를 여러 개 연결하면 단순 코드 수정을 넘어서 데이터베이스 쿼리, 외부 API 호출, 파일 시스템 조작을 하나의 에이전트 태스크로 묶을 수 있다. supports_parallel_tool_calls = true 설정과 함께 쓰면 멀티 도구 호출이 병렬로 실행되어 파이프라인 속도가 크게 개선된다.
openai codex 사용법을 더 깊이 다루려면 AGENTS.md 작성 패턴 고도화가 핵심이다. 단순히 “이 프로젝트는 Python이다”라고 적는 수준을 넘어서, 테스트 커버리지 기준·금지 패턴·리뷰 체크리스트까지 AGENTS.md에 녹이면 Codex 에이전트의 출력 품질이 수동 코드 리뷰 수준에 근접한다. codex config.toml 설정의 plan_mode_reasoning_effort를 프로젝트별로 다르게 잡으면 비용과 품질의 균형도 맞출 수 있다.
그리고 codex vs claude code 비교도 기술 선택에서 빠지지 않는 주제다. 두 도구 모두 터미널 에이전트라는 공통점이 있지만, 모델 백엔드·샌드박스 구현·MCP 연동 방식에서 차이가 있다. Responses API 기반 서버사이드 자동화까지 고려하면, 어느 쪽이 팀의 기술 스택과 맞는지가 선택 기준이 된다. gpt-5.2 codex reasoning effort 단계별 성능 차이를 실제 태스크에서 측정해보면, 비용 대비 품질의 최적 지점을 찾는 데 도움이 된다.