AI/Codex 기초 사용방법

Codex CLI 입문(1) : OpenAI Codex CLI 빠른 시작 - codex 설치, 인증 하기

안녕하세요! 갓대희 입니다.

Codex에 대해 처음 글을 작성한 지 꽤 오래되었다.

요즘 Claude Code 요금 부담 때문에 Codex를 다시 살펴보는 분들이 많아진 것 같다. 그래서 이번에는 기초부터 다시 정리해보려 한다. 이 글에서는 Codex CLI, 즉 터미널에서 쓰는 Codex를 중심으로 설치, 로그인, 첫 명령 실행, 안전하게 쓰는 기본 습관까지 실제로 따라 할 수 있는 순서로 다룬다.

이 글은 2026년 5월 기준 공식 문서(developers.openai.com/codex)를 바탕으로 작성되었다. 기능은 지속 업데이트되므로 최신 정보는 공식 문서에서 확인한다.

먼저 용어부터 가볍게 잡고 가자.
CLI는 마우스로 누르는 앱이 아니라 터미널에 명령어를 입력해서 쓰는 도구를 말한다.
터미널은 macOS의 Terminal, Windows의 PowerShell처럼 글자로 명령을 실행하는 창이다.
저장소(repo)는 프로젝트 코드가 들어 있는 폴더라고 이해하면 된다.

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 (현재 글) Part 2: 핵심 개념 4가지 Part 3: Subagents · Workflows (예정) Part 4: AGENTS.md · Rules (예정) Part 5: MCP · Plugins · Skills (예정) Part 6: 자동화 (예정) Part 7: 마이그레이션 (예정) Part 8: 병행 사용 패턴 (예정)

1. 설치하기

Codex CLI는 OpenAI의 로컬 터미널용 코딩 에이전트다. 공식 GitHub 저장소를 보면 Rust 중심으로 구현된 오픈소스 프로젝트라는 점도 확인할 수 있다. Rust는 빠르고 안정적인 프로그램을 만들 때 자주 쓰는 프로그래밍 언어이고, 오픈소스는 소스 코드가 공개되어 누구나 확인할 수 있다는 뜻이다.

macOS, Windows(PowerShell 또는 WSL2), Linux를 모두 지원한다. Windows에서는 PowerShell에서 네이티브로 실행할 수 있고, Linux 환경이 필요하면 WSL2를 사용할 수 있다. 설치 방법은 크게 세 가지다.

1.1 npm으로 설치

처음 시도하기 좋은 방법이다. Node.js가 설치되어 있다면 바로 사용할 수 있다.

npm은 Node.js 패키지를 설치하는 도구라서, 자바스크립트 개발을 해본 분들에게는 익숙할 것이다.

npm install -g @openai/codex

패키지명은 @openai/codex다. 처음이라면 위 명령어를 그대로 복사해 실행하면 된다. 나중에 최신 버전으로 업데이트할 때는 다음 명령어를 쓴다.

npm install -g @openai/codex@latest

1.2 Homebrew로 설치 (macOS)

macOS를 사용한다면 Homebrew로도 설치할 수 있다.

Homebrew는 맥에서 개발 도구를 설치할 때 많이 쓰는 패키지 관리자다.

다만 2026년 5월 기준으로 공식 문서와 GitHub README의 명령어 표기가 다르다.

# GitHub README(https://github.com/openai/codex) 기준
brew install --cask codex

# 공식 quickstart(developers.openai.com/codex/quickstart) 기준
brew install codex

처음 설치할 때는 공식 quickstart의 brew install codex를 먼저 기준으로 삼고, 환경에 따라 동작하지 않으면 GitHub README에 적힌 --cask 방식을 확인하는 식으로 접근하는 편이 안전하다. 이 부분은 문서 간 표기가 엇갈리므로, 설치 직전 최신 문서를 다시 확인한다.

1.3 바이너리 직접 다운로드

npm이나 Homebrew를 사용하기 어려운 환경이라면, GitHub Releases에서 플랫폼별 바이너리를 직접 내려받을 수 있다.

