Ch1. 설치/로그인

Codex는 CLI, 데스크톱 앱(Codex App), IDE 확장을 통해 사용할 수 있습니다. CLI는 오픈소스이며 Rust로 구현되어 있습니다. 팀에서는 설치/업데이트 경로를 표준화해 버전 불일치를 줄이는 것이 핵심입니다.

설치/로그인 원칙

• 설치 절차는 공식 CLI 문서를 기준으로 고정
• 로그인은 ChatGPT 계정 또는 API 키 방식 중 하나를 표준화
• CI/서버는 API 키 기반으로 분리 운용
• Windows는 네이티브 샌드박스/PowerShell 지원이 있는 공식 경로로 운영

CLI 빠른 시작 (공식)

# npm으로 설치
npm i -g @openai/codex

# 또는 직접 설치 스크립트 (macOS/Linux, 0.106.0+)
curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | sh

# 실행
codex

# 업데이트
npm i -g @openai/codex@latest

팀 표준화 체크리스트

• 버전 드리프트 방지: CI/빌드머신은 @openai/codex@<pin>으로 핀 고정(재현성)
• 업데이트 근거: "업데이트 = Changelog 근거 + 롤백 플랜"을 팀 규칙으로 고정
• IDE 확장 동기화: CLI와 IDE 확장의 호환성/승인 정책이 어긋나지 않게 운영
• 현재 최신 안정 버전: 0.130.0 (2026-05-08)
• app-server TUI 기준 통일: 0.117.0부터 app-server-backed TUI가 기본값이므로, 팀 문서도 이 UX를 기준으로 맞추기

인증(로그인) / 키 분리 전략

Codex는 최초 실행 시 로그인 흐름을 안내합니다. 운영 관점에서는 "사람"과 "자동화"의 자격증명을 분리하는 게 핵심입니다.

• 개인 개발자: ChatGPT 계정 로그인 기반(로컬 세션 중심)
• CI/자동화: CODEX_API_KEY 환경변수 기반(토큰/권한/감사 경로 분리)
• 플랜 확인: Codex는 ChatGPT Plus/Pro/Business/Edu/Enterprise 고객에게 제공됩니다(최종 정책은 pricing 페이지 기준)

ChatGPT Device-Code 로그인 (0.116.0 → 0.118.0)

App-server TUI 온보딩 시 디바이스 코드 기반 ChatGPT 로그인이 지원되며, 0.118.0부터는 app-server 클라이언트 전반에서 이 흐름을 더 안정적으로 시작할 수 있습니다. 브라우저 콜백 로그인에 의존하기 어려운 원격/헤드리스 환경에서 특히 유용합니다. 또한 기존에 발급된 ChatGPT 토큰의 자동 갱신도 처리되므로, 장시간 세션에서 토큰 만료로 인한 재인증 부담이 줄어듭니다.

셸 자동완성(팀 생산성 기본값)

codex completion을 켜두면 옵션/서브커맨드 탐색 비용이 크게 줄어듭니다.

# zsh 예시
eval "$(codex completion zsh)"

# bash / fish도 지원
codex completion bash
codex completion fish

zsh에서 compdef 관련 에러가 난다면, 공식 문서의 안내대로 compinit 초기화를 먼저 적용하세요.

Codex App(데스크톱)

Codex App은 macOS와 Windows 데스크톱 앱으로, 멀티에이전트 작업을 병렬로 관리하는 데 최적화되어 있습니다.

• 프로젝트별 스레드 관리: 사이드바에서 프로젝트 전환, 스레드별 독립 컨텍스트
• 프로젝트 없이 시작하는 chats: 리서치/기획/분석처럼 코드베이스 없이 시작하는 작업에 적합
• Git 워크트리 기본 지원: 여러 에이전트가 같은 레포에서 충돌 없이 병렬 작업
• 스레드별 통합 터미널: 테스트·빌드·커스텀 명령 실행
• task sidebar + artifact viewer: 계획, 소스, 산출물, 요약을 사이드바에서 추적하고 PDF/스프레드시트/문서/프레젠테이션을 미리보기
• 인라인 diff 리뷰/코멘트: 에이전트 변경사항을 앱 내에서 직접 리뷰
• 자동화(Automations): 백그라운드 실행 + Skills 연동, 인박스 관리, 로컬/워크트리 실행 선택, 모델·추론 수준 개별 지정 (App 26.312)
• 테마 커스터마이징: 베이스 테마, 색상, 폰트를 자유롭게 변경하고 팀과 공유 (App 26.312)
• in-app browser + thread automations: 로컬 웹앱을 앱 안에서 열고 코멘트할 수 있으며, 같은 스레드를 주기적으로 깨우는 자동화도 가능 (App 26.415)
• browser use + cookie 유지: in-app browser가 쿠키를 유지하고 browser use를 지원해, 로그인된 프리뷰를 더 현실적으로 검증 가능 (App 26.423)
• 이미지/Figma/Slides 워크플로우: 이미지를 바로 thread로 넣고, Figma integration과 slides 생성/편집까지 앱 안에서 이어갈 수 있음 (App 26.423)
• Chrome 확장: 로그인된 브라우저 상태가 필요한 외부 SaaS·내부 도구 작업을 Chrome tab group으로 병렬 실행 가능 (2026-05-07)

# CLI에서 앱으로 전환
codex app /path/to/repo

Windows / WSL 주의사항

Windows 지원은 별도 온보딩/제약이 있으므로, 팀 가이드에는 Windows 문서 링크를 포함해 동일한 절차로 따라가게 하세요.

Linux 알려진 이슈

앱 서버 배포 헬스체크

WebSocket 기반 앱 서버를 배포하는 경우, 0.114.0부터 GET /readyz와 GET /healthz 엔드포인트가 노출됩니다. Kubernetes liveness/readiness probe나 로드밸런서 헬스체크에 활용할 수 있습니다.

# Kubernetes 예시
livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
readinessProbe:
  httpGet:
    path: /readyz
    port: 8080

오픈소스(문제 해결 루프)

CLI는 오픈소스 개발이 진행되므로, 이슈 재현/리포팅은 GitHub 저장소를 기준으로 운영하는 편이 빠릅니다. 팀 내 "재현 로그 → 최소 재현 레포 → 이슈 등록" 프로세스를 표준화하면 장기적으로 비용이 줄어듭니다.

참고 문서

• Codex CLI 설치/로그인: https://developers.openai.com/codex/cli (영어)
• Codex App: https://developers.openai.com/codex/app (영어)
• Codex 문서 홈: https://developers.openai.com/codex (영어)
• Pricing(플랜/접근): https://developers.openai.com/codex/pricing (영어)
• Changelog(업데이트 근거): https://developers.openai.com/codex/changelog (영어)
• CLI 기능(자동완성/옵션): https://developers.openai.com/codex/cli/features (영어)
• Windows: https://developers.openai.com/codex/windows (영어)
• Open Source: https://developers.openai.com/codex/open-source (영어)
• GitHub Releases: https://github.com/openai/codex/releases