1. 설치와 첫 메시지

이 페이지에서 배우는 것

• 1 Codex app이 무엇인지, 그리고 ChatGPT 웹 버전과 어떻게 다른지 이해합니다.
• 2 내 컴퓨터에 Codex app을 설치하고, 로그인하는 방법을 배웁니다.
• 3 프로젝트 폴더를 열고, AI에게 첫 번째 작업 메시지를 보내는 전체 흐름을 따라합니다.
• 4 작업 전에 꼭 해야 하는 Git(코드 버전 관리 도구) 체크포인트 만드는 법을 익힙니다.

Codex가 뭔가요?

Codex app은 OpenAI가 만든 AI 코딩 어시스턴트(도우미) 프로그램입니다. 여러분이 평소에 사용하는 카카오톡이나 Slack처럼 채팅 창에 메시지를 입력하면, AI가 답변을 해주는 형태입니다. 하지만 단순한 채팅봇(chatbot)과는 결정적인 차이가 있습니다.

일반 ChatGPT 웹사이트에서는 "이런 코드를 작성해줘"라고 부탁하면, AI가 코드를 텍스트로 보여주기만 합니다. 그러면 여러분이 그 코드를 직접 복사해서, 파일을 열고, 붙여넣기 해야 합니다. 마치 요리법을 알려주기만 하고 실제로 요리는 해주지 않는 것과 비슷합니다.

반면 Codex app은 여러분의 컴퓨터에 있는 프로젝트 파일을 직접 읽고, 수정하고, 새로운 파일을 만들 수 있습니다. 요리법을 알려주는 것이 아니라, 직접 주방에 들어와서 요리를 해주는 셰프와 같습니다. "이 파일의 버그를 고쳐줘"라고 말하면, 실제로 그 파일을 열어서 코드를 수정해 줍니다. 그래서 코딩 경험이 적은 분들도 자연어(한국어, 영어 등)로 지시만 하면 많은 작업을 자동으로 처리할 수 있습니다.

이 프로젝트가 어떤 일을 하는 프로그램인지 한국어로 5줄 이내로 요약해 줘.
주요 폴더 구조와 진입점 파일도 함께 알려 줘. 코드는 아직 수정하지 마.

Codex 설치 경로 4가지

공식 Quickstart는 Codex를 사용할 수 있는 4가지 진입점을 안내합니다. 이 가이드는 그중 Codex App을 중심으로 설명하지만, 같은 ChatGPT 계정으로 다른 진입점에서도 동일한 작업을 이어갈 수 있습니다.

나는 [macOS / Windows] 사용자이고, 평소 [VS Code / Cursor / 터미널 / 브라우저]에서 일해.
코딩 경험은 [입문 / 중급 / 숙련]이고, 주로 하는 작업은 [예: 블로그 운영, 사이드 프로젝트, 회사 프로덕트].
이 환경에서 Codex 4가지 진입점(App / IDE Extension / CLI / Cloud) 중
어떤 걸 1순위로 깔고, 2순위로 보조로 쓰면 좋을지 이유와 함께 추천해 줘.

Quickstart 흐름: 4단계로 시작하기

Codex app을 처음 사용하는 과정은 아래 4단계로 요약됩니다. 마치 새 앱을 스마트폰에 설치하고, 로그인하고, 사용하는 것과 같은 흐름입니다. 각 단계를 순서대로 진행하면 5분 안에 첫 작업을 시작할 수 있습니다.

Step 1. 앱 설치 - 자세히 알아보기

먼저 openai.com/codex 페이지에 접속합니다. macOS는 Apple Silicon과 Intel 두 빌드를 별도로 제공하므로, 자기 Mac에 맞는 다운로드 버튼을 누르세요. Windows는 단일 빌드입니다.

macOS 사용자라면 .dmg 파일이 다운로드되고, Windows 사용자라면 .exe 파일이 다운로드됩니다. VS Code, Slack, Discord 같은 프로그램을 설치해 본 적이 있다면, 완전히 같은 방식입니다. 다운로드된 파일을 더블클릭해서 설치 과정을 따르면 됩니다.

