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

01 Codex 한눈에 보기

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

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

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

핵심 업데이트

출처: Codex changelog · Codex models · Linux app preview · GPT-5.6 preview · GPT-5.6 GA · Work with Codex from anywhere · Wasmer customer story · AI scorecard

02 Codex 제품군 한눈에 보기

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

03 지원 모델

현재 모델 가이드

⭐ 추천 모델

🔄 대안 모델

🛠️ 모델 설정 팁

model = "gpt-5.6-sol"

codex -m gpt-5.6-sol

출처: Codex models · Codex pricing · OpenAI API Models · GPT-5.6 API guidance

04 시스템 요구사항 & 가격

출처: Quickstart · Codex pricing · Codex rate card · Speed · Pay-as-you-go pricing for teams

05 설치 및 인증

# Standalone installer (macOS/Linux)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Standalone installer (Windows PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# npm
npm install -g @openai/codex
npm update -g @openai/codex

# Homebrew (macOS)
brew install codex
brew upgrade codex

# 설치 확인
codex --version

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

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

출처: Quickstart · Codex CLI · Windows app · IDE integrations · Authentication

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 ChatGPT 데스크톱 앱의 Codex

쓰레드 모드

핵심 기능

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

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

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.

출처: Codex app · App features · In-app browser · Browser extension · Site tools (WebMCP) · App automations · Apple Messages plugin · 읽기 전용 thread snapshot · Codex for (almost) everything

08 Codex IDE Extension

VS Code, Cursor, Windsurf, VS Code Insiders에는 Codex 확장을 설치하고, Xcode와 JetBrains IDE에서는 각 IDE의 자체 통합을 사용합니다. ChatGPT 계정 또는 API 키로 로그인할 수 있고 JetBrains는 JetBrains AI 구독도 지원합니다. Windows에서는 네이티브 sandbox를 기본 경로로 두고, Linux-native 도구나 이미 WSL2에 있는 저장소가 중요할 때 WSL2 워크스페이스를 선택하세요.

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

핵심 기능

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

09 Codex Web/Mobile (ChatGPT)

출처: Quickstart · Codex cloud · Remote connections · GitHub integration

10 권한 경계 + 승인 방식

# 현재 권한 선택기
/permissions

# 새 permission profile 방식
default_permissions = ":workspace"
approval_policy = "on-request"

# 예전 sandbox 설정을 쓴다면 위 profile과 섞지 않습니다
codex --sandbox workspace-write --ask-for-approval on-request

권한 범위는 로컬 명령이 읽고 쓸 경로와 접속할 네트워크를 묶습니다. 작업공간 범위는 활성 workspace와 임시 폴더 쓰기를 허용하지만 네트워크는 기본적으로 열지 않는 낮은 마찰의 시작점입니다. App의 Ask for approval·Approve for me는 경계를 넘는 요청을 누가 검토할지 정하는 방식이며, sandbox 경계 자체를 없애지 않습니다. 새 permission profile 방식과 예전 `sandbox_mode` 설정은 같은 구성에서 섞지 마세요.

출처: Permission modes · Permission profiles · Sandbox · Config reference

11 슬래시 명령어 & 단축키

12 AGENTS.md 설정 가이드

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

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

작성 5원칙

# 자동 생성
/init

출처: Best practices · AGENTS.md guide

13 config.toml 설정

#:schema https://developers.openai.com/codex/config-schema.json
# ~/.codex/config.toml — permission profile 방식
model = "gpt-5.6-sol"
review_model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "medium"
approval_policy = "on-request"
approvals_reviewer = "user"
default_permissions = "project_safe"
web_search = "cached"
personality = "friendly"

# sandbox_mode / sandbox_workspace_write와 함께 쓰지 않습니다
[permissions.project_safe]
description = "현재 프로젝트 안에서만 읽고 쓰는 기본 profile"
extends = ":workspace"

[permissions.project_safe.network]
enabled = false

[features]
fast_mode = true

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

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

codex --profile fast
codex --profile deep

출처: Best practices · Config reference · Permissions · Sandbox

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

출처: OpenAI Docs MCP · Best practices · Codex MCP

15 세션 관리

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

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

출처: Best practices · CLI commands · Subagents · Long-running work

16 로컬 Scheduled task & Git 자동화

반복 작업은 GitHub 연동이 없어도 실행할 수 있습니다. ChatGPT 데스크톱 앱의 Scheduled에서 로컬 프로젝트와 실행 환경을 고르면, 앱이 켜져 있고 프로젝트가 디스크에 있는 동안 현재 체크아웃 또는 격리된 worktree에서 작업합니다.

이 작업은 현재 로컬 Git 저장소의 공식 문서 기반 정기 업데이트다.

목표
- learn.chatgpt.com/docs를 제품 사용법의 1차 출처로 사용한다.
- 오래된 설명과 링크를 제거하고, 한국어/영어 내용을 같은 의미로 맞춘다.
- 실제 사용자가 따라 할 수 있는 짧은 예시와 검증 방법을 남긴다.

시작 전 확인
- 현재 branch, git status --short, remote를 확인한다.
- 사용자의 tracked 변경이 있거나 main과 origin/main이 갈라졌으면 수정·commit·push하지 말고 이유를 보고한다.
- 기존 untracked 파일은 수정·추가·삭제하지 않는다.
- git pull --ff-only가 실패하면 강제로 해결하지 말고 멈춘다.

작업과 검증
- 공식 문서에서 바뀐 사실만 반영한다. 추측과 홍보성 표현은 넣지 않는다.
- 관련 파일만 수정하고 JavaScript 구문 검사, 번역 검증, git diff --check를 실행한다.
- 로컬 페이지를 열어 한국어/영어와 모바일 레이아웃을 확인한다.

게시
- 모든 검사가 통과하고 diff가 이번 작업 범위에만 있을 때만 관련 tracked 파일을 명시적으로 stage한다.
- git commit -m "docs: refresh guide from official ChatGPT docs" 후 git push origin main을 실행한다.
- git add ., force push, amend, rebase, 사용자 파일 삭제는 금지한다.
- push 또는 원격 확인이 막히면 성공했다고 말하지 말고, 마지막 성공 단계와 필요한 조치만 보고한다.

# shell/CI에서는 codex exec를 별도 선택지로 사용
codex exec --sandbox workspace-write "Run the documented checks and report the diff"

# --full-auto는 새 스크립트에서 쓰지 않습니다

출처: 이벤트 기반 Scheduled tasks · Scheduled tasks · Local environments · Worktrees · codex exec · Code review · Permissions

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.6-sol     # 복잡하고 중요한 작업
/model gpt-5.6-terra   # 일상 작업
/model gpt-5.6-luna    # 빠른 반복 작업 / subagent

# 플러그인 디렉터리 (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 · Wasmer + Codex

19 FAQ

21 공식 문서 바로가기