Codex CLI 설치와 사용법,
첫 프로젝트를 샌드박스에서 끝내기

설치는 한 줄이지만 설치 방식은 세 가지입니다

OpenAI 공식 GitHub 저장소와 개발자 문서에 따르면 macOS·Linux에서는 다음 명령으로 표준 설치 스크립트를 실행합니다.

같은 명령을 다시 실행하면 업데이트로 동작합니다. npm 환경이 이미 있다면 npm install -g @openai/codex로, macOS에서 Homebrew를 쓴다면 brew install --cask codex로도 설치할 수 있습니다. 세 방법 모두 최종적으로 같은 codex 실행 파일을 PATH에 등록합니다. GitHub Releases에서 플랫폼별 바이너리(macOS는 Apple Silicon용 codex-aarch64-apple-darwin.tar.gz, 인텔 맥은 codex-x86_64-apple-darwin.tar.gz)를 직접 내려받아 압축을 풀고 codex로 이름을 바꿔 쓰는 방법도 있는데, 이 경우는 업데이트를 수동으로 반복해야 합니다.

Node.js가 필요한 npm 설치 방식과 달리 표준 설치 스크립트는 별도 런타임 없이 바로 실행 파일을 받습니다. 사내 프록시나 GitHub API 요청 제한 때문에 설치가 막히면 CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false 환경변수로 GitHub Releases 경로를 강제할 수 있습니다.

로그인은 ChatGPT 계정 또는 API 키, 두 갈래입니다

설치 뒤 프로젝트 폴더에서 codex를 실행하면 로그인 방식을 고르는 화면이 뜹니다. OpenAI 인증 문서는 두 가지를 안내합니다. ChatGPT로 로그인하면 Plus·Pro·Business·Edu·Enterprise 등 가입한 플랜의 사용량에 포함되고, API 키로 로그인하면 OpenAI Platform 계정의 표준 API 요금으로 별도 과금됩니다. API 키는 platform.openai.com/api-keys에서 발급받습니다.

CI·스케줄러처럼 사람이 없는 자동화에는 API 키 인증이 맞지만, 신뢰할 수 없는 환경이나 공개 저장소에 그대로 노출하지 않아야 합니다. ChatGPT 로그인은 토큰이 만료되기 전에 자동으로 갱신되므로 평소 사용에는 다시 로그인할 일이 적습니다.

첫 작업은 설치 확인이 아니라 저장소 탐색부터 시킵니다

공식 퀵스타트는 첫 실행에서 곧바로 코드를 고치기보다 Tell me about this project처럼 프로젝트를 설명해달라고 요청하는 예시를 제시합니다. 처음부터 큰 변경을 맡기면 승인 창이 계속 뜨고 결과도 검토하기 어려우므로, 작은 조회·설명 작업으로 시작해 Codex가 저장소 구조를 어떻게 읽는지 먼저 확인하는 편이 낫습니다. 문서는 작업 전후로 Git 체크포인트(커밋 또는 스태시)를 만들어두면 언제든 되돌릴 수 있다고 권장합니다.

실제로 기존 프로젝트에서 첫 작업을 맡길 때는 읽기 전용에 가까운 요청부터 시작하는 것이 안전합니다. 예를 들어 새로 받은 저장소라면 이 프로젝트의 빌드·테스트 명령을 알려줘처럼 실행 결과를 바꾸지 않는 질문으로 Codex가 프로젝트를 얼마나 정확히 파악하는지 가늠한 뒤, 작은 버그 수정 같은 실제 편집으로 넘어가는 순서가 안전합니다.

샌드박스 모드와 승인 정책은 따로 움직입니다

OpenAI 문서는 샌드박스와 승인을 다른 통제로 구분합니다. 샌드박스는 Codex가 어떤 파일을 건드리고 네트워크를 쓸 수 있는지 정하는 기술적 경계이고, 승인 정책은 그 경계를 넘을 때 언제 멈춰서 물어볼지를 정합니다. macOS에서는 기본 내장된 Seatbelt로 샌드박스가 자동 적용되고, Linux·WSL2에서는 bubblewrap을 먼저 설치해야 합니다.