macOS Homebrew 사용자라면 터미널에서 brew install codex 한 줄로도 설치할 수 있습니다 (공식 Quickstart에 명시).

설치가 완료되면 Codex app 아이콘이 응용 프로그램 목록(macOS의 Launchpad, Windows의 시작 메뉴)에 나타납니다. 클릭해서 실행하면 로그인 화면이 표시됩니다.

Step 2. 로그인 - 자세히 알아보기

Codex app에 로그인하는 방법은 두 가지입니다. 하나는 ChatGPT 구독 계정으로 로그인하는 것이고, 다른 하나는 API 키(API Key)를 입력하는 것입니다.

ChatGPT 구독 계정은 공식 Quickstart의 "Every ChatGPT plan includes Codex" 안내를 기준으로 사용할 수 있습니다. 다만 2026년 6월 기준 개발자 홈페이지는 Free/Go 한시 제공과 Plus·Pro·Business·Enterprise의 2x Codex rate limits를 별도로 강조하고 있으므로, 고정 플랜 목록보다 최신 공식 안내를 함께 확인하는 편이 정확합니다. 평소 ChatGPT 웹사이트에 로그인할 때 사용하는 이메일과 비밀번호를 그대로 사용하면 됩니다. 넷플릭스 계정으로 TV 앱에 로그인하는 것과 비슷합니다.

API 키는 조금 다른 개념입니다. API 키란 OpenAI가 여러분에게 발급해주는 특별한 비밀번호 같은 것입니다. platform.openai.com에서 직접 만들 수 있습니다. API 키 방식은 사용한 만큼만 비용을 지불하는 종량제 형태이며, 주로 회사에서 비용을 세밀하게 관리하고 싶을 때 사용합니다. 처음 시작하는 개인 사용자라면 ChatGPT 구독 로그인이 더 간편합니다.

Step 3. 프로젝트 선택 - 자세히 알아보기

"프로젝트 폴더"란 여러분의 코드 파일들이 들어 있는 폴더를 말합니다. 예를 들어 내문서/my-website 폴더 안에 HTML, CSS, JavaScript 파일들이 있다면, 그 my-website 폴더가 바로 프로젝트 폴더입니다.

Codex app에서 "Open Project" 또는 "프로젝트 열기"를 클릭하면, macOS에서는 Finder(파인더), Windows에서는 파일 탐색기(File Explorer)가 열립니다. 여기서 원하는 폴더를 선택하면 됩니다. 마치 워드(Word)에서 "파일 열기"를 하는 것과 같은 느낌입니다.

한 번 열었던 프로젝트는 Codex가 기억하고 있기 때문에, 다음에 앱을 열면 최근에 작업한 프로젝트 목록에서 바로 선택할 수 있습니다. 매번 폴더를 다시 찾을 필요가 없습니다.

Step 4. 첫 메시지 보내기 - 자세히 알아보기

프로젝트를 열면 화면 하단에 Composer(컴포저)라는 입력창이 보입니다. 이것은 카카오톡의 메시지 입력창과 비슷합니다. 여기에 AI에게 시키고 싶은 작업을 한국어 또는 영어로 자유롭게 적으면 됩니다.

메시지를 보내기 전에 Composer 하단에서 "Local"이 선택되어 있는지 확인하세요. Local 모드는 여러분의 컴퓨터에서 직접 작업하는 모드입니다. 처음 시작할 때는 이 모드가 가장 간단하고 안전합니다.

어떤 메시지를 보내야 할지 모르겠다면, 아래 예시들을 참고하세요. 처음에는 간단한 질문부터 시작하는 것을 추천합니다:

@README.md 파일을 자연스러운 한국어로 번역해 줘.
- 코드 블록과 명령어, 링크 URL은 원문 그대로 유지
- 기술 용어(예: API, deployment)는 번역 + 괄호 안에 영어 병기
- 헤딩 구조와 목차는 원본과 동일하게 유지
- README.md 한 파일만 수정하고, 다른 파일은 건드리지 마

컴포저에 컨텍스트 추가하기 (@file / @symbol / 이미지)

