목차
- TypeScript에서 Rust로: GPT-5 Codex CLI의 전환
- GPT-5 Codex CLI 설치와 초기 인증
- config.toml 상세 설정과 GPT-5 Codex 샌드박스 정책
- Codex CLI 실행 모드: TUI, exec, MCP 서버
- GPT-5 Codex 사용법 정리: 모델 제품군 선택 가이드
- reasoning effort 활용과 비용 최적화 전략
- 실전 적용 시 주의할 점과 한계
- GPT-5 Codex 다음 단계: MCP 연동과 에이전트 파이프라인
“Codex CLI는 예전 그대로 npm으로 설치하면 된다”라고 알려진 정보가 많은데, 사실 2026년 기준으로는 틀린 이야기다. 기존 TypeScript 기반 CLI는 Rust 구현으로 완전히 대체되었고, 설정 파일 형식도 JSON에서 TOML로 변경되었다. 이전 버전 기준으로 작성된 가이드를 그대로 따라가면 config 파일을 인식하지 못하거나 샌드박스 정책이 의도대로 적용되지 않는 상황이 발생한다. Rust 기반 Codex CLI의 설치, config.toml 설정, 샌드박스 정책, 모델 제품군 선택, MCP 서버 연동을 2026년 현재 시점 기준으로 정리한다.
TypeScript에서 Rust로: GPT-5 Codex CLI의 전환
가장 먼저 짚어야 할 부분은 CLI 런타임의 변경이다. 기존 TypeScript CLI는 Rust 구현으로 대체되었으며, 이에 따라 설정 파일 형식이 JSON에서 TOML(~/.codex/config.toml)로 바뀌었다. 기존에 .codexrc.json 같은 JSON 설정 파일을 사용하던 환경이라면 해당 파일은 더 이상 읽히지 않는 셈이다.
이 전환은 단순한 리팩토링이 아니라 하위 호환을 깨는 변경(breaking change)에 해당한다. 기존 JSON 설정을 그대로 두면 Codex CLI가 기본값으로 동작하므로, 의도한 샌드박스 정책이나 모델 지정이 무시될 수 있다. 따라서 기존 사용자라면 설정 마이그레이션이 필수다.
# config.toml 예시
sandbox_mode = "workspace-write"위 TOML 설정은 ~/.codex/config.toml 경로에 생성하면 된다. 기존 JSON 설정에서 키-값 쌍을 TOML 문법으로 옮기는 작업이 필요하다. TOML은 JSON과 달리 따옴표 규칙과 중첩 테이블 문법이 다르므로, Codex Rust CLI README에서 지원하는 키 목록을 확인하는 것이 좋다.
TypeScript CLI에서 사용하던 JSON 형식 설정 파일은 Rust CLI에서 인식되지 않는다. `~/.codex/config.toml`로 새로 작성해야 하며, 기존 설정 파일을 삭제하지 않아도 동작에는 영향이 없지만 혼동을 방지하려면 백업 후 제거를 권장한다.
GPT-5 Codex CLI 설치와 초기 인증
설치 자체는 간단하다. npm 글로벌 설치 또는 Homebrew cask 설치 두 가지 방법을 지원한다.
npm install -g @openai/codex
# 또는
brew install --cask codex설치 후 첫 실행 시에는 ChatGPT 계정 로그인을 권장한다. Plus, Pro, Business, Edu, Enterprise 플랜 중 하나에 가입된 계정이 필요하며, API 키 인증도 별도로 지원한다. 계정 로그인 방식은 브라우저 기반 OAuth 흐름으로 진행되고, API 키 방식은 환경 변수 또는 config.toml에 직접 지정하는 형태다.
개인 개발 환경에서는 ChatGPT 계정 로그인이 편리하다. CI/CD 파이프라인이나 서버 환경처럼 브라우저 없는 곳에서는 API 키 인증을 사용해야 한다. 두 방식을 동시에 설정하면 API 키가 우선 적용되는 경우가 있으므로 하나만 선택하는 편이 낫다.
한 가지 주의할 점이 있다. Codex CLI GitHub 저장소의 README에서도 언급하듯, npm 패키지명이 @openai/codex로 스코프가 지정되어 있다. 과거 비공식 패키지와 이름이 유사할 수 있으므로 반드시 @openai 스코프를 확인해야 한다.
config.toml 상세 설정과 GPT-5 Codex 샌드박스 정책
Codex CLI의 동작을 제어하는 핵심은 ~/.codex/config.toml 파일에 있다. 샌드박스 정책은 3단계로 나뉘며, 각 단계가 허용하는 파일 시스템 접근 범위가 다르다.
| 샌드박스 모드 | 파일 읽기 | 파일 쓰기 | 적합한 상황 |
|---|---|---|---|
| read-only (기본) | 프로젝트 전체 | 불가 | 코드 리뷰, 분석, 질의응답 |
| workspace-write | 프로젝트 전체 | 워크스페이스 내 | 코드 생성, 리팩토링, 테스트 작성 |
| danger-full-access | 시스템 전체 | 시스템 전체 | 시스템 설정 변경, 패키지 설치 자동화 |
기본값이 read-only라는 점이 중요하다. 별도 설정 없이 Codex를 실행하면 파일 수정 권한이 없으므로, 코드 생성 요청 시 “permission denied” 류의 에러가 발생할 수 있다. 코드 생성 작업을 주로 한다면 config.toml에서 sandbox_mode를 workspace-write로 지정해두는 게 일반적이다.
# ~/.codex/config.toml
sandbox_mode = "workspace-write"
# model = "gpt-5.3-codex" # 기본 모델 고정 시danger-full-access는 이름 그대로 위험한 모드다. 시스템 전체에 쓰기 권한을 부여하므로, 프로덕션 서버나 공유 개발 환경에서는 사용을 피해야 하는 것이 원칙이다. 로컬 개발 머신에서 패키지 설치 자동화 같은 특수한 경우에만 제한적으로 사용하는 편이 안전하다.
config.toml 키 구조
config.toml이 지원하는 설정 키의 전체 목록은 공식 문서에 명시되어 있지 않다. 현재 확인 가능한 키는 sandbox_mode 정도이며, 추가 설정 키에 대해서는 Codex Rust CLI README를 직접 참조해야 한다. 비공식 블로그에서 소개하는 설정 키가 실제로 동작하지 않는 경우가 있으므로, README의 TOML 예시를 기준으로 삼는 것이 가장 확실하다.
설정 파일의 기본 경로는 `~/.codex/config.toml`이다. 이 경로는 환경 변수로 오버라이드할 수 있는지 여부가 공식 문서에 명시되어 있지 않다. 디렉토리가 없으면 수동으로 `mkdir -p ~/.codex`를 실행한 뒤 파일을 생성해야 한다.
Rust 기반 Codex CLI는 세 가지 실행 모드를 제공한다. 각 모드의 용도가 뚜렷하게 구분되므로, 작업 유형에 맞는 모드를 선택하면 효율이 높아진다.
인터랙티브 TUI 모드
codex 명령을 인자 없이 실행하면 터미널 기반 대화형 인터페이스(TUI)가 열린다. 코드 생성, 수정, 리뷰를 실시간으로 주고받을 수 있는 모드로, 탐색적 작업에 적합하다. 프로젝트 디렉토리에서 실행하면 해당 디렉토리를 워크스페이스로 인식한다.
비대화 실행 모드 (codex exec)
자동화 파이프라인이나 스크립트에서 Codex를 호출할 때는 codex exec 모드를 사용한다.
codex exec "Summarize this" --ephemeral
# 샌드박스 모드 직접 지정
codex --sandbox workspace-write--ephemeral 플래그는 대화 컨텍스트를 저장하지 않고 1회성으로 실행하는 옵션이다. CI/CD 환경에서 코드 리뷰 자동화, 커밋 메시지 생성, 테스트 코드 작성 같은 작업을 스크립트로 묶을 때 이 모드가 유용하다. 명령줄에서 --sandbox 플래그로 샌드박스 모드를 직접 지정할 수도 있어서, config.toml 설정을 오버라이드하는 용도로 활용할 수 있다.
MCP 서버 모드
codex mcp-server 명령으로 Codex 자체를 MCP 서버로 기동할 수 있다. 이 모드는 다른 MCP 클라이언트(예: IDE 확장, 다른 에이전트)가 Codex의 코드 생성 능력을 도구로 호출할 수 있게 해주는 구조다.
MCP 서버 관리 명령은 다음과 같다:
codex mcp add— 외부 MCP 서버 등록codex mcp list— 등록된 서버 목록 조회codex mcp get— 특정 서버 상세 정보 확인codex mcp remove— 서버 등록 해제
이 MCP 연동 기능은 TypeScript CLI에는 없었던 것으로, Rust 전환과 함께 새로 추가된 기능이다. Codex를 단독 도구가 아니라 에이전트 체인의 한 노드로 배치할 수 있다는 점에서 활용 범위가 넓어진 셈이다.
GPT-5 Codex 사용법 정리: 모델 제품군 선택 가이드
GPT-5 Codex라는 이름 아래 실제로는 여러 모델 변형이 존재한다. 작업 유형과 요구 사항에 따라 적절한 모델을 선택해야 비용과 성능 사이의 균형을 맞출 수 있다.
GPT-5-Codex는 에이전트 코딩에 최적화된 GPT-5 변형이다. 주목할 점은 이 모델이 Responses API에서만 사용 가능하다는 것이다. 기존 Chat Completions API로는 호출할 수 없으므로, API 통합 시 엔드포인트 변경이 필요하다.
GPT-5.2-Codex는 여기에 reasoning effort 조절 기능을 더한 모델이다. low, medium, high, xhigh 4단계로 추론 깊이를 제어할 수 있으며, 함수 호출, 구조화 출력, 스트리밍, 프롬프트 캐싱을 지원한다. 단순 코드 포매팅에는 low, 복잡한 아키텍처 설계에는 high 이상을 사용하는 방식으로 비용을 최적화할 수 있다.
GPT-5.4는 GPT-5.3-Codex의 코딩 능력과 범용 추론을 통합한 최신 프론티어 모델이다. 1M 토큰 컨텍스트 윈도우를 지원하며, ChatGPT·API·Codex 전체에서 gpt-5.4로 접근 가능하다.
| 모델 | 주요 특징 | 권장 용도 | API 접근 |
|---|---|---|---|
| GPT-5-Codex | 에이전트 코딩 최적화 | 코드 생성·수정 에이전트 | Responses API 전용 |
| GPT-5.2-Codex | reasoning effort 4단계 | 비용 최적화가 필요한 코딩 작업 | Responses API |
| GPT-5.3-Codex | 코딩 전용 고성능 | 대규모 코드베이스 분석·리팩토링 | Responses API |
| GPT-5.4 | 코딩 + 범용 추론 통합, 1M 컨텍스트 | 코딩과 일반 작업 병행 | ChatGPT·API·Codex 전체 |
| GPT-5.4-mini | 경량 모델 | 간단한 작업, 비용 절감 | API |
코딩 전용 작업에는 gpt-5.3-codex를, 경량 작업에는 gpt-5.4-mini를 권장한다는 것이 OpenAI 모델 문서의 안내다. 다만 이 문서의 상세 스펙(정확한 가격, 토큰 제한, 레이트 리밋)은 2026-04 기준 직접 접근이 제한되어 원문 확인이 어려운 상태이므로, 실제 적용 전 최신 정보를 재확인해야 한다.
GPT-5-Codex 계열은 기존 Chat Completions API가 아닌 Responses API에서만 동작한다. 기존 코드에서 `POST /v1/chat/completions` 엔드포인트를 사용 중이라면 API 호출 구조를 변경해야 한다. 마이그레이션 시 요청/응답 스키마가 달라지므로 클라이언트 코드 수정이 필요하다.
GPT-5.2-Codex가 제공하는 reasoning effort 4단계는 실질적인 비용 절감 수단이 된다. 모든 요청에 high나 xhigh를 사용하면 토큰 소비량이 급증하므로, 작업 복잡도에 따라 단계를 조절하는 것이 핵심이다.
단계별 적합한 작업 유형
low — 코드 포매팅, 변수명 변경, 단순 문자열 치환처럼 추론이 거의 필요 없는 작업에 적합하다. 응답 속도도 가장 빠르다. 반복 실행이 많은 CI 자동화 스크립트에서 기본값으로 설정하면 토큰 소비 절감 효과가 크다.
medium — 함수 단위 리팩토링, 테스트 케이스 생성, 간단한 버그 수정 등 중간 수준의 맥락 이해가 필요한 작업에 사용한다. 코드베이스의 기존 패턴을 파악하고 일관된 스타일로 새 코드를 생성하는 작업에도 이 단계로 충분한 경우가 많다.
high — 여러 파일에 걸친 리팩토링, 아키텍처 변경 제안, 복잡한 알고리즘 구현 등 깊은 추론이 필요한 작업이다. 파일 간 의존성 추적이나 레거시 코드의 의도를 역추적해야 하는 경우에도 high가 적합하며, 토큰 소비량이 눈에 띄게 증가하는 구간이다.
xhigh — 가장 높은 추론 깊이를 사용하는 단계다. 공식 문서에서 상세 벤치마크가 확인되지 않으므로, high 대비 실제 성능 차이가 얼마나 유의미한지는 직접 테스트로 판단해야 한다. 최고 품질이 요구되는 설계 검토나 보안 감사 작업에서 실험적으로 활용하는 단계다.
비용 최적화의 기본 전략은 “기본값을 medium으로 두고, 복잡한 작업에만 high를 선택적으로 적용하는 것”이다. CI/CD 파이프라인에서 자동화된 코드 리뷰를 실행할 때는 low로 충분한 경우가 많고, 프롬프트 캐싱을 함께 활용하면 반복 요청의 비용을 추가로 줄일 수 있다.
함수 호출(function calling)과 구조화 출력(structured output) 기능도 GPT-5.2-Codex에서 지원된다. 에이전트 파이프라인에서 Codex의 출력을 JSON 스키마로 받아 다음 단계에 전달하는 구조를 만들 때, 구조화 출력을 사용하면 파싱 오류를 줄일 수 있다. 스트리밍 지원 역시 대규모 코드 생성 시 사용자 체감 응답 시간을 단축하는 데 유용하다.
실전 적용 시 주의할 점과 한계
GPT-5 Codex 사용법 정리에서 빠지기 쉬운 부분이 실제 적용 시의 제약 사항이다. 공식 문서에서 확인되지 않는 부분이 여전히 존재하며, 이를 인식하지 않으면 프로덕션 도입 시 문제가 될 수 있다.
공식 문서 접근 제한
2026-04 기준, platform.openai.com의 일부 문서 페이지가 403 응답을 반환하여 직접 접근이 불가한 상태다. 이로 인해 API 상세 스펙(정확한 가격, 토큰 제한, 컨텍스트 윈도우 수치)을 원문으로 확인하기 어렵다. help.openai.com 가이드 페이지도 마찬가지로 플랜별 요금과 레이트 리밋 원문 확인이 불가한 상황이다.
검증되지 않은 정보 구분
GPT-5-Codex의 Responses API 전용 여부, GPT-5.4의 1M 토큰 컨텍스트 윈도우 등은 API 레퍼런스에서 확인된 정보이나, 원문 직접 접근이 제한되어 완전한 검증이 이루어지지 않은 상태다. 프로덕션 도입 전에는 반드시 OpenAI 대시보드나 API 직접 호출로 모델 가용성과 제한 사항을 확인해야 한다.
자주 발생하는 에러 패턴
Codex CLI 사용 중 가장 자주 만나는 에러는 권한 오류와 모델 접근 제한이다. permission denied 에러는 sandbox_mode를 확인해야 하는 신호이고, model not found 또는 403 응답은 해당 모델이 현재 플랜에서 미지원이거나 Responses API 전용임을 의미하는 경우가 많다. 환경 변수 OPENAI_API_KEY가 설정되어 있는지, 현재 플랜이 해당 모델을 지원하는지 순서대로 점검하면 대부분 해결된다.
IDE 확장 설정
Codex IDE 확장(VS Code 등)의 설정 방법은 공식 문서에서 직접 검증되지 않았다. CLI와 IDE 확장의 설정 체계가 동일한지, config.toml을 공유하는지 여부는 별도 확인이 필요하다.
한국어 가이드 부재
한국어 공식 가이드는 존재하지 않는다. 모든 공식 문서가 영문이므로, 설정 키나 에러 메시지 해석 시 원문을 직접 참조해야 하는 것이 현실이다.
한국어 블로그나 커뮤니티에서 소개하는 config.toml 설정 키 중 실제 동작하지 않는 것이 있을 수 있다. config.toml이 지원하는 키의 공식 전체 목록이 문서화되어 있지 않으므로, GitHub README의 예시를 기준으로 삼고 동작하지 않는 키는 제거하는 방식으로 접근해야 한다.
Codex CLI를 단독 도구로 쓰는 단계를 넘어 MCP 연동과 에이전트 파이프라인으로 확장하는 방향을 다룬다.
Codex CLI의 MCP 서버 모드는 코드 생성 에이전트를 더 큰 자동화 파이프라인의 한 노드로 배치할 수 있는 가능성을 열어준다. codex mcp-server로 기동한 Codex를 다른 MCP 클라이언트가 도구로 호출하는 구조를 만들면, 코드 생성 → 테스트 실행 → 리뷰 → 배포까지의 흐름을 에이전트 체인으로 구성하는 것이 가능해진다. 이 부분은 OpenAI Codex CLI 설치 이후 가장 실용적인 확장 방향이기도 하다.
GPT-5.3-Codex vs GPT-5.4 비교도 실전에서 중요한 주제다. 코딩 전용 모델과 범용 모델 사이의 성능 차이가 특정 작업 유형에서 얼마나 유의미한지는 벤치마크로 직접 확인해야 모델 선택의 근거가 생긴다. 1M 토큰 컨텍스트 윈도우가 실제로 대규모 코드베이스 분석에서 어떤 차이를 만드는지도 검증이 필요한 영역이다.
Codex CLI config.toml 설정의 고도화도 다음 단계에 해당한다. 프로젝트별로 다른 샌드박스 정책을 적용하거나, codex exec 자동화 스크립트에서 reasoning effort를 동적으로 조절하는 패턴은 CI/CD 통합에서 비용과 품질의 균형을 잡는 핵심이 된다. GPT-5 Codex reasoning effort 설정과 프롬프트 캐싱을 결합한 최적화 전략은 별도로 깊이 다룰 만한 주제다.
관련 글
- Gmail Gemini 데이터 보안 — 개인 계정과 Workspace의 정책 차이 총정리 – Gmail에 통합된 Gemini는 계정 유형에 따라 데이터 처리 정책이 완전히 다르다. 개인 계정과 Workspace, Gemini API…