Codex CLI 사용법: 설치부터 프로젝트 실행까지 개발자 가이드

Codex CLI는 터미널 안에서 저장소를 읽고, 코드를 수정하고, 명령을 실행하며, 변경 결과를 검토할 수 있는 개발 도구입니다. 처음 사용할 때는 설치 명령만 외우기보다 프로젝트 폴더에서 시작하고, 권한을 확인하고, 작은 요청으로 수정한 뒤 테스트와 diff를 검증하는 흐름을 익히는 것이 중요합니다. 이 가이드는 Codex CLI 설치부터 로그인, 첫 프로젝트 실행, AGENTS.md 설정, 코드 수정과 검증까지 순서대로 설명합니다.

Codex CLI란 무엇인가요?

Codex CLI는 별도 웹 화면으로 코드를 복사하지 않고 현재 터미널과 로컬 저장소의 맥락에서 개발 작업을 수행합니다. 코드 탐색, 오류 원인 분석, 파일 편집, 테스트·린트 실행, 변경 검토뿐 아니라 반복 가능한 작업에서 codex exec를 사용할 수 있습니다. 다만 도구가 제안하거나 실행한 결과를 그대로 배포하는 것이 아니라 개발자가 변경 범위와 명령 결과를 최종 확인해야 합니다.

잘 맞는 작업	처음부터 맡기지 말아야 할 작업
프로젝트 구조와 실행 방법 파악	범위가 정해지지 않은 대규모 재작성
작은 기능 추가와 버그 수정	비밀키·운영 데이터가 필요한 작업
테스트·린트 실행과 실패 원인 분석	검토 없이 운영 배포하는 작업
로컬 diff와 PR 코드리뷰	백업 없는 데이터 삭제·마이그레이션

설치 전 준비할 것

• 지원되는 운영체제와 명령을 실행할 터미널
• 작업할 프로젝트와 해당 저장소에 필요한 Git·런타임·패키지 관리자
• ChatGPT 로그인 또는 조직이 허용한 다른 인증 방식
• 수정 전 상태를 확인할 수 있는 Git 저장소와 깨끗한 작업 트리

Codex CLI가 프로젝트의 빌드 도구까지 대신 설치해 주는 것은 아닙니다. Node.js 프로젝트라면 Node.js와 npm·pnpm, Java 프로젝트라면 JDK와 빌드 도구가 먼저 준비되어야 실제 테스트 명령을 실행할 수 있습니다.

Codex CLI 설치 방법

macOS와 Linux에서 설치하기

2026년 9월 9일 확인한 OpenAI 공식 Codex CLI 문서는 macOS·Linux용 독립 설치 스크립트를 다음과 같이 안내합니다.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

원격 스크립트를 실행하기 전에는 주소가 공식 도메인인지 확인하고 회사 장비라면 보안 정책을 먼저 따르세요. 설치 또는 업데이트 후 열려 있던 터미널을 닫고 새 터미널에서 다음 명령으로 확인합니다.

codex --version
codex --help

버전이 출력되면 실행 파일을 찾을 수 있는 상태입니다. 명령을 찾을 수 없다면 재설치를 반복하기 전에 셸의 PATH와 실제 설치 경로를 확인하세요.

Windows에서 설치하기

Windows는 네이티브 PowerShell과 WSL2가 서로 다른 실행 환경이므로 프로젝트가 있는 환경과 Codex CLI를 실행할 환경을 먼저 정해야 합니다. 설치 방식과 샌드박스 차이는 Codex Windows 설치 가이드에서 별도로 정리했습니다.

처음 로그인하고 프로젝트 열기

터미널에서 작업할 저장소로 이동한 뒤 codex를 실행합니다. 공식 문서에 따르면 첫 실행 때 ChatGPT 로그인 또는 화면에 제공되는 다른 로그인 방식을 선택할 수 있습니다.

cd /path/to/your-project
git status
codex

로그인용 주소, 토큰이나 API 키를 소스코드와 셸 기록에 남기지 마세요. 조직 계정을 쓴다면 올바른 워크스페이스로 로그인했는지 확인하고, 사용할 수 있는 모델과 기능은 계정·조직 정책에 따라 달라질 수 있습니다.

첫 프로젝트는 읽기 전용 요청으로 시작하세요