승인 정책은 untrusted(신뢰 목록에 없는 명령마다 확인), on-request(샌드박스 안에서는 자동 진행하고 경계를 넘을 때만 확인), never(승인 요청 없이 진행)로 나뉩니다. 일상적인 로컬 자동화에는 --sandbox workspace-write --ask-for-approval on-request 조합이 저위험 기본값으로 안내되고, 완전 자동화는 danger-full-access와 never를 함께 쓰는 --yolo에 해당하는데 이 조합은 잃어도 상관없는 컨테이너·VM 밖에서는 쓰지 말라고 명시돼 있습니다.

여러 디렉터리를 함께 다뤄야 한다면 설정에서 필요한 경로만 쓰기 가능 범위에 추가해 샌드박스를 유지한 채 경계를 넓힐 수 있습니다. 매번 같은 예외를 승인하기 귀찮다고 danger-full-access로 건너뛰기보다, 정말 필요한 디렉터리 하나만 허용하는 편이 파일 경계를 지키면서 문제를 해결하는 방법입니다.

AGENTS.md로 프로젝트 규칙을 알려줍니다

Codex는 작업을 시작할 때마다 AGENTS.md 파일을 찾아 읽습니다. 전역 설정은 ~/.codex(환경변수 CODEX_HOME으로 변경 가능) 아래의 AGENTS.md이고, 프로젝트 설정은 Git 루트에서 현재 작업 디렉터리까지 내려오며 각 디렉터리의 AGENTS.md를 순서대로 찾습니다. 여러 파일이 있으면 루트에서부터 이어 붙이되, 현재 디렉터리에 가까운 파일이 뒤에 오므로 더 구체적인 규칙이 앞선 규칙을 덮어씁니다.

세부 규칙이 필요한 하위 폴더에는 AGENTS.override.md를 둘 수 있습니다. 이 파일이 있으면 같은 디렉터리의 AGENTS.md보다 우선 적용됩니다. 파일 크기가 project_doc_max_bytes(기본 32KiB)를 넘으면 잘려나가므로, 규칙이 길어지면 파일을 하나로 몰아넣기보다 하위 디렉터리별로 나누는 편이 안전합니다. 이미 CLAUDE.md나 팀 내부 문서를 쓰고 있다면 project_doc_fallback_filenames에 파일명을 추가해 그대로 인식시킬 수 있습니다.

업데이트와 삭제, 설치 방식을 따라갑니다

표준 설치 스크립트로 설치했다면 같은 설치 명령을 다시 실행하는 것이 업데이트입니다. npm으로 설치했다면 npm install -g @openai/codex를 다시 실행하고, Homebrew라면 brew upgrade --cask codex를 씁니다. 삭제할 때는 설치에 쓴 방식의 역순으로 패키지 매니저에서 제거하거나 실행 파일을 지우고, 로그인 정보가 남아있는 ~/.codex 디렉터리(설정·AGENTS.md·auth.json 포함)도 계정 전환이나 재설치 전에 함께 정리할지 판단해야 합니다. 여러 설치 방식을 섞어 썼다면 which codex로 실제 실행되는 경로부터 확인하는 편이 업데이트 누락을 줄입니다.

자주 묻는 질문

Q. ChatGPT 로그인과 API 키 로그인을 나중에 바꿀 수 있나요?
네. 프로필 메뉴에서 로그아웃한 뒤 원하는 방식으로 다시 로그인하면 됩니다. 다만 조직에서 forced_login_method로 로그인 방식을 강제해뒀다면 관리자 설정을 따라야 합니다.

Q. workspace-write 모드에서도 인터넷을 쓸 수 있나요?
기본적으로 네트워크 접근은 막혀 있습니다. 패키지 설치나 git push처럼 네트워크가 필요한 명령은 조용히 실패하는 대신 승인 요청으로 나타나므로, 실제로 인터넷이 필요한 프로젝트라면 network_access = true 설정을 검토해야 합니다.

Q. AGENTS.md를 프로젝트마다 새로 써야 하나요?
전역 ~/.codex/AGENTS.md에 공통 작업 습관을 적어두면 모든 저장소에 상속되고, 프로젝트 루트의 AGENTS.md는 그 프로젝트에서만 적용됩니다. 팀 전체가 같은 도구·명령을 쓴다면 루트 파일 하나로 시작해 필요할 때 하위 디렉터리에 override를 추가하는 편이 관리하기 쉽습니다.