✨ 터미널에 AI 엔지니어가 왔다: Codex CLI 완전 입문 가이드

5분 만에 읽는 · 첫 AI 코딩 에이전트

대상: 초보자 · CLI · OpenAI

ChatGPT에 코드를 붙여넣고 "버그를 찾아줘"라고 물으면 훌륭한 분석을 해줍니다. 하지만 그 수정 사항을 에디터에 수동으로 다시 복사하고, 창을 전환하고, 테스트하다 보면... 어느새 30분이 지나 있습니다.

마치 "좋은 조언은 해주지만, 키보드에는 절대 손을 대지 않는" 친구 같습니다.

Codex CLI는 다릅니다. 조언할 뿐만 아니라, 당신의 머신 위에서 실제로 작업합니다.

Codex CLI는 OpenAI가 개발한

오픈 소스 터미널 AI 엔지니어입니다. 자연어로 지시를 내리는 것만으로 코드를 읽고, 파일을 편집하며, 명령어를 실행합니다 — 이 모든 것이 로컬 머신 위에서 이루어집니다.

도구	이미지
ChatGPT	전화 너머의 똑똑한 친구 — 조언은 해주지만 직접 손을 쓸 수는 없음
GitHub Copilot	옆에서 코드를 보완해 주는 동료 — 쾌적하지만 코드만 다룸
Codex CLI	맞은편 자리에 앉은 인턴 — 태스크를 맡기면 스스로 실행하여 성과를 가져다줌

ChatGPT	Codex CLI
코드를 읽을 수 있는가?	붙여넣은 만큼만
...	/review로 PR 전체를 감사
오픈 소스인가?	아니요
보안	콘텐츠 필터링만

ChatGPT는 "대화 도구", Codex CLI는 "실행 도구"입니다.

npm install -g @openai/codex

macOS 사용자는 Homebrew로도 가능:

brew install --cask codex

설치 후, OpenAI 계정으로 로그인:

codex auth

ChatGPT Plus/Pro 계정을 사용할 수 있습니다 (사용량은 구독 서비스에 합산되며, 추가 요금은 없습니다).

codex

전체 화면 터미널 인터페이스(TUI)가 표시됩니다.

TUI에 직접 입력:

Write a Python script that downloads the top 10 posts from Hacker News
and prints their titles with links.

Codex가 환경을 스캔하고, Python 확인, 스크립트 작성, 실행까지 수행합니다. 도중에 y를 한 번 누르기만 하면 됩니다.

이것이 Codex CLI의 기본 경험: 말한다 → 실행한다 → 확인한다 → 완료.

단축키	기능
그대로 입력	Codex에게 말하기
/diff	Codex가 변경한 내용 표시
/review	코드 리뷰 요청
/model gpt-5.5	모델 전환
/plan	실행 전 계획 확인
/permissions	보안 모드 전환
/clear	새로운 대화 시작
/fork	대화를 복제하여 다른 안 탐색
Ctrl+R	입력 이력 검색

초보자를 위한 조언: 첫 1주일은 "입력" + "/diff"만으로도 충분합니다.

Explain the architecture of this project. What are the main modules,
how do they connect, and where should I start reading?

반나절 걸리던 코드 리딩이 2분 만에 완료됩니다.

codex exec "Check which tests are failing, find the root cause, and fix them"

codex exec (줄여서 codex e)는 비대화형(Non-interactive) 모드입니다. CI/CD 파이프라인에 최적화되어 있습니다.

codex exec "Find all public functions without docstrings and add them following PEP 257" --sandbox workspace-write

500개 파일 규모의 프로젝트에서 기존 2일 → 30분으로 단축.

TUI에서 /review를 입력하기만 하면 됩니다. 변경 내용을 분석하여 리스크 평가와 개선 제안을 표시합니다.

codex -i mockup.png "Implement this UI using Tailwind CSS"

수작업을 70% 절감.

모드	AI 권한	용도
Read Only	읽기 전용	코드 탐색 · 리뷰
Auto	파일 편집 가능, 명령어 실행 전 확인	일상 개발 (기본값)
Full Access	제한 없음	CI/CD 파이프라인

/permissions로 언제든지 전환 가능.

macOS의 Seatbelt, Linux의 bubblewrap, Windows의 네이티브 샌드박스 (Sandbox)를 사용합니다. 기본적으로는 현재 디렉토리 내에서만 조작이 가능합니다.

sudo, bash -c, rm -rf / 등은 영구적으로 금지됩니다. AI가 아무리 설득하더라도 실행되지 않습니다.

ChatGPT와 같은 사용 방식: "이 코드를 설명해줘"가 아니라 "이 모듈을 async/await로 리팩터링(Refactoring)해줘" -
Full Access의 상시 사용 주의: 일상적으로는 Auto 모드를 사용하세요. 완전 자동화는 CI/CD 전용입니다 -
/diff를 습관화하기: 매 세션이 끝난 후 /diff로 변경 사항을 확인하는 습관을 들이세요

하고 싶은 작업	명령어
Codex CLI 실행	codex
TUI 종료	Ctrl+C → exit
비대화형(Non-interactive) 작업 실행	codex e "테스트 수정"
AI의 변경 사항 확인	/diff
코드 리뷰	/review
...

설치해서 놀아보기: 10분 만에 설치 → 로그인 → 3가지 간단한 명령어 실행 -
실제 작업에 적용하기: 업무 실무(문서 추가, 버그 수정, 프로젝트 탐색)를 Codex에 맡겨보세요 -
/diff를 습관으로: 매 세션 후에 변경 내용을 확인하는 습관을 기르세요

Codex CLI는 당신을 대체하는 것이 아니라, "무엇을 만들 것인가"라는 판단에 집중할 수 있는 시간을 만들어 줍니다.

• OpenAI Codex CLI 공식 문서
• Codex CLI GitHub 리포지토리 (74.5K+ Stars, Apache 2.0)
• Shareuhack: Codex CLI 완전 가이드
• Codex Knowledge Base: Rust 아키텍처