AI 코딩 도구 설치·레퍼런스 (4/7) — Codex CLI 설치: macOS·Linux·Windows·WSL2

-

공식 문서 기준 설치 경로 · 인증 · 샌드박스 · AGENTS.md · config.toml 한 페이지 레퍼런스

핵심 요약

  • 대상 독자: Claude Code는 써봤지만 Codex는 처음이거나, 두 툴을 병행하려는 사용자.
  • 얻을 것: 공식 OpenAI Codex 문서 기준 설치(npm/brew), 플랫폼별 verbatim 명령, ChatGPT vs API key 인증, AGENTS.md 첫 템플릿, config.toml 위치, 샌드박스 모드 3종.
  • 선행 조건: 터미널 기본 조작. Node.js 기반 설치이므로 추후 Node 환경이 필요.

1. 설치 방법 한눈에

공식 문서는 npm을 주 경로로, Homebrew를 보조 경로로 제공한다.

방법 플랫폼 권장 상황
npm (권장) macOS, Linux, Windows, WSL2 대부분의 개인 개발 환경
Homebrew macOS, Linux Homebrew로 툴 관리 중인 경우
codex exec (비대화형) 모든 플랫폼 CI·스크립트 자동화

Claude Code와 달리 Codex는 npm 설치가 deprecated가 아니다 — OpenAI 공식 문서가 npm을 1차 경로로 안내한다.

2. 시스템 요구사항

  • OS: macOS / Linux / Windows
  • Windows는 PowerShell 네이티브 (Windows 샌드박스) 또는 WSL2 둘 다 지원
  • Linux: x86_64, arm64
  • macOS: Apple Silicon, x86_64
  • Node.js: 공식 README에 명시 버전은 없음. 최신 LTS(Node 20+) 권장.
  • 네트워크: 인터넷 연결 필수 (ChatGPT 또는 API 인증 위해).

3. 설치 — verbatim 명령어

3.1 npm (권장)

npm i -g @openai/codex

업그레이드:

npm i -g @openai/codex@latest

sudo npm install -g는 권한·보안 이슈가 있으므로 피한다. nvm 또는 fnm으로 사용자 레벨 Node 환경을 쓰는 것이 안전.

3.2 Homebrew (macOS / Linux)

brew install --cask codex

3.3 Windows — PowerShell 네이티브

npm i -g @openai/codex

PowerShell 자체에서 설치되며, 후속 실행 시 Windows의 네이티브 샌드박스를 쓴다. config.toml의 windows.sandbox_mode 옵션으로 제어.

3.4 Windows — WSL2

Ubuntu/Debian 등의 WSL2 배포판에서 npm 명령을 그대로 실행.

npm i -g @openai/codex

WSL2 쪽은 Linux 샌드박스를 쓴다. 프로젝트가 Linux-only 툴체인(Docker, ripgrep, etc.)을 쓴다면 WSL2가 유리.

4. 설치 검증

codex --version

명령어가 잡히지 않으면 npm global bin이 PATH에 들어 있는지 확인:

npm bin -g

5. 인증 — 2가지 옵션

공식 문서가 명시한 두 방법.

옵션 대상 과금 설정 방법
ChatGPT 계정 (권장) Plus / Pro / Business / Edu / Enterprise 구독 구독료 (Codex 포함) 첫 실행 시 브라우저 로그인
API Key Platform 크레딧 사용자 사용량 과금 로그인 시 "API Key"로 전환

ChatGPT Plus/Pro/Business/Edu/Enterprise는 모두 Codex 접근을 포함한다. 무료 ChatGPT 플랜은 불가.

첫 codex 실행 시 프롬프트에서 "Sign in with ChatGPT" 또는 "Use an API Key"를 선택. 이후 자격 증명은 ~/.codex/에 저장.

6. 첫 세션

프로젝트 디렉터리에서:

cd /path/to/your/project
codex

대화형 세션이 시작된다. 기본 명령:

명령 동작
codex 대화형 세션 시작
codex exec "task" 비대화형 1회성 실행 (CI 친화)
codex init 프로젝트 초기화 (AGENTS.md 생성)
codex --version 버전 확인

세션 안에서 쓰는 슬래시 명령 중 기본: - /model — 모델 전환 (GPT-5, GPT-5-Codex 등) - /config — 설정 관련 - /exit 또는 Ctrl+D — 종료

전체 명령은 공식 CLI Reference에 있다.

7. AGENTS.md — Codex의 프로젝트 지침서

Codex는 AGENTS.md 파일을 작업 전 읽는다. Claude Code의 CLAUDE.md에 해당하는 개념이지만 몇 가지 규칙이 다르다.

7.1 파일 위치 및 로딩 우선순위

공식 문서 기준:

  1. 글로벌: ~/.codex/AGENTS.md 또는 ~/.codex/AGENTS.override.md
  2. 프로젝트: Git 루트에서 현재 작업 디렉터리까지 walk down
  3. 병합 순서: 루트에서 내려오며 concat. 현재 디렉터리에 가까운 파일이 위 규칙을 override
  4. 디렉터리당 최대 1개 파일 포함 (AGENTS.override.md가 있으면 그쪽 우선, 없으면 AGENTS.md)

7.2 첫 템플릿 — ~/.codex/AGENTS.md (글로벌)