바이너리는 설치 파일이나 실행 파일에 가까운 형태라고 보면 된다.

macOS(Apple Silicon/x86_64), Linux(x86_64/arm64) 옵션이 제공된다.

1.4 터미널이 부담스럽다면 IDE 확장으로 시작

이 글은 CLI 기준으로 설명하지만, Codex를 꼭 터미널에서만 써야 하는 것은 아니다. OpenAI의 Codex 업그레이드 발표와 공식 IDE 확장 문서에 따르면 Codex는 에디터 안에서도 사용할 수 있다.

공식 문서 기준으로 VS Code, VS Code Insiders, Cursor, Windsurf 같은 VS Code 계열 에디터와 JetBrains IDE 통합을 지원한다. 설치 후에는 에디터 사이드바에서 Codex를 열고, ChatGPT 계정 또는 API 키로 로그인해 사용할 수 있다.

Codex는 에디터에서 열어둔 파일, 선택한 코드, 현재 작업 중인 맥락을 참고할 수 있다. 그래서 터미널에서 파일 경로를 길게 적는 대신, 에디터에서 문제 구간을 선택한 뒤 "이 부분 왜 실패하는지 봐줘"처럼 짧게 요청해도 시작하기 쉽다.

ex) Cursor에 설치해 보도록 하자. Cursor 클릭시 빈 브라우저 새창이 열리면서 다음과 같이 컨펌 창이 열린다. Cursor 열기 클릭.

- 바로 Install을 클릭하여 설치해보자.

- 좌상한(다른 위치에 있을수 있는데 꽃 보양의 이모티콘을 찾아보자) 패널을 클릭해보면 Codex Extension이 설치 되어있는것을 볼 수 있다. 클릭해 보자.

- CODEX 플러그인이 활성화 되는데, Next 를 눌르며 읽어보자.

- Try GPT-5.5 now 를 클릭하면 이제 CODEX 플러그인도 사용할 준비가 되었다.

(Codex app 다운로드를 유도하는데 App은 별도의 글에서 다룬다. > Codex Mac App 가이드: 설치부터 권한, MCP, 자동화까지 )

입문자라면 IDE 확장도 좋은 시작점이다.
터미널 명령어가 아직 낯설다면 플러그인처럼 에디터 안에서 Codex를 먼저 써보는 편이 부담이 적다. 로컬 변경사항을 에디터 안에서 미리 보고, Codex가 제안한 코드도 바로 확인할 수 있기 때문이다.

DE 확장에서 클라우드 작업을 새로 만들고, 진행 중인 작업을 추적하고, 완료된 작업을 검토할 수 있다고 설명한다. 쉽게 말해 간단한 수정은 에디터 안에서 바로 처리하고, 오래 걸리는 작업은 클라우드에 맡긴 뒤 결과를 다시 에디터에서 이어볼 수 있다는 뜻이다.
다만 CI/CD(자동 빌드·테스트·배포), 자동화, 원격 서버 작업까지 다루려면 CLI 흐름도 알아두는 편이 좋다.
그래서 이 글에서는 CLI를 중심으로 설명하고, 에디터 중심 개발자는 IDE 확장을 함께 쓰는 방식을 추천한다.

2. 인증하기

설치가 끝나면 터미널에 codex를 입력해 실행한다. 첫 실행 시 ChatGPT 계정 또는 OpenAI API 키로 인증할 수 있다.

여기서 인증이라는 것은 "이 사용자가 Codex를 사용할 권한이 있는지 확인하는 과정"이다.

두 방식은 단순한 로그인 화면 차이가 아니다. 접근 권한, 요금 체계, 사용할 수 있는 기능, 적용되는 데이터 처리 정책이 조금씩 다르다.

2.1 ChatGPT 계정으로 로그인

ChatGPT 계정 로그인: ChatGPT 계정의 Codex 사용량과 권한을 사용하는 방식이다.
2026년 5월 기준 Codex pricing 문서는 ChatGPT Free, Go, Plus, Pro, Business, Edu, Enterprise 플랜에 Codex가 포함된다고 설명한다.
다만 플랜별 사용량, 모델, 클라우드 기능 지원 범위는 다르다.