처음부터 “프로젝트를 전부 개선해줘”라고 요청하면 목표와 완료 조건이 모호해집니다. 먼저 저장소 구조와 실행 명령을 확인하는 요청으로 Codex가 현재 위치와 프로젝트 규칙을 제대로 이해했는지 검증하세요.

답변에 나온 명령은 package.json, 빌드 파일 또는 프로젝트 문서와 일치하는지 확인합니다. 존재하지 않는 명령을 제안했다면 추측하지 말고 해당 설정 파일을 다시 읽도록 요청하세요.

작은 기능을 맡기는 프롬프트 작성법

좋은 요청에는 목표, 수정 범위, 지켜야 할 조건, 검증 방법이 들어갑니다. 다음 템플릿은 프론트엔드·백엔드·React·Java 프로젝트에 공통으로 적용할 수 있습니다.

React 예시

검색 입력의 디바운스를 300ms로 적용해줘.
src/components/SearchForm.tsx와 관련 테스트만 수정하고 새 패키지는 추가하지 마.
수정 후 lint와 해당 테스트를 실행하고 결과를 요약해줘.

Java 예시

OrderService의 null 요청 처리에 명확한 예외를 추가해줘.
공개 API 시그니처는 유지하고 관련 단위 테스트를 보강해줘.
변경 후 프로젝트에 정의된 테스트 명령을 실행해줘.

권한과 샌드박스는 어떻게 설정하나요?

CLI 화면에서 /permissions로 Codex가 할 수 있는 작업 범위를 확인할 수 있습니다. 공식 명령 참조에는 승인 정책을 조절하는 --ask-for-approval과 작업 디렉터리를 지정하는 --cd 같은 옵션도 문서화되어 있습니다. 기본값을 무조건 넓히기보다 현재 작업에 필요한 폴더와 명령만 허용하는 편이 안전합니다.

• 파일 읽기만 필요한 조사 단계에서는 수정하지 말라고 명시합니다.
• 패키지 설치, 외부 네트워크와 프로젝트 밖 경로 접근은 목적을 확인한 뒤 승인합니다.
• .env, 인증서, 고객 데이터와 운영 자격 증명은 프롬프트나 로그에 노출하지 않습니다.
• 승인과 샌드박스를 모두 우회하는 위험한 옵션은 격리된 환경이 아니라면 사용하지 않습니다.

AGENTS.md로 프로젝트 규칙 전달하기

Codex는 작업 전에 AGENTS.md를 읽어 저장소별 지침을 적용할 수 있습니다. 대화마다 반복할 빌드·테스트 명령, 코드 스타일, 수정 금지 영역과 완료 기준을 저장소 루트에 기록하면 결과의 일관성을 높일 수 있습니다. CLI에서 /init은 시작용 AGENTS.md를 만드는 데 사용할 수 있습니다.

# AGENTS.md

## Working agreements
- 변경 전 관련 코드를 먼저 읽습니다.
- 새 프로덕션 의존성은 임의로 추가하지 않습니다.
- 수정 후 프로젝트의 lint와 test를 실행합니다.
- 실패한 검증은 성공으로 표현하지 않습니다.
- .env와 자격 증명을 출력하지 않습니다.

상위 디렉터리와 하위 디렉터리의 규칙이 어떻게 합쳐지는지는 Codex AGENTS.md 작성법에서 예시와 함께 확인할 수 있습니다.

작업 중 자주 쓰는 명령

명령	용도	확인할 점
/status	현재 세션 설정 확인	작업 디렉터리와 권한이 맞는지
/permissions	허용된 작업 범위 선택	필요 이상으로 넓지 않은지
/model	모델과 추론 수준 선택	계정에서 제공되는 선택지인지
/review	변경을 검토하고 문제 탐색	최종 판단은 diff와 테스트로 재확인
/init	AGENTS.md 시작 파일 생성	프로젝트 명령에 맞게 수정했는지

명령은 버전에 따라 바뀔 수 있으므로 codex --help와 현재 화면에서 /를 입력해 제공되는 목록을 함께 확인하세요.

처음 30분에 해볼 안전한 실습

새 도구를 익힐 때는 실제 기능 개발보다 변경 범위가 작고 되돌리기 쉬운 문서 작업으로 전체 흐름을 먼저 경험하는 편이 좋습니다. 다음 실습은 저장소 설명을 확인하고 README의 오탈자 한 곳만 고친 뒤 diff를 검토하는 과정입니다.

