OpenAI Codex CLI

OpenAI Codex CLI 설치 가이드 — Windows, macOS, Linux에서 터미널 AI 코딩 도우미를 설치하고 New API에 연결합니다. 샌드박스 정책과 원자적 패치 편집을 지원합니다.

프로젝트 소개

Codex CLI는 OpenAI에서 제공하는 코딩 에이전트로, 사용자의 컴퓨터에서 로컬로 실행할 수 있습니다.

공식 홈페이지: https://chatgpt.com/codex
프로젝트 홈페이지: https://github.com/openai/codex

사용 예시

특징

기능 분류	특징
터미널 기반 코딩 도우미	Codex CLI는 터미널 기반의 대화형 코딩 도우미로, 명령줄에서 코드를 편집하고 패치를 생성하며 명령을 실행하는 데 사용됩니다.
도구 기반 아키텍처	`apply_patch`, `shell`, `update_plan`, `multi_tool_use` 등의 도구를 제공하여 저장소 파일과 작업을 제어 가능하게 수정할 수 있습니다.
원자적 패치 편집	전용 패치 형식을 사용해 `apply_patch`로 파일을 원자적으로 추가/업데이트/삭제할 수 있어 감사 및 롤백이 용이합니다.
샌드박스와 승인	샌드박스 정책(예: `workspace-write`, `read-only`)과 승인 모드(`on-request`, `on-failure`, `never`)를 지원하여 쓰기 및 네트워크 접근 권한을 제어합니다.
계획 추적	`update_plan`은 단계를 나열하고 상태를 추적하는 데 사용되며, 항상 하나의 `in_progress` 단계만 유지하여 진행 상황을 명확하게 관리합니다.
상호작용 규범	중요한 작업 전에 짧은 사전 설명을 보내고, 친근하고 간결한 톤을 유지하며 진행 상황을 업데이트합니다.
보안 제약	엄격한 규칙(무관한 파일을 임의로 변경하지 않음, 저작권 헤더를 추가하지 않음, 파괴적인 명령을 실행하지 않음)을 따르며, 민감한 작업에는 사용자 승인이 필요합니다.
테스트 및 포맷팅	변경 후 관련 테스트와 포맷팅 도구 실행을 권장하지만, 현재 작업과 무관한 문제까지 수정하지는 않습니다.
출력 및 스타일	최종 출력은 CLI 렌더링 규범(예: `**` 제목, 경로나 명령은 백틱 사용)을 따르며, 훑어보기 쉬운 간결한 구조를 유지합니다.
병렬 실행	`multi_tool_use.parallel`을 통해 여러 도구를 병렬로 실행하여 효율을 높일 수 있습니다.

AI 모델 설정 방법

Windows 가이드

1. 터미널 열기

windows_open_terminal

2. WSL 설치

Windows에서 최적의 성능을 얻으려면 Windows Subsystem for Linux (WSL2)를 설치하고 사용하세요.

WSL2 설치 후 Windows 컴퓨터 재시작

wsl --install

설치가 완료되면 Windows 컴퓨터를 재시작하세요.

Windows 주의사항

CMD보다 PowerShell 사용을 권장합니다
권한 문제가 발생하면 관리자 권한으로 실행해 보세요
일부 백신 소프트웨어가 오탐지할 수 있으므로 화이트리스트에 추가해야 할 수 있습니다

Node Version Manager (NVM) 다운로드

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

NVM으로 Node.js 22 설치

탭 바에서 새 PowerShell 창을 열고 WSL을 실행합니다:

wsl

Node.js를 설치합니다(버전 번호는 시점에 따라 달라질 수 있으므로 OpenAI 공식 문서 요구사항에 맞는 버전을 설치하세요):

nvm install 22

3. Codex CLI 설치

Codex CLI 설치

npm i -g @openai/codex

이 명령은 npm 공식 저장소에서 최신 버전의 Codex CLI를 다운로드하여 설치합니다.

4. 설정 파일 수정

원클릭으로 Codex CLI 설정 파일 수정

iex (irm 'https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/codex-cli-setup.ps1')

windows-configure

5. Codex CLI 사용 시작

이제 Codex CLI를 사용할 수 있습니다!

Codex CLI 시작

WSL2를 시작합니다:

wsl

Codex CLI를 바로 실행합니다:

codex

특정 프로젝트에서 사용하려면:

cd mnt/c/path/to/your/project
codex

Enter를 눌러 Codex CLI를 시작합니다.

Codex CLI 권한 설정: 1. Codex가 파일을 직접 수정하도록 허용; 2. Codex가 파일을 수정할 때 수동 승인 필요

모델 선택

/model

주의: 인터페이스 주소를 변경한 후에는 모든 모델(공식 프리셋 모델 포함)이 사용자 지정 엔드포인트를 호출하며, 공식 계정 Quota는 사용하지 않습니다.

macOS 가이드

1. Homebrew 설치(이미 설치되어 있으면 건너뛰기)

Homebrew는 macOS에서 누락된 소프트웨어 패키지를 관리하는 도구입니다.

공식 사이트: https://brew.sh

Homebrew 설치

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Node.js 환경 설치

Node.js 환경 설치 단계

Homebrew를 업데이트합니다:

brew update

Node.js를 설치합니다:

brew install node

macOS 주의사항