터미널에서 codex라고 입력해보자.

예를 들어 내 환경에서는 로그인 방식을 선택하는 화면이 나왔다. 나는 ChatGPT Pro 플랜을 사용 중이라 ChatGPT 계정 로그인을 선택했다.

브라우저가 열리면 사용 중인 ChatGPT 계정으로 인증을 완료한다.

인증이 끝난 뒤 터미널로 돌아와 Enter 키를 누르면 Codex를 사용할 준비가 된다.

2.2 OpenAI API 키로 로그인

API 키 인증: 공식 인증 문서에 따르면 OpenAI Platform 계정을 통해 표준 API 요금으로 청구된다.
API 키는 프로그램이 OpenAI Platform API에 접근할 때 쓰는 비밀번호 같은 값이다.
CI/CD처럼 사람이 직접 누르지 않고 자동으로 빌드·테스트·배포하는 흐름에 어울린다.

printenv OPENAI_API_KEY | codex login --with-api-key

API 키 인증을 사용할 때 한 가지 주의할 점이 있다.

ChatGPT 계정 대신 API 키를 쓰면 클라우드 쪽에서 이어지는 일부 기능을 사용할 수 없을 수 있다고 설명한다.

가격 문서도 API 키 방식은 CLI, SDK, IDE 확장에는 쓸 수 있지만 GitHub 코드 리뷰나 Slack 같은 클라우드 기반 기능은 제공되지 않는다고 설명한다. 개인 개발 작업이라면 ChatGPT 계정 로그인이, 자동화 스크립트나 CI/CD 파이프라인이라면 API 키가 적합하다.

2.3 인증 방식 선택 가이드

상황	권장 방식
개인 개발, 대화형 작업	ChatGPT 계정 로그인
CI/CD(자동 빌드·테스트·배포), 자동화 스크립트	API 키 인증
조직 워크스페이스 권한과 데이터 보관 정책을 맞춰야 할 때	ChatGPT 계정 (조직 설정 적용 범위 확인 필요)
브라우저를 열 수 없는 서버/원격 환경	`codex login --device-auth`

한 줄로 정리하면 이렇다. 직접 개발하면서 대화하듯 쓸 거라면 ChatGPT 계정이 편하고, 자동화 작업에 붙일 거라면 API 키가 더 자연스럽다.

보안 주의: 공식 인증 문서에 따르면 자격증명 저장 위치는 file(CODEX_HOME/auth.json, 기본값은 보통 ~/.codex/auth.json), keyring(macOS 키체인이나 Windows 자격 증명 관리자 같은 OS 보안 저장소), auto 중 config.toml에서 선택할 수 있다. file 방식을 쓰면 이 인증 파일을 비밀번호처럼 다뤄야 한다. Git에 커밋하거나 티켓/채팅에 붙여 넣으면 안 된다.

2.4 로그인 상태 확인과 로그아웃

입문 단계에서 의외로 자주 막히는 부분이 "내가 지금 어떤 방식으로 로그인되어 있는지"다.

codex login status

예를 들면 다음처럼 확인할 수 있다.

계정을 바꾸거나 API 키 인증을 지우고 싶다면 다음 명령어를 사용한다.

codex logout

회사 네트워크처럼 사내 인증서나 TLS 프록시를 쓰는 환경에서는 로그인 과정에서 인증서 문제가 날 수 있다.

이 경우 공식 인증 문서는 CODEX_CA_CERTIFICATE 환경 변수로 사내 루트 CA 번들을 지정하는 방법도 안내한다. 일반 개인 개발자는 보통 신경 쓰지 않아도 되지만, 회사 장비에서 로그인 실패가 반복된다면 확인할 만하다.

3. 처음 실행해보기

인증까지 마쳤다면 프로젝트 디렉토리, 즉 내가 작업하려는 코드 폴더로 이동한 뒤 codex를 실행한다. 터미널 UI가 열리면 평소 말하듯 작업을 입력하면 된다.

예시 1: 프로젝트 분석