## 테스트
- JavaScript 파일 수정 후 `npm test` 실행
- Python 파일 수정 후 `pytest -x`

## 의존성
- `pnpm` 선호 (npm 대신)
- 프로덕션 dependency 추가 전 확인 요청

## 커밋
- Conventional commits 사용 (feat:, fix:, chore:)
- 한 PR당 한 가지 주제

7.3 프로젝트 오버라이드 — services/payments/AGENTS.override.md


- `make test-payments`를 쓴다 (`npm test` 대신)
- API 키 rotation 시 보안 채널 통보 필수
- 새 PII 수집 시 법무팀 리뷰 필수

AGENTS.override.md는 상위 규칙을 완전히 덮어쓴다 (concat이 아니라 교체).

7.4 Claude Code의 CLAUDE.md와 공존

같은 레포에서 두 툴을 모두 쓰고 있다면 CLAUDE.md가 AGENTS.md를 import하게 만들면 중복 없이 운영 가능 (Claude Code 쪽 설정):

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

8. ~/.codex/config.toml 기본

CLI와 IDE 확장이 공유하는 설정 파일. 위치는 ~/.codex/config.toml.

주요 설정 카테고리:

model = "gpt-5-codex"

provider = "openai"

approval_policy = "on-request"  # 또는 "on-failure", "never"

sandbox_mode = "workspace-write"  # read-only / workspace-write / danger-full-access

[windows]
sandbox_mode = "elevated"  # 네이티브 Windows 샌드박스 옵션

고급 설정은 Config Reference 참고. 기본값으로 시작 → 필요할 때 추가.

9. 샌드박스 모드 3종

Codex는 세션 중 파일 시스템·네트워크 접근 수준을 샌드박스 모드로 제어한다.

모드 파일 읽기 파일 쓰기 네트워크
read-only ✅ ❌ ❌
workspace-write (기본) ✅ ✅ (작업 디렉터리 내) ❌ (기본)
danger-full-access ✅ ✅ (제한 없음) ✅

9.1 workspace-write에 추가 경로 허용

기본은 작업 디렉터리(cwd)만 쓰기 가능. 추가 경로가 필요하면:

[sandbox]
writable_roots = ["/tmp/build", "/var/log/myapp"]

9.2 승인 정책과의 관계

  • approval_policy: Codex가 언제 승인을 묻는가
  • on-request: 명령이 샌드박스를 벗어날 때마다
  • on-failure: 샌드박스 밖에서 실패했을 때만
  • never: 절대 묻지 않음 (자동화 전용, 위험)
  • sandbox_mode: Codex가 무엇을 할 수 있는가

두 축은 직교 — workspace-write + on-request가 가장 흔한 개인 개발 세팅.

10. Windows 네이티브 vs WSL2 — 선택 기준

조건 권장
Node/Python 위주 프로젝트, Docker 없음 Windows 네이티브
Linux-only 툴체인 (Docker, ripgrep, GNU make 등) WSL2
파일 시스템 성능이 중요한 대형 레포 WSL2 (ext4 내부 작업)
PowerShell 스크립트 자산 많음 Windows 네이티브

WSL2 초기 설정은 Windows Store에서 "Ubuntu" 설치 → wsl --install → 해당 쉘에서 npm 설치.

11. Claude Code와 병행 운영 시

같은 레포에서 두 툴을 모두 쓸 때 흔한 질문.

충돌 가능성 해결
.claude/ vs .codex/ 디렉터리 이름이 다르므로 충돌 없음
AGENTS.md vs CLAUDE.md Claude Code가 @AGENTS.md import → 한 소스
샌드박스 모드 이름이 다름 Codex는 workspace-write, Claude Code는 /sandbox 토글 — 독립
/model 명령 둘 다 같은 이름이지만 각자 자체 모델 리스트 사용

병행 워크플로(Codex로 탐색 → Claude Code로 구현 등)는 시리즈 후속 편에서 다룬다.

12. 반대 시나리오 — 이 가이드가 맞지 않는 경우

  • 무료 ChatGPT 플랜만 있다 → Codex 접근 불가. Plus 이상 또는 API Key 필요.
  • macOS 12 이하 → 공식 지원은 최신 macOS. 기존 시스템은 OS 업그레이드가 선행.
  • Node 없이 글로벌 CLI 쓰고 싶다 → 현재 공식 경로는 npm 중심. Homebrew로 우회 가능하지만 자동 업데이트는 수동.
  • 회사 정책이 /tmp 외 쓰기를 금지 → sandbox_mode = "read-only"로 시작 → 필요 명령만 승인 프롬프트로.

13. 다음 단계

설치가 끝났다면:

  1. ~/.codex/config.toml 고급 설정 — approval · sandbox · 모델 스위칭 실전 (예정).
  2. Codex + Claude Code 병행 워크플로우 — 두 툴의 역할 분담 (예정).
  3. Claude Code 설치 완전판 — 대비·병행 운영 참고.

참고

이 글은 "AI 코딩 CLI 진입 가이드" 시리즈의 6/15 편입니다. last verified: 2026-04-25 (OpenAI 공식 Codex CLI 문서 + GitHub README 기준).

시리즈 전체 안내: 시리즈 목차

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »