Codex CLI 완벽 가이드 — 설치·ChatGPT 인증·샌드박스·exec 자동화

Q: 승인 없이 알아서 다 하게 하려면 어떻게 하나요?

사람이 지켜보지 않는 환경이라면 --ask-for-approval never로 승인 프롬프트를 끄고, 필요에 따라 --sandbox 값을 조정한다. 로컬에서 저마찰로 쓰려면 --sandbox workspace-write --ask-for-approval on-request 조합이 무난하다. 모든 안전장치를 끄는 --dangerously-bypass-approvals-and-sandbox(--yolo)는 격리된 CI나 컨테이너가 아니라면 피하는 게 좋다.

Q: AGENTS.md와 config.toml은 뭐가 다른가요?

config.toml은 모델·승인 정책·샌드박스처럼 Codex CLI가 "어떻게 동작할지"를 정하는 도구 설정이고, AGENTS.md는 "우리 프로젝트의 규칙"(빌드·테스트 명령, 코드 스타일 등)을 에이전트에게 알려주는 지침 문서다. 전자는 동작 방식, 후자는 작업 맥락을 담당한다고 보면 된다.

터미널에서 “이 버그 좀 잡아줘”라고 자연어로 던지면 알아서 파일을 읽고, 고치고, 테스트까지 돌리는 코딩 에이전트가 이제는 낯설지 않다. 그중 OpenAI가 직접 만든 터미널 에이전트가 Codex CLI다. 이번 포스팅에서는 Codex CLI를 처음 접하는 사람이 설치와 인증부터 시작해, 실수로 파일을 날리지 않게 막아주는 승인 모드와 샌드박스, config.toml로 내 환경을 다듬는 법, 그리고 CI 파이프라인에서 돌리는 비대화형 자동화까지 공식 문서를 근거로 차근차근 정리하고자 한다.

Codex CLI가 대체 무엇인가

Codex CLI는 OpenAI가 만든, 내 컴퓨터에서 로컬로 도는 터미널 코딩 에이전트다. 자연어로 작업을 지시하면 코드베이스를 읽고 파일을 수정하고 명령을 실행한다. 공식 GitHub 저장소는 2026년 10월 기준 약 13만 개의 스타를 받았고 Apache-2.0 라이선스로 공개돼 있으며, 성능이 중요한 핵심부는 Rust(codex-rs)로 구현돼 있다.

헷갈리기 쉬운 지점부터 정리하자. “Codex”라는 이름은 하나의 제품이 아니다. 같은 Codex 브랜드 아래 터미널용 CLI, 에디터에 붙는 IDE 확장, 데스크톱 앱, 클라우드에서 도는 Codex Web이 따로 있다. 이 글에서 다루는 건 그중 터미널에서 도는 Codex CLI다.

제품	실행 위치	특징
Codex CLI	로컬 터미널	`codex` 명령으로 실행, 이 글의 주제
IDE 확장	VS Code·Cursor·Windsurf	에디터 안에서 에이전트 사용
데스크톱 앱	macOS·Windows	별도 앱 설치 후 세션 안에서 `/app`으로 현재 세션 열기
Codex Web	클라우드(chatgpt.com/codex)	격리된 원격 환경에서 작업

터미널 에이전트라는 점에서 Claude Code, OpenCode 같은 도구와 같은 범주에 속한다. Codex CLI만의 차별점은 뒤의 비교 섹션에서 따로 다룬다. 우선은 이 도구가 “로컬에서 도는 OpenAI제 터미널 에이전트”라는 한 줄만 기억하면 충분하다.

설치하고 ChatGPT로 로그인하기

Codex CLI 설치는 패키지 매니저 한 줄이면 끝나고, 인증은 ChatGPT 계정으로 로그인하는 방식이 가장 간단하다. 유료 ChatGPT 요금제(Plus·Pro·Business·Edu·Enterprise)를 쓰고 있다면 별도 API 키 없이 그 구독에 포함된 사용량으로 바로 쓸 수 있다. 전체 흐름은 세 단계다.

npm install -g @openai/codex(또는 brew install --cask codex)로 설치한다.
codex --version으로 설치가 됐는지 확인한다.
작업 폴더에서 codex를 실행하고 “Sign in with ChatGPT”로 로그인한다.

가장 흔한 설치 방법은 npm과 Homebrew다. 둘 중 편한 쪽을 고르면 된다.

# npm으로 전역 설치
npm install -g @openai/codex

# 또는 Homebrew(macOS)
brew install --cask codex

# npm으로 전역 설치
npm install -g @openai/codex

# 또는 Homebrew(macOS)
brew install --cask codex

ShellScript

위 두 명령 모두 codex라는 실행 파일을 PATH에 깔아준다. npm은 Node.js가 이미 있는 환경이라면 가장 빠르고, Homebrew는 macOS에서 버전 관리가 편하다. 설치가 끝나면 codex --version으로 정상 설치를 확인할 수 있다.

Node나 Homebrew가 없는 환경이라면 OpenAI가 제공하는 셸 설치 스크립트를 쓴다.

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

ShellScript

이 스크립트는 OS에 맞는 바이너리를 내려받아 설치한다. 기본적으로 releases.openai.com에서 받고, 실패하면 GitHub Releases로 폴백한다. 사내 정책 등으로 GitHub Releases만 써야 한다면 CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false 환경 변수로 강제할 수 있다.

설치가 끝났으면 인증이다. 작업할 디렉터리에서 codex를 실행하면 처음에는 로그인 화면이 뜬다.

cd ~/projects/my-app
codex
# 메뉴에서 "Sign in with ChatGPT" 선택 → 브라우저로 인증

cd ~/projects/my-app
codex
# 메뉴에서 "Sign in with ChatGPT" 선택 → 브라우저로 인증

ShellScript

ChatGPT 로그인을 고르면 브라우저가 열리고, 인증을 마치면 자격 증명이 로컬에 저장된다. 이후부터는 codex login/codex logout으로 로그인 상태를 관리한다. API 키로 인증하는 방식도 있지만 추가 설정이 필요하며, 개인 개발자라면 ChatGPT 로그인이 훨씬 단순하다. API 키 방식은 공식 인증 문서에서 확인할 수 있다.

처음 실행하면 보이는 화면과 기본 조작

codex를 실행하면 대화형 TUI(터미널 UI)가 뜨고, 입력창에 하고 싶은 작업을 자연어로 적으면 된다. 프롬프트를 명령 인자로 바로 넘겨 시작할 수도 있다.

# 빈 세션으로 시작
codex

# 처음부터 작업 지시와 함께 시작
codex "src/ 디렉터리에서 사용하지 않는 import를 전부 정리해줘"

# 빈 세션으로 시작
codex

# 처음부터 작업 지시와 함께 시작
codex "src/ 디렉터리에서 사용하지 않는 import를 전부 정리해줘"

ShellScript

세션에 들어가면 Codex가 코드베이스를 훑고, 수정 계획을 보여준 뒤, 변경을 적용하기 전에 승인을 요청한다. 화면 상단 배너에는 현재 쓰는 모델과 추론 강도가 표시되는데, 기본으로 gpt-6.1-sol 모델에 추론 강도 medium이 잡혀 표시된다.

세션 안에서는 슬래시 명령으로 자주 쓰는 동작을 호출한다. 처음 익혀둘 만한 것들은 다음과 같다.

/init        현재 프로젝트에 맞는 AGENTS.md 초안 생성
/model       사용할 모델과 추론 강도 변경
/status      현재 세션의 설정·사용량 확인
/review      작업한 변경 사항을 코드 리뷰
/permissions 이 세션에서 Codex가 할 수 있는 작업 범위 조정

/init        현재 프로젝트에 맞는 AGENTS.md 초안 생성
/model       사용할 모델과 추론 강도 변경
/status      현재 세션의 설정·사용량 확인
/review      작업한 변경 사항을 코드 리뷰
/permissions 이 세션에서 Codex가 할 수 있는 작업 범위 조정

Plaintext

