OpenAI Codex 사용법: 설치부터 첫 작업까지 (2026)

OpenAI Codex 사용법을 직접 30분간 돌려보고 정리한 한국어 개발자용 메모입니다.
마지막 갱신일: 2026-05-02.

Cursor, Claude Code, GitHub Copilot까지 코딩 에이전트가 이미 충분한데 왜 또 OpenAI Codex일까. 같은 질문을 안고 chatgpt.com/codex에 들어가 첫 스레드를 띄워봤다. 결론부터 말하면 Codex는 IDE 안에 살지 않고 비동기 PR 에이전트다. 로컬 IDE를 켜둘 필요가 없고, 브라우저 한 화면에서 작업 큐를 관리하는 형태라 사용 감각이 꽤 다르다.

이 글은 한국어 개발자가 Codex를 처음 켤 때 막히는 세 가지, 즉 요금제 활성화, GitHub 권한 연동, 첫 스레드 실행을 단계별로 풀어쓴 가이드다.

 

핵심 3줄 요약

• Codex는 ChatGPT Plus/Business 이상 요금제에서 켜지는 별도 에이전트로, chatgpt.com/codex 도메인에서 실행된다.
• 첫 셋업의 80%는 GitHub OAuth 권한과 작업 환경(컨테이너) 연결이며, 나머지가 스레드 작성이다.
• 결과는 자동 PR로 전달되므로 검토는 사람이 해야 한다. 승인 전까지 main에 닿지 않는 것이 기본 모델이다.

 

1. Codex와 다른 코딩 에이전트 차이

Codex는 OpenAI가 자체 코딩 모델을 GitHub와 묶어 내놓은 비동기형 에이전트다. Cursor가 IDE 통합형, Claude Code가 CLI 인터랙티브형이라면 Codex는 클라우드 PR 에이전트에 가깝다.

차이를 한 표로 정리하면 이렇다.

항목	OpenAI Codex	Claude Code	Cursor
실행 위치	클라우드 컨테이너	로컬 터미널	로컬 IDE
인터랙션	비동기 스레드	대화형 CLI	인라인 채팅
결과물	GitHub PR	파일 변경	파일 변경
주 사용 시나리오	백로그 처리·리팩터링	디버깅·페어링	코드 작성 보조

직접 만져본 체감으로는 Codex는 "맡겨두고 다른 일 하는" 워크플로에 강하다. 30분짜리 리팩터링 작업을 던지고 점심을 먹고 와도 PR이 와 있는 식이다. 반대로 즉각적인 페어 프로그래밍은 Claude Code나 Cursor가 더 자연스럽다.

 

2. 사전 준비 — 요금제와 권한

여기서 한국 개발자들이 가장 많이 멈춘다. 정리하면 3가지를 챙겨야 한다.

• ChatGPT Plus 이상 요금제: Free 플랜에서는 Codex 메뉴 자체가 보이지 않는다. 기존에 API만 쓰고 있었다면 chat.openai.com 결제와는 별개다.
• GitHub 계정 권한: Codex가 레포에 접근하려면 OAuth 앱 권한을 승인해야 한다. 조직(Org) 레포라면 Org Owner의 승인이 필요할 수 있다.
• 대상 레포 선정: 처음에는 본인 소유의 작은 사이드 프로젝트로 시작하는 편이 안전하다. 운영 레포로 바로 붙이면 권한 범위와 컨테이너 빌드 실패에 시간이 갈린다.

여기서 한 가지 팁. GitHub Org 레포에 붙일 때 "Personal access tokens" 정책이 막혀 있으면 OAuth 흐름이 중간에 멈춘다. 한국 시간 기준 새벽에 액세스하니 latency가 약간 더 낮은 편이었지만, 권한 이슈는 시간대와 무관하게 바로 막힌다. 회사 레포라면 사내 Git 관리자에게 미리 말해두자.

 

3. 첫 셋업 — 환경 연결까지

요금제와 권한이 준비됐다면 셋업은 의외로 빠르다. 직접 해본 순서는 다음과 같다.

1. chatgpt.com/codex 로 이동. 좌측에 "Environments" 메뉴가 보인다.
2. "Connect GitHub" 버튼을 누르고 OAuth 권한을 승인.
3. 연결할 레포를 선택. 처음에는 1개만 붙이는 편이 디버깅에 편하다.
4. 컨테이너 환경 설정 화면에서 베이스 이미지를 고른다. Node, Python 등 주요 런타임이 프리셋으로 있다.
5. 커스텀 셋업 스크립트가 필요하면 setup script 칸에 입력한다.

setup script 예시는 이렇다. 의존성 설치를 미리 끝내두면 첫 스레드가 훨씬 빨라진다.

#!/usr/bin/env bash
set -euo pipefail

# 의존성 설치
npm ci

# 테스트 환경 변수
export NODE_ENV=test

이 단계에서 자주 막히는 곳이 컨테이너 빌드 실패다. 빌드 로그가 우측에 같이 나오므로, 실패하면 setup script를 짧게 줄이고 단계적으로 늘려가는 편이 빠르다. 비슷한 컨테이너 워크플로를 다룬 Cursor 시작 가이드도 함께 보면 비교에 도움이 된다.

 

