OpenAI Codex CLI는 터미널에서 동작하는 로컬 AI 코딩 에이전트로, 자연어로 코드베이스를 이해하고 수정할 수 있다. OpenAI가 "클라우드 전용 AI"에서 "로컬 개발자 도구"로 전략을 확장한 첫 번째 본격적인 결과물이다. Claude Code가 열어놓은 터미널 기반 코딩 에이전트 시장에 OpenAI가 Rust로 직접 대응했다.
Claude Code가 Node.js 런타임 위에서 도는 "앱"이라면, Codex CLI는 Rust로 컴파일된 단일 바이너리다. 설치하면 끝이고, OS 커널(macOS Seatbelt, Linux Bubblewrap)이 직접 보안 감옥을 만들어줘서 컨테이너 없이도 커널 수준 격리를 달성한다.
더 독특한 점은 MCP 서버 모드다. Codex 자체가 다른 에이전트(Claude Code 등)의 도구로 사용될 수 있어서, 에이전트 생태계의 "도구 겸 사용자" 이중 역할을 수행한다.
Claude Code는 Node.js가 없으면 설치 불가. 기존 샌드박스 도구들은 Docker나 별도 컨테이너가 필요. OpenAI의 기존 AI 도구들은 클라우드 API만 지원해 오프라인 개발 불가.
Rust 단일 바이너리라 의존성이 없고, macOS Seatbelt·Linux Bubblewrap으로 커널 수준 격리를 달성한다. Ollama/LM Studio 연동으로 API 키 없이도 로컬에서 실행 가능하다.
| 비교 항목 | Codex CLI | Claude Code | Cursor/Windsurf |
|---|---|---|---|
| 언어 | Rust (네이티브 바이너리) | Node.js | Electron |
| 의존성 | 제로 (단일 바이너리) | Node.js 필요 | IDE 전체 |
| 샌드박스 | OS 네이티브 (Seatbelt/Bubblewrap) | 컨테이너 기반 | 없음 |
| MCP 지원 | 클라이언트 + 서버 둘 다 | 클라이언트 | 제한적 |
| 오프라인 지원 | Ollama / LM Studio 연동 | 없음 | 없음 |
| 비대화형 모드 | codex exec 지원 | 제한적 | 없음 |
| TUI | Ratatui 기반 풀스크린 | 인라인 | GUI |
| SDK | 경로 | 용도 |
|---|---|---|
| Python SDK | sdk/python/ | 프로그래밍 방식 접근 |
| TypeScript SDK | sdk/typescript/ | 웹/Node.js 연동 |
| CLI 래퍼 (Node.js) | codex-cli/ | @openai/codex npm 패키지 — 플랫폼별 바이너리 실행기 |
| 요소 | 설명 |
|---|---|
| Cargo workspace | 121개 크레이트 이상 모노레포 (2026-04 기준) |
| 최적화 | Release 프로필: Thin LTO + line-tables-only 디버그 정보, codegen-units=4 (배포 패키징 시 심볼 스트리핑) |
| 릴리즈 | 플랫폼별 네이티브 바이너리 (macOS ARM/x86, Linux ARM/x86) |
| CI | GitHub Actions |
# Workspace 멤버 예시
[workspace]
members = [
"core", # 비즈니스 로직
"cli", # 멀티툴 CLI
"tui", # 터미널 UI
"exec", # 헤드리스 실행
"sandboxing", # 보안 샌드박스
"mcp-server", # MCP 서버 모드
"ollama", # Ollama 연동
# ... 70개 이상
]// 조건부 컴파일로 OS별 샌드박스 구현
#[cfg(target_os = "macos")]
mod seatbelt; // macOS Sandbox (커널 수준 MAC)
#[cfg(target_os = "linux")]
mod bwrap; // Bubblewrap (유저스페이스 컨테이너)
#[cfg(target_os = "windows")]
mod windows_sandbox;
// 런타임에 적절한 샌드박스 선택
pub fn get_platform_sandbox() -> Box<dyn Sandbox> { ... }세 가지 정책 레벨: read-only(기본, 파일 읽기만) · workspace-write(작업 디렉토리 내 쓰기, 네트워크 차단) · danger-full-access(샌드박스 해제).
| 주제 | Codex에서 배울 것 | 실습 아이디어 |
|---|---|---|
| Cargo Workspace | 121개 크레이트 이상 모노레포 구성법 | 3~5개 크레이트로 미니 워크스페이스 구성 |
| 조건부 컴파일 | #[cfg(target_os)]로 OS별 분기 | 간단한 cross-platform CLI 도구 만들기 |
| 비동기 Rust | tokio로 API 호출 + 파일 감시 동시 처리 | tokio로 멀티 API 동시 요청 도구 |
| 에러 처리 | 엄격한 Clippy 규칙 (unwrap 금지) | thiserror/anyhow로 에러 체인 실습 |
| LTO 최적화 | Release 프로필 Thin LTO + codegen-units=4 (배포 시 심볼 스트리핑) | 빌드 프로필 비교 (바이너리 크기, 속도) |
채팅 위젯 구조: ratatui로 실시간 스트리밍 채팅 UI를 만드는 방법. 마크다운 렌더링: 터미널에서 코드 블록, 표, 제목을 컬러로 출력. Diff 시각화: git diff 스타일 코드 변경 표시. 터미널 팔레트 감지 → 자동 테마 적용.
Seatbelt (macOS): Apple의 커널 수준 필수 접근 제어(MAC)를 활용한 프로세스 격리. Bubblewrap (Linux): 유저 네임스페이스 기반 경량 컨테이너화. 정책 기반 보안: read-only / workspace-write / full-access 3단계 모델.
클라이언트 모드: 시작 시 외부 MCP 서버에 연결하여 도구 사용. 서버 모드: codex mcp-server로 Codex 자체가 MCP 서버가 됨 → 다른 에이전트가 Codex를 도구로 사용 가능. 이 이중 역할 패턴은 에이전트 생태계의 미래 방향을 보여준다.
SQLite 기반 세션 저장, Fork/Resume 패턴(기존 세션을 분기하거나 이어서 작업), 세션 내 모든 이벤트 기록으로 재현 가능한 실험 환경.
| 항목 | 요구사항 |
|---|---|
| OS | macOS (ARM/x86), Linux (ARM/x86), Windows |
| Node.js | v16+ (npm 설치 시 래퍼용) |
| 메모리 | 최소 4GB (에이전트 실행 시 API 응답 버퍼링) |
| 디스크 | ~50MB (바이너리) + 세션 저장소 |
| 네트워크 | OpenAI API 접속 필수 (또는 Ollama/LM Studio로 로컬 실행) |
| 인증 | ChatGPT Plus/Pro/Team/Edu/Enterprise 또는 OpenAI API 키 |
| Linux 샌드박스 | Bubblewrap 패키지 설치 권장 |
로컬 LLM 사용 시: Ollama나 LM Studio를 통해 로컬 모델을 사용하면 API 키·네트워크 불필요. GPU: VRAM 8GB+ 권장 (7B 모델 기준).
# 1. 설치
npm install -g @openai/codex
# 2. 기본 사용
codex "이 프로젝트의 README.md를 한국어로 번역해줘"
# 3. 샌드박스 모드 체험
codex --sandbox read-only "src/ 디렉토리 구조를 분석해줘"
codex --sandbox workspace-write "TODO 주석을 찾아서 이슈 파일로 정리해줘"
# 4. 비대화형 모드
codex exec "package.json의 의존성 목록을 표로 정리해줘"같은 작업을 Claude Code와 Codex CLI 양쪽에서 실행하고 비교한다.
Codex를 MCP 서버로 실행하고, 다른 에이전트에서 Codex를 도구로 연결한다.
# Codex를 MCP 서버로 실행
codex mcp-server
# Claude Code의 .mcp.json에서 Codex를 MCP 서버로 등록
# → Claude Code가 Codex를 도구로 사용하는 구조 체험Codex를 소스에서 직접 빌드하고, Codex의 TUI 구조를 참고하여 간단한 터미널 채팅 앱을 만든다.
git clone https://github.com/openai/codex.git
cd codex/codex-rs
cargo build --release
# 특정 크레이트만 빌드
cargo build -p codex-tui --release
# 스냅샷 테스트 리뷰
cargo insta reviewThe Rust Book(공식 문서) 1~10장, clap 크레이트로 CLI 인자 파싱 실습, 간단한 파일 처리 CLI 도구 만들기.
tokio 공식 튜토리얼, reqwest로 HTTP API 호출, tokio::fs로 비동기 파일 I/O, 여러 API를 동시에 호출하는 도구 만들기.
ratatui 공식 예제 따라하기, 채팅 인터페이스 만들기, 키보드 이벤트 처리, 레이아웃 시스템 (Flex, Constraint).
Linux 네임스페이스와 cgroups 개념, Bubblewrap 사용법 학습, macOS Sandbox(Seatbelt) 프로파일 작성, 간단한 샌드박스 래퍼 만들기.
MCP 스펙 문서 읽기, MCP 서버 만들기(Rust 또는 TypeScript), 여러 에이전트를 MCP로 연결하는 실험, Codex MCP 서버 모드 활용 실습.
OpenAI Codex + Claude Code 소스 비교 분석, 승인/권한 시스템 설계, 세션 관리 + 대화 히스토리 영속화, 나만의 미니 코딩 에이전트 프로토타입 만들기.
| 키워드 | 설명 |
|---|---|
| Cargo Workspace | Rust의 모노레포 도구. 여러 크레이트(패키지)를 하나의 워크스페이스에서 관리. 의존성 공유, 병렬 빌드 가능 |
| tokio | Rust의 비동기 런타임. Node.js의 이벤트 루프와 비슷하지만 멀티스레드 기반 |
| ratatui | Rust TUI 프레임워크. Python의 Rich/Textual, Go의 bubbletea에 해당 |
| crossterm | 크로스 플랫폼 터미널 조작 라이브러리. ratatui의 백엔드 |
| tree-sitter | 증분 파싱 라이브러리. 소스코드를 AST로 변환하여 코드 이해에 활용. VS Code, Neovim에서도 사용 |
| axum | tokio 기반 Rust 웹 프레임워크. Express.js의 Rust 버전. 타입 안전한 라우팅 |
| Seatbelt | macOS의 커널 수준 필수 접근 제어(MAC) 시스템. 앱의 파일/네트워크 접근을 프로파일로 제한 |
| Bubblewrap (bwrap) | Linux 유저스페이스 샌드박스. 네임스페이스를 사용하여 루트 권한 없이 프로세스 격리 |
| MCP | Model Context Protocol. 에이전트가 외부 도구를 사용하기 위한 표준 프로토콜. JSON-RPC 기반 |
| Fat LTO | 가장 적극적인 Link Time Optimization 모드. 전체 프로그램을 하나의 컴파일 단위로 최적화 |
| Clippy | Rust의 공식 린터. Codex는 37개 패턴을 deny로 설정하여 코드 품질을 강제 |
| insta | Rust 스냅샷 테스트 프레임워크. 출력을 파일로 저장하고 변경 시 리뷰 |
| sqlx | Rust 비동기 SQL 라이브러리. 컴파일 타임에 쿼리를 검증하는 기능 지원 |
| Guardian | Codex의 권한 승인 시스템. 도구 실행 전 사용자 승인을 관리하는 내부 구조 |
| codex exec | 비대화형 모드. 프롬프트를 주면 작업 완료 후 종료. CI/CD나 스크립트에서 활용 |
| Ollama | 로컬 LLM 실행 도구. Codex가 OpenAI API 대신 로컬 모델을 사용할 수 있게 연동 |
| PTY | Pseudo Terminal. 가상 터미널. Codex가 셸 명령을 실행할 때 사용하는 인터페이스 |