OpenAI Codex 사용법 2026, 설치·CLI·IDE 첫 작업 가이드
요약: OpenAI Codex 사용법을 CLI 설치, 로그인, 프로젝트 실행, VS Code·Cursor IDE 연결, 첫 프롬프트와 보안 설정 순서로 정리합니다.
OpenAI Codex 사용법을 검색한 사람이 가장 먼저 원하는 것은 “도입 검토 문서”가 아니라 오늘 바로 실행하는 순서다. 설치 명령은 무엇인지, 로그인은 ChatGPT 계정으로 하는지 API 키로 하는지, VS Code나 Cursor에서도 되는지, 첫 프롬프트는 어떻게 써야 하는지가 궁금하다. 그래서 이 글은 판단론보다 실전 흐름을 앞에 둔다.
공식 Codex CLI 문서 기준으로 Codex CLI는 터미널에서 로컬로 실행하는 코딩 에이전트다. 선택한 디렉터리의 코드를 읽고, 파일을 바꾸고, 명령을 실행할 수 있다. 이 말은 편하다는 뜻이면서 동시에 위험하다는 뜻이다. 처음부터 전체 저장소 수정, Git push, 배포 스크립트 실행까지 맡기면 안 된다. 첫날 목표는 “설치하고, 로그인하고, 저장소를 읽히고, 작은 테스트 하나를 안전하게 고치는 것”이면 충분하다.
아래 순서대로 진행하면 개인 개발자는 바로 시작할 수 있고, 팀 리더는 어떤 지점에서 보안·비용·리뷰 기준을 붙여야 하는지 감을 잡을 수 있다. 기업 도입 기준은 뒤쪽으로 미뤘다. 먼저 손에 잡히는 사용법부터 보자.
- OpenAI Codex 사용법의 첫 단계는 CLI 설치, 첫 실행, ChatGPT 계정 또는 API 키 로그인이다.
- 첫 작업은 새 브랜치에서 “파일 수정 없이 저장소 설명” → “테스트 명령 확인” → “작은 변경” 순서가 안전하다.
- VS Code, Cursor, Windsurf, JetBrains 계열은 IDE 확장으로 Codex를 옆 패널에서 쓸 수 있다.
- 회사 코드에 붙일 때는 .env, secrets, Git push, 배포 명령, 운영 API 호출을 먼저 제한해야 한다.
OpenAI Codex 설치 전 준비물
설치 전에 세 가지를 확인한다. 첫째, 사용할 계정이다. OpenAI 도움말 기준으로 Codex는 ChatGPT Free, Go, Plus, Pro, Business, Edu, Enterprise 등 여러 플랜에 포함되지만, 사용 한도와 크레딧 옵션은 플랜에 따라 다르다. 둘째, 작업할 프로젝트다. 아무 폴더에서 시작하지 말고 Git으로 관리되는 저장소에서 시작해야 되돌리기 쉽다. 셋째, 테스트 명령이다. 테스트를 모르면 Codex가 만든 변경이 맞는지 확인할 방법이 없다.
| 준비 항목 | 확인 방법 | 왜 필요한가 |
|---|---|---|
| ChatGPT 계정 또는 API 키 | 첫 실행 시 로그인 안내를 따른다 | Codex 사용 권한과 사용량 한도가 여기서 결정된다 |
| Git 저장소 | git status가 정상 출력되는 폴더에서 시작 | 변경 diff를 확인하고 되돌릴 수 있어야 한다 |
| 테스트 명령 | npm test, pytest, go test ./...처럼 실제 명령 확인 | Codex 수정 후 사람이 검증할 기준이 된다 |
| 민감 파일 위치 | .env, secrets/, 키 파일 경로 확인 | 처음부터 읽지 말라고 지시해야 한다 |
Codex CLI 설치 방법: macOS·Linux 기준
OpenAI 공식 CLI 문서는 macOS와 Linux에서 standalone installer를 쓰는 방법을 안내한다. 설치 명령은 짧다. 다만 회사 장비라면 셸 설치 스크립트를 실행하기 전에 보안 정책과 패키지 설치 권한을 확인해야 한다. 개인 장비에서 먼저 실험한 뒤 팀 배포를 논의하는 편이 낫다.
# macOS / Linux: Codex CLI 설치
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# CI나 서버 이미지처럼 대화형 입력이 어려운 환경의 설치 예시
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh
# 프로젝트 폴더에서 실행
cd ~/work/my-service
codex
# 업그레이드는 공식 문서 기준으로 설치 스크립트를 다시 실행
curl -fsSL https://chatgpt.com/codex/install.sh | sh설치 후 터미널에서 codex를 실행하면 첫 로그인 단계가 나온다. 공식 문서 기준으로 ChatGPT 계정 또는 API 키로 인증할 수 있다. ChatGPT 플랜에 포함된 사용량으로 시작할 수 있지만, 실제 한도는 플랜과 작업 복잡도에 따라 달라진다. 대형 저장소 분석이나 긴 테스트 반복은 작은 스크립트보다 훨씬 많은 사용량을 만들 수 있다.
Windows는 공식 문서 기준으로 PowerShell의 Windows sandbox를 쓰거나, Linux-native 환경이 필요하면 WSL2를 사용할 수 있다. Windows 개발팀은 “PowerShell에서 쓸지 WSL2에서 쓸지”를 먼저 통일하는 편이 좋다. 같은 저장소라도 경로, 권한, 테스트 명령이 달라지면 재현성이 깨진다.
첫 실행 후 바로 해야 할 안전한 사용 순서
처음부터 “이 버그 고쳐줘”라고 던지는 것은 비추천이다. Codex는 코드를 읽고 바꿀 수 있는 에이전트라서, 범위를 좁히지 않으면 원치 않는 파일까지 건드릴 수 있다. 첫 세션은 읽기 중심으로 시작한다. 저장소 구조를 설명하게 하고, 테스트 명령을 확인하게 하고, 수정은 사람 승인을 받은 뒤 진행시키는 흐름이 안전하다.
# Codex에게 바로 맡기기 전에 사람이 먼저 확인
pwd
git status --short
git branch --show-current
# 가능하면 새 브랜치에서 시작
git switch -c codex/test-login-bugfix
# 테스트 명령을 사람이 먼저 확인
npm test
# 또는
pytest
# 또는
go test ./...- 1단계 — 저장소 설명만 요청: “이 프로젝트 구조와 테스트 실행 방법을 설명해줘. 파일은 수정하지 마.”라고 시작한다.
- 2단계 — 작은 작업 선택: 문서 오탈자, 테스트 추가, 작은 버그 재현처럼 되돌리기 쉬운 일만 맡긴다.
- 3단계 — 수정 전 계획 요청: 어떤 파일을 바꿀지 먼저 말하게 한다. 바로 수정하지 않게 한다.
- 4단계 — diff 확인: Codex가 수정한 뒤
git diff를 보고 사람이 의도와 맞는지 확인한다. - 5단계 — 테스트 실행: Codex가 제안한 명령이 아니라 팀이 쓰는 공식 테스트 명령으로 확인한다.
- 6단계 — 커밋은 사람이: 첫날에는 commit, push, 배포는 자동으로 맡기지 않는다.
바로 복사해 쓸 첫 프롬프트 예시
Codex 프롬프트는 “무엇을 해줘”보다 “어디까지 하지 말아야 하는지”가 중요하다. 특히 운영 코드, 인증, 결제, 개인정보 로그처럼 위험한 영역은 수정 전 확인을 요구해야 한다. 아래 예시는 첫날 바로 쓸 수 있는 안전한 문장들이다.
1) 이 저장소 구조를 먼저 읽고, 주요 디렉터리와 테스트 실행 방법만 설명해줘. 파일은 수정하지 마.
2) 로그인 실패 테스트가 깨지는 원인을 찾아줘. 먼저 관련 파일 후보와 재현 명령만 제시하고, 수정은 내가 승인하면 진행해.
3) src/auth/session.ts의 만료 처리 로직에 테스트를 추가해줘. 운영 코드 변경은 최소화하고, 변경 전후 diff를 요약해줘.
4) 이번 변경에서 보안상 위험한 부분이 있는지 PR 리뷰어 관점으로 봐줘. 인증, 개인정보 로그, 예외 처리, 롤백 가능성을 우선 확인해줘.좋은 프롬프트는 결과물보다 제약이 선명하다. “전체 리팩터링해줘”는 범위가 너무 넓다. “테스트만 추가”, “수정 전 계획 먼저”, “운영 코드 변경 최소화”, “diff 요약”처럼 제한을 걸어야 리뷰가 쉬워진다.
VS Code·Cursor·Windsurf·JetBrains에서 쓰는 방법
터미널보다 IDE가 편한 개발자는 Codex IDE 확장을 쓰면 된다. OpenAI IDE 문서 기준으로 Codex VS Code extension은 VS Code와 Cursor, Windsurf 같은 VS Code fork에서 작동하며, JetBrains IDE 통합도 제공된다. 설치 후 에디터 사이드바에서 Codex를 열고 ChatGPT 계정 또는 API 키로 로그인한다.
| IDE | 설치/접근 위치 | 처음 확인할 것 |
|---|---|---|
| VS Code | Visual Studio Code Marketplace의 OpenAI ChatGPT/Codex 확장 | 설치 후 오른쪽 사이드바에 Codex가 보이는지 확인. 안 보이면 에디터 재시작 |
| Cursor | Cursor extension 링크 또는 VS Code 호환 확장 | Activity bar 방향 때문에 아이콘이 숨을 수 있어 사이드바 위치 확인 |
| Windsurf | Windsurf extension 링크 또는 VS Code 호환 확장 | 열린 파일과 선택 영역이 Codex 컨텍스트에 들어가는 범위 확인 |
| JetBrains | JetBrains IDE integration | ChatGPT 로그인, API 키, JetBrains AI 구독 중 어떤 인증을 쓸지 확인 |
IDE 확장의 장점은 열린 파일, 선택한 코드, @file 참조처럼 에디터 컨텍스트를 쉽게 줄 수 있다는 점이다. 단점도 같다. 열려 있는 파일과 선택 영역이 많으면 원치 않는 정보가 컨텍스트에 들어갈 수 있다. 회사 코드에서는 비밀값 파일을 열어둔 상태로 질문하지 않는 습관이 필요하다.
Codex 작업 후 반드시 확인할 명령
Codex가 “완료했습니다”라고 말해도 끝난 것이 아니다. 개발자가 확인해야 한다. 최소한 바뀐 파일, 실제 diff, 테스트, 비밀값 포함 여부를 확인한다. 아래 스크립트는 예시다. 프로젝트에 맞게 npm test 대신 pytest, go test ./..., mvn test 등으로 바꾸면 된다.
# Codex 작업 후 사람이 확인할 최소 명령
# 1. 어떤 파일이 바뀌었는지 확인
git diff --stat
# 2. 실제 diff 확인
git diff
# 3. 테스트/린트 실행
npm test && npm run lint
# 4. 의도하지 않은 비밀값 포함 여부 대략 확인
git diff -- . ':!package-lock.json' | grep -Ei 'api[_-]?key|secret|token|password|BEGIN PRIVATE KEY' && echo 'check secrets'
# 5. 사람이 커밋 메시지를 직접 작성
git add .
git commit -m "fix: add session expiry regression test"특히 첫 몇 주는 Codex가 만든 커밋을 그대로 믿지 않는다. PR 설명은 사람이 다시 읽고, 테스트가 없는 변경은 다시 요청한다. 생산성이 올라가는 지점은 “아무 검토 없이 병합”이 아니라 “초안과 테스트 후보를 빠르게 받고 사람이 더 좋은 리뷰를 하는 것”이다.
비용과 사용량: 무료처럼 보여도 작업 크기가 비용을 만든다
OpenAI 도움말은 Codex 사용량이 플랜과 작업 복잡도, 실행 위치에 따라 달라진다고 설명한다. 작은 함수 하나를 고치는 일과 대형 저장소에서 실패한 CI를 추적하는 일은 사용량이 다르다. 회사에서 쓸 때는 사용자 수보다 작업 유형별 사용량을 봐야 한다.
| 작업 유형 | 사용량이 늘어나는 이유 | 관리 기준 |
|---|---|---|
| 저장소 구조 설명 | 파일 목록과 주요 코드 맥락을 많이 읽을 수 있다 | 처음에는 특정 디렉터리만 대상으로 지정 |
| 버그 수정 | 원인 탐색, 수정, 테스트 재실행이 반복된다 | 재시도 횟수와 실패 원인을 기록 |
| 테스트 생성 | 기존 테스트 스타일 분석과 실행 로그 확인이 필요하다 | 테스트 파일 범위를 지정하고 리뷰어가 확인 |
| 코드 리뷰 | PR diff와 주변 맥락을 읽는다 | 자동 리뷰 대상 저장소와 PR 크기 제한 |
| 클라우드 작업 위임 | 긴 작업 시간이 생기고 GitHub 연결이 필요하다 | 파일럿 단계에서는 내부 도구 저장소만 허용 |
보안 설정: 처음부터 막아야 할 것
Codex는 개발 에이전트다. 로컬 파일을 읽고 수정하며, 설정에 따라 명령도 실행한다. 그러니 보안 기준은 “AI에게 물어봐도 되나”가 아니라 “이 에이전트가 무엇을 할 수 있나”로 봐야 한다. 첫날부터 제한해야 할 것은 시크릿 파일, 외부 네트워크 호출, Git push, 배포 명령, 운영 API 호출이다.
| 위험 항목 | 왜 위험한가 | 초기 권장값 |
|---|---|---|
| .env / secrets 파일 | 토큰·비밀번호·개인정보가 컨텍스트에 들어갈 수 있다 | 읽지 말라고 AGENTS.md와 프롬프트에 명시 |
| 외부 네트워크 호출 | 프롬프트 인젝션이나 데이터 반출 위험이 생긴다 | 필요한 도메인만 승인 |
| git push / tag / release | 원격 저장소와 배포 이력이 바뀐다 | 사람이 직접 실행 |
| DB migration | 데이터 손상과 롤백 문제가 생긴다 | 계획 검토 후 수동 실행 |
| 운영 API 호출 | 고객 데이터나 운영 상태가 바뀔 수 있다 | 파일럿 단계에서는 금지 |
팀에서 쓰기 위한 AGENTS.md 예시
Codex에게 매번 같은 주의사항을 말하는 대신 저장소에 짧은 작업 규칙을 두는 편이 낫다. 아래 예시는 그대로 복사하기보다 팀 정책에 맞게 줄여서 쓰면 된다. 핵심은 시크릿, 운영 명령, 인증·결제 변경, 테스트 보고를 명확히 적는 것이다.
# AGENTS.md 예시: Codex에게 줄 저장소 작업 규칙
## 작업 원칙
- 먼저 저장소 구조와 테스트 명령을 요약하고, 바로 수정하지 않는다.
- .env, secrets/, credentials/, private key 파일은 읽거나 출력하지 않는다.
- 인증, 결제, 개인정보 로그, DB 마이그레이션 변경은 반드시 사람 승인을 먼저 받는다.
- git push, 배포 명령, 운영 API 호출은 실행하지 않는다.
- 변경 후에는 테스트 명령, 실패 로그, 수정 파일 목록을 짧게 보고한다.
## 리뷰 우선순위
- P1: 인증 우회, 개인정보/토큰 로그, 롤백 없는 마이그레이션
- P2: 테스트 누락, 예외 처리 누락, 타입 불일치
- P3: 스타일, 네이밍, 문서 오탈자팀 파일럿 정책 스켈레톤
개인 사용이 아니라 팀 도입이라면 아래처럼 파일럿 범위를 문서화한다. 처음에는 CLI 또는 IDE 중 하나만 열고, 자동 코드 리뷰와 클라우드 작업은 나중에 붙이는 편이 안전하다.
# codex-team-rollout.yaml
# 목적: 팀 단위 Codex 사용 시작 전 최소 정책 합의용 스켈레톤
team: backend-platform
first_surface: cli_or_ide
allowed_repositories:
- internal-tools
- sample-service
blocked_paths:
- "**/.env"
- "**/.env.*"
- "**/secrets/**"
- "**/*credential*"
approval_required:
- git_push
- production_deploy
- database_migration
- auth_or_payment_code_change
- external_network_call
pilot_metrics:
- tasks_completed
- tests_added
- human_review_minutes
- reverted_changes
- failed_runs
stop_conditions:
- secret_exposure
- repeated_test_failure_without_explanation
- unauthorized_git_or_deploy_attempt
- review_time_increases_for_two_weeks실전 시나리오 1: 로그인 버그를 고칠 때
로그인 실패 버그를 Codex에게 맡긴다고 가정하자. 바로 “고쳐줘”가 아니라 “관련 파일 후보와 재현 명령만 먼저 찾아줘”라고 시작한다. Codex가 인증 미들웨어, 세션 만료 처리, 테스트 파일을 찾으면 사람이 범위를 좁힌다. 그 다음에 테스트 추가를 먼저 요청하고, 운영 코드 변경은 최소화한다. 이 조건이면 Codex를 쓰기 좋다. 실패해도 테스트와 diff로 되돌릴 수 있기 때문이다.
반대로 OAuth 시크릿, 운영 로그인 로그, 실제 고객 세션이 필요한 상황이면 보류다. 이때는 Codex보다 재현 가능한 테스트 데이터와 스테이징 환경 정리가 먼저다.
실전 시나리오 2: 레거시 코드 이해와 문서화
오래된 모듈을 인수인계받았을 때는 Codex가 특히 유용하다. “이 폴더의 진입점과 데이터 흐름을 설명해줘. 파일 수정은 하지 마.”라고 시작하면 된다. 다음에는 함수별 책임, 호출 흐름, 테스트 공백을 정리하게 한다. 문서 초안은 사람이 확인해서 README나 내부 위키에 반영한다.
이 작업은 코드 변경보다 위험이 낮고 효과가 빠르다. 그래서 팀 파일럿 첫 주제로 좋다. 단, 비밀값이나 운영 로그가 섞인 폴더를 읽히면 안 된다. 레거시 이해 작업도 읽기 권한 경계가 필요하다.
문제가 생겼을 때 점검 순서
- Codex 명령이 없다: 설치 스크립트 실행 후 터미널을 새로 열고 PATH를 확인한다.
- 로그인이 안 된다: ChatGPT 계정 플랜과 조직 정책, API 키 사용 여부를 확인한다.
- IDE에서 아이콘이 안 보인다: VS Code는 재시작, Cursor는 activity bar 위치와 확장 탭을 확인한다.
- 응답이 엉뚱하다: 열린 파일과 선택 영역을 줄이고, 작업 디렉터리를 좁힌다.
- 수정 범위가 크다: “수정 전 계획만”, “테스트 파일만”, “한 파일만”처럼 제약을 다시 건다.
- 테스트가 깨진다: Codex에게 재시도시키기 전에 실패 로그와 기존 테스트 명령이 맞는지 사람이 확인한다.
함께 보면 좋은 글
AI 에이전트 프레임워크 2026, LangChain·LlamaIndex·OpenAI Agents 도입 기준
사내 LLM 도입 2026, 디자인팀 AI 업무 적용 전 비용·보안 기준
2026년 실무자를 위한 로컬 LLM 실행 방법과 Python 개발 예제
RAG vs 파인튜닝 기업 맞춤형 LLM 최적화 전략 비교 가이드
AI 코드 리팩토링 팁 스파게티 코드를 클린 코드로 바꾸는 5가지 전략자주 묻는 질문
OpenAI Codex 사용법에서 가장 먼저 해야 할 일은 무엇인가요?
CLI를 설치하고 프로젝트 폴더에서 codex를 실행한 뒤 로그인한다. 첫 작업은 파일 수정이 아니라 저장소 구조 설명과 테스트 명령 확인으로 시작하는 편이 안전하다.
Codex CLI 설치 명령은 무엇인가요?
공식 문서 기준 macOS와 Linux에서는 curl -fsSL https://chatgpt.com/codex/install.sh | sh를 사용한다. 비대화형 설치는 CODEX_NON_INTERACTIVE=1를 붙일 수 있다.
VS Code나 Cursor에서도 Codex를 쓸 수 있나요?
가능하다. OpenAI의 Codex IDE extension은 VS Code와 Cursor, Windsurf 같은 VS Code fork에서 쓸 수 있고 JetBrains IDE 통합도 제공된다. 설치 후 사이드바에서 로그인한다.
회사 코드에 Codex를 바로 붙여도 되나요?
작은 내부 저장소와 읽기·테스트 중심 작업부터 시작하는 편이 낫다. .env, secrets, 운영 API, git push, 배포 명령은 초기에 제한해야 한다.
Codex가 만든 코드를 그대로 커밋해도 되나요?
권장하지 않는다. git diff, 테스트, 린트, 비밀값 포함 여부를 확인한 뒤 사람이 커밋 메시지를 작성하는 흐름이 안전하다.
Codex 사용량은 어떻게 관리하나요?
플랜별 한도와 크레딧 옵션은 공식 가격 페이지에서 확인해야 한다. 팀에서는 사용자 수보다 작업 유형, 재시도 횟수, 테스트 실행, 클라우드 작업 수를 같이 기록해야 한다.
출처와 확인일
- OpenAI Developers — Codex CLI 설치와 실행 (확인일: 2026-06-22)
- OpenAI Developers — Codex IDE extension (확인일: 2026-06-22)
- OpenAI Developers — Codex product overview (확인일: 2026-06-22)
- OpenAI Help Center — Using Codex with your ChatGPT plan (확인일: 2026-06-22)
- OpenAI Developers — Agent approvals & security (확인일: 2026-06-22)
- OpenAI Developers — Codex enterprise admin setup (확인일: 2026-06-22)
이 글은 일반적인 개발 도구 사용 가이드다. OpenAI Codex의 설치 방식, 지원 플랜, 사용량 한도, IDE 지원 범위, 보안·승인 기능은 변경될 수 있다. 실제 팀 도입 전에는 OpenAI 공식 문서와 조직의 보안 정책, 저장소 권한, 테스트·배포 절차를 다시 확인해야 한다.
댓글
댓글 쓰기