Ch1. 설치/로그인
npm·설치 스크립트·winget으로 Codex CLI 설치, ChatGPT 계정 vs CODEX_API_KEY 로그인 분리, 버전 핀 고정과 device-code 로그인·셸 자동완성·앱 서버 헬스체크까지 팀 표준화 전략
핵심 요약
- CLI는 Rust 오픈소스로
npm i -g @openai/codex, 0.106.0+ 직접 설치 스크립트, Windows는winget install OpenAI.Codex(0.113.0+)로 설치합니다. - 사람은 ChatGPT 계정 로그인, CI/자동화는
CODEX_API_KEY환경변수로 자격증명을 분리하고, CI/빌드머신은@openai/codex@<pin>으로 버전 드리프트를 막습니다. - 현재 최신 안정 버전은 0.139.0(2026-06-09)이며, 새 팀 표준은 최소 0.139.0을 기준으로 잡는 편이 안전합니다.
- 0.116.0~0.118.0의 device-code ChatGPT 로그인은 브라우저 콜백이 어려운 원격/헤드리스 환경에서 쓸모가 크고, 토큰도 알아서 갱신해 줍니다.
- 0.117.0부터 app-server TUI가 기본값이므로 팀 문서를 이 UX로 맞추고, WebSocket 앱 서버는
GET /readyz·GET /healthz를 K8s probe에 연결합니다.
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직접 설치 스크립트
CLI 0.106.0부터 macOS/Linux용 직접 설치 스크립트를 GitHub release asset으로 제공합니다. npm을 쓰지 않는 환경에서 유용합니다.
팀 표준화 체크리스트
- 버전 드리프트 방지: CI/빌드머신은
@openai/codex@<pin>으로 핀 고정(재현성) - 업데이트 근거: "업데이트 = Changelog 근거 + 롤백 플랜"을 팀 규칙으로 고정
- IDE 확장 동기화: CLI와 IDE 확장의 호환성/승인 정책이 어긋나지 않게 운영
- 현재 최신 안정 버전: 0.139.0 (2026-06-09)
- app-server TUI 기준 통일: 0.117.0부터 app-server-backed TUI가 기본값이므로, 팀 문서도 이 UX를 기준으로 맞추기
0.138.0~0.139.0 운영 포인트
새 팀 표준은 최소 0.139.0을 기준으로 잡는 편이 안전합니다. 0.138.0은 /app Desktop handoff,
로컬 이미지 파일 path 노출, reasoning effort fallback shortcuts, app-server token usage, ChatGPT v2
personal access token, plugin JSON 자동화를 추가했습니다. 0.139.0은 code mode web search, MCP schema
보존, codex doctor editor/pager diagnostics, Codex cloud용 exec agent provider,
plugin marketplace install/upgrade, codex debug app-server send-message-v2 복구를 반영했습니다.
0.133.0~0.137.0 운영 포인트
0.137.0까지의 핵심 운영 변화는 다음과 같습니다. 0.133.0은 /goal 기본 활성화,
permission profile inheritance, plugin discovery를 보강했고, 0.134.0은 --profile 파일 기반 전환과
MCP environment targeting을 도입했습니다. 0.135.0은 codex doctor와 named permission profile UX,
0.136.0은 /archive, codex app-server --stdio, Bedrock/Windows sandbox 보강, 0.137.0은
cloud-managed config bundle, remote-control grants, plugin JSON 출력, Multi-agent v2 runtime metadata를
추가했습니다.
인증(로그인) / 키 분리 전략
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 fishzsh에서 compdef 관련 에러가 난다면 공식 문서 안내대로 compinit 초기화를 먼저 적용하세요.
TUI 입력 생산성 보강 (0.121.0)
composer가 Ctrl+R reverse search와 accepted slash command local recall을 지원합니다. 팀에서
긴 프롬프트나 운영 명령을 자주 다시 쓴다면, shell completion만큼이나 TUI 입력 히스토리 사용법도
온보딩 문서에 넣어 두세요.
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)
- Mobile remote access: ChatGPT mobile app에서 Mac의 Codex app에 연결해 같은 projects/files/credentials/plugins/skills/configuration을 사용할 수 있음 (2026-05-14)
- Appshots/Archive 운영: 최근 App/CLI 흐름에서는 thread를 pin/archive하고 archived threads를 설정에서 복원할 수 있습니다. 완료된 조사나 폐기된 실험은 archive로 숨기고, 재개가 필요한 작업은
/goal과 title/statusline을 유지하세요. - Remote-control grants: 0.137.0부터 remote-control client pairing과 controller grant 조회/폐기 RPC가 보강됐습니다. 원격 host를 공유하는 팀은 "누가 어떤 controller를 연결했는지"를 운영 로그와 권한 회수 절차에 포함하세요.
- Desktop handoff: 0.138.0부터 CLI의
/app으로 현재 thread를 Codex Desktop으로 넘길 수 있습니다. CLI에서 조사한 뒤 앱의 review/worktree UI로 이어가는 흐름을 팀 표준으로 문서화하세요. - MCP/remote 가시성: App 26.608 계열에서는 active MCP server 표시, remote connection 지원, Computer Use rendering/responsiveness가 보강됐습니다. 앱 온보딩에는 MCP 연결 상태와 remote host 권한 확인을 포함하세요.
# CLI에서 앱으로 전환
codex app /path/to/repoCLI `/app` vs shell `codex app`
codex app /path/to/repo는 셸에서 Desktop 앱을 여는 서브커맨드이고, /app은 실행 중인 CLI thread를
Desktop으로 넘기는 slash command입니다. 팀 가이드에서는 두 경로를 구분해 적어야 혼동이 줄어듭니다.
App 26.423 운영 포인트
26.423부터는 approval dialog 전에 변경안을 검토하는 automatic approval review와, notification에서 현재 task를 이어가는 흐름이 앱 UX에도 드러납니다. 리뷰를 사람만 하도록 둘지, subagent review를 중간 게이트로 넣을지 팀 기준을 명시해 두는 편이 좋습니다.
Codex from anywhere (2026-05-14)
모바일에서 Codex를 쓸 때도 실제 실행은 연결된 Mac host에서 이뤄집니다. 따라서 모바일 접근 권한은 단순 UI 권한이 아니라 해당 host의 프로젝트, 파일, 자격증명, 플러그인, 스킬, 설정에 접근하는 권한으로 취급해야 합니다.
Chrome 확장 운영 기준
Chrome 확장은 로그인된 브라우저 상태와 방문 사이트 내용을 Codex 컨텍스트로 가져올 수 있습니다. localhost, file preview, 공개 페이지 검증은 in-app browser를 먼저 쓰고, Salesforce·Gmail·내부 어드민처럼 로그인 상태가 꼭 필요한 작업만 Chrome 확장으로 제한하세요. 새 host를 허용할 때는 페이지 내용을 신뢰하지 말고, allowlist/blocklist와 browser history 접근 여부를 별도 승인 기준으로 관리해야 합니다.
플랫폼 지원 현황 (2026-04 기준)
macOS(Apple Silicon + Intel Mac)와 Windows(2026-03-04 출시)를 지원합니다. Windows 앱은 네이티브 에이전트 샌드박스(제한된 토큰, 파일시스템 ACL, 전용 격리), PowerShell 지원, 크로스 플랫폼 세션 동기화를 포함합니다. Linux 버전은 개발 중입니다.
Windows / WSL 주의사항
Windows는 온보딩과 제약이 따로 있으니, 팀 가이드에 Windows 문서 링크를 넣어 같은 절차로 따라가게 하세요.
winget 설치 지원 (0.113.0+)
0.113.0부터 winget 퍼블리싱 자동화가 들어가, Windows에서 winget install OpenAI.Codex로 설치할 수 있습니다. npm 말고도 공식 배포 경로가 하나 더 생긴 셈이니 팀 가이드에 반영하세요.
Linux 알려진 이슈
tmux 크래시 수정 (0.114.0)
0.114.0 이전 버전에서 Linux tmux 환경에서 동시 user-shell 조회로 인한 크래시가 발생할 수 있었습니다. tmux 기반 워크플로우를 사용하는 팀은 반드시 0.114.0 이상으로 업데이트하세요.
앱 서버 배포 헬스체크
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