Codex CLI란 무엇인가 — 에이전트 코딩의 새 기준

Codex CLI는 OpenAI가 2025년 4월 공개하고, 2026년 2월 Codex 앱 출시와 함께 대폭 업그레이드한 오픈소스 터미널 기반 AI 코딩 에이전트입니다.
단순히 코드 한 줄을 제안하는 도구가 아니라, 사용자의 명령 하나로 계획 수립 → 파일 수정 → 명령 실행 → 결과 검증까지 전 과정을 자율적으로 처리합니다.

내부 엔진은 OpenAI의 GPT-5.3-Codex(codex-1) 모델을 기반으로 하며, SWE-Bench Verified 벤치마크에서 최고 수준의 정확도를 기록했습니다.
코드베이스를 읽고, GitHub에 PR을 올리고, 테스트가 실패하면 스스로 수정까지 처리합니다. 2026년 현재 개발자 커뮤니티에서 Claude Code와 함께 가장 많이 언급되는 CLI 도구입니다.

▲ 목차로 돌아가기

설치 3분 완성 — npm, Homebrew, 윈도우 WSL2

Codex CLI는 Node.js 22 이상이 설치된 환경이라면 플랫폼에 관계없이 설치됩니다. 아래 세 가지 방법 중 자신의 환경에 맞는 것을 선택하세요.

🐧 macOS / Linux — npm (권장)

# 설치
npm i -g @openai/codex
# 설치 확인
codex --version

🍺 macOS / Linux — Homebrew

brew install --cask codex

🪟 Windows — WSL2 경유 설치

Windows는 네이티브 환경에서 샌드박스 기능이 제한됩니다. 반드시 WSL2 (Ubuntu 22.04 이상)를 통해 설치하는 것을 권장합니다.
WSL2 내부에서 위의 npm 명령을 그대로 실행하면 됩니다. WSL2가 최신 버전이 아닐 경우 Landlock/seccomp 오류가 발생할 수 있으니
wsl --update 명령으로 먼저 업데이트하세요.

▲ 목차로 돌아가기

인증 방법 — ChatGPT 계정 vs API 키

Codex CLI는 두 가지 인증 방식을 지원합니다. ChatGPT Plus/Pro/Team 구독자라면 브라우저 로그인만으로 추가 과금 없이 사용할 수 있어 가장 합리적인 선택입니다.
반면 CI/CD 환경처럼 브라우저 없이 자동화해야 한다면 API 키 방식이 필수입니다.

방법 1: ChatGPT Plus/Pro/Team 계정 (추천)

# 실행 후 브라우저 자동 열림 → 로그인 완료
codex

로그인 후에는 인증 정보가 ~/.codex/auth.json에 저장됩니다. 별도 API 키 없이도 GPT-5.3-Codex 모델을 사용할 수 있으며, ChatGPT 구독 한도 내에서 무료입니다.
SSH 원격 서버에서 사용할 경우 아래처럼 포트 포워딩을 활용하세요.

ssh -L 1455:localhost:1455 user@your-server
codex   # 로컬 브라우저로 인증

방법 2: API 키 (CI/CD 환경)

export OPENAI_API_KEY="sk-..."
codex

API 키 사용 시 codex-mini-latest 기준 입력 100만 토큰당 $1.50, 출력 100만 토큰당 $6.00이 청구됩니다(2026년 3월 기준). ChatGPT 계정 인증 대비 약 75% 비싸므로 꼭 필요한 환경에서만 사용하는 것이 좋습니다.

▲ 목차로 돌아가기

승인 모드 3가지 — Read Only, Auto, Full Access

Codex CLI의 가장 중요한 개념 중 하나가 승인 모드(Approval Mode)입니다. AI가 파일을 얼마나 자율적으로 수정하고 명령을 실행할 수 있는지를 결정합니다.
초보자는 Read Only에서 시작해 신뢰가 쌓이면 점진적으로 권한을 높이는 것을 권장합니다.

# 일상 개발 (기본 Auto 모드)
codex
# 테스트 자동 수정 (Full Access)
codex --full-auto "Run tests and fix failures"
# CI 전용 (승인 완전 비활성화 — 격리된 환경만 사용)
codex --dangerously-bypass-approvals-and-sandbox "Deploy"

▲ 목차로 돌아가기

샌드박스·네트워크 설정 — 보안과 자동화의 균형

Codex CLI는 OS 수준의 격리(샌드박스)를 기본으로 제공합니다. macOS는 Apple Seatbelt, Linux는 Landlock + seccomp를 사용합니다.
이 덕분에 AI가 의도치 않게 시스템 파일을 건드리거나 외부 서버와 통신하는 것을 차단합니다.
네트워크 접근은 기본적으로 차단되어 있습니다.

네트워크 허용 방법

# 방법 1: 명령줄 옵션으로 일시 허용
codex -a never -s workspace-write \
-c 'sandbox_workspace_write.network_access=true' \
"npm install && npm test"
# 방법 2: config.toml에 영구 적용
# 파일 경로: ~/.codex/config.toml

