OpenAI Codex CLI 심층 분석 (2026): Rust 로컬 코딩 에이전트

💡 5분 요약: OpenAI가 2025년 4월 공개한 코딩 에이전트가 1년도 안 돼 95.7% Rust로 재작성됐다. 핵심 차별점은 OS 네이티브 샌드박스 (macOS Seatbelt / Linux bubblewrap+seccomp+landlock / Windows Restricted Token+WFP). 단일 정적 바이너리로 zero dependency 설치, 115+ 크레이트 Rust 모노레포, ChatGPT 플랜으로 API 키 없이 즉시 사용. Apache-2.0 라이선스.

Codex CLI란 무엇인가

README.md 첫 줄이 정체성을 정의한다:

“Codex CLI is a coding agent from OpenAI that runs locally on your computer.”

chatgpt.com/codex(클라우드 에이전트, Codex Web)와 혼동하기 쉽지만, 이 저장소는 사용자 머신에서 동작하는 로컬 CLI다. 그리고 같은 Rust 엔진이 다음을 모두 구동한다:

왜 Rust로 재작성했나

OpenAI는 2025년 4월 Codex CLI를 TypeScript로 처음 오픈소스로 공개했다. 그런데 1년이 채 지나지 않은 지금, 코드베이스의 95.7%가 Rust다.

Node.js 시절의 한계를 정리하면:

1. 설치 마찰 — Node.js 런타임을 별도로 관리해야 함
2. GC pause가 long-running agentic 프로세스의 latency와 충돌 — 시간 단위로 history와 diff가 누적되는 워크플로
3. 플랫폼 샌드박싱이 native binding 요구 — TypeScript는 FFI shim에 의존
4. 멀티 언어 SDK 확장을 위한 stable embedding surface 필요

Rust로 재작성하면서 얻은 것:

• 단일 정적 바이너리 (musl, gnullvm) — 의존성 zero, 빠른 시작
• OS 네이티브 보안 바인딩 — 메모리 안전성까지 보장
• GC pause 없음 — 결정적 메모리 동작
• TypeScript / Python SDK가 같은 바이너리를 spawn해서 IPC로 통신 — fragmentation 없음

주요 기능

1) 설치 (4가지 방법)

# 1. 공식 인스톨러 (macOS / Linux)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

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

# 3. npm
npm install -g @openai/codex

# 4. Homebrew (cask)
brew install --cask codex

codex 실행 후 “Sign in with ChatGPT” 선택 시 OAuth(PKCE)로 인증 — API 키 발급 불필요.

2) 실행 모드

3) Approval modes & Sandbox modes

Approval (AskForApproval enum):
– untrusted — 안전 명령만 자동, 나머지 묻기
– on-request — 모델이 필요할 때만 묻기 (기본값)
– granular — 5개 카테고리 세밀 제어
– never — 절대 묻지 않음 (codex exec용)

Sandbox (SandboxMode enum):
– read-only — 읽기만 (기본값)
– workspace-write — cwd + TMPDIR + ~/.codex/memories 쓰기 허용
– danger-full-access — 무제한 (컨테이너 내부에서만 권장)

4) 슬래시 명령 ~50개

5) 인증 5가지

1. ChatGPT 로그인 (OAuth PKCE) — 권장, OS 키체인에 저장
2. Device Code — 브라우저 없는 환경용
3. API 키 — OPENAI_API_KEY 환경변수
4. Access Token — CODEX_ACCESS_TOKEN
5. External Auth — 커스텀 외부 인증

코드 구조 — 115+ 크레이트 해부

codex/
├── codex-rs/           # Rust 본체 (115+ 크레이트 Cargo workspace)
│   ├── core/           # 에이전트 루프 (session/turn.rs)
│   ├── tui/            # ratatui TUI (chat_composer.rs 438KB!)
│   ├── cli/, exec/     # 진입점들
│   ├── sandboxing/, linux-sandbox/, windows-sandbox-rs/
│   ├── mcp/, mcp-server/
│   ├── protocol/       # 모든 wire-type의 single source of truth
│   └── rollout/        # 세션 영속화 (jsonl + SQLite 인덱스)
├── codex-cli/          # npm 래퍼 (단 3개 파일!)
├── sdk/                # TypeScript + Python SDK (모두 바이너리 spawn)
├── patches/            # Bazel용 Windows 호환 패치 27개
├── MODULE.bazel        # Bazel 모듈 (16KB)
├── MODULE.bazel.lock   # Bazel 락 파일 (1.4MB!)
└── AGENTS.md           # Codex 자신을 위한 에이전트 가이드라인 (18KB)

