VSCode에서 OpenAI Codex 쓰는 법 — Copilot 그 다음 단계

Copilot이 자동완성의 끝판왕이라고 생각했는데, Codex를 써보니까 레벨이 다르다. Copilot이 "이 줄 다음에 뭐가 올까?" 를 맞추는 거라면, Codex는 "이 프로젝트에서 이 기능을 구현하려면 어떤 파일을 어떻게 고쳐야 하는지" 를 통째로 처리하는 에이전트다. 파일 읽고, 수정하고, 터미널 명령어까지 실행한다.

처음에 "이게 Copilot이랑 뭐가 다르다는 거지?" 했는데, 한번 써보면 안다. 차원이 다른 물건이다. VSCode에서 Codex 세팅하는 법을 처음부터 끝까지 정리해본다.

---

Codex가 정확히 뭔데

OpenAI가 만든 코딩 에이전트다. 이름이 같아서 헷갈릴 수 있는데, 2023년에 없어진 옛날 Codex API와는 완전히 다른 제품이다. 2025년 4월에 CLI로 처음 나왔고, 지금은 VSCode 확장 프로그램, 데스크톱 앱, ChatGPT 웹 버전까지 다양한 형태로 쓸 수 있다.

핵심 특징:

• 프로젝트 전체 코드베이스를 읽고 이해한다
• 여러 파일을 동시에 수정할 수 있다
• 터미널 명령어를 직접 실행한다 (빌드, 테스트, Git 등)
• 샌드박스 안에서 안전하게 동작한다
• Codex Cloud로 클라우드에서 비동기 작업도 가능하다

2026년 3월 기준으로 주간 활성 사용자가 200만 명을 넘었다고 한다. 확실히 주변에서 쓰는 사람이 부쩍 늘었다.

---

설치 전 준비물

1. ChatGPT 유료 구독

Codex는 무료 플랜에서 사용할 수 없다. 다음 플랜 중 하나가 필요하다:

ChatGPT Plus       — 기본 Codex 사용 가능
ChatGPT Pro        — 더 많은 사용량
Business / Edu     — 팀/교육용
Enterprise         — 기업용

주의할 점은 ChatGPT 구독이라는 거다. OpenAI API 크레딧과는 별개다. ChatGPT Plus($20/월)만 있으면 Codex를 쓸 수 있다.

2. 운영체제

• macOS
• Windows (네이티브 + WSL 둘 다 지원)
• Linux

이전에는 Windows에서 WSL이 필수였는데, 지금은 Windows 네이티브 샌드박스도 지원한다. 다만 Linux 네이티브 환경이 필요한 프로젝트라면 WSL을 쓰는 게 낫다.

3. VSCode

당연히 필요하다. Cursor, Windsurf 같은 VSCode 포크에서도 동작한다.

---

Step 1: Codex CLI 설치

VSCode 확장 프로그램은 CLI 위에서 동작한다. CLI부터 깔아야 한다.

macOS / Linux

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

패키지 매니저로 설치

# macOS (Homebrew)
brew install openai-codex

# npm
npm install -g @openai/codex

설치 확인:

codex --version

버전 번호가 나오면 성공이다.

첫 로그인

codex

처음 실행하면 로그인 프롬프트가 뜬다. ChatGPT 계정으로 인증하면 된다. API 키로도 인증 가능하다.

---

Step 2: VSCode 확장 프로그램 설치

1. VSCode 열기
2. Cmd+Shift+X (Mac) 또는 Ctrl+Shift+X (Windows/Linux)
3. "Codex" 검색
4. OpenAI 공식 배포본의 [Install] 클릭

Cursor나 Windsurf를 쓰고 있다면 해당 마켓플레이스에서 검색하면 된다.

설치 후 VSCode를 재시작하면 사이드바에 Codex 아이콘이 나타난다.

💡 팁: 확장 프로그램이 CLI 설정(~/.codex/config.toml)을 공유한다. CLI에서 이미 로그인했으면 확장 프로그램에서 따로 인증할 필요 없다.

---

Step 3: 기본 사용법

Codex 패널 열기

