Codex CLI 기술 레퍼런스
핵심 요약
Codex CLI는 단순히 코드를 생성하는 챗봇이 아니라, 코드베이스를 읽고, 패치를 만들고, 명령을 실행하고, 테스트 결과를 반영하는 개발 에이전트입니다.
개발자가 Codex를 효과적으로 사용하려면 다음 5가지를 먼저 이해해야 합니다.
| 핵심 시스템 | 목적 | 개발자가 얻는 효과 |
|---|---|---|
config.toml | 모델, 권한, MCP, 프로필 설정 | 세션마다 반복 설정하지 않음 |
| Sandbox / Approval | 파일·네트워크·명령 실행 범위 통제 | 안전한 자동화 가능 |
AGENTS.md | 프로젝트별 작업 규칙 제공 | 팀 표준을 에이전트에 내장 |
| MCP | 외부 도구·문서·API 연결 | GitHub, Figma, Sentry, 사내 API 연동 |
| Skills / Plugins | 반복 워크플로 패키징 | 긴 프롬프트를 재사용 가능한 기능으로 전환 |
실무 사용 루프는 다음과 같습니다.
요구사항 입력
→ 관련 파일 지정
→ 계획 수립
→ 패치 생성
→ 테스트/빌드 실행
→ diff 검토
→ 커밋/PR
Codex를 어떻게 이해해야 하나?
Codex는 하나의 모델이 여러 실행 표면(surface)에서 동작하는 구조로 이해하면 쉽습니다.
| 실행 표면 | 적합한 상황 |
|---|---|
| CLI | 터미널 중심 개발, 빠른 수정, 자동화 스크립트 |
| IDE Extension | VS Code, Cursor 등에서 열린 파일·선택 영역 기반 작업 |
| Desktop App | 여러 작업 스레드, Git worktree, 시각적 diff 리뷰 |
| Codex Cloud / Web | 장시간 작업, 비동기 분석, PR 생성 |
| Browser / App 통합 | 웹 기반 디버깅, 문서·외부 서비스와의 연결 |
개발자는 보통 CLI만으로 시작해도 충분하지만, 팀 단위로 확장하려면 다음 순서로 적용하는 것이 좋습니다.
CLI 사용
→ AGENTS.md 작성
→ config.toml 표준화
→ MCP 연결
→ 반복 업무를 Skill로 분리
→ 공유가 필요하면 Plugin으로 패키징
설치 및 인증
macOS / Linux 설치
curl -fsSL https://chatgpt.com/codex/install.sh | sh
또는 npm으로 설치할 수 있습니다.
npm install -g @openai/codex
macOS에서는 Homebrew도 사용할 수 있습니다.
brew install --cask codex
Windows 설치
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
또는 npm을 사용할 수 있습니다.
npm install -g @openai/codex
Windows에서 샌드박스 안정성과 Linux 개발 환경 호환성이 중요하다면 WSL2 기반 실행을 우선 검토합니다.
로그인
codex
처음 실행하면 ChatGPT 계정 로그인 또는 API 키 인증을 선택할 수 있습니다.
일반적으로는 ChatGPT 계정 로그인을 권장합니다.
codex login
codex login status
codex logout
API 키 기반 사용이 필요한 경우:
export CODEX_API_KEY="sk-..."
codex login --with-api-key
첫 번째 세션
프로젝트 루트에서 실행합니다.
cd ~/projects/my-app
codex
처음에는 코드 변경보다 읽기와 요약 작업으로 시작하는 것이 좋습니다.
이 프로젝트의 구조를 요약해 줘.
주요 진입점, 빌드 명령, 테스트 명령을 찾아서 정리해 줘.
변경하지 말고 분석만 해 줘.
이후 작은 작업을 시킵니다.
src/api/users.ts의 getUser 함수에서 null 반환 가능성을 방어해 줘.
변경 후 관련 테스트만 실행해 줘.
작업이 끝나면 diff를 검토합니 다.
/diff
/review
/status
기본 명령과 슬래시 명령
CLI 실행 명령
| 명령 | 용도 |
|---|---|
codex | 대화형 TUI 실행 |
codex "prompt" | 초기 프롬프트와 함께 실행 |
codex exec "prompt" | 비대화형 실행 |
codex app | 데스크톱 앱 실행 또는 handoff |
codex mcp | MCP 서버 관리 |
codex completion <shell> | 셸 자동완성 생성 |
예시:
codex "이 저장소의 테스트 실행 방법을 찾아줘"
codex exec "README의 오타를 수정하고 diff를 요약해줘"
codex mcp --help
자주 쓰는 슬래시 명령
| 명령 | 용도 |
|---|---|
/status | 현재 모델, 권한, 토큰, AGENTS 로딩 상태 확인 |
/model | 모델 변경 |
/permissions | 승인·샌드박스 모드 변경 |
/plan | 계획 모드 진입 |
/diff | 변경 사항 확인 |
/review | 변경 사항 리뷰 |
/compact | 대화 컨텍스트 압축 |
/init | AGENTS.md 초안 생성 |
/mcp | MCP 서버 상태 확인 |
/skills | 사용 가능한 Skill 확인 |
/plugins | Plugin 탐색·관리 |
설정 시스템: config.toml
Codex 설정은 개인, 프로젝트, 시스템 레벨로 나눌 수 있습니다.
기본 위치
| 범위 | 경로 | 용도 |
|---|---|---|
| 사용자 기본값 | ~/.codex/config.toml | 개인 기본 모델, 권한, MCP |
| 프로젝트 설정 | .codex/config.toml | 저장소별 규칙 |
| 프로필 설정 | ~/.codex/<profile>.config.toml | 빠른 전환용 프리셋 |
| 시스템 설정 | /etc/codex/config.toml | 조직 공통 설정 |
| 강제 정책 | /etc/codex/requirements.toml | 사용자가 완화할 수 없는 제약 |
설정 우선순위
최신 공식 문서 기준으로 우선순위는 다음과 같습니다.
1. CLI 플래그와 --config 오버라이드
2. 프로젝트 .codex/config.toml
3. --profile 로 선택한 프로필 파일
4. 사용자 ~/.codex/config.toml
5. 시스템 /etc/codex/config.toml
6. 내장 기본값
기본 설정 예시
# ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[features]
hooks = true
[sandbox_workspace_write]
network_access = false
프로필 예시
반복 작업과 신중한 작업을 분리합니다.
# ~/.codex/fast.config.toml
model = "gpt-5.5"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
# ~/.codex/careful.config.toml
model = "gpt-5.5"
model_reasoning_effort = "high"
approval_policy = "untrusted"
sandbox_mode = "read-only"
실행:
codex --profile fast
codex --profile careful
Sandbox와 Approval
Codex 보안 모델은 두 계층으로 나뉩니다.
Sandbox = 기술적으로 무엇을 할 수 있는가
Approval = 언제 사람에게 물어볼 것인가
Sandbox 모드
| 모드 | 설명 | 권장 상황 |
|---|---|---|
read-only | 읽기 전용 | 분석, 코드 리뷰, 보안 검토 |
workspace-write | 현재 작업공간 쓰기 가능 | 일반 개발 작업 |
danger-full-access | 전체 시스템 접근 | 격리된 컨테이너 내부, 매우 신뢰된 작업만 |
권장 기본값:
codex --sandbox workspace-write --ask-for-approval on-request
분석만 할 때:
codex --sandbox read-only
Approval 정책
| 정책 | 설명 | 권장 상황 |
|---|---|---|
untrusted | 대부분의 작업에 승인 요청 | 처음 보는 저장소 |
on-request | 경계 밖 작업에만 승인 요청 | 일반 개발 |
never | 승인 없이 진행 | CI/CD, 완전 자동화 |
비대화형 자동화에서는 다음 조합을 사용할 수 있지만, 신뢰된 환경에서만 사용합니다.
codex exec \
--sandbox workspace-write \
--ask-for-approval never \
"테스트 실패 원인을 수정하고 결과를 요약해 줘"
AGENTS.md: 프로젝트 지침 파일
AGENTS.md는 Codex에게 전달되는 프로젝트 수준의 운영 규칙입니다. 매번 긴 프롬프트를 쓰는 대신, 팀 규칙을 문서화해 자동으로 로딩되게 하는 방식입니다.
언제 필요한가?
다음과 같은 지시를 반복하고 있다면 AGENTS.md로 옮깁니다.
- 테스트는 npm test로 실행해.
- API 변경 시 OpenAPI 문서도 업데이트해.
- SQL은 반드시 파라미터 바인딩을 사용해.
- Controller에는 비즈니스 로직을 넣지 마.
- 변경 후 /review로 diff를 검토해.
위치와 병합 방식
~/.codex/AGENTS.md # 개인 기본 지침
repo-root/AGENTS.md # 저장소 공통 지침
repo-root/services/api/AGENTS.md # 하위 디렉터리 지침
더 가까운 디렉터리의 지침이 더 구체적인 규칙으로 작동합니다.
예시
# AGENTS.md
## Repository overview
- Backend: .NET Core
- Frontend: Vue
- Database: SQL Server
- Do not use Entity Framework in this repository.
## Build and test
- Backend build: `dotnet build`
- Backend test: `dotnet test`
- Frontend install: `pnpm install`
- Frontend test: `pnpm test`
## Engineering rules
- Do not change public API contracts without updating docs.
- Prefer small, reviewable patches.
- Do not add new production dependencies without asking first.
- After code changes, run the smallest relevant test suite.
## Definition of done
- Code compiles.
- Relevant tests pass.
- Diff is reviewed.
- Risky changes are called out in the final summary.
초기 파일은 다음 명령으로 생성할 수 있습니다.
/init
Plan Mode와 작업 제어
Plan Mode
복잡한 작업은 바로 수정하지 말고 /plan으로 시작합니다.
/plan 인증 모듈의 refresh token 처리 방식을 개선해 줘.
현재 구조를 먼저 분석하고, 변경 계획과 위험 요소를 제안해 줘.
적합한 상황:
- 3개 이상의 파일을 수정해야 함
- 아키텍처 변경이 포함됨
- DB 마이그레이션이 있음
- 테스트 전략이 필요함
- 성능/보안 영향이 있음
작업 중 방향 전환
작업 중간에 개입할 수 있습니다.
잠깐, 이 방식 말고 기존 인터페이스는 유지하고 내부 구현만 바꿔.
또는 현재 작업이 끝난 뒤 이어서 처리하도록 요청할 수 있습니다.
이 작업이 끝나면 lint와 unit test도 실행해 줘.
MCP: 외부 도구 연결
MCP(Model Context Protocol)는 Codex가 외부 도구나 데이터 소스를 사용할 수 있게 해주는 연결 계층입니다.
예시:
- Context7: 최신 라이브러리 문서 조회
- GitHub: PR, issue, Actions 로그 확인
- Figma: 디자인 스펙 확인
- Sentry: 런타임 오류 확인
- 사내 API: 배포, 로그, 검색, 업무 시스템 연동
CLI로 MCP 서버 추가
codex mcp add context7 -- npx -y @upstash/context7-mcp
상태 확인:
/mcp
또는:
codex mcp --help
config.toml 직접 설정
[mcp_servers.context7]
enabled = true
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
환경변수가 필요한 경우:
[mcp_servers.github]
enabled = true
command = "npx"
args = ["-y", "github-mcp-server"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }
MCP 도입 기준
MCP는 “있으면 좋은 도구”가 아니라, 반복적인 수동 조회를 줄일 수 있을 때 도입합니다.
| 반복 작업 | MCP 후보 |
|---|---|
| PR 상태 확인 | GitHub MCP |
| 프론트엔드 구현 중 디자인 확인 | Figma MCP |
| 장애 분석 | Sentry / 로그 MCP |
| 최신 API 사용법 조회 | Context7 |
| 내부 업무 API 호출 | 사내 MCP 서버 |
Skills
Skill은 Codex가 필요할 때만 로드하는 재사용 가능한 작업 패키지입니다.
긴 프롬프트를 매번 붙여 넣는 대신, 다음과 같은 반복 업무를 Skill로 만듭니다.
- PR 리뷰 체크리스트
- 릴리스 노트 생성
- 장애 로그 분석
- DB 마이그레이션 검토
- 보안 점검
- 프로젝트 표준 코드 생성
Skill 구조
my-skill/
SKILL.md # 필수: 지침과 메타데이터
scripts/ # 선택: 실행 스크립트
references/ # 선택: 참고 문서
assets/ # 선택: 템플릿, 이미지 등
agents/openai.yaml # 선택: UI, 의존성, MCP 등
SKILL.md 예시
---
name: dotnet-api-review
description: Use this skill when reviewing .NET Core API changes for contract safety, SQL safety, test coverage, and deployment risk.
---
# .NET API Review Skill
## Goal
Review API changes before merge.
## Steps
1. Identify changed controller, service, repository, and contract files.
2. Check whether public request/response contracts changed.
3. Check SQL access for parameter binding.
4. Check exception handling and logging.
5. Check relevant tests.
6. Produce a review summary with:
- blocking issues
- non-blocking issues
- test gaps
- deployment risk
## Do not
- Do not rewrite code unless explicitly asked.
- Do not approve changes without listing risks.