/init은 프로젝트를 분석해 뒤에서 설명할 AGENTS.md의 초안을 만들어주므로 새 저장소에서 가장 먼저 실행하면 좋다. 긴 대화로 컨텍스트가 늘어지면 요약으로 압축하는 명령도 있어서, 한 세션을 길게 끌고 가도 토큰이 무한정 불어나지 않는다. 스크린샷이나 목업 이미지를 함께 넘기고 싶다면 --image(단축 -i) 플래그로 파일 경로를 붙일 수 있다.

# 디자인 시안 이미지를 첨부해 UI 구현 요청
codex -i mockup.png "이 화면을 React 컴포넌트로 만들어줘"

# 디자인 시안 이미지를 첨부해 UI 구현 요청
codex -i mockup.png "이 화면을 React 컴포넌트로 만들어줘"

ShellScript

이미지 첨부는 “이 에러 스크린샷 보고 원인 짚어줘” 같은 디버깅에도 유용하다. 여러 장을 넘길 때는 -i a.png,b.png처럼 쉼표로 구분한다.

한 번 끝낸 세션을 이어서 작업하고 싶을 때는 되살리면 된다.

# 현재 저장소의 가장 최근 세션 이어가기
codex resume --last

# 디렉터리와 무관하게 이전 세션 목록에서 고르기
codex resume --all

# 현재 저장소의 가장 최근 세션 이어가기
codex resume --last

# 디렉터리와 무관하게 이전 세션 목록에서 고르기
codex resume --all

ShellScript

codex resume --last는 지금 저장소에서 마지막으로 하던 세션을 그대로 불러오고, --all은 어느 폴더에서 돌렸든 과거 세션 전체를 목록으로 보여준다. 긴 리팩터링을 하루에 못 끝냈을 때, 어제 맥락을 처음부터 다시 설명하지 않고 바로 이어갈 수 있어 유용하다.

승인 모드와 샌드박스, Codex CLI 안전장치의 핵심

승인 정책(approval policy)은 Codex CLI가 위험한 작업을 실행하기 전에 사람에게 물어볼지를 정하고, 샌드박스(sandbox)는 에이전트가 파일과 네트워크에 접근할 수 있는 범위를 제한한다. 이 둘이 “에이전트가 내 파일과 네트워크에 어디까지 손댈 수 있는가”를 결정하는 Codex CLI의 핵심 안전장치다. 샌드박스가 기술적 경계를 긋고, 승인 정책은 그 경계를 넘으려 할 때 멈춰 물어볼 타이밍을 정한다.

샌드박스는 세 가지 모드가 있고, --sandbox(단축 -s) 플래그나 설정 파일로 지정한다.

`sandbox_mode`	파일 쓰기	네트워크	주 용도
`read-only`	불가(읽기만)	불가	코드 분석·리뷰, 안전하게 둘러보기
`workspace-write`	작업 폴더 안에서만	기본 차단(허용 가능)	일상적인 로컬 작업(저마찰 기본값)
`danger-full-access`	제한 없음	제한 없음	격리된 환경에서만

공식 샌드박스 문서에 따르면 read-only는 파일을 읽을 수만 있어 분석과 리뷰에 안전하고, workspace-write는 작업 중인 폴더 안에서는 파일을 고치고 명령을 돌릴 수 있는 일상용 기본 모드다. danger-full-access는 말 그대로 샌드박스를 꺼버리므로 격리된 CI 러너나 컨테이너처럼 외부로 보호된 환경이 아니라면 쓰지 않는 게 좋다.

승인 정책은 샌드박스 경계를 넘으려 할 때 사람에게 물어볼 타이밍을 정한다.

# 저마찰 로컬 작업: 작업 폴더 안에서 자유롭게, 경계 넘을 때만 승인
codex --sandbox workspace-write --ask-for-approval on-request

# 비대화형(자동)에서 승인 프롬프트 없이
codex --ask-for-approval never

# 저마찰 로컬 작업: 작업 폴더 안에서 자유롭게, 경계 넘을 때만 승인
codex --sandbox workspace-write --ask-for-approval on-request

# 비대화형(자동)에서 승인 프롬프트 없이
codex --ask-for-approval never

ShellScript