1. git status --short로 시작 전 변경 파일을 기록합니다.
2. Codex에 프로젝트 구조와 README에서 확인 가능한 오탈자 후보만 찾도록 요청합니다.
3. 후보와 근거를 읽은 뒤 수정할 문장 한 곳을 지정합니다.
4. 수정 후 git diff -- README.md로 예상한 한 부분만 바뀌었는지 확인합니다.
5. 문서 검사 명령이 있으면 실행하고, 없다면 실행하지 않았다고 결과에 기록합니다.
6. 원하지 않는 변경이면 해당 파일의 사용자 작업을 보존한 상태에서 수정 부분만 되돌립니다.

작업 결과를 기록하는 템플릿

“완료했습니다”라는 문장만으로는 변경의 안전성을 판단하기 어렵습니다. 작업이 끝나면 아래 형식으로 결과를 요청하고 실제 터미널 출력과 대조하세요.

Codex CLI 첫 작업 체크리스트 내려받기

기록 항목	작성 내용	판정 기준
요청 목표	해결하려던 한 가지 문제	최초 요청과 일치
변경 파일	추가·수정·삭제 파일	허용한 범위 안에 있음
핵심 diff	동작이 달라진 이유	불필요한 재작성 없음
검증 명령	명령과 성공·실패 결과	원문 결과와 일치
미검증 항목	실행하지 못한 검사와 이유	성공한 것처럼 표현하지 않음
남은 위험	호환성·보안·배포 영향	후속 판단 가능

수정 후 반드시 검증하는 순서

1. 변경 파일 확인: git status --short로 예상하지 않은 파일이 생기지 않았는지 봅니다.
2. diff 읽기: git diff로 요구 범위를 벗어난 수정과 비밀정보 노출을 확인합니다.
3. 정적 검사: 프로젝트에 정의된 lint와 타입 검사를 실행합니다.
4. 테스트: 관련 단위 테스트부터 전체 테스트로 범위를 넓힙니다.
5. 빌드: 배포 산출물이 필요한 프로젝트라면 실제 빌드까지 확인합니다.
6. 수동 확인: UI·API처럼 자동 검사로 부족한 부분은 직접 동작을 확인합니다.

git status --short
git diff
# 프로젝트에 정의된 명령 예시
pnpm run lint
pnpm test
pnpm build

테스트가 실패했는데 “기존 문제”라고 단정하지 말고, 변경 전에도 같은 오류였는지 재현하거나 원인을 분리해야 합니다. 상세한 diff 검토 절차는 Codex 코드리뷰 사용법을 참고하세요.

초보자가 자주 겪는 오류

증상	먼저 확인할 항목
codex 명령을 찾을 수 없음	새 터미널, 설치 경로, PATH, codex --version
로그인이 반복됨	계정·워크스페이스, 시스템 시간, 프록시와 조직 정책
엉뚱한 프로젝트를 읽음	pwd, git rev-parse --show-toplevel, 실행 위치
파일 수정이 거부됨	워크스페이스 범위, 샌드박스, 승인 요청
테스트 명령이 실패함	의존성 설치, 런타임 버전, 프로젝트 공식 스크립트
화면이 멈춘 것처럼 보임	승인 대기, 장시간 명령, 다른 에이전트 작업 상태

증상별 PATH, 인증, 네트워크, 로그와 샌드박스 진단은 Codex CLI 오류 해결 가이드에 정리했습니다.

반복 작업은 codex exec로 자동화하기

대화형 실행에 익숙해진 뒤에는 공식 문서에 안내된 codex exec로 스크립트와 CI 같은 비대화형 흐름을 구성할 수 있습니다. 먼저 위험이 낮고 결과를 사람이 검토할 수 있는 작업부터 시작하세요.

codex exec "현재 변경 사항을 검토하고 잠재적 버그를 요약해줘"

자동화에서는 표준 출력, 종료 코드, 승인 정책, 비밀정보 처리와 실패 시 중단 조건을 명확히 해야 합니다. 저장소를 수정하거나 배포하는 자동화는 대화형 세션에서 충분히 검증한 뒤 별도 보호 장치와 함께 적용하세요.

설치와 첫 실행 검증표