4. 첫 스레드 — 지시문 작성 팁

스레드는 Codex의 작업 단위다. 하나의 스레드 = 하나의 PR 후보로 이해하면 깔끔하다. 좋은 지시문은 다음 4가지를 포함한다.

• 목표 파일 경로: "src/utils/date.ts 의 함수 X를 ..." 처럼 명시.
• 변경 범위 한정: "이 PR에서는 테스트만 추가" 같은 경계 선언.
• 테스트 명령: npm test -- --runInBand 등 검증 방법.
• 금지 사항: "package.json 의존성은 추가하지 말 것" 같은 가드레일.

처음 5번 정도는 짧은 작업으로 감을 잡는 편이 좋다. 직접 해보니 "README의 영어 문장 5개를 한국어로 번역" 같은 텍스트성 작업이 첫 스레드로 안전했다. 코드 변경은 그 다음 단계다.

지시문 길이는 너무 짧으면 모호한 PR이 오고, 너무 길면 컨텍스트 한계로 후반부 요구가 누락된다. 체감 적정선은 200~400자 사이였다.

 

5. 결과 검증·승인 워크플로

스레드를 실행하면 Codex 컨테이너에서 작업이 돌고, 끝나면 자동으로 GitHub에 브랜치가 푸시되며 PR이 열린다. 응답 페이로드는 대략 이런 형태다.

{
  "thread_id": "thr_abc123",
  "status": "completed",
  "branch": "codex/translate-readme-ko",
  "pr_url": "https://github.com/<user>/<repo>/pull/42",
  "tests": {"passed": 12, "failed": 0}
}

여기서 중요한 점. Codex는 PR을 만들 뿐 머지하지 않는다. 즉 승인 전 main에 닿지 않는다. 검토는 사람의 몫이고, diff를 직접 읽고 테스트 로그를 확인한 뒤 머지하는 흐름이 기본이다.

검토할 때 보는 포인트는 다음과 같다.

• 의도하지 않은 파일이 변경되지 않았는가
• 테스트가 실제로 의미 있는 변경을 커버하는가
• 의존성 버전이 임의로 올라가지 않았는가
• 시크릿이나 환경 변수가 코드에 박히지 않았는가

OpenAI 에이전트 생태계 전반은 OpenAI Agents SDK 튜토리얼에서 더 깊게 다룬다.

 

6. 자주 막히는 곳·트러블슈팅

직접 30분 돌려보면서 부딪힌 지점, 그리고 커뮤니티에서 반복 보고되는 케이스를 정리한다.

• 요금제 메뉴가 안 보임: 결제는 됐는데 좌측 메뉴에 Codex가 없다 → 브라우저 캐시·쿠키 비우고 재로그인. 그래도 안 보이면 OpenAI 계정 지역 설정 확인.
• OAuth 권한 승인이 무한 로딩: GitHub Org의 SSO 정책에 걸린 경우가 많다. Org 설정에서 OAuth 앱 승인 정책을 확인하자.
• 컨테이너 빌드 실패: setup script의 첫 줄부터 실패하는 경우가 흔하다. set -euo pipefail 위치, Node/Python 버전 미스매치 체크.
• PR이 만들어지지 않음: 작업 권한 범위에 contents: write, pull-requests: write 가 들어 있는지 확인.
• 한국어 지시문에서 오해 발생: 모델이 한국어를 잘 이해하지만, 파일 경로는 영어로 쓰는 편이 정확도가 높았다.

 

7. 다음 단계 — 지금 바로 할 일

첫 스레드가 PR로 돌아왔다면 이제 본격적인 워크플로 설계가 남는다. 추천 순서는 다음과 같다.

1. 테스트 자동화 작업부터 위임 — 새 기능보다 누락 테스트 추가가 검토 부담이 낮다.
2. 리팩터링 가드레일 만들기 — setup script에 lint·typecheck를 넣어 PR 단계에서 막히게 한다.
3. 코드 리뷰 체크리스트 정착 — Codex PR도 사람이 만든 PR과 동일 기준으로 본다.

장기적으로는 Codex를 다른 에이전트와 결합해 쓰는 패턴이 자연스럽다. 로컬 디버깅은 Claude Code, 비동기 백로그는 Codex, IDE 안 페어링은 Cursor 식의 분업이다. 모델 선택 기준은 Claude Opus 4.7 릴리스 정리 글에서 비교했으니 같이 보면 좋다.

이번 글은 첫 진입에 초점을 맞췄고, 다음 글에서는 setup script 고도화와 멀티 레포 환경 분리를 다룰 예정이다.

참고 자료

• OpenAI: Introducing Codex
• OpenAI Codex documentation
• ChatGPT 요금제 비교
• GitHub OAuth 앱 정책 가이드

---

작성자: AI 코딩 에이전트를 매일 다루는 개발자. Cursor·Claude Code·Codex를 동시에 사용하며 한국어 워크플로 문서를 정리하고 있다. 마지막 갱신일: 2026-05-02.