--ask-for-approval(단축 -a)의 현재 값은 on-request와 never 두 가지다. on-request는 대화형으로 쓸 때 권장되는 값으로, 샌드박스 밖으로 나가야 하는 작업에서만 멈춰 물어본다. never는 아예 묻지 않으므로 사람이 지켜보지 않는 파이프라인용이다. 참고로 예전 문서에 보이던 untrusted는 더 이상 선택할 수 없고, on-failure는 이미 폐기(deprecated)됐으니 지금 설정에 쓰지 않는다.

이 샌드박스가 OS 수준에서 실제로 어떻게 강제되는지도 알아두면 좋다. macOS에서는 내장 Seatbelt 프레임워크, Linux와 WSL2에서는 bubblewrap(bwrap), 네이티브 Windows에서는 PowerShell로 실행 시 Windows 샌드박스를 사용한다. 즉 “에이전트가 알아서 조심한다”가 아니라 운영체제 차원의 격리로 막는다는 뜻이다.

마지막으로, 정말 급할 때 모든 안전장치를 끄는 플래그도 있다. --dangerously-bypass-approvals-and-sandbox(별칭 --yolo)는 승인도 샌드박스도 전부 건너뛴다. 공식 문서도 “외부적으로 단단히 격리된 환경에서만 쓰라”고 경고하는 옵션이므로, 로컬 개발 머신에서 습관적으로 붙이는 일은 피해야 한다.

config.toml로 내 환경 고정하기

매번 플래그를 길게 붙이기 번거롭다면 ~/.codex/config.toml에 기본값을 박아두면 된다. 이 파일은 사용자 수준 설정으로, 모델·추론 강도·승인 정책·샌드박스 모드를 한곳에서 관리한다. 공식 설정 레퍼런스가 모든 키를 설명한다.

# ~/.codex/config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
writable_roots = ["/Users/me/scratch"]   # 작업 폴더 밖에서 추가로 쓰기 허용할 경로
network_access = false                    # workspace-write에서 네트워크 허용 여부

# ~/.codex/config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
writable_roots = ["/Users/me/scratch"]   # 작업 폴더 밖에서 추가로 쓰기 허용할 경로
network_access = false                    # workspace-write에서 네트워크 허용 여부

Plaintext

최상위 키 네 개(model, model_reasoning_effort, approval_policy, sandbox_mode)가 평소 가장 자주 건드리는 값이다. [sandbox_workspace_write] 테이블은 workspace-write 모드일 때만 의미가 있는데, writable_roots로 작업 폴더 밖의 특정 경로까지 쓰기를 열어주거나 network_access = true로 샌드박스 안에서 외부 네트워크(예: 패키지 설치)를 허용한다. /tmp나 $TMPDIR를 쓰기 대상에서 빼고 싶으면 exclude_slash_tmp, exclude_tmpdir_env_var 키로 조정한다.

프로젝트마다 다른 설정을 쓰고 싶다면 프로필을 활용한다. 프로필 파일은 config.toml 옆에 두고 실행할 때 --profile(단축 -p)로 골라 얹는다.

# review라는 프로필을 얹어 실행
codex --profile review

# 일회성으로 특정 키만 덮어쓰기
codex -c model_reasoning_effort="high"

# review라는 프로필을 얹어 실행
codex --profile review

# 일회성으로 특정 키만 덮어쓰기
codex -c model_reasoning_effort="high"

ShellScript

--profile은 기본 설정 위에 프로필 값을 겹쳐 적용하고, --config(단축 -c) key=value는 설정 파일을 건드리지 않고 이번 실행에만 값을 바꿀 때 쓴다. 참고로 프로젝트 안에 두는 .codex/config.toml에서는 model_provider, profiles 같은 일부 키를 설정할 수 없으니, 그런 값은 사용자 수준 파일에 둔다.

AGENTS.md로 프로젝트 규칙을 에이전트에게 심기

AGENTS.md는 “우리 프로젝트는 이런 규칙으로 돌아간다”를 에이전트에게 알려주는 지침 파일이다. 빌드 명령, 코드 스타일, 테스트 방법, 손대면 안 되는 디렉터리 같은 걸 적어두면 Codex가 작업할 때마다 참고한다. 세션마다 같은 설명을 반복하지 않아도 되니, 사실상 프로젝트별 시스템 프롬프트에 가깝다.