빌드 시스템 — Cargo + Bazel 병행

• Cargo — 일상 개발(just test, just fix, IDE) 빠른 incremental build
• Bazel — 릴리스 빌드, hermetic, RBE, cross-platform 바이너리
• MODULE.bazel.lock 1.4MB로 두 빌드 의존성 정합성 유지

patches/의 27개 패치는 거의 전부 외부 의존성을 Windows에서 빌드 가능하게 만들기 위한 것 — LLVM, abseil, ring, aws-lc-sys, rules_rust 등의 Windows MSVC/gnullvm 호환 패치들.

핵심 아키텍처

에이전트 루프 — run_turn

본체는 codex-rs/core/src/session/turn.rs의 run_turn 함수. 핵심 사이클:

loop {
    // 1) 모델 실행 중 사용자가 보낸 메시지 드레인
    let pending_input = sess.input_queue.get_pending_input(&sess.active_turn).await;

    // 2) hook 실행
    if run_hooks_and_record_inputs(&sess, &turn_context, &pending_input).await {
        break;
    }

    // 3) 히스토리로 sampling input 구성
    let sampling_request_input = sess.clone_history().await
        .for_prompt(&turn_context.model_info.input_modalities);

    // 4) 모델에 요청 — 스트리밍 응답
    match run_sampling_request(Arc::clone(&sess), ..., sampling_request_input, ...).await {
        Ok(SamplingRequestResult { needs_follow_up, last_agent_message }) => {
            // 5) 토큰 한계 시 auto compact
            if token_limit_reached && needs_follow_up {
                run_auto_compact(...).await;
                continue;
            }
            // 6) follow-up 불필요면 stop hook 실행 후 break
            if !needs_follow_up {
                run_turn_stop_hooks(...).await;
                break;
            }
            continue;
        }
        Err(CodexErr::TurnAborted) => break,
        Err(e) => break,
    }
}

함수 호출 → 결과 → 다음 sampling 반복, assistant 메시지만 오면 턴 종료. 토큰 한계 자동 압축. stop hook으로 외부 정책 개입 가능.

모델 클라이언트 — Responses API only

WireApi enum이 단 하나, Responses 뿐이다. Chat Completions는 명시적으로 제거됨:

const CHAT_WIRE_API_REMOVED_ERROR: &str =
    "`wire_api = \"chat\"` is no longer supported.
     How to fix: set `wire_api = \"responses\"` in your provider config. ...";

이는 큰 의미를 갖는다 — Codex CLI는 OpenAI Responses API에 강하게 결합된다. Bedrock, Ollama, LM Studio 같은 OSS 프로바이더도 Responses API 호환 엔드포인트를 노출해야 한다.

추가 디테일:
– WebSocket prewarm — v2 전용 response.create를 generate=false로 미리 보내 connection 데우기
– Reasoning summary — include = ["reasoning.encrypted_content"]로 암호화된 reasoning 콘텐츠 수신
– 모델별 시스템 프롬프트 핀(gpt_5_codex_prompt.md, gpt_5_1_prompt.md, gpt_5_2_prompt.md 등)

샌드박싱 — 진짜 OS 수준 격리

여기가 Codex의 가장 진지한 부분이다. codex-rs/sandboxing/src/manager.rs:

pub enum SandboxType {
    None,
    MacosSeatbelt,
    LinuxSeccomp,
    WindowsRestrictedToken,
}

플랫폼별 선택은 cfg!(target_os = ...)로 컴파일 타임에 결정.

Linux

• bubblewrap (bwrap) — 파일시스템 격리. linux-sandbox/src/bwrap.rs만 105KB
• seccomp — 네트워크 차단 시 syscall 필터링. 단순 차단이 아니라 AF_UNIX 소켓만 허용:

