바이브코딩 · Codex

✅ 설치 확인

설치가 끝나면 터미널(PowerShell/터미널)에서 아래 명령으로 버전이 출력되는지 확인하세요.

node -v
npm -v
git --version
python --version

※ Windows에서 python이 안 되면 py --version을 써보세요. 명령이 안 잡히면 PATH 설정 후 터미널을 새로 여세요.

🖥️ Codex 데스크탑 앱 (Windows) — 추천

OpenAI 공식 Windows 데스크탑 프로그램입니다. 터미널 명령(CLI)이 아니라 마우스로 클릭해 쓰는 일반 윈도우 앱이에요. 여러 작업을 동시에 돌리는 worktree, Git 변경 리뷰 패널, 자동화, 인앱 브라우저가 들어 있습니다. (2026년 출시)

• 요구사항: Windows 10 (버전 19041.0) 이상
• 계정: ChatGPT 계정 (Free · Go · Plus · Pro 모두 가능)
• 실행 환경: 기본 PowerShell + Windows 샌드박스, 또는 설정에서 WSL2 선택

또는 터미널(PowerShell)에서 winget으로 설치:

winget install Codex -s msstore

Codex 크롬 확장앱 OpenAI 공식

Codex가 로그인된 크롬 브라우저로 웹 작업을 직접 수행하게 해주는 공식 확장앱입니다. 데스크탑 앱과 함께 쓰는 플러그인이에요.

• 로그인이 필요한 사이트(Gmail · 노션 · CRM · 사내 도구 등)에서 리서치·폼 작성·대시보드 확인·다단계 작업
• 여러 탭·세션을 동시에 활용, 웹앱 테스트·DevTools 활용
• 내 브라우징을 가로채지 않고 별도 탭에서 작동, 민감한 작업 전엔 항상 승인 요청

설치 방법 — Codex 데스크탑 앱의 Plugins(플러그인) 메뉴에서 설치하는 것이 정석입니다. 또는 아래 버튼으로 웹스토어에서 직접 설치:

※ Chrome 전용(Edge·Brave·Arc 등 미지원). 현재 EU·UK는 지원 예정. 웹스토어에서 Chrome에 추가 → 확장 프로그램 추가 후 데스크탑 앱과 연결됩니다.

📥 데스크탑 앱 설치 & 첫 실행

위 버튼(또는 winget)으로 설치한 뒤 아래 순서대로 진행하세요. 터미널 명령 없이 마우스로 진행됩니다.

1. 설치 — Microsoft Store 페이지에서 받기/설치를 누릅니다. (보안 경고가 뜨면 허용)
2. 실행 — 설치 후 시작 메뉴 → Codex를 클릭해 앱을 엽니다.
3. 로그인 — ChatGPT 계정으로 로그인합니다. (Free/Go/Plus/Pro 모두 가능)
4. 실행 환경 선택 — 기본은 PowerShell + Windows 샌드박스. 리눅스 기반 프로젝트면 설정에서 WSL2로 바꾸고 앱을 재시작합니다.
5. 프로젝트 열기 — Ctrl+O로 작업할 폴더를 엽니다. 선호 에디터(VS Code 등)·터미널·샌드박스 권한은 설정에서 조정합니다.
6. 작업 시작 — 자연어로 지시하면 Codex가 작업하고, Git 리뷰 패널에서 변경 내용을 확인·승인합니다. worktree로 여러 작업을 동시에 돌릴 수 있습니다.

권장 개발 도구도 함께 설치해 두면 좋습니다 (PowerShell에서):

winget install Git.Git
winget install OpenJS.NodeJS.LTS
winget install Python.Python.3.14
winget install GitHub.cli

문제 해결 · 권한 부족 시 앱을 관리자 권한으로 실행 · PowerShell 실행 정책 오류 시 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned · WSL에서 Windows 앱과 로그인 공유: CODEX_HOME=/mnt/c/Users/<사용자>/.codex

1) 첫 실행 & 로그인

1. 시작 메뉴에서 Codex 실행
2. ChatGPT 계정으로 로그인 (Free·Go·Plus·Pro 모두 가능)
3. 로그인하면 작업 화면(메인 대시보드)이 열립니다

2) 프로젝트 열기

작업할 폴더(프로젝트)를 앱에 추가합니다.

• Ctrl+O → 폴더 선택 (Windows 폴더 또는 WSL 경로)
• 처음이면 빈 폴더를 하나 만들어 열어도 됩니다 (예: 내문서\codex-test)

3) 작업 지시 & 승인 (핵심)

화면 아래 입력창(Composer)에 자연어로 지시하면 Codex가 작업을 시작합니다.

• 예: "간단한 할 일 목록 웹페이지를 만들어줘"
• Codex가 파일을 만들거나 명령을 실행하기 전, 승인(Approve) 창이 뜹니다 → 확인 후 승인
• 승인 수준(읽기 전용 / 작업폴더 편집 / 전체)은 화면에서 바꿀 수 있습니다. 처음엔 보수적으로 두세요.

4) 변경 내용 확인 — Git 리뷰 패널

Codex가 코드를 바꾸면 Git 리뷰 패널에서 변경된 부분(diff)을 색으로 보여줍니다.

• 바뀐 파일·줄을 눈으로 확인 → 마음에 들면 적용(커밋), 아니면 되돌리기
• Git이 설치돼 있으면 변경 이력 관리가 더 편합니다 (환경 설치 탭 참고)

5) 여러 작업 동시에 — Worktrees

하나의 프로젝트에서 여러 작업을 동시에 진행할 수 있습니다. 한 작업이 도는 동안 다른 작업을 시작해 두면 시간을 아낄 수 있어요.

6) 반복 작업 — 자동화(Automations)

자주 하는 작업(테스트 실행, 린트 정리 등)을 자동화로 등록해 반복 실행할 수 있습니다.

7) 설정

• 에디터: VS Code 등 선호 에디터 연결
• 터미널/실행 환경: PowerShell(기본) 또는 WSL2
• 샌드박스 권한: 기본 권한으로 안전하게, 필요 시 예외 규칙 추가

8) 크롬 확장앱 연동

앱의 Plugins(플러그인) 메뉴에서 크롬 확장앱을 설치하면, 로그인된 브라우저에서 리서치·폼 작성 등 웹 작업도 Codex가 대신 해줍니다. (설치는 "Codex 앱 설치" 탭 참고)

1) 설치 (터미널 / npm)

npm install -g @openai/codex

설치 확인:

codex --version

2) 실행 & 로그인

작업할 프로젝트 폴더에서 실행합니다.

cd my-project
codex

처음 실행하면 인증을 묻습니다. 두 가지 방법 중 하나를 선택하세요.

• ChatGPT 계정 로그인 — 브라우저로 로그인 (Plus/Pro 등 구독 활용)
• API Key — OpenAI Platform에서 발급한 키 사용

# API Key 방식 (환경변수)
# macOS / Linux
export OPENAI_API_KEY="sk-..."
# Windows PowerShell
$env:OPENAI_API_KEY="sk-..."

3) 첫 작업 실행

codex "이 프로젝트에 README를 만들어줘"

Codex가 변경 사항을 제안하면 승인(approval)하여 적용합니다.

1. 시스템 요구사항

• OS: macOS · Linux · Windows(WSL2 권장)
• Node.js: LTS(18+ 권장) — npm 설치 시 필요
• 계정: ChatGPT 계정(Plus/Pro/Team 등) 또는 OpenAI API Key
• Git: 변경 추적·되돌리기에 권장

2. 설치 & 업데이트

npm 전역 설치(권장) 또는 Homebrew를 사용합니다.

# npm (모든 OS)
npm install -g @openai/codex

# 또는 Homebrew (macOS/Linux)
brew install codex

버전 확인 & 최신 업데이트:

codex --version
npm install -g @openai/codex@latest

3. 인증 (로그인)

두 가지 방식 중 하나로 인증합니다. 처음 codex를 실행하면 로그인 화면이 안내됩니다.

# API Key 방식
# macOS / Linux
export OPENAI_API_KEY="sk-..."
# Windows PowerShell
$env:OPENAI_API_KEY="sk-..."

※ 로그인 정보는 보통 ~/.codex/auth.json에 저장됩니다. 공용 PC에서는 작업 후 로그아웃하세요.

4. 실행 방식 — 대화형 vs 비대화형

대화형(TUI): 프로젝트 폴더에서 codex를 실행해 대화하며 작업합니다.

cd my-project
codex
# 또는 첫 지시를 바로 전달
codex "이 레포 구조를 설명하고 README를 만들어줘"

비대화형(exec): 스크립트·CI에서 한 번에 실행하고 끝냅니다.

codex exec "린트 에러를 모두 고치고 결과를 요약해줘"

※ 서브커맨드 이름(exec 등)은 버전에 따라 다를 수 있습니다.

5. 승인(Approval) & 샌드박스 — 가장 중요

Codex가 파일 편집·명령 실행을 어디까지 자동으로 할지 정하는 안전장치입니다. 처음엔 보수적으로, 익숙해지면 자동화 수준을 높이세요.

# 안전하게 시작 (읽기 전용)
codex --sandbox read-only

# 작업 폴더 자동 편집 + 실패 시만 승인 (편의 플래그)
codex --full-auto

# 위험: 전체 권한 (신뢰된 환경에서만)
codex --sandbox danger-full-access --ask-for-approval never

※ --full-auto는 대략 workspace-write + on-failure의 단축입니다. 정확한 조합·기본값은 codex --help로 확인하세요.

6. 설정 파일 & AGENTS.md

전역 설정은 ~/.codex/config.toml에, 프로젝트별 작업 지침은 레포 루트의 AGENTS.md에 둡니다. (Claude Code의 CLAUDE.md와 같은 역할)

# ~/.codex/config.toml 예시
model = "gpt-5-codex"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

# 프로젝트 루트 AGENTS.md 예시
- 패키지 매니저는 pnpm을 사용한다
- 커밋 메시지는 Conventional Commits 형식
- 테스트는 vitest로 작성한다

※ 키 이름은 버전에 따라 다를 수 있습니다. TUI에서 /init으로 AGENTS.md 초안을 생성할 수 있습니다.

7. 모델 선택 & 추론 강도

작업 난이도에 맞춰 모델을 바꿉니다. 복잡한 설계·디버깅은 상위 모델, 단순 편집은 빠른 모델을 사용하세요.

codex -m gpt-5-codex "이 함수 성능을 개선해줘"
# 설정 파일에 고정: model = "gpt-5-codex"

※ 사용 가능한 모델명·추론 강도 옵션은 계정·버전에 따라 다릅니다.

8. 대화형(TUI) 슬래시 명령

※ 제공되는 슬래시 명령은 버전마다 다릅니다. 세션에서 /를 입력해 목록을 확인하세요.

9. MCP 서버 연동 (확장)

Codex도 MCP(Model Context Protocol)로 외부 도구·데이터에 연결할 수 있습니다. ~/.codex/config.toml에 서버를 등록합니다.

# ~/.codex/config.toml
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path"]

※ 설정 형식은 버전에 따라 다를 수 있습니다.

10. 문제 해결

📚 공식 문서

명령·플래그·설정은 버전마다 바뀌므로 최신 정보는 공식 자료를 확인하세요.

• GitHub: github.com/openai/codex
• 개발자 문서: developers.openai.com/codex/cli
• 터미널에서: codex --help

주요 명령 & 플래그

※ 명령·슬래시 구문은 Codex CLI 버전에 따라 달라질 수 있습니다. 항상 codex --help를 기준으로 확인하세요.

인증 관련