CLI
Codex CLI는 로컬 코드베이스를 읽고 수정하며 명령을 실행하는 코딩 에이전트다. TUI와 비대화형 codex exec, 앱 연동 서버를 같은 Rust 워크스페이스에서 제공한다. 추론은 구성한 모델 공급자에서 처리하므로 “로컬 도구 실행”과 “로컬 추론”은 별개다.
네이티브 배포 파일은 Node 없이 실행할 수 있다. npm 경로는 codex-cli/bin/codex.js가 OS·CPU에 맞는 플랫폼 패키지의 바이너리를 찾는 방식이다. 설치 경로에 따라 런타임 조건이 다르다.
이 저장소에서 살펴볼 가치는 실행 경계가 코드로 분리되어 있다는 점이다. cli가 명령을 선택하고 core가 작업을 조율하며 sandboxing·execpolicy가 파일·프로세스·권한 정책을 맡는다. 화면, 정책, 실제 실행을 나눠 읽으면 코딩 에이전트의 통제 지점을 배울 수 있다.
이번 소스의 CLI에는 review, resume, fork, queue, archive, doctor와 실험적 app-server·exec-server가 정의되어 있다. 예전 문서의 codex mcp-server는 이 커밋의 명령 목록에 없다. 외부 MCP 서버 관리는 codex mcp, 앱 연결은 별도 app-server 프로토콜로 구분한다.
| 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 |
2026-10-31 재검토에서는 아래를 현재 모듈 간 책임을 설명하는 개념도로 사용한다. 실행 모드마다 모든 계층을 반드시 거치는 호출 스택은 아니다.
TUI / exec / 앱 클라이언트
│
CLI 명령 선택 ── app-server / transport / protocol
│
core · thread-manager · tools · model-provider
│ │
정책·승인·샌드박스 모델 공급자 / 외부 MCP
│
파일·셸 실행 (로컬 또는 구성된 실행 환경)
cli/src/main.rs는 사용자 명령을 파싱한다. app-server는 stdio·Unix 소켓·WebSocket 등의 전송 설정과 별도 프로토콜 크레이트를 둔다. exec-server는 독립 실행 서비스의 실험적 진입점이다. app-server를 MCP 서버의 다른 이름으로 해석하면 안 된다.
승인 정책은 명령 실행 여부를 판단하고 샌드박스는 실제 접근 범위를 제한한다. sandboxing/src/의 seatbelt, bwrap, landlock, windows와 manager를 함께 읽는다. 설정과 관리 정책에 따라 동작이 달라지므로 기본 모드를 일괄 단정하지 않는다.
워크스페이스에는 thread-store, state, rollout, skills, plugin, hooks와 ext/*가 나뉘어 있다. 기능 플래그로 노출되는 실험 기능과 안정 사용자 기능을 구분해 읽는다.
codex/ ├── codex-cli/ # npm manifest와 Node 실행 래퍼 ├── codex-rs/ │ ├── cli/ # clap 명령 분기 │ ├── core/ # 에이전트 핵심 처리 │ ├── tui/ # 터미널 화면 │ ├── exec/ # 비대화형 실행 │ ├── app-server*/ # 앱 서버·전송·클라이언트·프로토콜 │ ├── exec-server*/ # 실행 서비스·CLI·프로토콜 │ ├── sandboxing/ # 플랫폼 정책·격리 │ ├── linux-sandbox/ # Linux 실행 경계 │ ├── codex-mcp/ # MCP 관리 명령 │ ├── rmcp-client/ # MCP 클라이언트 │ ├── skills/ · plugin/ # 확장 기능 │ ├── state/ · thread-store/ # 영속 상태 │ └── rust-toolchain.toml # 고정 Rust 개발 도구 ├── sdk/ # SDK 구현 └── docs/ # 설치·개발 문서
전체 크레이트 수보다 경계를 먼저 읽는다. Cargo.toml의 실제 workspace members를 목록과 대조하고, CLI에서 관심 있는 명령의 분기로 이동하면 진입점을 찾기 쉽다.
| 주제 | 읽을 코드 | 학습 과제 |
|---|---|---|
| 명령 분기 | cli/src/main.rs의 Subcommand | exec·review·app-server의 인자와 분기를 표로 정리 |
| 플랫폼 배포 | codex-cli/bin/codex.js | OS·CPU가 플랫폼 패키지로 매핑되는 경로 추적 |
| 프로토콜 상태 | app-server/README.md | thread/list의 커서·오류·정상 종료 구분 |
| 샌드박스 | sandboxing/src/manager.rs | 승인 결정과 OS의 접근 제한이 적용되는 위치 비교 |
고정 소스의 docs/install.md는 macOS 12 이상, Ubuntu 20.04/Debian 10 이상, Windows 11의 WSL2 경로와 RAM 최소 4GB·권장 8GB를 안내한다. 네이티브 Windows용 패키지도 npm 래퍼에 매핑되어 있으므로 문서가 안내하는 개발 경로와 배포 파일 지원을 구분한다.
| 구분 | 대조 결과 |
|---|---|
| 네이티브 설치 | README의 독립 설치 프로그램·Homebrew·릴리스 바이너리 |
| npm 설치 | codex-cli/package.json의 Node >=16 선언; JS 래퍼를 실행하는 조건 |
| Rust 소스 빌드 | codex-rs/rust-toolchain.toml의 1.95.0, clippy·rustfmt·rust-src |
| 인증 | ChatGPT 로그인 또는 별도 API 키 구성 |
| 로컬 모델 | Ollama·LM Studio 모듈이 있으나 모델 준비·자원 조건은 별도 |
로컬 모델을 선택해도 MCP·웹 도구·패키지 다운로드가 네트워크를 사용할 수 있다. 모델 제공 방식만으로 세션 전체가 오프라인이라고 단정하지 않는다.
npm install -g @openai/codex codex --version codex --help
npm 래퍼와 네이티브 실행 파일의 역할을 설명하고, 설치한 버전의 도움말을 소스 명령 목록과 비교한다.
codex --sandbox read-only "이 저장소의 진입점과 모듈 의존 관계를 설명해줘"
격리된 연습 저장소에서 실행하고 권한 설정·도구 사용 내역을 확인한다.
codex-rs/cli/src/main.rs의 Exec·Review·Mcp 분기를 읽는다. 외부 MCP 연결 관리와 Codex를 외부에서 호출하는 app-server 연동의 입력·출력을 구분한다.
git clone https://github.com/openai/codex.git cd codex/codex-rs cargo build just test -p codex-tui
docs/install.md의 Rust·just·DotSlash·nextest 준비 절차를 따른다. 빌드와 테스트는 독자의 별도 개발 환경에서 수행하는 과제이며 이 글의 검토 과정에서 실행한 결과가 아니다.
The 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로 연결하는 실험, 외부 MCP 관리와 app-server 프로토콜 비교.
OpenAI Codex의 CLI·core·실행 경계 비교 분석, 승인/권한 시스템 설계, 세션 관리 + 대화 히스토리 영속화, 나만의 미니 코딩 에이전트 프로토타입 만들기.
| 키워드 | 설명 |
|---|---|
| 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가 셸 명령을 실행할 때 사용하는 인터페이스 |
2026-10-31 고정 커밋 67f0994b532b의 README·CLI 분기·workspace·설치 문서를 대조했다. 제품 사용 안내는 공식 Codex CLI 문서를 참고한다.