긴 설명 대신 참조 토큰을 쓰면 Codex가 정확히 어떤 코드를 봐야 하는지 바로 압니다(공식 features 문서).

• ✓@를 입력하면 파일 자동완성이 뜹니다 — @src/app.ts처럼 적으면 해당 파일이 컨텍스트로 첨부됩니다.
• ✓@ 뒤에 함수·클래스 이름을 입력하면 심볼 단위로 참조할 수 있습니다 — @calculateTotal.
• ✓스크린샷·UI 모형 등 이미지를 컴포저에 드래그&드롭하면 시각 컨텍스트로 함께 전달됩니다.

@src/utils/date.js 파일의 @formatKoreanDate 함수만 봐 줘.
- 입력이 null이거나 빈 문자열일 때 "날짜 없음"을 반환하도록 가드(guard) 추가
- 기존 인터페이스(파라미터, 리턴 타입)는 절대 바꾸지 말 것
- 같은 파일에 간단한 단위 테스트 케이스 3개를 주석으로 적어 줘

플랫폼 및 로그인 지원 현황

Codex app은 현재 macOS(맥)와 Windows(윈도우) 두 가지 운영체제를 지원합니다. 로그인 방식도 두 가지를 지원하므로, 자신에게 맞는 방식을 선택하면 됩니다.

ChatGPT 로그인 vs API 키 로그인 비교

로그인 방식에 따라 사용할 수 있는 기능 범위가 달라집니다. 쉽게 말해, ChatGPT 구독 로그인은 "정액제 뷔페"이고, API 키 로그인은 "먹은 만큼 내는 식당"이라고 생각하면 됩니다. 아래 표에서 주요 차이점을 확인하세요.

어떤 로그인을 선택해야 할까요?

두 가지 로그인 방식 중 어떤 것을 선택해야 할지 고민된다면, 아래 가이드를 참고하세요. 대부분의 개인 사용자에게는 ChatGPT 구독 로그인이 더 간편합니다.

핵심 포인트

• 1 Quickstart 문서 기준으로 Codex는 ChatGPT 구독 또는 API 키 로그인 모두 지원합니다. 두 방식 모두 Local 모드에서의 기본 기능은 동일합니다.
• 2 앱 설치 후 프로젝트 폴더를 선택하면 과거에 작업했던 프로젝트도 다시 열 수 있습니다. 매번 폴더를 다시 찾을 필요 없이, 최근 프로젝트 목록에서 바로 클릭할 수 있습니다.
• 3 첫 메시지를 보내기 전에 Composer(입력창)에서 Local이 선택되어 있으면 현재 머신에서 작업합니다. 이 모드에서는 여러분의 컴퓨터에 있는 파일을 직접 읽고 수정합니다.
• 4 API 키 로그인 시 일부 기능, 특히 Cloud Threads(클라우드에서 실행되는 작업)는 공식 Quickstart의 "might not be available" 안내처럼 아예 사용 불가할 수 있습니다. 처음에는 Local 모드만 사용해도 충분합니다.

지금 너의 실행 모드(Local/Cloud), 현재 워킹 디렉터리, 그리고 네가 변경 권한을 가진 파일 범위가 무엇인지
한국어로 정리해 줘. 이번 세션에서 절대 건드리면 안 되는 폴더로
.git, node_modules, .env*, dist, build 를 추가해 줘. 다음 메시지부터 이 규칙을 지켜.

Git 체크포인트: 왜 필요하고, 어떻게 만드나요?

Codex를 사용하기 전에 반드시 알아야 할 것이 하나 있습니다. 바로 Git(깃)이라는 도구입니다. Git이 낯설게 느껴질 수 있지만, 개념은 의외로 간단합니다.

왜 Git이 필요한가요? Codex app은 여러분의 프로젝트 파일을 직접 수정할 수 있기 때문입니다. AI가 코드를 잘못 수정하거나, 의도하지 않은 방향으로 바꿀 수도 있습니다. 이때 Git 체크포인트가 있으면, "수정하기 전 상태"로 안전하게 되돌릴 수 있습니다. 보험에 가입하는 것과 같다고 생각하면 됩니다.

