Codex CLI 설치하는 법, 명령어와 오류 해결까지

Codex CLI 설치하는 법, 명령어와 오류 해결까지

Codex CLI 설치는 준비 환경, 명령어, 인증 설정, 실행 확인 순서로 잡으면 덜 막힙니다. 특히 업무 저장소에서 바로 실행하기 전에는 작업 디렉터리 권한과 승인 모드를 먼저 좁혀합니다.

Codex CLI는 로컬 터미널에서 실행되는 OpenAI의 코딩 에이전트입니다. 공식 문서 기준으로 선택한 디렉터리의 코드를 읽고 수정하며, 로컬 명령 실행까지 이어갈 수 있습니다.

30초 요약

• Codex CLI는 터미널에서 쓰는 OpenAI 코딩 에이전트입니다.
• 설치는 npm install -g @openai/codex 또는 Homebrew 경로를 따릅니다.
• 업무 저장소에서는 승인 모드, 샌드박싱, 작업 디렉터리 범위를 먼저 좁힙니다.
• 실행 확인은 버전 확인, 도움말 출력, 테스트 저장소 실행 순서로 진행합니다.
• 오류가 나면 인증, Node 또는 Homebrew 경로, 권한 범위를 차례로 점검합니다.

Codex CLI 설치 전에 확인할 환경

Codex CLI 설치 전에는 로컬 터미널, 패키지 설치 경로, 인증 방식, 작업 디렉터리 권한을 먼저 정리합니다. 이 도구는 코드를 읽고 수정할 수 있으므로 개인 실험 폴더와 업무 저장소를 구분해서 시작하는 쪽이 낫습니다.

설치 전에 아래 항목을 메모해두면 첫 실행에서 덜 헤맵니다.

항목	확인할 내용	막히는 장면
실행 위치	개인 테스트 폴더인지 업무 저장소인지 구분	원하지 않는 파일 수정
설치 방식	npm 또는 Homebrew 중 하나 선택	codex 명령어를 못 찾음
인증	OpenAI 계정 또는 API 관련 설정	로그인·권한 오류
승인 모드	명령 실행과 파일 수정 범위 제한	자동 실행 범위가 커짐
프로젝트 규칙	AGENTS.md 같은 작업 규칙 준비	팀 규칙과 다른 변경 발생

처음부터 운영 저장소 루트에서 실행하기보다 작은 샘플 폴더에서 반응을 보는 흐름이 깔끔합니다.

터미널에서 실행할 기본 명령어

Codex CLI 기본 설치 명령은 공식 문서 기준 npm 전역 설치 또는 Homebrew 설치 흐름으로 시작합니다. 설치 뒤에는 codex --help처럼 읽기 전용 확인 명령부터 실행하면 환경 문제를 빨리 좁힐 수 있습니다.

npm을 쓰는 환경이라면 다음 명령어로 시작합니다.

npm install -g @openai/codex

macOS에서 Homebrew를 쓰는 팀이라면 공식 문서의 Homebrew 경로를 따릅니다.

brew install codex

설치 직후에는 바로 저장소 수정을 맡기지 말고 도움말부터 봅니다.

codex --help
codex --version

테스트 폴더를 따로 만들고 실행하면 파일 변경 범위를 눈으로 따라가기 쉽습니다.

mkdir codex-cli-test
cd codex-cli-test
git init
codex

프롬프트는 처음부터 크게 잡지 않는 쪽이 낫습니다.

이 폴더의 파일 구조를 읽고, 수정 없이 요약해줘.

초기 설정 파일과 환경변수

초기 설정에서는 인증 정보, 승인 모드, 샌드박싱, 프로젝트 규칙 파일을 한 번에 정리합니다. 특히 팀 저장소에서는 Codex가 읽을 규칙과 실행해도 되는 명령 범위를 문서로 남겨두는 편이 운영 사고를 줄입니다.

환경변수는 사용하는 인증 방식과 조직 정책에 따라 달라질 수 있습니다. 공식 문서에서 현재 권장 방식을 다시 확인한 뒤 셸 설정 파일에 넣습니다.

export OPENAI_API_KEY="YOUR_API_KEY"

zsh를 쓰면 예시는 이렇게 정리할 수 있습니다.

echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc
source ~/.zshrc

프로젝트 루트에는 작업 규칙 파일을 두면 무난합니다. 예를 들어 AGENTS.md에는 이런 내용을 넣을 수 있습니다.

# Project Rules

- 테스트 없이 대규모 리팩터링을 진행하지 않는다.
- 패키지 매니저는 npm을 사용한다.
- 파일 삭제 전에는 변경 이유를 설명한다.
- 비밀값이 들어간 파일은 읽거나 수정하지 않는다.

