2026년 최신 Codex 설치 및 사용 가이드: GPT-5.5-Codex 완전판

2026년 OpenAI는 Codex를 「옛날 코드 자동완성 모델」에서 완전한 프로그래밍 Agent 플랫폼으로 재정의했습니다. Codex CLI는 로컬 터미널에서 저장소를 읽고, 파일을 고치고, 명령을 실행합니다. GPT-5.5-Codex는 소프트웨어 공학 특화 모델입니다. 본문은 한국어판 설치+운영 권위 가이드——3가지 설치법, ChatGPT 로그인, config.toml, 승인 샌드박스, /model 전환, 첫 검증 작업까지 다룹니다. Claude Code / Cursor와의 관계가 궁금하면 아래 비교표와 선택 매트릭스를 참고하세요.

1. 2026년에 Codex CLI를 별도로 설치하는 이유

ChatGPT 웹에서도 코드를 쓸 수 있습니다. 그러나 엔지니어링 팀의 실제 문제는 대화창 제안이 감사 가능한 git diff로 바로 이어지지 않고, 테스트 루프가 불안정하며, CI에 연결하기 어렵다는 점입니다. Codex CLI가 푸는 것은 실행 경계——GPT-5.5 계열을 지정 디렉터리에 두고 샌드박스·승인 정책 아래 파일을 수정하고 shell을 돌리는 것입니다.

2021년 「Codex 자동완성 API」와 달리, 2026년 Codex는 Rust 오픈소스 터미널 Agent(openai/codex)입니다. ChatGPT 구독과 연동되고 IDE 확장·데스크톱 App·Codex Cloud 비동기 작업으로 확장됩니다. 분수령은 「OpenAI vs Anthropic 누가 더 강한가」가 아니라 터미널 Agent에 작업을 맡길 의지가 있는가입니다.

2. Codex 네 가지 진입점 정리

본 가이드는 Codex CLI 중심이지만, 플랫폼 전체는 네 면이며 설정은 ~/.codex/를 공유합니다:

권장 경로는 CLI 우선: CLI 설치 후 IDE 확장·App은 같은 계정으로 설정을 재사용합니다.

3. 핵심 비교: Codex vs Claude Code vs Cursor

요금을 쉽게 말하면: 셋 다 입문은 대략 월 20달러(약 2만7천 원)지만 사는 것이 다릅니다——

• Codex·Claude Code: 휴대폰 데이터 패키지 같습니다. 몇 시간마다 한도가 리셋되고, AI에 파일을 한꺼번에 많이 고치게 하면 금방 소진됩니다.
• Cursor: 헬스장 월 회원권 같습니다. 월 정액이고, 매일 IDE에 붙어 코딩하는 사람일수록 청구가 읽기 쉽습니다.

아래 표의 녹색 열은 「어떻게 과금되고, 월말 청구가 예측 가능한가」——도구 선택 시 가장 봐야 할 축입니다.

IDE 비교 상세는 Claude Code vs Cursor 2026; Anthropic·OpenAI Agent 노선은 Claude Code 시대 서사 참고.

4. 시나리오별 선택

5. 추천 조합(2026 엔지니어링 스택)

• 개인 개발자— Codex CLI(GPT-5.5-Codex) + 기존 IDE로 소규모 수정; 큰 작업은 주말에 codex 위임.
• 풀스택 + iOS— 비즈니스 코드는 Codex/Cursor 로컬; Xcode 빌드·서명은 Cloud Mac 또는 GitHub Runner 실행 노드.
• 팀 CI— codex exec 또는 Codex Cloud patch → Actions 빌드·테스트 → 사람이 PR 리뷰. Runner는 Job당 Workspace 격리.
• 지식 집약 저장소— Codex MCP로 Issue 추적 + 선택 CodeGraph; 규칙은 .codex/config.toml과 AGENTS.md.

6. 설치 전 준비

• 계정— ChatGPT Plus / Pro / Business / Edu / Enterprise(Codex 포함) 또는 OpenAI API Key.
• OS— macOS·Linux 1급; Windows는 PowerShell 네이티브 또는 WSL2.
• Git 저장소— 빈 폴더보다 실제 프로젝트 루트에서 검증 권장.
• Node.js 18+— npm install -g @openai/codex 사용 시만.

uname -a
git --version
node -v   # npm 경로일 때
which codex # 미설치면 출력 없음

7. 세 가지 설치 방법(2026 공식 경로)

# 비대화(CI 이미지)는 먼저
export CODEX_NON_INTERACTIVE=1

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version

npm install -g @openai/codex@latest
codex --version
# EACCES 시: npm config set prefix ~/.npm-global, ~/.npm-global/bin을 PATH에

8. 로그인 및 인증

첫 codex 실행 시 대화 TUI에서 선택:

• Sign in with ChatGPT(권장)— 브라우저 OAuth, 한도는 ChatGPT 플랜에 반영.
• API Key— 자동화·token 정산용; Key를 git에 커밋하지 말 것.

설정·자격 증명은 ~/.codex/. 공유 머신은 파일 권한 주의; CI는 시크릿 관리로 API Key 주입.

9. GPT-5.5-Codex: 모델 전환과 config.toml

GPT-5.5는 범용 플래그십; GPT-5.5-Codex는 코드 작업 특화(저장소 읽기, patch 적용, 툴체인 추론). 일상 소프트웨어 공학은 Codex 변형 기본, 범용 Q&A는 gpt-5.5로 전환.

세션 내 전환: TUI에서 /model → gpt-5.5-codex 및 reasoning 레벨.

영구 기본값: ~/.codex/config.toml(프로젝트는 .codex/config.toml, 프로젝트 신뢰 시):

# 기본 프로그래밍 모델
model = "gpt-5.5-codex"