let unix_only_rule = SeccompRule::new(vec![SeccompCondition::new(
    0, SeccompCmpArgLen::Dword, SeccompCmpOp::Ne, libc::AF_UNIX as u64,
)?])?;
rules.insert(libc::SYS_socket, vec![unix_only_rule.clone()]);

• landlock — 레거시/백업, 주력은 bwrap
• PR_SET_NO_NEW_PRIVS — seccomp 적용 전 항상 설정
• WSL1 미지원 — user namespace 불가

macOS

• Seatbelt (/usr/bin/sandbox-exec) — 경로 하드코딩으로 PATH 가로채기 공격 방지
• sbpl 정책 — Scheme-like DSL. Chrome 샌드박스 정책을 모티프로 한 default-deny

(version 1)
; inspired by Chrome's sandbox policy
(deny default)
(allow process-exec)
(allow process-fork)
(allow signal (target same-sandbox))
(allow file-write-data
  (require-all
    (path "/dev/null")
    (vnode-type CHARACTER-DEVICE)))

Windows

• Restricted Token + Windows Filtering Platform(WFP) + DPAPI
• windows-sandbox-rs/src/에 30+ 모듈: acl.rs (25KB), setup.rs (61KB), wfp.rs, token.rs
• conpty 통합으로 PTY 지원

다만 공식 docs는 Windows를 “WSL2 only”로 권장 — 코드는 native Windows 샌드박스를 구현하고 있지만 공식 지원과 실제 구현 사이에 미묘한 갭이 있다.

장점

⭕ S1. Rust 기반 안전 코드 강제

워크스페이스 전반에 30+개의 clippy lint = deny:
– unwrap_used / expect_used = deny — 명시적 에러 처리 강제
– await_holding_lock = deny — async 데드락 방지
– uninlined_format_args = deny — format!("{x}") 강제

⭕ S2. OS 수준 샌드박싱의 깊이

3대 OS 모두에서 OS 네이티브 격리. seccomp 규칙이 단순 차단이 아니라 시나리오별 분기. Seatbelt 정책이 Chrome 정책을 모티프로 한다는 점에서 진지함을 알 수 있다.

⭕ S3. ChatGPT 플랜으로 즉시 사용

API 비용 없이 Plus/Pro/Edu/Business/Enterprise 플랜으로 사용. ChatGPT OAuth로 별도 키 발급 없음.

⭕ S4. 다중 표면 일관성 (fragmentation 거의 없음)

같은 Rust 엔진이 CLI / TUI / headless exec / MCP server / IDE 확장 백엔드 / Cloud Tasks 클라이언트 / 데스크톱 앱까지 일관 동작. TypeScript/Python SDK도 동일 바이너리 임베드.

⭕ S5. 활발한 개발과 광범위 CI

워크플로 ~25개, 86개 통합 테스트, 83개 TUI insta 스냅샷, nornagon 같은 외부 메인테이너를 위한 ratatui/crossterm fork 운영, cargo-nextest + divan 벤치마크.

⭕ S6. 풍부한 운영·통합 기능

OpenTelemetry · SQLite 세션 인덱스 · 관리자 정책(requirements.toml) · OS 키체인 · Windows/macOS 코드 사이닝 자동화.

⭕ S7. 확장성 우선 설계

양방향 MCP · hooks · skills · plugins · extensions · code-mode · connectors · external agent migration — 단순 도구가 아니라 에이전트 플랫폼으로 진화 중.

단점과 한계

❌ L1. OpenAI Responses API에 강결합

WireApi가 Responses 단 하나. Chat Completions 명시적 제거. Anthropic Claude · Google Gemini · Mistral 등을 1급으로 쓰기 어렵다.

❌ L2. 단일 벤더 락인

인증(ChatGPT OAuth), 백엔드(chatgpt.com/backend-api/codex 하드코딩), 모델 모두 OpenAI 중심. 모델별 시스템 프롬프트가 GPT-5 계열에 최적화.

❌ L3. 외부 기여 정책의 폐쇄성

docs/contributing.md:

“External contributions are by invitation only … Pull requests that have not been explicitly invited by a member of the Codex team will be closed without review.”

