Codex가 무엇인지는 알아도, 실제로 CLI를 어떻게 설치하고 첫 실행을 어떻게 시작해야 하는지는 막막한 경우가 많습니다.
이 글은 가장 짧고 안전한 시작 흐름에 맞춰 정리했습니다. 설치와 인증을 끝낸 뒤, 범위가 작은 작업 하나를 검증 가능한 형태로 시작하는 방법까지 바로 이어서 설명합니다.
Codex CLI는 무엇을 하는 도구일까?
OpenAI는 Codex CLI를 로컬 터미널에서 동작하는 코딩 에이전트로 설명합니다. 현재 작업 디렉터리를 읽고, 파일을 수정하고, 명령을 실행하는 흐름을 한 번에 처리할 수 있습니다.
그래서 설치 자체보다도 어떤 저장소에서 어떤 작업으로 시작하느냐가 더 중요합니다.
OpenAI Codex CLI 설치 방법
OpenAI 공식 Codex CLI 문서에 나온 기본 설치 명령은 아래와 같습니다.
npm i -g @openai/codex설치 후 실행은 다음처럼 합니다.
codex업데이트가 필요할 때는 공식 문서 기준으로 아래 명령을 사용합니다.
npm i -g @openai/codex@latestOpenAI 문서에서는 현재 Windows 지원이 실험적이라고 안내하고 있고, 가능하면 WSL 환경에서 사용하는 쪽을 권장합니다.
인증은 어떻게 진행될까?
처음 codex를 실행하면 로그인 절차가 시작됩니다. OpenAI 문서 기준으로 인증은 다음 두 방식 중 하나로 진행됩니다.
- ChatGPT 계정
- API 키
어떤 방식이 가능한지는 계정 플랜에 따라 달라질 수 있으므로, 먼저 접근 가능한 인증 경로를 확인하는 편이 좋습니다.
첫 실행은 어떻게 시작하는 게 좋을까?
첫 실행에서는 “큰 기능 개발”보다 “도구가 저장소를 어떻게 읽는지 익히는 작업”이 더 중요합니다.
좋은 첫 작업 예시는 이렇습니다.
- 이 저장소 구조를 설명해줘
- 환경변수가 어디에서 읽히는지 찾아줘
- 작은 컴포넌트 이름 하나만 바꾸고 빌드까지 확인해줘
- 현재 diff를 읽고 위험한 부분을 짚어줘
반대로 좋지 않은 첫 작업은 이렇습니다.
- 앱 전체 리팩터링
- 데이터베이스 구조 전면 수정
- 문제 있어 보이는 것 전부 고치기
첫 작업 예시
실제 프로젝트 디렉터리에서 범위가 분명한 요청으로 시작하는 것이 좋습니다.
예를 들면:
이 블로그에서 카테고리 랜딩 순서가 어디에서 정의되는지 찾아서 설명하고, Dev 카테고리 우선순위를 바꾸려면 어떤 파일을 수정해야 하는지 알려줘.그다음 작은 수정으로 넘어갑니다.
Dev 카테고리 카드 설명 문구를 바꾸고 빌드가 깨지지 않는지 확인해줘.이런 흐름이 처음부터 큰 기능을 던지는 것보다 훨씬 안정적입니다.
실제 편집 전에 먼저 정의하면 좋은 것
Codex는 저장소 규칙이 분명할수록 결과가 좋아집니다.
최소한 아래 정도는 정리돼 있으면 좋습니다.
- 빌드 명령
- 테스트 명령
- lint 명령
- 함부로 건드리면 안 되는 파일
- 폴더 구조와 네이밍 규칙
실무에서는 보통 AGENTS.md, package script, 폴더 규칙이 이 역할을 합니다.
자주 하는 설치 실수
1. 잘못된 디렉터리에서 실행하기
Codex는 현재 작업 트리를 기준으로 동작하므로, 실행 위치가 틀리면 처음부터 흐름이 꼬입니다.
2. 첫 작업을 너무 크게 잡기
처음부터 큰 작업을 주면 도구 성능보다 작업 범위가 문제인지 구분하기 어려워집니다.
3. 검증을 생략하기
수정이 좋아 보여도 npm run build 같은 검증 명령은 같이 주는 편이 안전합니다.
4. Windows 동작을 다른 환경과 같다고 가정하기
공식 문서에서도 Windows 지원은 아직 실험적이라고 설명하므로, WSL이 더 안전한 경우가 많습니다.
설치가 끝났다면 다음 단계는 분명합니다. 범위가 작은 저장소 작업 하나를 실행해 보고, 그 흐름을 반복 가능한 일상 루프로 만드는 것입니다.
FAQ
Q. 설치가 제대로 됐는지는 어떻게 확인할까?
codex 명령이 실행되고 로그인 흐름이 시작되면 기본 설치는 된 상태입니다.
Q. ChatGPT 계정과 API 키 중 무엇으로 시작해야 할까?
자신의 플랜과 팀 워크플로우에 맞는 방식으로 고르면 되지만, 두 방식이 항상 동일하게 열려 있다고 가정하지 않는 편이 좋습니다.
Q. 첫 작업은 무엇이 가장 좋을까?
저장소 구조 설명이나 작은 수정 + 빌드 확인 같은 작업이 가장 무난합니다.
Codex 설치와 첫 작업 흐름이 익숙해졌다면, 이제는 도구 전체 맥락을 정리한 OpenAI Codex 가이드와 반복 가능한 작업 루프를 다룬 Codex 워크플로우 가이드로 이어가는 흐름이 자연스럽습니다.
다음에 읽기 좋은 글
- CLI가 전체 Codex 흐름에서 어디에 맞는지 먼저 잡고 싶다면 OpenAI Codex 가이드로 이어서 보면 좋습니다.
- 설치를 반복 가능한 작업 루프로 바꾸고 싶다면 Codex 워크플로우 가이드가 다음 단계입니다.
관련 글
Sources:
심사 대기 중에는 광고 대신 관련 가이드를 먼저 보여줍니다.
먼저 읽어볼 가이드
검색 유입이 많은 핵심 글부터 이어서 보세요.
- 미들웨어 트러블슈팅 가이드: Redis vs RabbitMQ vs Kafka 개발자를 위한 미들웨어 트러블슈팅 허브 글입니다. Redis, RabbitMQ, Kafka 중 어떤 증상부터 먼저 봐야 하는지와 어떤 문제 패턴이 각 시스템에 가까운지 정리합니다.
- Kubernetes CrashLoopBackOff: 먼저 볼 것들 startup failure, probe, config, resource limit 관점에서 CrashLoopBackOff를 어떻게 나눠서 봐야 하는지 정리한 가이드입니다.
- Kafka consumer lag가 계속 늘 때: 트러블슈팅 가이드 Kafka consumer lag가 계속 늘어날 때 무엇부터 봐야 하는지 정리합니다. poll 주기, 처리 속도, rebalance, consumer 설정까지 실전 기준으로 다룹니다.
- Kafka Rebalancing Too Often 가이드 Kafka consumer group에서 rebalance가 너무 자주 일어날 때 membership flapping, poll timing, protocol, assignment churn을 어떤 순서로 봐야 하는지 설명하는 실전 가이드입니다.
- Docker container가 계속 재시작될 때: 먼저 확인할 것들 exit code, command failure, environment mistake, health check 관점에서 Docker restart loop를 푸는 실전 가이드입니다.
심사 대기 중에는 광고 대신 관련 가이드를 먼저 보여줍니다.