# 승인: on-request = 권한 초과 시 확인(권장)
approval_policy = "on-request"

# 샌드박스: read-only로 시작, 익숙해지면 workspace-write
sandbox_mode = "read-only"

# 추론 강도(작업에 맞게)
model_reasoning_effort = "medium"

우선순위(뒤가 앞을 덮음): 내장 기본 → ~/.codex/config.toml → 프로젝트 .codex/config.toml → Profile(codex --profile ci) → CLI 인자. 공식 Config basics 참고.

10. 일상 운영: TUI, 승인, MCP, 스크립트화

대화 모드

cd your-repo
codex
# 또는 한 줄 작업
codex "npm test 실행 후 실패 케이스 수정. package-lock은 건드리지 마"

승인 모드(안전 레드라인)

rm, 프로덕션 설정 변경, 비밀 파일 접근은 반드시 수동 승인. 기업 환경은 requirements.toml로 never·danger-full-access 금지 가능.

MCP 확장

Codex는 Model Context Protocol 지원. config.toml에 MCP Server 선언 시 GitHub·DB 등 외부 컨텍스트 읽기. Claude Code MCP와 개념 유사——MCP 설치 가이드에서 PAT 최소 권한 원칙 확인.

exec 스크립트화와 Cloud

• codex exec "..." — 헤드리스 실행. cron / CI 사전 점검.
• Subagents — 대작업 병렬 서브 Agent(TUI 내).
• 로컬 Code Review — 커밋 전 독립 Agent로 diff 리뷰.
• Codex Cloud — 터미널에서 클라우드 작업 시작, patch 가져와 로컬 적용.

11. 흔한 오해

1. Codex를 ChatGPT 웹과 동일시 — CLI 없이 diff 미검토면 엔지니어링 루프 불가.
2. 처음부터 sandbox_mode = danger-full-access — 클릭은 줄지만 실수 삭제는 복구 불가. read-only부터.
3. 하위 디렉터리에서 codex 시작 — Agent는 cwd만 봄. Monorepo는 올바른 패키지 루트에서.
4. Windows 경로 차이 무시 — PowerShell 네이티브와 WSL 저장소 경로는 다름. 하나로 통일.
5. 모델만 비교하고 진입점 무시 — GPT-5.5-Codex는 강력하지만 Tab 자동완성이 핵심이면 Cursor + Codex 확장이 현실적.

12. 7단계 실천 목록

1. CLI 설치 — 공식 install.sh 또는 npm i -g @openai/codex, codex --version 확인.
2. 로그인 — ChatGPT OAuth 또는 API Key, ~/.codex/ 생성 확인.
3. config.toml 작성 — model = "gpt-5.5-codex", approval_policy = "on-request", sandbox_mode = "read-only".
4. 저장소 선택 — 익숙한 중형 프로젝트로 cd, git status 클린 또는 기능 브랜치.
5. 스모크 작업 — codex "src 디렉터리 구조 설명하고 트리 그려줘"로 파일 읽기 확인.
6. 폐루프 작업 — codex "테스트 명령 [your test cmd] 실행 후 실패 수정"으로 shell 실행 확인.
7. 팀 스택 연결 — 24/7 빌드 필요 시 Runner를 Cloud Mac에; 그래프 필요 시 MCP.

13. FAQ

Codex, Claude Code, Cursor 중 가장 저렴한 것은?

겉으로는 모두 $20/월부터, 절대적 「최저가」는 없습니다. ChatGPT 사용 중이면 Codex는 사실상 포함; Claude Pro면 Claude Code도 동일. 처음부터 월 고정이면 Cursor가 읽기 쉽습니다. 대량 파일 일괄 수정 헤비 사용은 $100~$200대 필요할 수 있음——비교표 참고.

Codex 별도 과금 필요?

보통 아니오. ChatGPT Plus($20/월)에 Codex 포함. API Key 종량도 가능하나 클라우드 코드 리뷰 등 멤버 기능 없음. 한도는 OpenAI 안내 참고.

GPT-5.5와 GPT-5.5-Codex 차이?

GPT-5.5 범용; GPT-5.5-Codex는 소프트웨어 공학 튜닝으로 코드 읽기·patch·도구 연동에 강함. 코딩 기본은 Codex 변형.

Codex와 Claude Code 동시 설치?

가능. 설정은 ~/.codex/와 ~/.claude.json 분리. 같은 저장소 시나리오 분리 가능——포맷 이중 수정 방지를 위해 스타일 규약 통일.

설치 후 command not found?

스크립트 후 shell 재시작 또는 설치 경로를 PATH에. Homebrew는 /opt/homebrew/bin; npm은 ~/.npm-global/bin 확인.

Codex 업그레이드 방법?

npm install -g @openai/codex@latest 또는 공식 install 스크립트 재실행; Homebrew는 brew upgrade codex.

14. 마무리

2026년 Codex 설치 가이드의 본질은 OpenAI 프로그래밍 Agent를 파일 시스템·터미널에 연결하는 것입니다. 세 줄로 CLI 설치, ChatGPT 로그인, config.toml에서 gpt-5.5-codex 기본·on-request 승인으로 안전선을 그으면——재현 가능하고 스크립트화되며 Cloud에도 올릴 코딩 워크플로를 갖게 됩니다. Claude Code와 겨루는 것은 「터미널 Agent 진입점」, Cursor와 겨루는 것은 「누가 코딩 주도권을 쥐는가」. 많은 팀은 결국 둘 또는 셋을 병행합니다.

진짜 macOS 빌드가 필요한 독자에게: Agent가 아무리 빨라도 Xcode와 Runner는 Apple 하드웨어에 있어야 합니다. Cloud Mac은 Codex로 로컬 수정·원격 컴파일 「쓰기」와 「검증」 분리에 적합합니다.