Tell me about this project

가장 처음 해볼 만한 명령이다. Codex가 현재 폴더의 코드를 읽고 프로젝트 구조를 설명해준다. 여기서 모듈은 기능별로 나뉜 코드 묶음, 의존성은 이 프로젝트가 가져다 쓰는 외부 라이브러리라고 생각하면 된다.

한국어로는 "해당 프로젝트에 대해 간단히 요약해줘"처럼 입력해도 된다.

예시 2: 기능 구현

Build a classic Snake game in this repo

새 파일을 만들고 기존 파일을 수정하는 작업도 수행한다.

다만 승인 모드 설정에 따라 각 변경 전에 확인을 요청할 수도 있고, 자동으로 진행할 수도 있다.

예시 3: 버그 수정

Find and fix bugs in my codebase with minimal, high-confidence changes

여기서 "minimal, high-confidence changes"는 "작고 확실한 수정만 해달라"는 뜻이다. 이런 제약 조건을 같이 적어두면 좋다. 범위를 지정하지 않으면 Codex가 내가 생각한 것보다 넓게 파일을 바꿀 수 있다.

예시 4: 기능 추가

Add a new command-line option --json that outputs JSON.

이 예시는 원하는 사용 방법을 꽤 구체적으로 적은 명령이다. 여기서 인터페이스 명세는 "사용자가 어떤 옵션을 입력하면 프로그램이 어떻게 동작해야 하는지"를 뜻한다. 이렇게 적으면 Codex가 바꿔야 할 파일, 추가할 로직, 필요한 테스트를 더 잘 좁힐 수 있다.

좋은 첫 프롬프트의 4요소

공식 best practices(모범 사례)는 프롬프트에 목표, 맥락, 제약, 완료 기준을 넣으라고 권장한다. 처음부터 길게 쓸 필요는 없지만, 이 네 가지를 넣으면 Codex가 덜 추측하고 더 좁은 범위에서 작업한다.

요소	초심자식 표현
Goal	무엇을 만들거나 고치고 싶은가
Context	관련 파일, 오류 메시지, 참고 문서가 무엇인가
Constraints	건드리면 안 되는 범위나 지켜야 할 규칙은 무엇인가
Done when	어떤 테스트나 확인이 끝나야 완료로 볼 것인가

Goal: 로그인 오류를 고쳐줘.
Context: 에러 메시지는 "Invalid token"이고, 관련 파일은 src/auth.ts야.
Constraints: API 응답 형식은 바꾸지 말아줘.
Done when: 기존 테스트를 통과하고, 로그인 실패 케이스 테스트를 하나 추가해줘.

4. 샌드박스와 승인 정책 이해하기

Codex CLI를 처음 사용할 때 꼭 이해해야 할 개념이 권한과 승인 설정이다. Codex는 코드를 읽는 것뿐 아니라 파일을 편집하고 셸 명령도 실행할 수 있다. 그래서 "어디까지 자동으로 맡길 것인가"를 정해야 한다.

Codex의 안전 장치는 샌드박스(격리)와 승인 정책 두 축으로 구성된다. 공식 best practices(모범 사례) 문서도 이 둘을 Codex 권한을 조절하는 핵심 손잡이로 설명한다.

두 축을 분리해서 이해하자.
sandbox_mode는 Codex가 어디까지 접근할 수 있는지를 정한다. 파일 수정 범위, 네트워크 접근, 셸 명령 실행 범위가 여기에 걸린다.
approval_policy는 Codex가 작업하다가 언제 사용자에게 물어볼지를 정한다.
--yolo는 이 두 안전장치를 함께 우회하는 별도 고위험 옵션이다.

중요한 점은 샌드박스가 Codex 내부 파일 편집뿐 아니라 Codex가 실행하는 git, 패키지 매니저, 테스트 명령에도 적용된다는 것이다. 예를 들어 npm install은 단순한 설치 명령처럼 보여도 네트워크 요청과 설치 스크립트 실행을 동반할 수 있다.

