OpenAI Codex: 3가지 실전 예제로 배우는 단계별 가이드

요약

• OpenAI Codex는 클라우드 기반 소프트웨어 엔지니어링 에이전트로, ChatGPT(Plus, Pro, Team, Enterprise 요금제) 안에서 사용할 수 있습니다.

• Codex를 GitHub 리포지토리에 연결한 뒤 버그 수정, 패치 적용, 테스트 생성, 코드 설명 등의 작업을 할당하세요.

• 각 작업은 격리된 샌드박스에서 실행되며, Codex가 병합 전 검토할 수 있도록 Pull Request를 엽니다.

• AGENTS.md 파일을 사용해 Codex가 모든 작업에서 따를 코딩 규칙을 정의할 수 있습니다.

• Codex는 Codex CLI로 터미널에서도, 그리고 VS Code 확장으로도 실행됩니다.

OpenAI의 Codex란?

OpenAI Codex는 코드를 작성하고 편집하며, 테스트를 실행하고, 버그를 수정하고, Pull Request까지 제안할 수 있는 클라우드 기반 소프트웨어 엔지니어링 에이전트입니다. 각 작업은 자체 샌드박스 환경에서 실행됩니다.

Codex는 OpenAI의 최신 프런티어 모델로 구동되며, 안전성, 테스트 가능성, 개발자 생산성을 중시해 구축되었습니다. AGENTS.md 파일로 Codex를 가이드하거나 ChatGPT 사이드바에서 직접 상호작용할 수 있습니다.

또한 Codex CLI를 사용하면 이러한 기능을 터미널로 직접 가져올 수 있습니다.

Codex 접근 방식 한눈에 보기:

OpenAI의 Codex 설정하기

Codex 설정은 몇 분이면 충분합니다. 시작을 위한 단계별 안내는 다음과 같습니다.

1단계: Codex 도구 찾기

먼저 ChatGPT에 로그인하세요. 왼쪽 사이드바에서 Codex를 찾습니다. 출시 당시 Codex는 ChatGPT Pro, Business, Enterprise 사용자에게 제공되었으며, 현재는 모든 요금제에 포함되어 있습니다(단, Free와 Go의 접근은 매우 제한적입니다).

2단계: Codex 시작하기

Codex를 클릭하면 초기 설정을 위한 새 탭으로 이동합니다. “Get Started”를 클릭하고 다음 단계의 인증 절차를 따라주세요.

3단계: 다중 요소 인증

“Set up MFA to continue”를 클릭하고 즐겨 사용하는 인증 앱(예: Google Authenticator, Authy)으로 QR 코드를 스캔하세요. 코드를 입력해 인증하면 완료됩니다.

4단계: GitHub 연결

다중 요소 인증이 완료되면 Codex를 GitHub에 연결합니다.

4.1단계: GitHub 커넥터 승인

“Connect to GitHub”를 클릭하면 GitHub 커넥터 승인을 위한 팝업으로 이동합니다. 내용을 확인한 뒤 Authorize를 클릭하세요.

4.2단계: GitHub 계정 추가

GitHub 연결이 끝나면 계정을 추가해야 합니다. GitHub organization 탭에서 “Add a GitHub account”를 선택하세요. 

그러면 “Install and Authorize” 팝업으로 이동합니다. 승인하면 모든 리포지토리가 ChatGPT 인터페이스에 표시됩니다. 선택한 리포지토리만 승인할 수도 있습니다.

4.3단계: 환경 생성

작업할 리포지토리를 선택하고 “Create environment”를 클릭하세요.

이후 “Data Controls”로 이동합니다. Codex는 아직 활발히 개발 중이며, 데이터가 모델 개선에 사용되도록 허용하는 선택적 프롬프트가 표시될 수 있습니다. 원하지 않으면 끄고 진행할 수 있습니다.

이제 환경 탐색을 시작할 준비가 되었습니다. Codex는 미리 선택된 작업으로 병렬 작업을 시작할 수 있도록 지원합니다.

“Start tasks”를 클릭하거나 필요에 따라 작업을 선택하세요. 그러면 질문을 하거나 에이전트에게 기능 구현을 요청할 수 있는 인터페이스로 이동합니다.

모든 작업이 준비되면 원하는 작업을 선택하거나 여러 작업을 병렬로 진행하세요.

5단계: AGENTS.md 파일(선택 사항)

AGENTS.md 파일은 OpenAI가 Codex 플랫폼과 함께 사용하도록 도입한 특수 구성 파일로, 에이전트가 코드베이스에서 작업할 때 방향을 잡아주도록 설계되었습니다. AI 팀원을 위한 개발자 매뉴얼로 생각하시면 됩니다. README.md와 유사하지만 자율 에이전트를 위한 지침에 초점을 맞춥니다. 다음은 예시 AGENTS.md 파일입니다.

# AGENTS.md

## Code Style
- Use Black for Python formatting.
- Avoid abbreviations in variable names.

## Testing
- Run pytest tests/ before finalizing a PR.
- All commits must pass lint checks via flake8.

## PR Instructions
- Title format: [Fix] Short description
- Include a one-line summary and a "Testing Done" section

Codex가 코드베이스에서 작업을 실행할 때는 다음과 같이 동작합니다.

• AGENTS.md 파일 중 수정 대상 파일의 범위에 포함되는 것을 검색합니다.
• 해당 파일의 지침을 적용해 변경 사항을 포맷하고, 테스트하고, 문서화합니다.
• 여러 파일이 적용되는 경우 더 깊게 중첩된 지침을 우선합니다(계단식 설정과 유사).

도구와 API 전반에서 실행까지 연결되는 시스템 구축을 폭넓게 살펴보려면 OpenAI Agents SDK 튜토리얼을 참고하세요.