VSCode에서 Codex를 여는 방법:

• 사이드바의 Codex 아이콘 클릭
• 명령 팔레트(Cmd+Shift+P) → "Codex" 검색

패널이 열리면 채팅 입력창에 자연어로 요청하면 된다.

승인 모드(Approval Mode) — 이게 핵심이다

Codex는 세 가지 모드로 동작한다. 얼마나 자유를 줄지 내가 정할 수 있다.

Chat 모드

- 파일을 읽지 않는다
- 코드를 수정하지 않는다
- 명령어를 실행하지 않는다
- 그냥 대화만 한다

설계를 상의하거나 아키텍처를 논의할 때 쓴다. "이 구조에서 인증은 어떻게 하는 게 좋을까?" 같은 질문.

Agent 모드 (기본값)

- 파일을 읽을 수 있다
- 코드를 수정할 수 있다
- 작업 디렉토리 안에서 명령어를 실행할 수 있다
- 작업 디렉토리 밖이나 네트워크 접근은 승인 필요

대부분의 작업에서 이 모드를 쓴다. Codex가 알아서 파일을 읽고 수정하지만, 위험한 작업은 내 승인을 먼저 받는다. 신입 개발자한테 코드 리뷰 받는 느낌이랄까.

Agent (Full Access) 모드

- 파일 읽기/쓰기 자유
- 명령어 실행 자유
- 네트워크 접근도 자유
- 승인 없이 다 한다

완전 자율 모드. 뭘 하든 안 물어본다. 편하긴 한데, 신뢰할 수 있는 환경에서만 쓰자. 프로덕션 서버가 연결된 환경에서 Full Access 켜놓으면... 상상에 맡기겠다.

⚠️ 나는 기본적으로 Agent 모드를 쓰고, 반복적인 작업(테스트 실행, 빌드 같은)을 많이 시킬 때만 잠깐 Full Access로 바꾼다. 끝나면 바로 돌려놓는다.

---

실전에서 이렇게 쓴다

코드 작성 요청

"src/api/users.ts에 비밀번호 변경 API를 추가해줘. 
현재 비밀번호 확인 → 새 비밀번호 유효성 검사 → bcrypt로 해싱 → DB 업데이트 순서로."

Codex가 파일을 읽어서 기존 코드 스타일에 맞춰 구현해준다. 변경사항이 diff로 표시되고, 수락하면 적용된다.

버그 수정

"npm run test 돌리면 UserService.test.ts에서 3개 실패하는데, 고쳐줘."

이러면 Codex가 직접 테스트를 실행하고, 에러 메시지를 읽고, 원인을 분석해서 수정 코드를 제안한다. 테스트 코드가 잘못된 건지 실제 코드가 잘못된 건지까지 판단해준다.

리팩토링

"src/utils/ 폴더의 모든 함수를 TypeScript strict mode에 맞게 타입을 추가해줘."

여러 파일을 한 번에 수정해야 하는 작업에서 Codex가 진가를 발휘한다. 파일 하나하나 열어서 고치는 것보다 열 배는 빠르다.

코드 이해

새 프로젝트에 투입됐을 때 이게 진짜 유용하다.

"이 프로젝트의 전체 아키텍처를 설명해줘. 어떤 프레임워크를 쓰고, 
주요 모듈은 뭐고, 데이터 흐름이 어떻게 되는지."

README를 읽는 것보다 빠르고 정확하다. 코드를 직접 읽고 분석하니까.

Git 작업

"지금까지 변경한 내용으로 커밋해줘. 커밋 메시지는 conventional commit 형식으로."

"이 브랜치의 변경사항으로 PR 설명을 작성해줘."

---

Codex Cloud — 클라우드에서 비동기 작업

이게 Codex의 킬러 피처 중 하나다. 오래 걸리는 작업을 클라우드에서 돌릴 수 있다.

1. VSCode에서 작업 요청
2. "Run in the cloud" 선택
3. 환경 설정 (Node.js, Python 등)
4. Codex Cloud에서 작업 실행
5. 진행 상황을 IDE에서 실시간으로 확인
6. 완료되면 결과 리뷰 + 적용