아래 세 가지는 --sandbox에 넣는 샌드박스 모드이고, 승인 정책은 뒤에서 --ask-for-approval 또는 approval_policy로 따로 지정한다.

4.1 샌드박스 3단계

공식 sandboxing(격리) 문서와 CLI reference(옵션 목록)에 따르면 샌드박스 모드는 다음 세 가지다.

모드	CLI 플래그 값	언제 쓰나
read-only	`--sandbox read-only`	낯선 저장소를 처음 분석할 때. 파일을 읽는 데 집중하고, 수정이나 명령 실행은 막아두고 싶을 때
workspace-write	`--sandbox workspace-write`	일반적인 로컬 개발 기본값. 현재 작업 폴더 안의 파일 읽기/수정은 허용하고, 바깥 폴더 수정이나 네트워크 접근은 기본적으로 제한
danger-full-access	`--sandbox danger-full-access`	샌드박스 경계를 제거해야 하는 특수 상황. 로컬 입문자에게는 비권장. 승인 정책까지 자동으로 꺼지는 것은 아니지만, `never`와 결합하면 사실상 전체 권한 실행에 가까워짐

처음에는 workspace-write로 시작하는 편이 낫다. 어느 파일을 바꾸는지 감이 잡히고, 저장소를 충분히 신뢰할 수 있을 때만 권한을 넓힌다.

네트워크 접근은 별도 문제다.
공식 설정 reference(설정 목록) 기준으로 workspace-write에서도 네트워크 접근은 별도 설정(sandbox_workspace_write.network_access)으로 다룬다.
패키지 설치, 외부 API 호출, 웹 요청이 필요하면 승인 요청이 뜨거나 설정을 바꿔야 할 수 있다.
초심자라면 네트워크가 필요한 작업인지 먼저 확인하고, 왜 필요한지 Codex에게 설명하게 하는 습관이 좋다.

4.2 승인 정책 3단계

--ask-for-approval은 사용자 확인을 언제 받을지 정하는 옵션이다. 2026년 5월 기준 공식 CLI reference(옵션 목록)와 로컬 codex-cli 0.128.0 도움말에서 확인되는 주요 값은 다음과 같다.

값	의미	주의점
untrusted	신뢰된 명령 목록에 없는 명령을 실행하기 전에 사용자 승인을 요청	보수적으로 시작하고 싶을 때 유용
on-request	샌드박스 안에서 가능한 작업은 진행하고, 경계를 넘을 필요가 있을 때 승인 요청	일반적인 대화형 로컬 개발에 가장 무난
never	사용자 승인을 요청하지 않음. 실패는 곧바로 모델에게 돌아감	승인만 끄는 것이지 샌드박스를 자동으로 끄는 것은 아님. `never`와 `--yolo`는 다름

예전 문서나 글에서 보이는 on-failure는 현재 도움말에서 더 이상 권장하지 않는 값(deprecated)으로 표시된다. 새로 설정한다면 대화형 작업은 on-request, 비대화형 작업은 상황에 따라 never를 검토하는 편이 낫다.

4.3 처음 고를 조합

처음에는 옵션 이름을 외우는 것보다 상황별 조합을 기억하는 편이 쉽다.

상황	권장 조합	이유
처음 보는 저장소를 읽기만 할 때	`read-only + on-request`	수정 없이 구조 파악부터 할 수 있음
일반적인 로컬 개발	`workspace-write + on-request`	작업 폴더 안에서는 진행하고, 범위를 넘을 때 멈춰 물어봄
CI나 자동화 스크립트	`workspace-write` 기반으로 별도 검토	깨끗한 Git 상태, 임시 실행 환경(CI runner), 필요한 네트워크 권한을 함께 설계해야 함
전체 파일/네트워크 권한이 필요한 특수 작업	입문 단계 비권장	먼저 `--add-dir`나 쓰기 허용 폴더(writable roots)로 필요한 폴더만 추가하는 편이 안전

CLI 플래그로 실행할 때마다 지정할 수도 있다. 플래그는 명령어 뒤에 붙여서 동작 방식을 바꾸는 옵션이다.