# ~/.codex/config.toml 예시
model = "gpt-5.3-codex"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = true

샌드박스 오류 해결

개인적인 의견으로는, 네트워크 차단 기본값이 처음엔 불편하게 느껴지지만 장기적으로 옳은 설계입니다.
AI 에이전트가 외부 서버와 자유롭게 통신할 수 있다면 보안 사고 위험이 기하급수적으로 증가하기 때문입니다.
필요할 때만 명시적으로 허용하는 방식이 기업 환경에서도 훨씬 안전합니다.

▲ 목차로 돌아가기

AGENTS.md 완전 정복 — AI에게 프로젝트 맥락 주입

AGENTS.md는 Codex CLI가 작업을 시작하기 전에 반드시 읽는 프로젝트 설명서입니다. README.md와 비슷하지만 AI 에이전트를 위해 쓴 지시서라고 생각하면 됩니다.
빌드 명령, 테스트 방법, 코딩 컨벤션, 금지 파일 목록 등을 명시하면 AI가 엉뚱한 파일을 건드리는 실수를 획기적으로 줄일 수 있습니다.

# AGENTS.md 예시 (프로젝트 루트에 위치)
## 빌드 및 테스트
- 빌드: `npm run build`
- 테스트: `npm test`
- 린트: `npm run lint`
## 코딩 규칙
- TypeScript strict 모드 사용
- 컴포넌트 파일명: PascalCase
- 커밋 메시지: Conventional Commits 형식
## 수정 금지 파일
- `src/config/secrets.ts`
- `.env` 파일 전체
## 주요 디렉터리
- `src/` : 소스 코드
- `tests/` : 테스트 파일
- `docs/` : 문서

파일 크기 제한은 32 KiB이며, 프로젝트 루트 또는 $CODEX_HOME 디렉터리에 위치시킵니다.
AGENTS.override.md를 사용하면 특정 작업 세션에서만 임시로 지시를 덮어쓸 수도 있습니다.
팀 프로젝트라면 AGENTS.md를 Git에 커밋해 팀원 모두가 동일한 AI 지시 환경을 공유하는 것을 강력 권장합니다.

▲ 목차로 돌아가기

실전 활용 시나리오 4가지

Codex CLI가 실제로 가장 빛나는 상황 4가지를 구체적인 명령어와 함께 정리했습니다.

1깨진 빌드 자동 수정

codex --full-auto "Fix failing tests and make npm test pass"

CI에서 테스트가 깨졌을 때 이 명령 하나로 Codex가 오류 로그를 분석하고 관련 파일을 직접 수정합니다. Cisco, Temporal, Superhuman 등 기업들이 이 방식으로 개발 사이클을 단축한 것으로 알려져 있습니다.

2대규모 리팩터링

codex "Rename processData to processUserData across the entire repo"

함수명 변경처럼 단순하지만 파일이 수십 개에 걸쳐 있는 작업을 한 줄로 처리합니다. 수동으로 하면 실수가 나올 수 있는 작업에서 특히 효과적입니다.

3CI/CD 파이프라인 연동

# .github/workflows/codex.yml
- name: Run Codex
run: |
npm i -g @openai/codex
codex exec --full-auto "Update CHANGELOG and bump version"
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

GitHub Actions와 연동하면 PR이 머지될 때마다 자동으로 CHANGELOG를 업데이트하거나 릴리스 노트를 생성하는 워크플로를 구축할 수 있습니다. API 키를 GitHub Secrets에 저장해 보안을 유지하세요.

4로컬 LLM 연결 (오프라인 환경)

# ollama 0.13.4+ 또는 LM Studio 0.3.39+ 사용 시
codex --oss "Refactor this module"

인터넷이 없는 보안망 환경에서도 --oss 플래그로 ollama나 LM Studio의 로컬 모델에 연결해 사용할 수 있습니다. 오픈소스 라이선스 덕분에 이런 확장이 가능한 것이 Codex CLI의 진정한 강점입니다.

▲ 목차로 돌아가기

Codex CLI vs Claude Code — 솔직한 비교

2026년 현재 터미널 AI 코딩 도구 시장은 사실상 Codex CLI vs Claude Code 양강 구도입니다.
어느 것이 더 낫냐고 묻는다면, 솔직히 “사용 목적에 따라 다르다”는 말이 정답에 가장 가깝습니다.

ChatGPT Plus 구독자라면 Codex CLI가 비용 면에서 압도적입니다. IDE 중심으로 작업하고 VS Code나 JetBrains에 깊이 통합된 경험을 원한다면 Claude Code가 더 자연스러울 수 있습니다.
기업 보안망이나 오프라인 환경이라면 로컬 LLM을 지원하는 Codex CLI가 사실상 유일한 선택지입니다.

▲ 목차로 돌아가기