오픈소스이지만 코드 기여 자체는 매우 제한적.

❌ L4. Windows 샌드박싱은 구현되어 있지만 공식적으론 WSL2 권장

docs/install.md가 Windows를 “via WSL2”만 지원 명시. 그럼에도 windows-sandbox-rs/는 매우 큰 노력으로 네이티브 샌드박스 구현 중 — 공식 지원과 실제 구현 사이의 갭.

❌ L5. Rust 빌드의 무거움

MODULE.bazel.lock 1.4MB, V8(v8 = "=147.4.0"), AWS SDK 셋, WebRTC 등 무거운 라이브러리. lto = "fat" 릴리스 빌드 매우 느림. RUST_MIN_STACK=8MiB 필요.

❌ L6. 거대 모듈과 자기 모순적 컨벤션

AGENTS.md가 “500 LoC 이하” 규칙을 정해놓고… core/src/session/mod.rs는 3,339줄, tui/src/bottom_pane/chat_composer.rs는 438KB.

❌ L7. 학습 곡선

115+ 크레이트, 50+ 슬래시 명령, 5+ 인증 방법, 5개 approval 모드, 3개 sandbox 모드, 양방향 MCP, hooks/skills/plugins/extensions/connectors — 처음 사용자에게 압도적.

누구에게 추천하는가

✅ 적합

• OpenAI 생태계에 이미 투자한 팀 — ChatGPT 플랜으로 API 비용 없이 즉시 시작
• 보안 민감 환경 — OS 네이티브 샌드박스를 신뢰
• CI/CD 자동화 — codex exec --json 헤드리스, codex review, GitHub Action 라벨 워크플로
• 다중 표면 일관 운영 — IDE / CLI / MCP / 데스크톱 / 클라우드 / Action 모두 같은 엔진
• MCP 생태계 연동 — 클라이언트·서버 양방향 지원
• Rust/시스템 프로그래밍에 익숙한 팀
• Linux/macOS 사용자 — 가장 완성도 높은 두 플랫폼

⚠️ 피해야 할 경우

• OpenAI 외 모델이 필수인 팀 — Responses API 호환만 지원
• Windows 네이티브 사용 중시 팀 — 공식 권장은 WSL2
• 외부 코드 기여 영향력을 원하는 OSS 활동가 — 초청제 PR
• 모든 것을 customize 해야 하는 팀 — GPT-5 계열에 핀된 프롬프트
• 가벼운 CLI 원하는 사용자 — 115+ 크레이트의 거대한 모노레포
• 벤더 락인 우려 엔터프라이즈

Codex vs 다른 코딩 에이전트

결론

Codex CLI는 OpenAI 생태계에 투자한 팀에게 “OS 네이티브 샌드박스 + 다중 표면 일관성”이라는 강력한 가치를 제공하는 reference 코딩 에이전트다. Rust로 다시 쓴 결정은 latency · security · embedding의 세 마리 토끼를 잡으려는 의지의 표현이며, 결과는 매우 진지하다. 다만 Responses API에 강하게 결합되어 있고 외부 기여 정책이 폐쇄적이라, 멀티 벤더 전략을 추구하거나 커뮤니티 중심 확장을 원하는 팀에게는 부적합하다.

ChatGPT Plus/Pro 플랜을 이미 쓰고 있다면 추가 비용 없이 한 명령으로 시작할 수 있고, OS 수준 샌드박스로 LLM의 위험한 명령 실행을 진짜로 차단할 수 있다. 그게 가장 큰 가치다.

📚 참고 자료

• 공식 저장소: github.com/openai/codex
• 공식 문서: developers.openai.com/codex
• CLI 레퍼런스: developers.openai.com/codex/cli/reference
• 샌드박스 가이드: developers.openai.com/codex/concepts/sandboxing
• Agent approvals & security: developers.openai.com/codex/agent-approvals-security
• codex-rs 아키텍처 분석: codex.danielvaughan.com/2026/03/28/codex-rs-rust-rewrite-architecture

본 문서는 2026-05-24 기준 openai/codex 저장소를 직접 클론·정독해 작성되었습니다. 모든 코드 인용은 파일 경로:라인 형식으로 명시되어 있습니다.