# 기본 권장 조합 (로컬 작업)
codex --sandbox workspace-write --ask-for-approval on-request

# 읽기 전용으로 탐색만 할 때
codex --sandbox read-only

# 스크립트나 CI처럼 비대화형 실행이 필요할 때
codex exec "run the tests and summarize failures"

여기서 주의할 점이 있다. codex exec는 비대화형으로 실행하는 방식이지, 그 자체가 안전 모드는 아니다.

자동화가 필요하면 제한된 샌드박스, 깨끗한 Git 상태, 임시 실행 환경, 필요한 네트워크 권한을 함께 설계해야 한다.

자주 쓰는 조합은 별칭(alias)으로 줄여도 된다.
옵션이 길어서 매번 입력하기 번거롭다면 본인이 기억하기 쉬운 짧은 명령어를 만들어둘 수 있다. 예를 들어 나는 Codex를 자주 쓰는 기본 조합으로 실행하기 위해 cdd 같은 별칭을 만들어 사용한다.
macOS나 Linux의 zsh/bash라면 ~/.zshrc 또는 ~/.bashrc에 아래처럼 적어둘 수 있다.

alias cdd='codex --sandbox workspace-write --ask-for-approval on-request'

다만 별칭은 편의 기능일 뿐이다. 별칭 이름만 보고 어떤 권한으로 실행되는지 잊어버리면 오히려 위험해질 수 있다. 처음 만들 때는 alias cdd로 실제 실행 명령을 확인하고, 권한을 넓힌 별칭에는 더 노골적인 이름을 붙이는 편이 안전하다.

ex) cdd

4.4 yolo는 빠른 모드가 아니라 우회 모드다

위험 옵션은 의미를 알고 써야 한다. 공식 CLI reference(옵션 목록)는 --dangerously-bypass-approvals-and-sandbox와 별칭 --yolo를 승인 프롬프트와 샌드박스를 모두 건너뛰는 옵션으로 설명한다.
즉, 단순히 "빠르게 실행"하는 모드가 아니라 로컬 파일, 네트워크, 패키지 설치 스크립트, 환경변수나 토큰이 노출될 수 있는 경계까지 함께 넓히는 선택이다.
기술적으로는 사용자가 위험을 이해하고 감수한다면 쓸 수 있다. 다만 그 경우에도 평소 쓰는 로컬 프로젝트 폴더가 아니라 사용 후 버리는 가상 머신(disposable VM), 임시 컨테이너, 제한된 자동화 실행 환경(CI runner)처럼 외부에서 격리된 환경을 먼저 준비하는 편이 맞다. 입문 단계에서는 이름과 의미를 알아두되, 예제 명령어처럼 따라 치는 옵션으로 소개하지 않는다.

never와 yolo를 혼동하지 말자.
approval_policy = "never"는 승인 질문을 하지 않겠다는 뜻이다. 샌드박스 설정은 별도로 남아 있을 수 있다.
반면 --yolo는 승인과 샌드박스를 함께 우회한다. 이 차이를 모르면 "승인만 줄이려던 설정"이 "보호장치 전체 해제"로 바뀔 수 있다.

4.5 영구 설정

매번 플래그를 입력하기 번거롭다면 config.toml에 기본값을 설정한다. 이 파일은 Codex의 기본 동작을 적어두는 설정 파일이다.

sandbox_mode = "workspace-write"
approval_policy = "on-request"

공식 설정 문서 기준으로 개인 기본값은 ~/.codex/config.toml에 두고, 특정 프로젝트 전용 설정은 저장소 안의 .codex/config.toml에 둔다. 우선순위는 CLI 플래그와 --config, 프로필, 프로젝트 설정, 사용자 설정, Unix의 시스템 설정(/etc/codex/config.toml), 내장 기본값 순서다. 프로젝트 설정은 신뢰한 프로젝트에서만 적용된다.