이 파일은 팀 규칙을 Codex에게 알려주는 역할입니다. 공식 문서의 설정 항목과 함께 맞춰두면 반복 작업에서 결과가 안정적으로 나옵니다.

설치가 끝났는지 확인하는 방법

설치 확인은 명령어 인식, 버전 출력, 도움말 출력, 테스트 폴더 실행 순서로 보면 됩니다. 여기서 하나라도 실패하면 저장소 작업을 맡기기 전에 설치 경로와 인증 상태부터 고칩니다.

가장 먼저 셸이 codex 명령을 찾는지 확인합니다.

which codex
codex --version
codex --help

npm 전역 설치 경로가 꼬였을 때는 아래 명령으로 현재 경로를 봅니다.

npm config get prefix
npm list -g --depth=0

Homebrew 설치라면 경로를 따로 봅니다.

brew list codex
brew info codex

실행 확인용 프롬프트는 수정 없는 요청으로 시작합니다.

현재 디렉터리의 파일 목록을 읽고, 어떤 프로젝트인지 요약해줘. 파일 수정은 하지 마.

이 단계에서 파일을 읽는 위치와 출력 내용이 예상과 맞으면 다음 단계로 넘어갑니다.

자주 막히는 오류와 해결 순서

Codex CLI 오류는 대개 명령어 경로, 인증, 작업 디렉터리 권한, 승인 모드에서 발생합니다. 증상만 보고 바로 재설치하기보다 어느 단계에서 끊겼는지 먼저 잡으면 시간이 줄어듭니다.

증상	먼저 볼 곳	처리 방향
command not found	npm 또는 Homebrew 설치 경로	전역 설치 경로와 PATH 확인
인증 오류	계정 로그인 또는 API 키	공식 문서의 인증 방식 재확인
파일 수정 거부	작업 디렉터리 권한	저장소 권한과 샌드박싱 설정 점검
명령 실행 대기	승인 모드	실행 허용 범위 확인
예상 밖 변경	프롬프트와 규칙 파일	AGENTS.md에 제한 조건 추가

command not found가 나오면 먼저 셸 경로를 봅니다.

echo $PATH
which npm
which codex

인증 관련 오류는 비밀값이 셸에 들어갔는지부터 봅니다.

echo $OPENAI_API_KEY

실제 키가 그대로 출력되는 환경에서는 터미널 공유에 주의합니다. 화면 녹화나 페어 작업 중에는 값을 마스킹해두는 편이 낫습니다.

예상 밖 파일 변경이 있었다면 Git 상태부터 봅니다.

git status
git diff

변경 내용을 읽고 필요한 부분만 남기는 습관이 필요합니다. 코딩 에이전트는 도구일 뿐이고, 최종 반영 책임은 저장소를 운영하는 사람에게 남습니다.

실무 자동화에 붙이는 예시

실무 자동화에서는 Codex CLI를 배포 전체보다 작은 반복 작업에 먼저 붙이는 구성이 어울립니다. 예를 들면 테스트 실패 요약, 문서 초안, 리팩터링 후보 정리처럼 되돌리기 쉬운 작업부터 시작합니다.

작게 시작하는 예시는 이런 식입니다.

codex

최근 변경된 파일을 읽고 테스트가 필요한 지점을 목록으로 정리해줘. 파일은 수정하지 마.

테스트 실패 분석도 현실적인 출발점입니다.

npm test

방금 테스트 실패 로그를 기준으로 원인을 3개 이하로 정리해줘. 수정 전에는 어떤 파일을 볼지 먼저 말해줘.

문서 보강도 부담이 적습니다.

README의 설치 섹션을 현재 package.json 기준으로 갱신해줘. 명령어는 실제 스크립트 이름만 사용해줘.

팀에서 붙일 때는 아래처럼 범위를 제한합니다.

작업	Codex에 맡길 수 있는 범위	사람이 보는 지점
테스트 실패 요약	로그 분석과 의심 파일 제안	실제 수정 방향
문서 초안	README, 설정 안내 초안	공개 문구와 비밀값
반복 리팩터링	작은 함수 단위 변경	동작 차이와 테스트
PR 검토 보조	변경 파일 요약	보안·비용 영향
자동화 스크립트	초안 작성	권한과 실행 조건

Codex CLI 비교 포인트

Codex CLI 비교는 가격만으로 끝내기 어렵습니다. 로컬 터미널에서 어떤 권한으로 실행되는지, 컨텍스트를 어떻게 다루는지, 실패했을 때 사람이 끊어낼 수 있는지가 실제 차이를 만듭니다.

