OpenAI 공식 문서 기반

Codex 한국어 실전 가이드

코드를 직접 읽고, 수정하고, 실행까지 해주는 AI 소프트웨어 엔지니어. 설치부터 운영 자동화까지 공식 문서 기반으로 정리했습니다.

OpenAI 공식 Codex 문서

Codex란?

OpenAI가 만든 AI 소프트웨어 엔지니어링 에이전트입니다. 단순한 코드 생성 도구가 아니라, 프로젝트 전체 코드베이스를 읽고 이해한 뒤 직접 코드를 수정·생성·삭제하고, 터미널 명령(빌드, 테스트)까지 실행합니다.

코드 생성 새 기능 구현, 리팩토링, 보일러플레이트 생성
코드 이해 코드베이스 분석, 구조 설명, 의존성 파악
코드 리뷰 PR 리뷰, 코드 품질 검토, 개선 제안
디버깅 버그 원인 분석, 수정, 테스트 작성
작업 자동화 반복 작업 예약, PR 자동 처리, CI 연동

각 작업은 독립된 샌드박스에서 실행되어 기존 코드에 영향을 주지 않으며, ChatGPT 로그인과 OpenAI API 키 로그인을 기준으로 사용할 수 있습니다. 2026년 6월 기준 최신 개발자 홈페이지는 Free/Go 한시 제공과 Plus·Pro·Business·Enterprise의 2x Codex rate limits를 함께 안내합니다.

Codex App (데스크톱)

macOS와 Windows에서 설치해 사용하는 GUI 데스크톱 애플리케이션입니다. 프로젝트를 열고 Local, Worktree, Cloud 실행 모드 중 작업 성격에 맞는 방식을 선택해 코드를 분석하고 수정합니다.

⚡
멀티 스레드

여러 작업을 동시에 병렬 실행. 각 스레드가 독립 샌드박스에서 작동합니다.

🔍
Review Pane

AI가 변경한 코드를 시각적 diff로 확인하고 승인/수정/거부할 수 있습니다.

🌿
Git Worktree 자동 관리

작업별로 독립 브랜치를 자동 생성하고, PR까지 연동합니다.

🔄
Automations

정해진 주기나 기존 스레드 기반으로 반복 작업을 실행하고, 결과를 Triage에 모아 검토할 수 있습니다.

🧩
Skills & IDE 확장

커스텀 Skills로 기능 확장. IDE 확장은 VS Code, VS Code Insiders, Cursor, Windsurf, JetBrains IDE(Rider/IntelliJ/PyCharm/WebStorm)에서 사용 가능하며, 편집기 안에서 Chat / Agent / Agent (Full Access) 3가지 모드를 전환하고 장시간 작업은 Cloud로 오프로드해 IDE 안에서 진행 상황을 볼 수 있습니다.

Codex CLI (터미널)

터미널에서 실행하는 오픈소스 명령줄 도구입니다. 로컬 머신에서 직접 코드를 수정하며, 스크립트와 CI 파이프라인에 통합할 수 있습니다.

📦
설치

npm: npm i -g @openai/codex (업그레이드는 npm i -g @openai/codex@latest). Homebrew: brew install codex. 공식 Quickstart에 두 명령 모두 안내됩니다.

💬
인터랙티브 모드

터미널에서 대화형으로 코드 수정을 요청하고 결과를 바로 확인합니다.

🛡️
승인 정책 & 샌드박스

최신 CLI는 approval policy(언제 사용자에게 묻는지)와 sandbox mode(read-only / workspace-write / danger-full-access)를 분리해 자율성과 권한을 따로 조절합니다. CLI 인터랙티브 세션 안에서 /model 명령으로 모델·추론 수준을 전환할 수 있고(기본 모델 gpt-5-codex), 데스크톱 앱의 빌트인 슬래시(/feedback /mcp /plan-mode /review /status)와는 별개입니다.

⚙️
서브커맨드 & CI 통합

주요 서브커맨드 (공식 CLI reference에 등재된 20여 개 중 핵심): 실행 — 대화형 codex, 비대화형 codex exec(CI에서), 세션 재개 codex resume, 세션 분기 codex fork. 작업 적용 — Cloud 작업 diff를 로컬에 적용 codex apply, 코드 리뷰 codex review. 샌드박스/정책 — 임의 명령을 Codex 샌드박스에서 codex sandbox, 실행 정책 평가 codex execpolicy. 플러그인/스킬 — codex plugin marketplace add|remove|upgrade(GitHub·Git·SSH·로컬 디렉터리 등록), 기능 플래그 영구 토글 codex features list|enable|disable. 관리 — MCP 서버 관리 codex mcp, Codex를 MCP 서버로 실행 codex mcp-server, Cloud 작업 codex cloud, 데스크톱 앱 실행 codex app, 자동완성 codex completion, CLI 자체 업데이트 codex update, 인증 codex login/codex logout.
자주 쓰이는 플래그: -m/--model, --profile <name>, -c key=value(config 오버라이드), --sandbox <mode>, --ask-for-approval <policy>, --full-auto(앞 두 플래그의 alias), --cd <dir>, --image <path>, --skip-git-repo-check, --dangerously-bypass-approvals-and-sandbox(또는 --yolo), --search(웹 검색), --output-last-message <file>, --json. 전체 목록은 공식 CLI reference를 참고하세요.

🔌
MCP & AGENTS.md

MCP 서버 연동, AGENTS.md로 프로젝트별 맞춤 지시를 설정합니다.

실행 환경과 샌드박스

클라우드 실행 (Cloud)