예를 들어 "이 프로젝트의 테스트 커버리지를 80%까지 올려줘" 같은 작업을 던져놓고, 나는 다른 일을 하면 된다. 작업이 끝나면 알려주니까 그때 리뷰하면 된다.

로컬에서 돌리면 내 맥북이 몇 시간 동안 끙끙대야 할 작업을 클라우드에서 알아서 처리해준다.

---

AGENTS.md — 프로젝트별 지시사항

프로젝트 루트에 AGENTS.md 파일을 만들면 Codex가 해당 프로젝트에서 항상 참고하는 커스텀 지시사항이 된다. Claude Code의 CLAUDE.md와 같은 개념이다.

# AGENTS.md

## 프로젝트 정보
- Next.js 14 + TypeScript + Prisma + PostgreSQL
- 패키지 매니저: pnpm
- 테스트: Vitest + Testing Library

## 코딩 규칙
- 함수형 컴포넌트만 사용 (클래스 컴포넌트 금지)
- CSS는 Tailwind CSS만 사용
- API 응답 형식: { success: boolean, data?: T, error?: string }
- 에러 핸들링은 try-catch로 통일

## 명령어
- 개발 서버: pnpm dev
- 테스트: pnpm test
- 빌드: pnpm build
- 린트: pnpm lint

## 주의사항
- .env 파일은 절대 커밋하지 말 것
- DB 마이그레이션은 반드시 별도 PR로 올릴 것
- console.log는 프로덕션 코드에 남기지 말 것

이걸 써두면 매번 "pnpm 쓰고 있어", "Tailwind로 해줘" 같은 말을 반복하지 않아도 된다. 팀원 전체가 같은 AGENTS.md를 공유하면 Codex가 일관된 코드를 만들어준다.

---

샌드박스와 보안

Codex가 내 컴퓨터에서 명령어를 실행한다는 게 좀 무섭게 느껴질 수 있다. 나도 처음에 그랬다. 근데 보안 구조를 알고 나면 괜찮다.

샌드박스 모드

Codex는 OS 수준의 샌드박스 안에서 동작한다:

• 네트워크 접근: 기본적으로 차단. 필요하면 승인 필요.
• 파일 쓰기: 작업 디렉토리 안에서만 가능. 밖은 승인 필요.
• 민감한 경로: .git/이나 .codex/ 같은 경로는 쓰기 잠금.

그러니까 Codex가 갑자기 시스템 파일을 건드리거나, 몰래 네트워크 요청을 보내거나 하는 일은 없다. Agent 모드에서는 위험한 작업마다 "이거 해도 돼?" 하고 물어본다.

config.toml로 세부 설정

# ~/.codex/config.toml

# 기본 승인 정책
approval_policy = "on-request"

# 샌드박스 모드
sandbox_mode = "workspace-write"

# 파일 열기에 사용할 에디터
file_opener = "vscode"

보안 수준을 프로젝트별로 다르게 가져갈 수도 있다.

---

Copilot이랑 같이 쓸 수 있나?

쓸 수 있다. 역할이 다르니까 오히려 같이 쓰면 좋다.

Copilot  → 타이핑 중 실시간 자동완성. 한 줄, 두 줄 빠르게 채우기.
Codex    → "이 모듈 전체를 리팩토링해줘" 같은 대규모 에이전트 작업.

둘 다 켜놓고 쓰면 자동완성은 Copilot이 처리하고, 구조적인 작업은 Codex에게 맡기는 식으로 자연스럽게 분담된다. 나도 이 조합으로 쓰고 있다.

Claude Code와 비교하자면:

• Codex: ChatGPT 계정으로 쓸 수 있고, Codex Cloud(비동기 클라우드 작업)가 강점. Windows 네이티브 지원.
• Claude Code: Anthropic 계정 필요. 터미널 중심. 코드 품질은 체감상 비슷한데, 각자 잘하는 영역이 다르다.

둘 다 써봤는데, 결국 어느 쪽 계정/생태계에 더 익숙한지에 따라 선택하게 되는 것 같다.

---

자주 쓰는 슬래시 명령어