비교 항목	Codex CLI	일반 채팅형 코딩 도구	IDE 확장형 도구
실행 위치	로컬 터미널	웹 또는 앱	IDE 내부
파일 접근	선택한 디렉터리 중심	사용자가 붙여넣은 코드 중심	열린 프로젝트 중심
명령 실행	로컬 명령 실행 가능	대개 직접 실행 없음	확장 권한에 따라 다름
팀 규칙 반영	설정과 규칙 파일 활용	대화 맥락 의존	IDE 설정 의존
리스크	권한 범위가 커질 수 있음	코드 누락 가능성	IDE 권한 관리 필요

비교할 때는 “누가 더 똑똑한가”보다 “우리 저장소에서 어디까지 실행권을 줄 것인가”가 먼저입니다. 특히 결제와 호출량은 공식 계정 설정과 요금 정책을 다시 확인합니다. 이 글에서는 공식 원문으로 확인되지 않은 비용 수치를 단정하지 않습니다.

도입 전 체크리스트

Codex CLI를 업무에 붙이기 전에는 공식 문서, 권한 범위, 비용, 실패 복구, 수동 검증을 한 번씩 통과시키면 됩니다. 이 다섯 가지가 정리되지 않으면 자동화 범위를 줄여서 시작합니다.

• 공식 문서와 GitHub 저장소를 확인했다.
• npm 또는 Homebrew 설치 경로를 정했다.
• 인증 방식과 비밀값 보관 위치를 정했다.
• 작업 디렉터리를 테스트 폴더로 먼저 제한했다.
• 승인 모드와 샌드박싱 범위를 정했다.
• AGENTS.md에 팀 규칙을 적었다.
• 첫 실행은 파일 수정 없는 요청으로 시작했다.
• git status와 git diff로 변경 내용을 검토했다.
• 자동화 전 수동 검증을 1회 거쳤다.
• 실패 시 멈추는 절차를 팀 안에 공유했다.

자주 묻는 질문

Codex CLI FAQ는 초보자 사용, 업무 자동화, 대안 비교로 많이 모입니다. 답은 설치 가능 여부보다 권한과 실행 범위를 어디까지 줄였는지에 따라 달라집니다.

Codex CLI는 초보 개발자도 바로 쓸 수 있나요?

기본 실행은 가능합니다. 다만 처음에는 테스트 폴더에서 읽기 중심 요청으로 시작하고, 파일 수정과 명령 실행은 승인 범위를 좁힌 뒤 진행하는 쪽이 현실적입니다.

Codex CLI를 업무 자동화에 써도 되나요?

반복 작업과 초안 작성부터 붙이면 됩니다. 공식 문서와 조직 보안 정책을 먼저 맞추고, 배포나 대량 수정처럼 되돌리기 어려운 작업은 사람이 검토하는 구조가 필요합니다.

Codex CLI와 비슷한 도구는 어떻게 비교하나요?

가격만 보지 말고 실행 위치, 컨텍스트 처리, 외부 명령 연결, 실패 복구 절차를 함께 봅니다. 로컬 터미널 권한을 주는 도구라면 작업 디렉터리 제한이 특히 큽니다.

설치했는데 codex 명령어가 안 뜨면 어디부터 보나요?

which codex, npm config get prefix, echo $PATH 순서로 봅니다. Homebrew 설치라면 brew info codex로 설치 위치를 확인합니다.

업무 저장소에서 바로 실행해도 되나요?

처음 실행은 별도 테스트 폴더가 낫습니다. 저장소에서 실행한다면 git status가 깨끗한 상태인지 보고, 수정 없는 요청으로 반응을 먼저 봅니다.

공식 문서와 추가 확인 링크

Codex CLI 관련 내용은 OpenAI 공식 문서와 GitHub 저장소를 우선 확인합니다. 설치 명령, 설정 옵션, 보안 관련 내용은 업데이트될 수 있으므로 공개 글이나 팀 문서에 옮기기 전 원문을 다시 보는 흐름이 필요합니다.

• OpenAI Codex CLI 공식 문서: https://developers.openai.com/codex/cli
• Codex CLI 설정 문서: https://developers.openai.com/codex/cli/configuration
• Codex CLI 보안 문서: https://developers.openai.com/codex/cli/security
• OpenAI Codex GitHub 저장소: https://github.com/openai/codex

이 글은 위 공식 문서와 GitHub 저장소에 근거해 설치 전 환경, 기본 명령어, 설정, 오류 해결 순서를 정리했습니다. 공식 원문으로 확인되지 않은 성능 수치나 비용 평가는 넣지 않았습니다.