공식 AGENTS.md 가이드에 따르면 Codex는 두 수준에서 이 파일을 찾는다. 하나는 전역 수준으로, Codex 홈 디렉터리(~/.codex, 또는 CODEX_HOME)에 AGENTS.override.md가 있으면 그것을, 없으면 AGENTS.md를 읽는다. 다른 하나는 프로젝트 수준으로, 프로젝트 루트(보통 Git 루트)에서 현재 작업 디렉터리까지 내려오며 파일을 읽는다.

# AGENTS.md (프로젝트 루트에 둔다)

## 빌드 & 테스트
- 빌드: `./gradlew build`
- 테스트: `./gradlew test` (PR 전 반드시 통과)

## 코드 스타일
- 들여쓰기는 스페이스 4칸, 한 줄 120자 제한
- 공개 API에는 반드시 KDoc 작성

## 건드리지 말 것
- `src/generated/` 아래는 자동 생성 코드이니 수정 금지

# AGENTS.md (프로젝트 루트에 둔다)

## 빌드 & 테스트
- 빌드: `./gradlew build`
- 테스트: `./gradlew test` (PR 전 반드시 통과)

## 코드 스타일
- 들여쓰기는 스페이스 4칸, 한 줄 120자 제한
- 공개 API에는 반드시 KDoc 작성

## 건드리지 말 것
- `src/generated/` 아래는 자동 생성 코드이니 수정 금지

Plaintext

이렇게 저장소 루트에 AGENTS.md를 두면 Codex가 매 작업마다 이 규칙을 반영한다. 새 프로젝트라면 앞서 본 /init 슬래시 명령으로 초안을 생성한 뒤 손보는 게 빠르다. 다만 이 파일에는 기본 32KiB(project_doc_max_bytes) 크기 제한이 있어서, 너무 길면 조용히 잘릴 수 있다. 내용이 많아지면 디렉터리별로 쪼개 두거나 한도를 올리는 식으로 관리하는 게 안전하다. 그리고 AGENTS.md는 장기 기억 시스템이 아니라 매번 읽어 들이는 지침일 뿐이라, 에이전트가 알아서 학습해 채워주지는 않는다.

비대화형 exec로 자동화·CI에 붙이기

Codex CLI는 사람이 지켜보는 대화형 모드뿐 아니라, 스크립트와 CI 파이프라인에서 돌리는 비대화형 모드를 제공한다. 이때 쓰는 명령이 codex exec(별칭 codex e)다. 프롬프트를 주면 끝까지 알아서 수행하고 결과를 출력한 뒤 종료한다.

# 비대화형으로 한 번 실행하고 결과를 파일로
codex exec "CHANGELOG.md를 최근 커밋 기준으로 업데이트해줘" \
  --output-last-message result.txt

# Git 저장소가 아닌 곳에서도 돌리기
codex exec --skip-git-repo-check "이 디렉터리의 README 초안 작성"

# 비대화형으로 한 번 실행하고 결과를 파일로
codex exec "CHANGELOG.md를 최근 커밋 기준으로 업데이트해줘" \
  --output-last-message result.txt

# Git 저장소가 아닌 곳에서도 돌리기
codex exec --skip-git-repo-check "이 디렉터리의 README 초안 작성"

ShellScript

codex exec는 승인 프롬프트 없이 동작하는 게 기본이므로, 보통 --ask-for-approval never와 함께 쓴다. --output-last-message(단축 -o)는 에이전트의 마지막 메시지를 파일로 저장해 후속 단계에서 쓰기 좋고, 결과를 다른 도구로 넘겨 파싱하려면 --json으로 줄 단위 JSON 이벤트를 받을 수 있다. CI처럼 Git 저장소 밖에서 돌 때는 --skip-git-repo-check를 붙인다.

GitHub Actions라면 OpenAI가 제공하는 공식 액션을 쓰는 게 가장 깔끔하다. openai/codex-action이 CLI 설치와 codex exec 실행을 대신 처리해준다.

# .github/workflows/codex-review.yml
name: Codex PR Review
on:
  pull_request:
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: "이 PR의 변경 사항을 리뷰하고 위험한 부분을 지적해줘"
          sandbox: workspace-write
          safety-strategy: drop-sudo