OpenAI의 Codex: 세 가지 실전 예제

리포지토리에서 실행한 세 가지 예제를 통해 Codex가 실제 개발에서 어떻게 도움이 되는지 살펴보겠습니다.

예제 1: 기본 수정과 오타

Codex는 하나의 요청을 같은 워크스페이스 안에서 오타 수정, README 개선, 테스트 작성 같은 하위 작업으로 나눌 때가 있습니다.

초기 검토를 바탕으로 기존 작업 내에서 새 작업을 시작하거나, 기존 코드베이스에 대한 변경을 요청하거나, 텍스트박스를 통해 질문할 수 있습니다. 작업을 확장하거나 새로운 수정을 하려면 “Code”를 클릭해 바로 하위 작업을 시작하세요.

변경 사항에 만족하면 “Push”를 클릭하세요. 새 Pull Request가 생성됩니다. 몇 초 후 “View Pull Request”를 클릭해 PR에 접근하고 메인에 병합할 수 있습니다.

예제 2: 코드베이스 설명

다음으로, 편집이 아닌 작업에 Codex를 사용했습니다. 코드베이스를 탐색하며 앞으로 무엇을 할 수 있을지 물어봤습니다. 신규 프로젝트에 합류했거나 빠르게 온보딩해야 할 때, 혹은 특정 함수의 동작을 이해하지 못해 막혔을 때 특히 유용합니다.

Codex는 프로젝트를 탐색하며 코드베이스 구조를 초보자도 이해하기 쉽게 깔끔히 정리해 주었습니다. 단순히 파일을 나열하는 대신, 목적별로 묶어 설명했습니다.

• qwen3_demo.py가 주요 스크립트이며, 추론 모드 전환용 인터페이스와 다국어 번역용 인터페이스, 두 개의 Gradio 기반 인터페이스를 실행한다는 점을 강조했습니다.
• qwen3_demo.ipynb는 대안적인 대화형 노트북임을 식별했습니다.
• test_qwen3_demo.py는 단위 테스트를, README.md는 문서 및 동영상 가이드를 제공한다는 점을 짚었습니다.

이외에도 의존성(Ollama CLI), _run_ollama 함수의 역할, 인터페이스 확장을 위한 팁 등 “알아두면 좋은 핵심 사항”을 정리해 주었습니다. 모델 버저닝 탐색, UI 개선, 에러 처리 추가 같은 다음 단계도 제안했습니다.

예제 3: 버그 찾기와 수정

Codex는 코드베이스 전체를 스캔해 버그를 식별하고, 수정안을 제시하며, 변경 사항 미리보기를 보여줄 수 있습니다. 이 과정은 GitHub의 코드 변경 검토와 유사합니다.

“Logs”를 클릭하면 백그라운드에서 이루어진 변경 과정의 로그를 확인해 이해할 수 있습니다.

Codex는 변경 사항 요약과 함께 생성되었거나 영향을 받은 파일 목록을 반환합니다. 변경 사항에 대해 질문하거나, 현재 구현을 개선할 새 코드를 작성해 달라고 요청할 수도 있습니다.

코드 수정에 만족하면 “Push”와 “Create New PR”를 눌러 새 Pull Request를 여세요.

몇 초 후 “View Pull Request”를 클릭해 PR에 접근하고 메인에 병합할 수 있습니다.

Codex를 사용하면 몇 번의 클릭만으로 변경 사항을 병합할 수 있습니다.

몇 초 안에 변경 사항이 메인 브랜치에 반영됩니다.

왜 Codex가 중요할까요?

Codex는 수동적인 코드 생성기가 아니라 협업형 에이전트입니다. 작성, 리팩터링, 테스트, 디버그, 설명을 요청하면 각 단계의 터미널 로그, 출처, 출력물을 보여줍니다.

제가 관찰한 현실 세계의 이점은 다음과 같습니다.

• 작업이 추적 가능하고 검증 가능합니다.
• Codex는 병렬로 동작해 여러 변경을 대기열에 넣을 수 있습니다.
• AGENTS.md로 규칙을 구성해 두면 개발 환경과 관례를 존중합니다.
• 인간의 PR 기준에 부합하며 CI 테스트를 통과할 수 있습니다.

제게는 OpenAI가 소프트웨어 엔지니어링 인턴을 막 출시한 듯한 느낌입니다.

마무리

Codex가 버그를 수정하고, 기능 패치를 적용하며, 코드 로직을 설명하는 동시에 Pull Request를 생성하고, 테스트를 실행하며, 터미널 로그와 diff로 작업을 근거 제시하는 방법을 살펴봤습니다.

이 실습형 안내를 통해 레거시 코드 디버깅, 새 리포지토리 온보딩, 유지보수 작업 분류 등 일상적인 개발자 워크플로가 Codex로 어떻게 개선될 수 있는지 확인했습니다.

Codex가 발전함에 따라 IDE, CI 파이프라인, 작업 플래너와의 통합이 더 깊어져 어떤 엔지니어링 워크플로에도 실용적인 추가 기능이 될 것으로 예상합니다. Codex에 대해 더 알아보려면 공식 출시 블로그를 읽어보세요. OpenAI의 YouTube 채널에서도 사례를 확인할 수 있습니다.

OpenAI의 엔지니어링 중심 모델과 도구를 더 깊이 파고들고 싶다면 다음 블로그를 추천합니다.

• OpenAI Codex CLI 튜토리얼
• GPT-5.1 Codex 가이드: GitHub 이슈 분석 에이전트 만들기
• 데이터 워크플로 자동화를 위한 Codex CLI: 완벽 가이드
• Codex CLI MCP 튜토리얼: 포트폴리오 대시보드 에이전트 구축