TL;DR
OpenAI Codex CLI는 npm install -g @openai/codex 한 줄로 설치하는 AI 코딩 도구로, 대화형·헤드리스 양쪽 모드를 지원한다. --ask-for-approval never로 완전 자동화, stdin 파이프로 CI 파이프라인 통합이 가능하며, .agents/skills/의 Skills 시스템으로 팀 단위 반복 작업을 표준화할 수 있다.
문제 정의: 개발 워크플로우의 반복 비용
한국 백엔드 팀에서 매일 반복되는 작업들이 있다. DTO 작성, 테스트 픽스처 생성, PR 설명 작성, 에러 로그 분석. 이런 작업들은 LLM에게 맡기면 되는데, 매번 ChatGPT 창을 열고 컨텍스트를 붙여 넣는 과정이 오히려 마찰을 만든다.
Codex CLI는 이 마찰을 제거한다. 터미널에서 바로 동작하고, 파일을 직접 읽고 수정하며, 파이프라인에 끼워 넣을 수 있다.
설치 및 초기 설정
# npm 설치
npm install -g @openai/codex
# 또는 yarn
yarn global add @openai/codex
# API 키 설정
export OPENAI_API_KEY="sk-..."
# 또는 ~/.codex/config.toml에 영구 저장
설치 후 codex --version으로 확인한다. Node.js 18 이상이 필요하다.
핵심 모드: 대화형 vs 헤드리스
대화형 모드 (기본)
# 프로젝트 루트에서 실행
codex
# 또는 초기 프롬프트와 함께
codex "이 프로젝트의 README를 업데이트해줘"
대화형 모드에서는 AI가 파일을 읽고, diff를 제안하고, 사용자가 승인하면 실제로 파일을 수정한다.
헤드리스 모드 (파이프라인 통합)
# 프롬프트를 positional argument로 전달
codex "src/utils/ 아래 모든 함수에 JSDoc 주석을 추가해줘"
# stdin으로 컨텍스트 주입 (파이프)
cat error.log | codex "이 에러의 원인과 해결 방법을 분석해줘"
# CI에서 PR 설명 자동 생성
git diff main | codex "이 diff를 보고 PR 설명 초안을 작성해줘"
stdin으로 파이프된 컨텍스트는 프롬프트에 자동 포함된다. CI/CD 파이프라인에서 테스트 실패 분석, 빌드 로그 요약 등에 활용할 수 있다.
실무 패턴
승인 모드 선택
# on-request: 파일 편집·명령 실행 모두 승인 요청 (기본값)
codex --ask-for-approval on-request "테스트 코드를 작성해줘"
# on-failure: 실패 시에만 승인 요청
codex --ask-for-approval on-failure "리팩터링해줘"
# never: 모든 액션 자동 승인 — 샌드박스 환경 전용
codex --ask-for-approval never "보일러플레이트를 전부 업데이트해줘"
# untrusted: 신뢰할 수 없는 명령은 항상 승인 요청
codex --ask-for-approval untrusted "의존성을 업데이트해줘"
샌드박스 격리 수준도 별도로 제어할 수 있다:
# 읽기 전용 파일시스템 — 파일 수정 없이 분석만
codex --sandbox read-only "이 코드의 보안 취약점을 분석해줘"
# 작업 디렉터리만 쓰기 허용 (기본값)
codex --sandbox workspace-write "테스트를 추가해줘"
# 전체 파일시스템 접근 허용 (주의)
codex --sandbox danger-full-access "시스템 설정을 업데이트해줘"
팀 코드베이스에서는 on-request 또는 on-failure를 권장한다. never는 실수 복구 비용이 크므로 git 커밋 후 사용한다.
Skills로 팀 워크플로우 표준화
.agents/skills/ 디렉터리에 frontmatter가 포함된 SKILL.md를 작성하면 커스텀 워크플로우로 등록된다.
mkdir -p .agents/skills/pr-description
cat > .agents/skills/pr-description/SKILL.md << 'EOF'
---
name: pr-description
description: 현재 브랜치의 PR 설명 초안 작성
---
# PR 설명 작성
현재 브랜치와 main의 diff를 분석해 PR 설명을 작성합니다.
## 절차
1. `git diff main` 실행
2. 변경 사항을 분석해 아래 형식으로 PR 설명 작성:
- ## Summary (변경 목적 3줄)
- ## 주요 변경 사항 (불릿 리스트)
- ## 테스트 방법
3. 한국어로 작성, 기술 용어는 영어 유지
EOF
카카오·토스 등 대규모 팀에서 PR 설명 형식을 표준화할 때 이 패턴이 특히 유용하다.
모델 선택과 비용 최적화
# GPT-5.4 — 복잡한 리팩터링, 아키텍처 설계
codex --model gpt-5.4 "이 모듈을 CQRS 패턴으로 재설계해줘"
# GPT-5.3-Codex — 단순 보일러플레이트, 주석 추가, 포맷 변환
codex --model gpt-5.3-codex "이 클래스에 Lombok 어노테이션을 추가해줘"
일상적인 반복 작업은 가벼운 모델로 전환하면 토큰 비용을 절감할 수 있다.
세션 재개
# 마지막 세션 재개
codex resume --last
# 특정 세션 ID로 재개
codex resume <session-id>
긴 리팩터링 작업을 여러 세션에 걸쳐 이어갈 때 유용하다.
주의사항
| 항목 | 내용 |
|---|---|
--ask-for-approval never |
모든 파일 변경이 자동 승인 — 반드시 git 커밋 후 사용 |
| 컨텍스트 관리 | 대형 모노레포에서 전체 인덱싱 불가 — AGENTS.md에 제외 디렉터리와 코드 컨벤션 명시 |
| Node.js 필요 | Python 전용 환경에서도 Node.js 18+ 별도 설치 필요 |
| OPENAI_API_KEY | 무료 티어 없음 — 사용량에 따라 비용 발생 |
| config 파일 | 설정은 ~/.codex/config.toml TOML 형식으로 저장 |
AGENTS.md 활용 예시:
# Project Context
## 제외 대상
- node_modules/, dist/, build/ 디렉터리는 수정하지 말 것
- *.lock, *.log 파일 무시
## 코드 스타일
- TypeScript strict mode 사용
- 함수형 컴포넌트만 사용 (클래스 컴포넌트 금지)
- 테스트는 Jest + Testing Library 사용
결론
Codex CLI는 터미널 워크플로우에 AI를 끼워 넣는 가장 마찰이 적은 방법이다. stdin 파이프로 CI 파이프라인에 분석을 추가하고, Skills로 팀 워크플로우를 표준화하면 반복 작업의 상당 부분을 자동화할 수 있다. 개인 프로젝트에서는 --ask-for-approval never로, 팀 코드베이스에서는 on-failure 모드로 시작하는 것이 현실적인 진입점이다.