Codex 채팅창에서 /를 입력하면 슬래시 명령어를 쓸 수 있다.

/permissions     — 현재 승인 모드 확인/변경
/model           — 사용할 모델 변경
/goal            — 장기 목표 설정 (지속적으로 추적)
/compact         — 대화 기록 압축 (컨텍스트 절약)
/clear           — 대화 초기화

/goal은 꽤 유용한 기능인데, "이 프로젝트의 테스트 커버리지를 80%까지 올리기" 같은 장기 목표를 설정하면 Codex가 진행 상황을 추적해준다. 일시중지했다가 나중에 이어서 할 수도 있다.

---

자주 겪는 문제와 해결법

"codex: command not found"

CLI가 PATH에 안 잡힌 거다.

# 설치 경로 확인
which codex

# 없으면 재설치
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# shell 설정 새로고침
source ~/.zshrc  # 또는 source ~/.bashrc

확장 프로그램에서 로그인이 안 됨

# CLI에서 인증 상태 확인
codex auth

# 재인증
codex auth login

# 그래도 안 되면 설정 디렉토리 삭제 후 재시도
rm -rf ~/.codex/credentials*
codex auth login

환경 진단

뭔가 안 되는데 원인을 모르겠으면:

codex doctor

환경, Git, 터미널, 인증 상태를 전부 체크해서 알려준다. 이게 은근 유용하다.

Windows에서 환경변수 문제

Windows에서 VSCode를 앱 런처(시작 메뉴)로 열면 환경변수가 안 잡히는 경우가 있다. 터미널에서 code .로 VSCode를 열면 해결된다.

# 터미널에서 VSCode 실행
cd C:\Users\myuser\projects\myapp
code .

---

실전 팁

1. 작은 작업부터 시작하자

처음부터 "전체 프로젝트 리팩토링해줘" 이러면 결과가 정신없다. 파일 하나, 함수 하나부터 시작해서 Codex가 어떻게 동작하는지 감을 잡자.

2. Agent 모드로 시작하고, 필요할 때만 Full Access

기본 Agent 모드에서 대부분의 작업이 가능하다. Full Access는 반복적으로 승인 누르기 귀찮을 때만 쓰고, 작업 끝나면 바로 돌려놓자.

3. AGENTS.md를 잘 써두면 생산성이 배로 올라간다

프로젝트 컨벤션, 사용 기술 스택, 빌드 명령어 같은 걸 정리해두면 Codex가 처음부터 맥락을 이해한 상태에서 작업한다. 이 초기 세팅 시간이 나중에 열 배로 돌아온다.

4. diff는 꼭 확인하자

아무리 AI가 잘 해줘도 무조건 수락은 위험하다. diff를 확인하는 습관을 들이자. 특히 보안 관련 코드, DB 쿼리, 외부 API 호출 부분은 꼼꼼하게.

5. Codex Cloud를 적극 활용하자

테스트 전체 실행, 대규모 리팩토링, 문서 생성 같은 시간 오래 걸리는 작업은 클라우드에서 돌리자. 로컬 머신 리소스를 아낄 수 있다.

---

마무리

VSCode에서 Codex 쓰는 과정을 정리하면:

1. ChatGPT 유료 구독 확인 (Plus 이상)
2. Codex CLI 설치 (curl 한 줄)
3. VSCode 확장 프로그램 설치 (마켓플레이스에서 "Codex" 검색)
4. 로그인 (ChatGPT 계정)
5. 사이드바에서 Codex 패널 열고 사용 시작

핵심 정리:

• 세 가지 승인 모드(Chat, Agent, Full Access)를 상황에 맞게 쓰자
• 기본은 Agent 모드. 위험한 작업은 승인을 거치니까 안전하다
• AGENTS.md에 프로젝트 컨벤션을 써두면 반복 설명이 필요 없다
• Codex Cloud로 오래 걸리는 작업은 비동기로 던져놓을 수 있다
• Copilot과 같이 쓸 수 있다. 자동완성은 Copilot, 에이전트 작업은 Codex
• codex doctor로 환경 문제를 빠르게 진단할 수 있다