검증 단계	실행 또는 확인	통과 기준
설치	codex --version	오류 없이 버전 표시
프로젝트 위치	git rev-parse --show-toplevel	의도한 저장소 루트 표시
규칙 인식	적용 지침을 요약하도록 요청	AGENTS.md 핵심 규칙과 일치
읽기 전용 분석	구조와 명령만 설명하도록 요청	파일 변경 없음
작은 수정	한 기능과 검증 명령 지정	허용 범위 안에서만 변경
최종 검토	git diff와 테스트	예상 diff와 성공한 검증 확인

편집부 결론

Codex CLI를 안정적으로 쓰는 핵심은 설치 자체보다 실행 위치, 프로젝트 규칙, 권한, 요청 범위와 검증 습관입니다. 저장소 루트에서 읽기 전용 분석으로 시작하고, 작은 수정 단위로 요청한 뒤 diff·테스트·빌드를 직접 확인하세요. 이 흐름을 지키면 프론트엔드, 백엔드, React, Java 등 기술 스택이 달라도 같은 원칙으로 적용할 수 있습니다.

이 글은 2026년 9월 9일 OpenAI 공식 Codex CLI, 개발자 명령, AGENTS.md 문서를 대조해 작성한 가이드입니다. 특정 운영체제에서 설치 전 과정을 직접 촬영한 체험담은 아니며 CLI 버전, 계정과 조직 정책에 따라 설치 화면·명령·기능이 달라질 수 있습니다. 실행 전 최신 공식 문서와 현재 CLI의 도움말을 함께 확인하세요.

공식 문서와 함께 읽을 글

OpenAI Codex CLI 공식 가이드 확인하기

Codex CLI 명령과 옵션 확인하기

Codex AGENTS.md로 프로젝트 규칙 설정하기

Codex CLI 실행 오류 단계별 해결하기

Codex로 변경 코드와 PR 검토하기

자주 묻는 질문

Codex CLI 설치 후 가장 먼저 무엇을 해야 하나요?

새 터미널에서 codex --version을 확인한 뒤 작업할 Git 저장소로 이동해 codex를 실행하세요. 로그인 후에는 파일을 수정하지 않는 프로젝트 구조 분석부터 시작하는 것이 좋습니다.

Codex CLI는 코딩을 몰라도 사용할 수 있나요?

자연어로 요청할 수 있지만 변경된 코드와 테스트 결과를 판단할 기본 개발 지식은 필요합니다. 검토 없이 생성 코드를 운영 환경에 배포해서는 안 됩니다.

Codex CLI는 어떤 프로젝트에서 사용할 수 있나요?

현재 컴퓨터에서 열 수 있고 필요한 개발 도구가 준비된 다양한 코드 저장소에서 사용할 수 있습니다. 실제 실행 가능 여부는 언어, 런타임, 저장소 권한과 조직 정책에 따라 달라집니다.

첫 프롬프트는 어떻게 작성하면 좋나요?

프로젝트 목적, 주요 폴더, 적용되는 지침, 실행 가능한 테스트 명령을 설명하되 파일은 수정하지 말라고 요청하세요. 답변이 실제 설정 파일과 맞는지 확인한 뒤 작은 변경을 맡깁니다.

Codex가 수정한 코드는 어떻게 확인하나요?

git status --short와 git diff로 변경 범위를 읽고 프로젝트의 lint, test와 build를 실행하세요. UI나 API 동작은 필요한 경우 직접 수동 검증도 해야 합니다.

AGENTS.md는 꼭 만들어야 하나요?

필수는 아니지만 반복되는 빌드·테스트 명령, 코드 스타일, 금지 사항과 완료 기준을 일관되게 전달하는 데 유용합니다. 짧고 검증 가능한 규칙부터 작성하세요.

권한 요청은 모두 허용해도 되나요?

아닙니다. 실행할 명령, 접근할 경로와 외부 네트워크가 작업에 필요한지 확인하고 최소 범위만 승인하세요. 비밀정보와 운영 데이터 접근은 특히 주의해야 합니다.

Codex CLI를 자동화에도 사용할 수 있나요?

공식 문서의 codex exec를 통해 반복 워크플로와 CI에 사용할 수 있습니다. 먼저 대화형 실행으로 작업을 검증하고 종료 코드, 실패 처리와 권한 정책을 명확히 설정하세요.