Codex 설치

Codex는 로컬 프로젝트나 GitHub 저장소를 읽고, 코드를 수정하고, 필요한 명령을 실행하면서 개발 작업을 도와주는 코딩 에이전트입니다. 처음 사용할 때는 어떤 환경에서 Codex를 쓸지 먼저 정하는 것이 좋습니다.

Codex를 시작하는 대표적인 방법은 네 가지입니다.

Codex 앱: 로컬 프로젝트를 별도 데스크톱 앱에서 다루고 싶을 때 적합합니다.
IDE 확장: VS Code, Cursor, Windsurf 같은 에디터 안에서 바로 사용하고 싶을 때 적합합니다.
CLI: 터미널에서 현재 디렉터리를 기준으로 Codex를 실행하고 싶을 때 적합합니다.
Codex Cloud: 브라우저에서 GitHub 저장소를 연결하고, 작업을 백그라운드로 맡기고 싶을 때 적합합니다.

처음에는 IDE 확장이나 Codex 앱으로 시작하는 편이 쉽습니다. 터미널 작업에 익숙하다면 CLI도 좋은 선택입니다.

시작하기 전에

Codex를 사용하려면 ChatGPT 계정이나 OpenAI API 키로 로그인해야 합니다. 계정 유형이나 플랜에 따라 사용할 수 있는 기능, 사용량, 클라우드 작업 가능 여부가 달라질 수 있습니다.

또한 Codex는 프로젝트 파일을 읽고 수정할 수 있습니다. 처음에는 실험용 저장소나 Git으로 관리되는 프로젝트에서 사용하는 것이 좋습니다. 작업 전후로 커밋을 만들어 두면 결과가 마음에 들지 않을 때 되돌리기 쉽습니다.

Codex 앱으로 시작하기

Codex 앱은 macOS와 Windows에서 사용할 수 있는 데스크톱 환경입니다. 여러 프로젝트를 열어 두고 작업하거나, 변경 사항을 앱 안에서 검토하고 싶을 때 편리합니다.

Codex 앱을 설치합니다.

운영체제에 맞는 Codex 앱을 설치합니다. macOS에서 Intel 기반 Mac을 사용한다면 Intel 빌드를 선택해야 합니다. 앱 다운로드는 Codex 홈페이지에서 할 수 있습니다.
Codex를 열고 로그인합니다.

ChatGPT 계정이나 OpenAI API 키로 로그인합니다. API 키로 로그인하는 경우 일부 클라우드 기반 기능은 제한될 수 있습니다.
프로젝트 폴더를 선택합니다.

Codex가 작업할 로컬 프로젝트 폴더를 선택합니다. 이전에 Codex 앱, CLI, IDE 확장을 사용한 적이 있다면 기존 프로젝트 목록이 보일 수 있습니다.
첫 메시지를 보냅니다.

로컬 프로젝트에서 작업하려면 Local 모드가 선택되어 있는지 확인합니다. 처음에는 코드를 바로 수정하게 하기보다 프로젝트를 설명하게 하거나, 작은 작업부터 맡기는 것이 좋습니다.

IDE 확장으로 시작하기

IDE 확장은 에디터 안에서 Codex를 함께 띄워 놓고 사용할 수 있는 방식입니다. 현재 열려 있는 파일, 선택한 코드, 프로젝트 구조를 활용해 질문하거나 작업을 맡길 수 있습니다.

확장을 설치합니다.

Codex 확장은 VS Code 계열 에디터와 일부 JetBrains IDE에서 사용할 수 있습니다.
Codex 패널을 엽니다.

설치가 끝나면 에디터 사이드바에서 Codex 패널을 찾을 수 있습니다. 보이지 않는다면 에디터를 다시 시작하거나, 확장 목록에서 Codex가 설치되어 있는지 확인합니다.
로그인하고 작업을 시작합니다.

ChatGPT 계정이나 OpenAI API 키로 로그인합니다. IDE 확장은 기본적으로 Agent 모드에서 시작하며, 이 모드에서는 Codex가 프로젝트 파일을 읽고, 명령을 실행하고, 필요한 경우 코드를 수정할 수 있습니다.
변경 사항을 검토합니다.

Codex가 코드를 수정한 뒤에는 diff를 확인하고, 테스트나 빌드를 실행해 결과를 검증합니다. 특히 여러 파일이 바뀌는 작업에서는 Git 상태를 자주 확인하는 것이 좋습니다.

CLI로 시작하기

Codex CLI는 터미널에서 실행하는 방식입니다. 현재 디렉터리를 기준으로 Codex가 프로젝트를 읽고 작업하므로, 명령어 기반 개발 흐름에 익숙한 경우 효율적입니다.