처음에는 sandbox_mode = "workspace-write"와 approval_policy = "on-request" 조합을 기본값으로 두는 편이 안전하다. default_permissions는 샌드박스와 승인 정책 자체가 아니라, 재사용할 권한 프로필 이름을 고르는 설정으로 이해하면 된다. 신뢰하지 않는 프로젝트에서는 프로젝트 안의 .codex/config.toml을 무조건 믿지 말고 먼저 내용을 확인한다.

공식 문서에 따르면 sandbox_workspace_write.writable_roots로 쓰기를 허용할 폴더 범위도 지정할 수 있다. 쉽게 말해 "Codex가 이 폴더 안에서는 파일을 수정해도 된다"라고 선을 그어두는 설정이다. 실행할 때만 임시로 추가 폴더를 허용하고 싶다면 CLI reference의 --add-dir 플래그를 사용할 수 있다.

4.6 플랫폼별 샌드박스 구현

macOS는 내장 Seatbelt 프레임워크를 사용한다. Seatbelt는 앱의 접근 범위를 제한하는 macOS의 보안 장치다.

Linux나 WSL2에서는 bubblewrap(bwrap) 기반 격리를 사용한다. 환경에 따라 설치 상태나 보안 설정이 달라질 수 있으므로, 샌드박스 오류가 나면 공식 sandboxing 문서의 Linux/WSL2 안내를 함께 확인한다.

입문자를 위한 권장 접근법: 공식 best practices(모범 사례)는 처음엔 기본 설정(workspace-write + on-request)으로 시작하고, 특정 저장소에서의 필요가 분명해진 뒤에만 권한을 넓히도록 권장한다. 나도 이 방식이 가장 무난하다고 본다. 처음부터 --yolo로 시작하면 의도치 않은 파일 삭제나 네트워크 요청이 발생할 수 있다.

Codex 공식 UseCase 번역글도 참고

OpenAI Codex 공식 유즈케이스 12가지 살펴보기 : Codex로 뭘 할 수 있나? 공식 12가지 사례 한국어 정리

5. 안전하게 쓰기 — Git checkpoint 패턴

Codex CLI는 코드베이스, 즉 프로젝트 전체 코드를 실제로 수정한다. 그래서 강력하지만 동시에 조심해야 한다. 공식 문서도 이 점을 명확히 언급한다.

"Codex can modify your codebase, so consider creating Git checkpoints before and after each task so you can easily revert changes if needed."
— 공식 quickstart

번역: Codex는 내 코드베이스를 수정할 수 있으므로, 필요할 때 쉽게 되돌릴 수 있도록 각 작업 전후에 Git 체크포인트를 만들어 두는 것이 좋다는 뜻이다.

뜻은 간단하다. Codex에게 작업을 맡기기 전에 현재 상태를 Git에 저장해두면, 결과가 마음에 들지 않을 때 되돌릴 수 있다. Git은 코드 변경 이력을 저장하는 도구이고, checkpoint는 "지금 상태를 저장해두는 지점"이라고 보면 된다.

실전 Git checkpoint 패턴

# 작업 시작 전 checkpoint 생성
git status
git add -A && git commit -m "checkpoint: before codex task - [작업 내용 간략 설명]"

# Codex 작업 실행
codex

# 작업 결과 확인 후, 만족스러우면 다시 커밋
git diff
git add -A && git commit -m "feat: [작업 완료 내용]"

# 이미 커밋한 Codex 결과를 취소하고 싶을 때
git log --oneline -5
git revert <codex_result_commit_sha>

주의: 공식 문서는 checkpoint를 만들라고 권장하지만, 어떤 Git 명령으로 되돌릴지는 상황에 따라 다르다. 초심자에게는 보통 git revert가 더 안전하다. 이전 이력을 지우지 않고 "되돌리는 새 커밋"을 만들기 때문이다. 작업 이력을 지우는 reset 계열 명령은 저장하지 않은 변경을 즉시 삭제할 수 있으므로, Git에 익숙하지 않다면 이 글의 예제로 따라 하지 않는다.

이건 단순히 "커밋을 자주 하라"는 말이 아니다.

AI 에이전트가 여러 파일을 한 번에 수정하면, 나중에 어느 변경이 문제였는지 찾기 어려워진다.

