OpenAI Codex를
한국 실무에 바로 붙이는 가이드

01 Codex 에코시스템 개요

OpenAI Codex는 소프트웨어 개발을 위한 코딩 에이전트입니다. 공식 문서는 Codex를 앱, IDE, CLI, 웹/iOS, SDK 기반 자동화에서 사용할 수 있다고 설명하며, 대부분의 작업은 `gpt-5.4`부터 시작하고 빠른 로컬 작업이나 보조 에이전트에는 `gpt-5.4-mini`, Codex Cloud와 복잡한 엔지니어링 작업에는 `gpt-5.3-codex`, 거의 즉각적인 반복 작업에는 `gpt-5.3-codex-spark`를 보라고 안내합니다. 최근 공식 가이드는 여기서 더 나아가 Codex를 오픈소스 유지보수와 팀 단위 개발 운영까지 확장하는 흐름도 함께 제시합니다.

"단순 코드 생성 → 소프트웨어 엔지니어 팀원"

Codex는 코드 자동완성 도구가 아닙니다. 여러 파일을 동시에 수정하고, 테스트를 실행하고, 결과를 검증하며, 스스로 디버깅하는 자율 에이전트입니다.

타임라인

02 Codex 제품군 한눈에 보기

03 지원 모델

현재 모델 가이드

⭐ 추천 모델

🔄 대안 모델

🛠️ 모델 설정 팁

model = "gpt-5.4"

codex -m gpt-5.4

04 시스템 요구사항 & 가격

05 설치 및 인증

# npm
npm install -g @openai/codex

# Homebrew (macOS)
brew install codex

# Update
npm update -g @openai/codex

# ChatGPT 계정 로그인 (권장)
codex login

# 또는 API 키 사용
export OPENAI_API_KEY="your-api-key-here"

06 Codex CLI 사용법

# 인터랙티브 모드
codex

# 프롬프트와 함께
codex "explain this codebase"

# 특정 디렉토리
codex --cd /path/to/project

# 파일 참조
@src/components/Button.tsx 리팩토링해줘

# 쉘 명령어 실행
!npm test

07 Codex App (macOS + Windows)

Codex App은 여러 프로젝트를 넘나들며 병렬 agent thread를 운영하고 결과를 한곳에서 리뷰하는 데 가장 적합한 데스크톱 표면입니다. Windows에서는 PowerShell 기반 네이티브 sandbox를 쓰거나, 설정에서 agent를 WSL로 전환해 Linux 경로로 운영할 수 있습니다.

쓰레드 모드

핵심 기능

08 Codex IDE Extension

VS Code, Cursor, Windsurf, JetBrains IDE에 통합되는 AI 코딩 에이전트입니다. JetBrains 통합은 ChatGPT 계정, API 키, JetBrains AI로 로그인할 수 있습니다. VS Code 계열 확장은 macOS/Linux 중심으로 문서화되어 있고, Windows 지원은 아직 실험적이며 가장 안정적인 경로는 WSL 워크스페이스에서 에이전트 모드를 쓰는 것입니다.

Chat 모드는 자동으로 파일을 탐색/수정하지 않지만, @file·열린 파일·선택 영역을 컨텍스트로 포함해 질문할 수 있습니다.

핵심 기능

09 Codex Web (ChatGPT 대시보드)

ChatGPT 웹의 `chatgpt.com/codex`에서 GitHub 환경을 연결하고 클라우드 코딩 작업을 실행할 수 있습니다. PR 댓글에서 `@codex`로 위임하거나, 브라우저에서 바로 diff를 보고 PR을 만들 수 있습니다.

10 승인 + 샌드박스 조합

codex --sandbox read-only --ask-for-approval on-request
codex --full-auto
codex --sandbox workspace-write --ask-for-approval untrusted
codex --dangerously-bypass-approvals-and-sandbox

보안: 로컬 Codex는 OS 수준 sandbox를 사용합니다. macOS는 Seatbelt, Linux는 bubblewrap + seccomp, Windows는 네이티브 sandbox 또는 WSL을 사용합니다. 기본 `workspace-write`에서는 네트워크가 꺼져 있고 `.git`·`.codex`·`.agents`는 보호 경로로 읽기 전용입니다. Cloud는 setup 단계와 offline agent 단계를 분리한 런타임입니다.

11 슬래시 명령어 & 단축키

12 AGENTS.md 설정 가이드

Codex에게 프로젝트 맥락과 규칙을 알려주는 핵심 파일. CLI, App, IDE, Web 모두에서 참조합니다.

# AGENTS.md 위치 및 우선순위
AGENTS.override.md  → 최우선
./AGENTS.md         → 가장 가까운 파일
../AGENTS.md        → 상위 디렉토리
~/.codex/AGENTS.md  → 전역 개인 설정

작성 5원칙

# 자동 생성
codex init

출처: Codex Best practices · AGENTS.md guide

13 config.toml 설정

#:schema https://developers.openai.com/codex/config-schema.json
# ~/.codex/config.toml
model = "gpt-5.4"
review_model = "gpt-5.4"
model_provider = "openai"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
model_reasoning_effort = "medium"
model_instructions_file = "~/.codex/instructions.md"

[sandbox_workspace_write]
network_access = false

[tools]
web_search = { context_size = "medium" }