Codex CLI를 설치합니다.

npm을 사용한다면 다음 명령으로 설치할 수 있습니다.
```
npm install -g @openai/codex
```
Homebrew를 사용한다면 다음 명령으로 설치할 수 있습니다.
```
brew install codex
```
작업할 프로젝트로 이동합니다.
```
cd path/to/your-project
```
codex를 실행하고 로그인합니다.
```
codex
```
처음 실행하면 ChatGPT 계정이나 OpenAI API 키로 로그인하라는 안내가 표시됩니다.
현재 디렉터리를 기준으로 작업을 요청합니다.

CLI에서 Codex는 현재 디렉터리의 파일을 기준으로 응답합니다. 따라서 반드시 작업하려는 프로젝트 루트에서 실행하는 것이 좋습니다.

Windows에서는 PowerShell에서 네이티브로 실행할 수 있고, Linux 환경이 필요한 프로젝트라면 WSL2를 사용할 수 있습니다.

Codex Cloud로 시작하기

Codex Cloud는 브라우저에서 GitHub 저장소를 연결하고 작업을 맡기는 방식입니다. 로컬 컴퓨터에서 오래 실행하기 부담스러운 작업이나, pull request 중심의 흐름에 적합합니다.

Codex Cloud를 엽니다.

chatgpt.com/codex에 접속합니다.
GitHub 저장소를 연결합니다.

첫 작업을 시작하기 전에 환경 설정에서 Codex가 사용할 저장소와 실행 환경을 설정합니다. 저장소 접근 권한, 브랜치, 의존성 설치 방식 등을 확인해야 합니다.
작업을 실행하고 로그를 확인합니다.

환경이 준비되면 Codex 인터페이스에서 작업을 시작할 수 있습니다. 작업이 진행되는 동안 로그를 보면서 어떤 파일을 읽고 어떤 명령을 실행하는지 확인할 수 있습니다.
변경 사항을 검토하고 pull request를 만듭니다.

작업이 끝나면 diff를 검토하고, 필요하면 Codex에게 추가 수정을 요청합니다. 변경 사항을 받아들이기로 했다면 pull request를 만들거나 로컬에서 브랜치를 받아 테스트할 수 있습니다.
```
git fetch
git checkout BRANCH_NAME
```

GitHub pull request 댓글에서 @codex를 태그해 작업을 위임하는 방식도 사용할 수 있습니다. 이 기능은 계정과 저장소 설정에 따라 사용할 수 있는 범위가 달라질 수 있습니다.

처음 보내기 좋은 요청

처음부터 큰 기능을 맡기기보다 프로젝트를 이해하는 요청으로 시작하는 것이 좋습니다. Codex가 어떤 파일을 읽고 어떤 방식으로 답하는지 확인할 수 있기 때문입니다.

이 프로젝트의 구조를 간단히 설명해 줘.
주요 디렉터리의 역할과 애플리케이션이 실행되는 흐름을 중심으로 정리해 줘.
아직 코드는 수정하지 마.

작은 기능을 맡길 때는 목표와 제약을 함께 적는 것이 좋습니다.

이 프로젝트에 간단한 검색 필터 기능을 추가해 줘.

조건:
- 기존 UI 스타일을 유지해 줘.
- 새 의존성은 추가하지 마.
- 관련 테스트가 있으면 함께 업데이트해 줘.
- 작업 후 변경한 파일과 확인한 명령을 요약해 줘.

버그 수정을 맡길 때는 재현과 검증을 명시하는 것이 좋습니다.

현재 실패하는 테스트를 재현하고 원인을 찾아 고쳐 줘.

진행 방식:
1. 먼저 테스트를 실행해 실패를 확인해 줘.
2. 실패 원인을 관련 파일과 함께 설명해 줘.
3. 최소한의 변경으로 수정해 줘.
4. 같은 테스트를 다시 실행해 통과 여부를 확인해 줘.

작업할 때의 기본 습관

Codex가 만든 결과는 항상 검토해야 합니다. 특히 파일 삭제, 데이터베이스 마이그레이션, 배포 설정, 인증과 권한, 외부 API 호출처럼 영향 범위가 큰 작업은 더 신중하게 확인해야 합니다.

실무적으로는 다음 순서가 안정적입니다.

작업 전 Git 상태를 확인합니다.
Codex에게 목표, 제약, 검증 방법을 함께 알려 줍니다.
Codex가 수정한 파일을 diff로 확인합니다.
테스트, 린트, 빌드 중 가능한 검증을 실행합니다.
변경 사항을 커밋하거나, 필요하면 Codex에게 후속 수정을 요청합니다.