권한 문제가 발생하면 sudo가 필요할 수 있습니다
처음 실행할 때 시스템 환경설정에서 허용해야 할 수 있습니다
Terminal 또는 iTerm2 사용을 권장합니다

설치 성공 여부 확인

설치가 완료되면 터미널을 열고 다음 명령을 입력하세요:

node --version
npm --version

버전 번호가 표시되면 설치가 성공한 것입니다.

3. Codex CLI 설치

Codex CLI 설치

터미널을 열고 다음 명령을 실행하세요:

# Codex CLI 전역 설치
npm install -g @openai/codex

권한 문제가 발생하면 sudo를 사용할 수 있습니다:

sudo npm install -g @openai/codex

Codex CLI 설치 확인

설치가 완료되면 다음 명령으로 정상 설치 여부를 확인하세요:

codex --version

버전 번호가 표시되면 축하합니다! Codex CLI가 성공적으로 설치되었습니다.

4. 설정 파일 수정

원클릭으로 Codex CLI 설정 파일 수정

curl -fsSL https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/codex-cli-setup.sh | bash

macos-configure

5. Codex CLI 사용 시작

이제 Codex CLI를 사용할 수 있습니다!

Codex CLI 시작

Codex CLI를 바로 실행합니다:

codex

특정 프로젝트에서 사용하려면:

cd /path/to/your/project
codex

Enter를 눌러 Codex CLI를 시작합니다.

Codex CLI 권한 설정: 1. Codex가 파일을 직접 수정하도록 허용; 2. Codex가 파일을 수정할 때 수동 승인 필요

주의: 인터페이스 주소를 변경한 후에는 모든 모델(공식 프리셋 모델 포함)이 사용자 지정 엔드포인트를 호출하며, 공식 계정 Quota는 사용하지 않습니다.

6. macOS 자주 발생하는 문제 해결

설치 중 권한 오류가 표시되는 경우

다음 해결 방법을 시도해 보세요:

sudo를 사용해 설치: sudo npm install -g @openai/codex
또는 npm이 사용자 디렉터리를 사용하도록 설정: npm config set prefix ~/.npm-global

macOS 보안 설정으로 실행이 차단되는 경우

시스템이 Codex CLI 실행을 차단하는 경우:

"시스템 환경설정" → "보안 및 개인정보 보호"를 엽니다
"그래도 열기" 또는 "허용"을 클릭합니다
또는 Terminal에서 다음을 실행합니다: sudo spctl --master-disable

Linux 가이드

1. Node.js 환경 설치

Codex CLI를 실행하려면 Node.js 환경이 필요합니다.

Node.js 환경 설치 단계

NodeSource 저장소를 추가합니다:

sudo curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

Node.js를 설치합니다:

sudo apt-get install -y nodejs

Linux 주의사항

일부 배포판은 추가 의존성 설치가 필요할 수 있습니다
권한 문제가 발생하면 sudo를 사용하세요
사용자가 npm 전역 디렉터리에 대한 쓰기 권한을 가지고 있는지 확인하세요

설치 성공 여부 확인

설치가 완료되면 터미널을 열고 다음 명령을 입력하세요:

node --version
npm --version

버전 번호가 표시되면 설치가 성공한 것입니다.

2. Codex CLI 설치

Codex CLI 설치

터미널을 열고 다음 명령을 실행하세요:

# Codex CLI 전역 설치
npm install -g @openai/codex

권한 문제가 발생하면 sudo를 사용할 수 있습니다:

sudo npm install -g @openai/codex

Codex CLI 설치 확인

설치가 완료되면 다음 명령으로 정상 설치 여부를 확인하세요:

codex --version

버전 번호가 표시되면 축하합니다! Codex CLI가 성공적으로 설치되었습니다.

3. 설정 파일 수정

원클릭으로 Codex CLI 설정 파일 수정

curl -fsSL https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/codex-cli-setup.sh | bash

macos-configure

4. Codex CLI 사용 시작

이제 Codex CLI를 사용할 수 있습니다!

Codex CLI 시작

Codex CLI를 바로 실행합니다:

codex

특정 프로젝트에서 사용하려면:

# 프로젝트 디렉터리로 이동
cd /path/to/your/project

# Codex CLI 시작
codex

Enter를 눌러 Codex CLI를 시작합니다.

Codex CLI 권한 설정: 1. Codex가 파일을 직접 수정하도록 허용; 2. Codex가 파일을 수정할 때 수동 승인 필요

주의: 인터페이스 주소를 변경한 후에는 모든 모델(공식 프리셋 모델 포함)이 사용자 지정 엔드포인트를 호출하며, 공식 계정 Quota는 사용하지 않습니다.

5. Linux 자주 발생하는 문제 해결

설치 중 권한 오류가 표시되는 경우

다음 해결 방법을 시도해 보세요:

sudo를 사용해 설치: sudo npm install -g @openai/codex
또는 npm이 사용자 디렉터리를 사용하도록 설정: npm config set prefix ~/.npm-global
그런 다음 PATH에 추가: export PATH=~/.npm-global/bin:$PATH

의존성 라이브러리 누락

일부 Linux 배포판은 추가 의존성 설치가 필요합니다:

# Ubuntu/Debian
sudo apt install build-essential

# CentOS/RHEL
sudo dnf groupinstall "Development Tools"

이 페이지의 목차