# .github/workflows/codex-review.yml
name: Codex PR Review
on:
  pull_request:
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: "이 PR의 변경 사항을 리뷰하고 위험한 부분을 지적해줘"
          sandbox: workspace-write
          safety-strategy: drop-sudo

YAML

위 워크플로는 PR이 열릴 때마다 Codex가 변경을 리뷰하도록 한다. API 키는 반드시 GitHub Secret에 넣고, 러너는 Linux나 macOS를 쓴다(Windows는 safety-strategy: unsafe가 필요하다). 참고로 위 예시의 sandbox 입력은 레거시 방식이고, 최신 워크플로에서는 permission-profile: ":workspace"를 권장한다(두 입력은 함께 쓸 수 없다). 한 가지 주의할 점은 공식 GitHub Action 문서도 경고하듯 read-only라 해도 권한이 상승된 상태로 돌기 때문에, 비밀값 보호를 샌드박스 모드 하나에만 의존하면 안 된다는 것이다.

MCP 서버로 도구 확장하기

Codex CLI는 MCP(Model Context Protocol) 서버를 붙여 외부 도구와 데이터 소스를 연결할 수 있다. 사내 문서 검색, 데이터베이스 조회, 특정 API 호출 같은 걸 에이전트가 쓸 수 있게 만드는 통로다. Codex CLI는 stdio 방식의 MCP 서버를 지원하며, codex mcp add로 추가하고 codex mcp list로 등록 상태를 확인한다(공식 CLI 레퍼런스). 연결은 이 CLI 명령이나 설정 파일 둘 다로 가능하다.

# CLI로 MCP 서버 추가
codex mcp add

# 등록된 MCP 서버 목록 확인
codex mcp list --json

# CLI로 MCP 서버 추가
codex mcp add

# 등록된 MCP 서버 목록 확인
codex mcp list --json

ShellScript

간단히는 codex mcp add로 대화식 등록을 하고, 등록 상태는 codex mcp list로 확인한다. 설정을 코드로 관리하고 싶다면 config.toml에 직접 서버를 정의하는 편이 재현성이 좋다.

# ~/.codex/config.toml
[mcp_servers.docs]
command = "npx"
args = ["-y", "some-mcp-server"]
env = { API_MODE = "read" }

# ~/.codex/config.toml
[mcp_servers.docs]
command = "npx"
args = ["-y", "some-mcp-server"]
env = { API_MODE = "read" }

Plaintext

[mcp_servers.NAME] 테이블에서 command는 MCP stdio 서버를 띄우는 실행 명령, args는 그 명령에 넘길 인자 배열, env는 서버로 전달할 환경 변수다. 이렇게 설정 파일에 박아두면 팀원들과 같은 MCP 구성을 공유하기 쉽다.

Claude Code·Cursor와 뭐가 다른가

Codex CLI는 OpenAI 모델 기반의 터미널 에이전트, Claude Code는 Anthropic 모델 기반의 터미널 에이전트, Cursor는 에디터에 통합된 형태다. Codex CLI만의 차별점은 ChatGPT 구독 사용량을 그대로 쓰고, Seatbelt·bubblewrap 같은 OS 수준 샌드박스를 전면에 내세운다는 점이다.

항목	Codex CLI	Claude Code	Cursor
기반 모델	OpenAI(`gpt-6.1-sol`)	Anthropic Claude	여러 모델 중 선택
실행 형태	터미널 CLI	터미널 CLI	에디터 통합(IDE)
인증·과금	ChatGPT 구독 또는 API 키	Claude 구독 또는 API 키	자체 구독
샌드박스	OS 수준(Seatbelt·bubblewrap·Windows 샌드박스)	권한 승인 기반	에디터 권한
소스 공개	Apache-2.0 오픈소스	비공개	비공개

