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

01 Codex 한눈에 보기

OpenAI Codex는 코드를 읽고, 고치고, 테스트하고, 결과를 설명하는 코딩 에이전트입니다.

"코드를 쓰는 도구 → 작업을 끝내는 에이전트"

모델, 요금, 설정은 뒤에서 자세히 보고, 여기서는 Codex가 어떤 표면으로 확장되어 왔는지만 빠르게 잡습니다.

핵심 업데이트

출처: Codex overview · Codex models · OpenAI API Models · Introducing GPT-5.5 · Work with Codex from anywhere

02 Codex 제품군 한눈에 보기

출처: Quickstart · Codex app · IDE extension · Codex CLI

03 지원 모델

현재 모델 가이드

⭐ 추천 모델

🔄 대안 모델

🛠️ 모델 설정 팁

model = "gpt-5.5"

codex -m gpt-5.5

출처: Codex models · Codex pricing · OpenAI API Models · GPT-5.5 pro API model

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"

출처: Quickstart · Windows guide · Windows app · IDE extension · Advanced Account Security

06 Codex CLI 사용법

# 인터랙티브 모드
codex

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

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

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

# 쉘 명령어 실행
!npm test

출처: Quickstart · Codex CLI · CLI slash commands

07 Codex App (macOS + Windows)

Codex App은 여러 프로젝트를 넘나들며 병렬 agent thread를 운영하고, built-in Git와 integrated terminal로 결과를 리뷰하며, chats·artifact preview·computer use·in-app browser·image generation·memories·thread automations를 한곳에서 다루는 데 가장 적합한 데스크톱 표면입니다. 최신 App 문서와 2026년 4월 업데이트 기준으로 multiple terminal tabs, richer summary/sidebar, 더 넓어진 plugins, SSH devbox, IDE sync, projectless chats 흐름까지 함께 보는 것이 현재 상태에 가깝고, 로컬 작업은 기본적으로 cached web search를 쓰며 Windows에서는 네이티브 sandbox 또는 WSL2 경로를 선택할 수 있습니다.

쓰레드 모드

핵심 기능

이번 대규모 업데이트 기능 실전 가이드

아래 블록은 단순 소개가 아니라 “언제 쓰고, 어떻게 시작하고, 무엇을 주의해야 하는지”를 기능별로 압축한 실전 챕터입니다. 이번 릴리스에서 중요도가 큰 기능부터 읽으면 됩니다.

Use @Browser to open http://localhost:3000/settings.
Reproduce the mobile overflow bug at 390px width, fix only the overflowing controls,
then verify the page again and attach the screenshot result.

Computer use

Computer use를 하나의 기능 챕터로 이해하기

공식 문서 기준으로 `gpt-5.4`는 첫 mainline built-in computer use 모델입니다. 즉, 화면을 보고 다음 행동을 정하고, 클릭이나 입력을 실행하고, 바뀐 화면을 다시 확인하는 루프를 모델 자체가 더 잘 돌 수 있게 됐다는 뜻입니다.

• 단순 채팅형 답변보다 “직접 UI를 보면서 작업”하는 자동화에 더 잘 맞습니다.
• 핵심 흐름은 `screenshot → action → screenshot → verify/fix` 입니다.
• 브라우저 테스트, 폼 입력, 단계가 많은 업무 플로우 검증에서 특히 설명이 쉬워집니다.
• `Plugins`가 외부 서비스를 연결하는 도구 상자라면, `computer use`는 눈과 손으로 화면을 직접 다루는 기능에 가깝습니다.
• `Skills`는 일을 하는 방법을 설명하는 설명서이고, `computer use`는 그 설명서를 따라 실제 버튼을 누르고 입력하는 실행 수단입니다.

공식 Computer use 가이드 보기

출처: Codex app · App features · In-app browser · App automations · Codex for (almost) everything

08 Codex IDE Extension

VS Code, Cursor, Windsurf, JetBrains IDE에 통합되는 AI 코딩 에이전트입니다. 일반적으로 설치 후 Agent mode가 기본이며, JetBrains 통합은 ChatGPT 계정, API 키, JetBrains AI로 로그인할 수 있습니다. 현재 공식 문서는 IDE 통합이 macOS·Windows·Linux에 걸쳐 제공된다고 설명합니다. Windows에서는 네이티브 sandbox를 기본 경로로 두고, Linux-native 도구나 이미 WSL2에 있는 저장소가 중요할 때 WSL2 워크스페이스를 선택하세요.

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