긴 작업을 원격으로 맡길 때 쓰는 모드입니다. 코드를 격리된 클라우드 컨테이너에서 실행합니다.

  • 저장소를 체크아웃한 독립 컨테이너에서 작업
  • 노트북을 닫아도 비동기로 작업 계속 진행
  • 결과는 diff로 로컬에 적용
  • 환경 설정으로 필요한 도구/의존성 설치 가능
로컬 실행 (Local)

내 컴퓨터에서 직접 실행. 플랫폼별 샌드박스로 안전하게 격리합니다.

  • macOS — Seatbelt 프레임워크 (Apple 내장)
  • Windows — 데스크톱 앱은 native Windows 샌드박스(Codex 자체 보호; Microsoft의 Hyper-V "Windows Sandbox" 기능과는 별개) 사용. CLI는 experimental이며 WSL2 권장 (Codex 0.115부터 WSL1 미지원, bubblewrap 기반으로 변경)
  • Linux — bubblewrap(bwrap) 프로세스 격리. PATH의 bwrap을 우선 사용하며, 없으면 번들된 helper로 fallback (unprivileged user namespace 지원이 전제)

Python이나 Node.js가 필수인가요?

아닙니다. Codex는 언어에 관계없이 동작합니다. Python, JavaScript, TypeScript, Go, Rust, Java 등 어떤 프로젝트든 사용 가능합니다. 클라우드 환경에서는 프로젝트에 필요한 도구와 의존성을 자유롭게 설정할 수 있습니다.

시스템 요구사항은?

macOS: Apple Silicon 또는 Intel macOS 모두 지원 (공식 다운로드는 두 빌드를 별도 제공).
Windows: 데스크톱 앱은 Microsoft Store에서 설치하면 Native Windows 샌드박스가 즉시 동작합니다. WSL2는 선택 사항이며, CLI는 experimental입니다.
계정: ChatGPT 로그인과 OpenAI API 키 로그인을 모두 지원합니다. 최신 개발자 홈페이지 기준으로 Free/Go는 한시 제공일 수 있고, Plus·Pro·Business·Enterprise는 2x Codex rate limits가 안내됩니다.

VM을 사용하나요?

전통적인 VM은 아닙니다. Codex는 가벼운 샌드박스 기술을 사용합니다. 클라우드에서는 격리된 컨테이너, 로컬에서는 OS 내장 샌드박스를 통해 코드를 안전하게 실행합니다. 필요 시 danger-full-access 모드로 샌드박스 제한을 해제할 수 있습니다.

Codex App vs Codex CLI

Codex는 데스크톱 앱과 CLI(터미널) 두 가지 형태로 제공됩니다.
같은 AI 엔진을 사용하지만, 인터페이스와 워크플로가 다릅니다.

비교 항목
Codex App (데스크톱)
Codex CLI (터미널)
인터페이스
GUI 윈도우 앱
터미널 명령줄
실행 환경
Local / Worktree / Cloud 모드 선택 (기본: Local)
로컬 머신에서 직접 실행
병렬 처리
여러 스레드 동시 실행
한 번에 하나의 세션
코드 리뷰
Review Pane으로 시각적 확인
터미널에서 diff 확인
Git 워크플로
Worktree 자동 생성, PR 연동
Git 명령 직접 실행
자동화
Automations 규칙 설정
셸 스크립트로 조합
커스터마이징
Settings UI, Skills 지원
~/.codex/config.toml, AGENTS.md, CLI 플래그
적합한 경우
팀 협업, 멀티태스킹, 비주얼 리뷰
빠른 단일 작업, CI 통합, 스크립트

Codex App이 할 수 있는 일 / 할 수 없는 일

할 수 있는 일

  • 버그 분석 및 수정
  • 새 기능 구현 및 코드 리팩토링
  • 테스트 코드 작성 및 실행
  • PR 생성 및 리뷰 대응
  • 여러 작업을 병렬로 동시 처리
  • Git Worktree 자동 관리
  • 프로젝트 구조 분석 및 설명
  • Automations로 반복 작업 자동화
  • In-app browser로 로컬 미리보기와 공개 페이지 확인
  • macOS Computer Use로 승인된 앱 조작

할 수 없는 일

  • 기존 브라우저 쿠키, 로그인 세션, 확장 프로그램 재사용
  • 사용자 승인 없는 자격증명·비밀키 접근
  • 샌드박스 밖 로컬 파일 무제한 접근
  • 사용자 승인 없는 앱 클릭·입력·화면 제어
  • 지역·플랜에 따라 일부 기능(예: Cloud Threads, Computer Use)이 제한될 수 있음 — 정확한 제공 범위는 공식 안내 확인
  • GPU 모델 학습이나 장기 상주 서비스 운영
  • 운영 데이터베이스 무승인 직접 조작
  • 팀 정책을 우회한 네트워크·권한 확대

최신 공식 업데이트

최근 문서 변경 반영

2026년 6월 기준 공식 문서와 개발자 홈페이지에서 확인되는 변화 중, 현재 가이드에 직접 영향을 주는 항목만 추려 반영했습니다.

한눈에 이해하기

Codex 운영 인포그래픽 14개

로그인, 실행 모드, 리뷰, worktree, 자동화, 브라우저, 승인 정책, AGENTS.md, MCP까지 실제 사용 흐름을 시각적 단계 카드로 정리했습니다.

공식 문서 대조 보완

반영한 개선 항목 90+

OpenAI 공식 Codex 문서의 앱, Review, Worktrees, Local environments, Automations, Settings, Commands, Windows, Troubleshooting, In-app browser, Computer Use 내용을 대조해 누락되기 쉬운 운영 포인트를 보강했습니다. 추가로 Web search, 이미지 생성/입력, Chats, 알림, 전원 설정, 자동화 보안 모델, 로그 공유 기준, config.toml, Rules, AGENTS.md, MCP, 인증, 원격 연결, Hooks까지 확장했습니다.