이미 ChatGPT 유료 구독이 있고 터미널 중심으로 일하며 OS 격리 기반의 안전장치를 중시한다면 Codex CLI가 자연스러운 선택이다. 에디터 안에서의 자동완성과 인라인 편집이 더 중요한 사람에게는 IDE 통합형 도구가 맞고, 여기에 모델 자체의 성향 차이까지 더해져 선택이 갈린다. 도구별 장단을 더 깊게 비교한 내용은 AI 개발 도구 파워 랭킹과 Claude Code vs Cursor 비교 글에서 다뤘고, 오픈소스 터미널 에이전트를 찾는다면 OpenCode 가이드도 함께 참고할 만하다.

FAQ

Codex CLI는 무료인가요?

CLI 자체는 Apache-2.0 오픈소스라 무료로 설치해 쓸 수 있다. 다만 실제 모델 호출에는 사용량이 든다. ChatGPT Plus·Pro·Business·Edu·Enterprise 구독이 있으면 “Sign in with ChatGPT”로 로그인해 그 구독에 포함된 사용량으로 쓸 수 있고, 구독이 없으면 OpenAI API 키를 연결해 사용량만큼 과금되는 방식으로 쓴다. 실제 사용량은 작업 규모와 추론 강도(reasoning effort)에 비례하므로 큰 작업일수록 비용이 늘어난다.

승인 없이 알아서 다 하게 하려면 어떻게 하나요?

사람이 지켜보지 않는 환경이라면 --ask-for-approval never로 승인 프롬프트를 끄고, 필요에 따라 --sandbox 값을 조정한다. 로컬에서 저마찰로 쓰려면 --sandbox workspace-write --ask-for-approval on-request 조합이 무난하다. 모든 안전장치를 끄는 --dangerously-bypass-approvals-and-sandbox(--yolo)는 격리된 CI나 컨테이너가 아니라면 피하는 게 좋다.

Codex CLI는 Windows에서도 쓸 수 있나요?

쓸 수 있다. PowerShell 설치 스크립트로 설치하고, 샌드박스는 PowerShell에서 실행 시 Windows 샌드박스로 강제된다. 다만 GitHub Actions 등 CI에서 돌릴 때는 Linux·macOS 러너가 권장되며, Windows 러너에서는 safety-strategy: unsafe 설정이 필요하다.

AGENTS.md와 config.toml은 뭐가 다른가요?

config.toml은 모델·승인 정책·샌드박스처럼 Codex CLI가 “어떻게 동작할지”를 정하는 도구 설정이고, AGENTS.md는 “우리 프로젝트의 규칙”(빌드·테스트 명령, 코드 스타일 등)을 에이전트에게 알려주는 지침 문서다. 전자는 동작 방식, 후자는 작업 맥락을 담당한다고 보면 된다.

사내망(폐쇄망)이나 오프라인에서도 쓸 수 있나요?

CLI 바이너리 설치 자체는 GitHub Releases 폴백으로 폐쇄망에서도 가능하다. 다만 실제 작업은 OpenAI·ChatGPT 모델 엔드포인트로 요청이 나가야 하므로 완전한 오프라인 실행은 불가능하다. 아웃바운드가 막힌 사내망이라면 해당 도메인에 대한 프록시·방화벽 허용이 필요하고, 코드가 외부로 전송되는 구조이므로 보안 정책을 먼저 확인해야 한다. 모델 선택은 세션 안 /model이나 config.toml의 model 키로 바꿀 수 있다.

마치며

터미널 에이전트를 여럿 써보면서 느낀 건, 처음 3분 안에 승인 모드와 샌드박스를 이해하고 넘어가느냐가 경험을 갈랐다는 점이다. 이걸 건너뛰고 --yolo부터 붙이면 에이전트가 엉뚱한 파일을 고쳐도 모르고 지나가고, 반대로 겁먹고 read-only만 쓰면 “읽기만 하고 아무것도 안 하네” 하고 실망하게 된다. Codex CLI는 workspace-write + on-request라는 기본 조합이 꽤 영리하게 균형을 잡아놨으니, 처음엔 이 상태로 두고 작업 폴더 안에서 충분히 굴려보길 권한다. 그러다 반복 작업이 눈에 들어오면 그때 AGENTS.md로 규칙을 심고, codex exec로 CI에 넣는 순서가 자연스럽다. 지금까지 OpenAI Codex CLI의 설치부터 승인·샌드박스, 설정과 자동화까지 정리해 보았다.