git commit(깃 커밋)이란, 현재 프로젝트의 상태를 스냅샷(snapshot)으로 저장하는 것입니다. 스마트폰으로 사진을 찍어두는 것과 비슷합니다. 한 번 커밋하면 그 시점의 모든 파일 상태가 기록됩니다.

아래는 터미널(Terminal, 명령어 입력 창)에서 Git 체크포인트를 만드는 가장 기본적인 명령어입니다. macOS에서는 "터미널" 앱을, Windows에서는 "명령 프롬프트" 또는 "PowerShell"을 열어서 입력하면 됩니다:

현재 작업 트리에 변경된 게 있다면 git status로 보여주고,
변경이 있을 경우에만 "chore: Codex 작업 시작 전 체크포인트" 라는 메시지로 커밋해 줘.
변경이 없으면 그냥 "변경 없음"이라고만 답하고 아무 것도 만들지 마.

Git 설치부터 GitHub 연동까지: 완전 가이드

Git을 설치했다고 해서 바로 GitHub에 코드를 올릴 수 있는 것은 아닙니다. Git은 내 컴퓨터에서 버전을 관리하는 도구이고, GitHub(깃허브)는 인터넷에 있는 코드 저장소 서비스입니다. 이 둘을 연결하는 중간 과정이 필요합니다. 아래 단계를 순서대로 따라하면 처음부터 끝까지 완료할 수 있습니다.

Step 1. Git 설치하기

먼저 내 컴퓨터에 Git이 설치되어 있는지 확인합니다. 터미널(macOS) 또는 명령 프롬프트/PowerShell(Windows)을 열고 아래 명령어를 입력하세요:

Git이 설치되어 있지 않다면, 운영체제에 맞게 설치합니다:

Step 2. Git 사용자 정보 설정하기 (필수)

Git을 처음 설치하면, "나는 누구인지"를 Git에게 알려줘야 합니다. 이것은 나중에 코드를 수정할 때 "누가 이 변경을 했는지" 기록으로 남기기 위해서입니다. 회사 이메일을 쓸 필요는 없고, 아무 이름/이메일이나 괜찮습니다. 단, GitHub에 가입할 이메일과 같은 이메일을 쓰면 나중에 연동이 더 자연스럽습니다.

Step 3. GitHub 계정 만들기

github.com에 접속하여 무료 계정을 만듭니다. 이메일, 비밀번호, 사용자 이름(username)만 있으면 됩니다. GitHub 무료 계정으로도 코드를 무제한으로 저장하고 공개/비공개 프로젝트를 만들 수 있습니다.

Step 4. 내 컴퓨터에서 GitHub 인증 설정하기

이 단계가 가장 많은 초보자가 놓치는 부분입니다. Git을 설치하고, GitHub 계정을 만들었다고 해서 바로 코드를 올릴 수 있는 것이 아닙니다. 내 컴퓨터가 "나는 이 GitHub 계정의 주인이다"라고 증명해야 합니다. 이것을 인증(Authentication)이라고 합니다.

인증 방법은 크게 세 가지가 있는데, 초보자에게 가장 쉬운 순서대로 소개합니다:

GitHub CLI를 이용한 인증 전체 과정을 터미널에서 따라해 보세요:

Step 5. GitHub에 저장소 만들고 코드 올리기

이제 모든 준비가 끝났습니다! 내 컴퓨터의 프로젝트를 GitHub에 올리는 과정을 따라해 봅시다. 크게 두 가지 상황이 있습니다:

상황 A: 새 프로젝트를 처음 올리기

상황 B: Codex로 수정한 내용을 GitHub에 올리기

이미 GitHub에 연결된 프로젝트에서 Codex가 코드를 수정한 후, 변경사항을 올리는 방법입니다:

전체 흐름 한눈에 보기

Git 설치부터 GitHub에 코드를 올리기까지의 전체 과정을 정리하면 다음과 같습니다:

이 폴더를 GitHub의 새 비공개 저장소로 올려 줘. 절차:
1) git status로 현재 상태 보여주기
2) .gitignore가 없다면 내 프로젝트 종류에 맞게 생성
3) git init이 안 되어 있다면 초기화
4) "feat: initial commit" 메시지로 첫 커밋
5) gh repo create <폴더명> --private --source=. --push 로 업로드
각 단계마다 어떤 명령을 왜 실행했는지 한 줄로 설명한 뒤 다음 단계로 넘어가 줘.
실패하면 멈추고 원인을 한국어로 알려 줘.

실전 팁

Codex app을 처음 사용할 때 알아두면 좋은 팁들을 모았습니다. 특히 코딩 경험이 많지 않은 분들은 아래 내용을 꼭 읽어보세요.

내가 하고 싶은 일: [예: src/ 아래 코드 스타일을 통일하고 싶어]
지금은 코드를 바꾸지 말고, 다음만 해 줘:
1) 작업을 5단계 이내로 쪼갠 실행 계획 제안
2) 각 단계마다 영향 받는 파일 수 추정
3) 각 단계가 실패하면 어떻게 롤백할지 한 줄씩
계획에 동의하면 내가 "1단계 시작" 이라고 다시 말할게.

Composer 모드 안내

첫 메시지를 보내기 전에 Composer(입력창) 하단에서 실행 모드를 확인하세요. Local 모드가 선택되어 있으면 현재 내 컴퓨터에서 직접 코드를 수정합니다. Cloud 모드는 OpenAI의 원격 서버에서 작업하는 방식으로, 더 복잡한 설정이 필요할 수 있습니다.

첫 번째 작업 예시: 단계별 따라하기

실제로 Codex app을 사용하는 과정을 구체적인 시나리오로 따라해 봅시다. 여기서는 "프로젝트의 README 파일을 한국어로 번역하기"를 예시로 들겠습니다. README(리드미) 파일은 프로젝트를 설명하는 문서로, 대부분 영어로 작성되어 있습니다.

아래 작업을 순서대로 진행해 줘. 각 단계 결과를 한 줄로 보고하면서 진행해.

1) 현재 폴더에 README.md 가 있는지 확인. 없다면 멈추고 "README 없음" 알려 줘.
2) 변경 전 백업: 변경된 파일이 있으면 "chore: 번역 전 체크포인트" 메시지로 커밋.
3) README.md 를 자연스러운 한국어로 번역. 코드 블록·링크·이미지는 그대로 유지.
4) 기술 용어는 번역 + 괄호 안 영어 병기 (예: 배포(deployment)).
5) 번역 후 README.md 원본/번역본 길이를 줄 수 단위로 비교해 알려 줘.
6) 다른 파일은 절대 수정하지 마.

자주 묻는 질문 (FAQ)

Codex app을 처음 접하는 분들이 자주 궁금해하는 질문과 답변을 모았습니다.

이 프로젝트에서 비밀로 다뤄야 할 값(API 키, 비밀번호, 토큰, 개인정보, 내부 URL 등)이
소스 코드나 설정 파일에 하드코딩돼 있는지 점검해 줘.
- 의심 패턴: sk-, ghp_, AIza, AKIA, password=, secret=, BEGIN RSA PRIVATE KEY 등
- 발견하면 파일·줄 번호·발견 사유를 표로 보여 줘
- 절대 수정하지 말고 보고만 해
- 마지막에 .gitignore 와 환경변수(.env) 분리 권고도 한국어로 정리해 줘

다음 단계

첫 메시지를 성공적으로 보냈다면, 이제 Codex app의 더 많은 기능을 탐색해 볼 차례입니다. 아래 순서대로 학습하면 Codex를 더 효과적으로 활용할 수 있습니다.

• 프로젝트와 멀티태스킹 - 여러 프로젝트를 동시에 관리하고, 하나의 프로젝트에서 여러 작업을 병렬로 실행하는 방법을 배웁니다.
• Review Pane로 변경 검토하기 - Codex가 수정한 코드를 검토하고, 수락하거나 되돌리는 방법을 익힙니다. 초보자에게 특히 중요합니다.
• Settings에서 조정할 수 있는 것 - 자주 사용하는 설정을 조정해서 나만의 작업 환경을 만드는 방법을 알아봅니다.

장점 / 단점 / 한계점