핵심 기능

출처: IDE extension · IDE features · IDE slash commands · Windows app

09 Codex Web/Mobile (ChatGPT)

ChatGPT 웹의 `chatgpt.com/codex`에서는 GitHub 환경을 연결하고 클라우드 코딩 작업을 실행할 수 있습니다. Remote connections는 별도 축입니다. 현재 공식 문서는 ChatGPT iOS/Android 모바일 앱이 awake/online macOS 또는 Windows Codex App host를 제어할 수 있다고 설명합니다. 모바일에서는 active thread 이어가기, 승인, model 변경, 새 작업 시작, screenshot/terminal output/diff/test result 확인을 할 수 있지만, 실제 파일·credential·permission·plugin·browser setup·Computer Use·local tool은 연결된 host에 남습니다. 같은 account/workspace와 필요한 SSO/MFA/passkey가 맞아야 하고, Business/Enterprise에서는 admin/owner가 Remote Control을 workspace settings 또는 RBAC로 허용해야 할 수 있습니다. Windows host는 휴대폰이나 Mac에서 제어할 수 있지만, Windows Codex App 자체는 아직 다른 컴퓨터를 제어하는 클라이언트로 쓰지 못합니다. Codex App은 SSH config의 구체 host alias를 통해 SSH host 프로젝트를 열어 remote filesystem/shell에서 실행할 수도 있습니다.

출처: Quickstart · Codex cloud · Remote connections · GitHub integration · Work with Codex from anywhere · Using Codex with your ChatGPT plan · Enterprise/Edu release notes

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을 사용합니다. Windows native에서는 `elevated`가 권장 경로이고, 관리자 승인이나 정책 때문에 막히면 `unelevated` fallback을 씁니다. 기본 `workspace-write`에서는 네트워크가 꺼져 있고 `.git`·`.codex`·`.agents`는 보호 경로로 읽기 전용입니다. Cloud는 setup 단계와 offline agent 단계를 분리한 런타임입니다.

출처: Agent approvals & security · Config reference · Windows guide · Windows sandbox engineering

11 슬래시 명령어 & 단축키

12 AGENTS.md 설정 가이드

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

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

작성 5원칙

# 자동 생성
/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.5"
review_model = "gpt-5.4"
model_provider = "openai"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "medium"
personality = "friendly"
service_tier = "fast"
default_permissions = "project_safe"
model_instructions_file = "~/.codex/instructions.md"

[sandbox_workspace_write]
network_access = false

[tools]
web_search = { context_size = "medium", allowed_domains = ["developers.openai.com", "openai.com"] }
view_image = true

[permissions.project_safe.filesystem]
":project_roots" = "write"

[permissions.project_safe.network]
enabled = false

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

[profiles.deep]
model = "gpt-5.5"
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 · Running Codex safely · OpenAI on AWS

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

출처: Docs MCP · 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 · Dell enterprise partnership · Gartner enterprise coding agents

17 Prompting Codex Agents

<assistant_rules>
- 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_rules>

<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>
- Define the core question and success criteria before searching.
- Break the question into 3-5 sub-questions.
- Use the smallest retrieval budget that can answer with evidence.
- Search again only when a required fact, date, owner, or source is missing.
- Cite only sources retrieved in this run.
- If results are thin, retry once with a broader query before concluding.
- Stop when more search is unlikely to change the answer.
</research_mode>

<coding_agent_rules>
- Start from the target outcome, success criteria, constraints, and stop rules.
- 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.
- If validation cannot run, explain why and name the next best check.
- Report what changed, what was verified, and what remains risky.
</coding_agent_rules>

Update this codebase to [target outcome].

Success criteria:
- [observable behavior, test result, or deliverable]

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 rules:
- Do prerequisite lookups before editing.
- Persist until the change is implemented and verified.
- Run the lightest relevant verification step before finalizing.
- If validation cannot run, explain why and name the next best check.
- If blocked, say exactly what is missing.

Answer this question with evidence: [question]

Success criteria:
- The answer distinguishes supported facts from inference.
- Factual claims cite sources retrieved in this run.

Research rules:
- Break it into 3-5 sub-questions.
- Search each one with the smallest useful retrieval budget.
- Search again only if a required fact, date, owner, or source is missing.
- 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 · Self-improving tax agents with Codex

19 FAQ

20 참고 자료