작업 단위로 checkpoint를 남겨두면 디버깅도 쉽고, 결과가 별로일 때 되돌리기도 훨씬 편하다.

6. 정리 + Part 2 예고

이 편에서 다룬 내용을 정리하면:

설치: npm install -g @openai/codex (npm) 또는 Homebrew로 시작. Homebrew 명령은 공식 quickstart와 GitHub README 표기가 다를 수 있으니 설치 직전 최신 문서를 확인
인증: 직접 개발할 때는 ChatGPT 계정이 편하고, 자동 실행에는 API 키가 어울림. 단, 플랜별 사용량과 클라우드 기능 지원 범위는 다름
시작: 목표, 맥락, 제약, 완료 기준을 넣고 프로젝트 설명 요청 → 작은 기능 구현 → 버그 수정 순으로 난이도를 높임
권한과 승인 모드: 처음에는 workspace-write + on-request로 시작하고, yolo는 위험을 이해하고 감수할 때 격리 환경에서만 검토
Git checkpoint: 작업 전후 커밋으로 되돌릴 수 있는 안전망을 만들어 둠
계정 관리: codex login status와 codex logout으로 현재 인증 상태를 확인하고 정리

주요 CLI 플래그 빠른 참조

터미널에서 codex --help를 실행하면 전체 옵션 목록을 확인할 수 있다. 옵션이 너무 많아 보일 수 있지만, 처음에는 아래 주요 항목만 알아도 충분하다.

플래그	축약	역할
`--sandbox`	`-s`	Codex가 접근할 수 있는 파일 범위 선택 (`read-only` / `workspace-write` / `danger-full-access`)
`--ask-for-approval`	`-a`	사용자 확인을 언제 받을지 선택 (`untrusted` / `on-request` / `never`)
`--dangerously-bypass-approvals-and-sandbox`	`--yolo`	격리와 승인 절차를 모두 끄는 고위험 옵션. 외부에서 충분히 격리된 실행 환경 전용
`--add-dir`	-	현재 작업 폴더 외에 추가로 쓰기 허용할 폴더 지정

전체 옵션은 codex --help 또는 공식 CLI reference(옵션 목록)에서 확인한다.

처음 실행 시 자주 겪는 문제

Codex CLI를 처음 설치하고 실행할 때 자주 마주칠 수 있는 상황과 대응법이다.

인증 토큰 만료: codex를 실행했을 때 인증 오류가 발생하면 codex login을 다시 실행해 재인증한다.
어떤 계정으로 로그인했는지 헷갈림: codex login status로 확인하고, 계정을 바꾸려면 codex logout 후 다시 로그인한다.
Linux/WSL2에서 샌드박스 오류: bubblewrap(bwrap)이 설치되지 않은 경우 발생할 수 있다. 패키지 매니저로 bubblewrap을 먼저 설치한다.
패키지 설치나 외부 요청이 막힘: 기본적으로 네트워크 접근이 꺼져 있을 수 있다. Codex가 왜 네트워크가 필요한지 설명하게 한 뒤, 필요한 경우에만 승인하거나 설정을 바꾼다.
그 외 오류: 먼저 공식 인증 문서의 로그인 진단 안내와 공식 troubleshooting(문제 해결) 문서를 확인한다. 같은 증상이 없으면 GitHub Issues(openai/codex)에서 오류 메시지를 그대로 검색한다.

Codex CLI를 지금 당장 써볼 상황 vs 잠시 미룰 상황

지금 쓸 때	잠시 미룰 때
혼자 개발하는 사이드 프로젝트	프로덕션 배포 직전 작업
리팩토링이나 테스트 보강	보안 민감 코드 직접 수정
버그 재현/분석 탐색	팀 규칙 정의가 아직 없는 경우

다음 편(Part 2)에서는 Codex를 제대로 쓰기 위해 알아야 할 Prompting, Memories, Sandboxing, Models를 정리한다.

핵심은 단순하다. 어떻게 지시할지, Codex가 무엇을 기억하게 할지, 어디까지 실행하게 할지, 어떤 모델을 고를지에 대해서이다.