가이드 목록으로
코딩 에이전트·2026년 9월 17일·6분 분량

Codex CLI 설치: 설정, 로그인 및 첫 작업

설치 방법 하나를 선택하고 실행 파일을 확인한 뒤 로그인하세요. 사용자 지정 제공업체 설정을 추가하기 전에 작은 프로젝트 작업부터 시작하세요.

마지막 검토일: .

Codex CLI를 설치하고 실행 파일을 확인한 다음 로그인한 후 프로젝트 디렉터리에서 작은 작업으로 시작하세요. 공식 설치 프로그램은 이제 macOS, Linux, Windows를 모두 지원하며 npm과 Homebrew도 대안으로 남아 있습니다. 아래에서 한 가지 방법을 선택하세요. 정상적으로 작동하는 설치가 첫 단계이며, 계정 액세스와 API 청구는 별도의 선택 사항입니다.

1. 설치 방법 하나 선택

이 명령은 공식 Codex CLI 설치 가이드에서 가져온 것입니다. 에이전트를 실행할 환경에 맞는 설치 프로그램을 사용하세요. Windows 실행 파일을 설치해도 WSL 내부에 별도의 Linux 복사본이 설치되지는 않으며, 노트북에 설치해도 나중에 연결할 원격 서버에 설치되지는 않습니다.

macOS 또는 Linux: 공식 독립 실행형 설치 프로그램
curl -fsSL https://chatgpt.com/codex/install.sh | sh
Windows: 공식 독립 실행형 설치 프로그램
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

이미 패키지 관리자로 개발 도구를 관리하고 있다면 두 설치 프로그램을 모두 실행하지 말고 해당 대안을 사용하세요.

방법설치업데이트
npmnpm install -g @openai/codexnpm install -g @openai/codex
Homebrewbrew install --cask codexbrew upgrade --cask codex
독립 실행형운영 체제에 맞는 설치 프로그램 실행동일한 설치 프로그램을 다시 실행

npm 경로를 사용하려면 작동하는 npm 설치가 필요합니다. 먼저 npm --version를 확인하세요. Node 도구가 따로 필요하지 않다면 독립 실행형 경로가 유용합니다. 관리되는 시스템에서는 관리자가 지원하는 설치 방법을 사용해 이후 업데이트를 예측 가능하게 유지하세요.

2. 어떤 실행 파일이 실행되는지 확인

설치 후 명령을 찾을 수 없다면 새 터미널을 시작하세요. macOS 또는 Linux에서는 command -v codex로 셸에서 선택한 실행 파일을 확인할 수 있습니다. PowerShell에서는 Get-Command codex을 사용하세요. 다시 설치하기 전에 해당 경로를 선택한 설치 방법과 비교하세요. 설치된 복사본이 두 개면 한쪽을 업데이트하면서도 다른 쪽을 계속 실행할 수 있습니다.

확인하고 로그인한 후 첫 작업 실행
codex --version
codex --help

# Open your own project directory before starting
cd /path/to/your/project
codex login
codex login status
codex --sandbox read-only "Explain this project's structure and how its tests run. Do not modify files."

예시 프로젝트 경로를 자신의 경로로 바꾸세요. 최종 명령은 초기 설명을 위해 읽기 전용 샌드박스를 사용합니다. 올바른 저장소와 모델에 접근할 수 있는지 확인한 뒤 에이전트에게 변경을 요청할 수 있으므로 유용한 첫 점검입니다. 사용 가능한 플래그를 확인하려면 설치된 CLI의 도움말이나 명령어 참조를 사용하세요.

3. 올바른 계정 경로 선택

codex login는 계정 로그인 절차를 시작합니다. 완료하기 전에 브라우저 계정과 작업 공간을 확인하세요. OpenAI API를 직접 결제하는 경우 문서에 설명된 대안은 표준 입력을 통해 Platform 키를 받습니다:

선택 사항: OpenAI Platform API 인증
# After supplying OPENAI_API_KEY through your credential setup:
printenv OPENAI_API_KEY | codex login --with-api-key

이 API 명령은 OpenAI Platform 키용입니다. 타사 게이트웨이에 필요한 전체 설정은 아닙니다. 사용자 지정 공급자에는 자체 구성, 엔드포인트, 자격 증명 소스 및 지원 모델이 필요합니다. 인증 문서에서는 경로를 설명하고, Codex API 키 가이드에서는 공급자 설정을 자세히 다룹니다.

4. 첫 번째 응답을 유용한 첫 작업으로 전환

  1. 관련 소스와 테스트가 어디에 있는지 물은 다음, 저장소를 기준으로 답변을 확인하세요.
  2. 작은 변경 하나를 선택하고 예상 동작을 명시하세요.
  3. 깨끗한 브랜치나 체크포인트를 사용하고, 해당 변경에 적절한 권한을 선택하세요.
  4. Codex가 관련 검사를 실행하도록 한 다음, 변경 사항과 설명을 검토하세요.

예를 들어 실패하는 테스트 하나나 작은 문서 수정부터 시작하세요. 첫 작업을 애플리케이션 전체 재작성으로 만들지는 마세요. 설치, 자격 증명, 로컬 종속성 및 작업 품질을 한 번에 평가하기가 모두 더 어려워집니다. 짧은 반복 과정이 작동하면 프로젝트 지침을 추가하고 범위를 넓히세요.

설정이 중단되면 해당 계층을 수정하세요

“Command not found”는 설치 또는 PATH 문제를 가리킵니다. 401은 인증 문제를 가리킵니다. 모델 오류는 선택한 공급자와 모델 문제를 가리킵니다. 한도 경고는 사용량 또는 결제 문제를 가리킵니다. 작동하는 계층은 유지하고 상황에 맞게 401 체크리스트 또는 사용량 한도 가이드를 따르세요. 실행 파일을 다시 설치해도 계정 잔액이 충전되지는 않습니다.

로컬 Codex 작업에 Kunavo를 평가하려면 계정을 만들고 Codex 통합을 따르세요. Responses 호환 공급자 구성을 사용합니다. 더 큰 프로젝트에 새 결제 경로를 사용하기 전에 작은 작업 하나를 확인하세요.

자주 묻는 질문

Codex CLI는 어떻게 설치하나요?

운영 체제에 맞는 공식 독립 실행형 설치 프로그램이나 npm 또는 Homebrew 대안을 사용하세요. 필요한 경우 새 터미널을 열고 codex --version을 확인한 다음 프로젝트 디렉터리에서 Codex를 시작하고 인증 방법을 선택하세요.

npm install -g @openai/codex는 아직 지원되나요?

예. 2026년 9월 17일에 확인한 공식 설치 문서에는 독립 실행형 설치 프로그램 및 Homebrew와 함께 npm이 나와 있습니다. 설치 방법 하나를 선택하고 해당 업데이트 경로를 사용해 서로 충돌하는 복사본이 생기지 않도록 하세요.

Codex를 설치하려면 ChatGPT 구독이 필요한가요?

설치와 모델 액세스는 별개입니다. 지원되는 로컬 작업을 위해 사용 가능한 ChatGPT 로그인 경로나 별도로 청구되는 API 액세스를 선택하세요. 결제 방법을 정하기 전에 현재 계정 옵션을 확인하세요. CLI를 설치해도 모델 크레딧이 추가되지는 않습니다.

Windows에 Codex를 설치할 수 있나요?

예. OpenAI는 Windows용 독립 실행형 설치 프로그램을 제공합니다. 대신 WSL 내부에서 작업하려면 해당 환경 안에 Linux 버전을 설치하고 실행하며, 별도의 프로젝트 경로와 환경 변수를 관리해야 합니다.

공식 설치 문서와 로컬 CLI 도움말을 2026년 9월 17일에 확인했습니다.