# 프로필
[profiles.fast]
model = "gpt-5.4-mini"
model_reasoning_effort = "low"

[profiles.deep]
model = "gpt-5.4"
model_reasoning_effort = "high"

[windows]
sandbox = "elevated"
sandbox_private_desktop = true

# 필요한 경우 세밀 승인 정책
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

# OpenAI Docs MCP
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"
required = true

codex --profile fast
codex --profile deep

출처: Codex Best practices · config reference · sandboxing

14 MCP (Model Context Protocol)

MCP는 Codex가 외부 도구와 문서를 읽고, 브라우저를 제어하고, 원격 시스템과 연결할 수 있게 해주는 표준 프로토콜입니다.

# 1) 초보자 추천: OpenAI Docs MCP
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

# 2) 연결 확인
codex mcp list
codex mcp get openaiDeveloperDocs

# 3) UI 작업이 많다면 Playwright도 추가
codex mcp add playwright -- npx --yes @playwright/mcp@latest

Always use the OpenAI developer documentation MCP server for OpenAI API, ChatGPT Apps SDK, Codex, and related product questions unless I explicitly say otherwise.

# 연결 후 테스트 프롬프트
OpenAI Responses API의 tools 요청 스키마를
OpenAI developer docs에서 찾아서
필수 필드만 bullet 5개로 요약해줘.

# 전역 설정: CLI와 IDE Extension이 공유
~/.codex/config.toml

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

# 프로젝트에만 적용하고 싶다면
./.codex/config.toml

출처: Codex Best practices · Codex MCP

15 세션 관리

codex resume --last     # 마지막 세션
codex resume            # 목록에서 선택
codex resume <ID>       # 특정 세션

# 세션 내 명령
/permissions  /mcp  /status  /review  /feedback  /compact

출처: Codex Best practices · CLI slash commands · Multi-agents concepts · Execution plans guide

16 비대화형 자동화 & CI/CD

# codex exec - 실행 후 자동 종료
codex exec "Review this PR" --output stdout
codex exec "Fix all TODOs" --full-auto

출처: Codex Best practices · Codex app review · GitHub integration · Automations · Worktrees

17 Prompting GPT-5.4

<assistant_contract>
- Return exactly the requested sections, in the requested order.
- Keep progress updates short and outcome-focused.
- If the next step is reversible and low risk, continue without asking.
- Ask first for destructive changes, production writes, purchases, sending, or deletions.
- If a newer user instruction conflicts with an older one, follow the newer one.
- Preserve earlier instructions that still do not conflict.
</assistant_contract>

<agent_execution_loop>
- Use tools whenever they materially improve correctness or completeness.
- Do not skip prerequisite lookups just because the final action seems obvious.
- If a lookup is empty or suspiciously narrow, retry with one broader or alternate strategy.
- Treat the task as incomplete until every requested item is covered or explicitly marked blocked.
- Before finalizing, verify requirements coverage, grounding, and output format.
</agent_execution_loop>

<research_mode>
- Break the question into 3-5 sub-questions.
- Search each sub-question and follow one deeper lead if needed.
- Cite only sources retrieved in this run.
- If results are thin, retry once with a broader query before concluding.
- Stop only when more search is unlikely to change the answer.
</research_mode>

<coding_agent_contract>
- Persist until the requested change is implemented and verified.
- Use tools when they improve correctness, not just convenience.
- Give the user short updates only at phase changes.
- Run the lightest relevant test, build, or lint step before stopping.
- Report what changed, what was verified, and what remains risky.
</coding_agent_contract>

Update this codebase to [goal].

Constraints:
- Work only in the files that are relevant.
- Keep the final response concise.
- If the request is clear and low risk, proceed without asking.

Execution contract:
- Do prerequisite lookups before editing.
- Persist until the change is implemented and verified.
- Run the lightest relevant verification step before finalizing.
- If blocked, say exactly what is missing.

Answer this question with evidence: [question]

Research contract:
- Break it into 3-5 sub-questions.
- Search each one and retry once if results are thin.
- Cite only sources retrieved in this run.
- Distinguish supported facts from inference.
- Stop only when more search is unlikely to change the conclusion.

18 고급 활용 기법

최신 best practices와 customization 문서를 같이 보면 장기적으로 잘 쓰는 사용자는 반복 작업을 skill로 만들고, 팀에 공유할 때는 plugin으로 묶고, 외부 시스템 연결은 MCP로 붙이고, 장기 작업은 bounded delegation으로 나눕니다.

# 모델 선택
/model gpt-5.4         # 기본 추천
/model gpt-5.3-codex   # Codex-특화 비교용

# 플러그인 디렉터리 (CLI)
/plugins

# 멀티 디렉토리
codex --add-dir /path/to/libs

# 웹 검색(인터랙티브에서 --search 전역 옵션 사용)
codex --search "optimize with Next.js 15"

# 컨텍스트 압축
/compact

출처: Codex Best practices · Customization · Skills · Plugins · Multi-agents

19 Codex vs Cursor vs Claude Code

비교표는 자주 바뀌는 영역입니다. 실제 구매/도입 전에는 각 공식 문서와 가격 페이지를 반드시 재확인하세요.

출처: OpenAI Codex docs · Cursor docs/pricing · Anthropic Claude Code docs

20 FAQ

21 참고 자료