하네스 엔지니어링 위키

2. Codex

Properties2
tags프레임워크분석, codex
aliasesCodex, OpenAI Codex, codex-rs

15 min read

2. Codex

한 줄 요약

OpenAI 공식 터미널 코딩 에이전트로, OS 레벨 샌드박스 + 실행정책 + LLM 자동승인을 결합해 “위험한 명령을 어떻게 안전하게 자동 실행할까”를 프로덕션 수준으로 풀어낸 단일 에이전트 하네스다. → 왜 배우나: 안전(샌드박스·승인·가드)을 코드 구조에 박아 넣는 설계의 교과서이기 때문이다. 하네스를 “기능”이 아니라 “권한과 경계”로 설계하는 법을 배운다.

그림

flowchart TD
    U["사용자 / CLI·IDE·App·Cloud"] -->|한 턴 요청| CORE["codex-core<br/>(심장: 세션·턴·컨텍스트)"]
    CORE -->|도구 호출| REG["registry<br/>(도구 등록)"]
    REG --> RT["router<br/>(라우팅)"]
    RT --> ORC["orchestrator<br/>(승인·샌드박스선택·재시도)"]
    ORC -->|안전 판정| GUARD["가드 4중<br/>OS샌드박스·실행정책<br/>패치판정·Guardian LLM"]
    GUARD --> RUN["runtime<br/>(실제 실행)"]
    RUN -->|결과| CORE
    CORE -->|영속| PERSIST["rollout JSONL<br/>+ state SQLite<br/>+ memories"]
    CORE -->|필요시| SUB["서브에이전트 트리<br/>(default·explorer·worker)"]

그림 읽는 법

모든 도구 호출은 registry→router→orchestrator→runtime 한 줄로 흐르고, 위험한 결정(승인·샌드박스)은 전부 가운데 orchestrator에 모인다. 안전 판정은 별도 4중 가드가 담당한다.

쉽게 풀기

Codex를 **“엄격한 보안 규정을 가진 회사의 신입 개발자”**라고 생각하면 쉽다.

  1. 일감 받기 (턴) — 사용자가 “이 버그 고쳐줘”라고 시키면, 신입은 한 번에 다 못 하고 모델 호출 → 도구 실행 → 다시 모델 호출을 반복하며 일을 진행한다. 이 반복 한 사이클이 “한 턴”이다.

  2. 도구를 함부로 못 씀 (파이프라인) — 파일을 고치거나 명령을 실행하려면 반드시 접수처(registry) → 안내데스크(router) → 보안실장(orchestrator) → 실행장(runtime) 순서를 거쳐야 한다. 핵심은 모든 위험 판단이 보안실장 한 명에게 모인다는 것이다. 책임 소재가 흩어지지 않는다.

  3. 4중 보안검색대 (가드레일) — 보안실장은 명령을 그냥 통과시키지 않는다.

    • OS 샌드박스: 아예 격리된 방 안에서만 일하게 한다 (macOS Seatbelt / Linux bubblewrap / Windows 제한토큰).
    • 실행정책: rm -rf / 같은 위험 명령을 명령어 사전과 대조해 거른다.
    • 패치판정: 파일 수정이 안전한지 미리 정적으로 검사한다.
    • Guardian(LLM 검토자): 사람이 “승인할까?” 고민할 자리에 전용 AI가 들어가 자동으로 판정한다. 단, 헷갈리거나 오류나면 무조건 거부(fail-closed) — “안전한 쪽으로 막는다”.

  4. 모든 걸 기록 (영속) — 신입은 업무일지(rollout JSONL), 색인 장부(state SQLite), 교훈 노트(memories)를 따로 남긴다. 다음에 같은 일을 더 잘하기 위해서다.

  5. 혼자 못 하면 팀 (서브에이전트) — 기본은 혼자 일하지만, 큰 일은 보조 신입(서브에이전트)을 몇 명 불러 역할(탐색·작업)을 나눈다. 이름은 과학자 풀(Euclid, Turing…)에서 뽑아 추적하기 쉽게 한다.

한 단어로

Codex의 정체성은 “기능 많은 에이전트”가 아니라 **“권한과 경계를 코드로 강제하는 에이전트”**다.

핵심 정리

항목내용한 줄 의미
본체codex-rs Cargo 워크스페이스 (120+ 크레이트)책임을 폴더로 물리 분리
심장codex-core (약 16만 줄)세션·턴·도구·컨텍스트·안전
실행면CLI · IDE · App · Cloud하나의 프로토콜로 통일
주력 언어Rust (+TS·Python SDK, Starlark)정책은 Starlark, 실행은 Rust

10축 점수 (만점 5)

  • 아키텍처/포지셔닝 5 — 120+ 크레이트로 안전/실행/영속/확장을 폴더 단위 분리
  • 컨텍스트엔지니어링 5 — 25개+ 타입 fragment + diff 기반 최소 업데이트로 캐시 친화
  • 툴/확장 5 — 풍부한 내장 도구 + code-mode + contributor 트레이트(승인검토·토큰사용량까지 개방)
  • 오케스트레이션 4 — orchestrator 단일 시퀀스 + 병렬실행 + 멀티에이전트 V2(단, 협업 패턴은 얕음)
  • 가드레일/안전 5 — OS샌드박스 3종 + Starlark정책 + 패치판정 + Guardian의 4중 독립 가드
  • 검증루프 4 — 전용 review_model 스레드 + 턴별 diff 추적 + Post/Stop 훅
  • 자기개선/반복 3 — memories(Experimental·기본 비활성) + goal steering, 자동 코드진화는 없음
  • 상태/영속성 5 — rollout JSONL + state SQLite + memories + thread-store
  • 배포/DX 5 — 정적 musl 바이너리 + 다채널 설치 + 다언어 SDK + 비대화형 CI 모드
  • 철학/차별점 5 — feature lifecycle 코드화 + 샌드박스 우선 + PermissionProfile 단일 권한 계약

꼭 기억할 독창 아이디어 5가지

  • Guardian 자동승인 — 사람 승인 자리에 LLM 검토 세션, fail-closed (Stable·기본 활성)
  • Code-mode — 도구를 하나씩 호출 대신 V8 JS 코드로 묶어 실행 (TS는 타입설명용)
  • Starlark 실행정책 — git add . && rm -rf / 같은 합성 명령을 분해해 가장 엄격한 규칙 적용
  • OS 네이티브 샌드박스 3종 자체구현 + 거부시 에스컬레이션 재시도
  • PermissionProfile = 단일 권한 계약 — 한 값이 설정·승인·샌드박스·네트워크까지 일관 적용

강점과 약점은 동전의 양면

강점: 4중 안전 모델이 독립 작동 · 도구 파이프라인 명확 · 영속성 강력 · DX 우수. 약점: 멀티에이전트는 아직 보조적(built-in role 3개) · 자기개선이 코드진화가 아닌 기억·목표 지속에 한정 · OpenAI 생태계 종속 · 16만 줄+이중빌드로 기여 진입장벽 높음 · Windows 샌드박스는 옵션적.

실제 예시

도구 호출 파이프라인의 책임 분리를 코드 위치로 확인하면 설계가 한눈에 보인다.

# codex-rs/core/src/tools/  — 도구 파이프라인 4단계
registry.rs       # 1) 등록: 어떤 도구가 존재하는가
router.rs         # 2) 라우팅: 이 호출을 어디로 보낼까
orchestrator.rs   # 3) 승인→샌드박스선택→시도→에스컬레이션 재시도 (위험 결정 집중)
parallel.rs       # 도구 병렬 실행
runtime           # 4) 실제 실행
# codex-rs/  — 4중 가드레일이 사는 곳
sandboxing/src/manager.rs                  # OS 샌드박스 통합
sandboxing/src/seatbelt_base_policy.sbpl   # macOS Seatbelt 정책 DSL
linux-sandbox/src/linux_run_main.rs        # Linux bubblewrap 기본 + seccomp (Landlock은 legacy fallback)
execpolicy/src/policy.rs                   # Starlark 실행정책 파서
core/src/safety.rs                         # 패치 안전성 정적 판정(AutoApprove/AskUser/Reject)
core/src/guardian/mod.rs                   # LLM 자동승인 (fail-closed)
# 핵심 설계가 박힌 파일들
core/src/config/mod.rs                  # PermissionProfile = 단일 권한 계약
features/src/lib.rs                      # feature lifecycle 중앙관리(Stable/Experimental/UnderDevelopment/Removed)
core/src/context_manager/updates.rs     # 컨텍스트 diff 기반 최소 업데이트(캐시 미스 억제)
ext/extension-api/src/contributors.rs   # 확장 contributor 트레이트(승인검토·토큰사용량까지 개방)
core/src/agent/role.rs                   # built-in role: default/explorer/worker
# 비대화형 CI 모드 — JSONL 이벤트로 파이프라인 통합
codex exec "테스트 통과시켜줘"   # AGENTS.md의 `just test` 검증 규약을 따른다

요약 & 셀프체크

3줄 요약

  1. Codex는 모든 도구 호출을 registry→router→orchestrator→runtime 한 줄로 흘리고, 위험 결정을 orchestrator에 집중시킨다.
  2. 안전은 OS샌드박스·실행정책·패치판정·Guardian LLM의 4중 독립 가드로 보장하며, 헷갈리면 항상 거부(fail-closed)한다.
  3. 정체성은 기능이 아니라 권한과 경계다 — PermissionProfile 단일 계약과 feature lifecycle 코드화가 그 증거다.

스스로 답해보기

  • 도구 호출이 실제 실행되기까지 거치는 4단계는? 그중 위험 판단이 모이는 곳은?
  • “fail-closed”가 안전 설계에서 의미하는 바는? Guardian이 타임아웃되면 어떻게 되나?
  • PermissionProfile이 “단일 권한 계약”으로 불리는 이유는? 어떤 영역들을 관통하나?

연결

기능별 분해 (번호순)

  • CX_10_agent-loop-and-turn — 진입점과 에이전트 실행 루프(run_turn/Task): 한 턴이 모델호출→도구실행→재호출로 도는 심장부.
  • CX_20_prompt-and-context-assembly — 프롬프트·컨텍스트 조립: base 프롬프트 + AGENTS.md + 환경/스킬/권한 fragment를 마커로 이어붙여 주입.
  • CX_30_tool-system — 도구 시스템: ToolSpec 정의 형식과 모델 노출, ToolRouter 디스패치(registry→router→orchestrator→runtime).
  • CX_40_hooks — 확장점 Hooks: 라이프사이클 이벤트(PreToolUse/PostToolUse/Stop 등)에 외부 명령을 끼워 넣는 훅.
  • CX_50_skills — 확장점 Skills: SKILL.md 폴더 + progressive disclosure(목차만 먼저, 필요할 때 본문)로 컨텍스트 절약.
  • CX_60_subagents-multi-agent — 확장점 Subagents: 역할·깊이·총수 제한으로 서브에이전트를 병렬 spawn하는 멀티에이전트(V2 + role 레이어).
  • CX_70_mcp-and-plugins — 확장점 MCP + Plugins: MCP=런타임 도구 연결, Plugin=훅·스킬·MCP·앱을 한 매니페스트(JSON)로 배포하는 봉지.
  • CX_80_sandbox-and-approval-guardrails — 가드레일: OS 샌드박스(Seatbelt/bubblewrap+seccomp/Windows 제한토큰) + 승인 정책 + Guardian LLM 자동승인.
  • CX_90_persistence-and-memory — 상태·메모리 영속성: Rollout JSONL(속기록) + state SQLite(색인 장부) + Memories(교훈 위키) 3분리.
  • CX_100_code-mode-special — 고유 특별기능 Code Mode: 도구 목록 대신 exec 한 개만 주고 모델이 JS 셀을 써 도구를 한 번에 오케스트레이션(V8 실행).

비교·기준

_분석축_루브릭 · HOME · _비교매트릭스

핵심 소스 파일 (근거)

  • /mnt/d/6study/_소스레포/codex/codex-rs/Cargo.toml — 120+ 크레이트 워크스페이스
  • /mnt/d/6study/_소스레포/codex/AGENTS.md — 안전 규약·검증 규약(CODEX_SANDBOX_NETWORK_DISABLED 수정금지)
  • /mnt/d/6study/_소스레포/codex/codex-rs/features/src/lib.rs — feature lifecycle 중앙관리(29/790/860/1144/1150)
  • /mnt/d/6study/_소스레포/codex/codex-rs/core/src/tools/orchestrator.rs — 승인·샌드박스·재시도 중앙처리
  • /mnt/d/6study/_소스레포/codex/codex-rs/core/src/tools/{router,parallel}.rs — 도구 라우팅·병렬실행
  • /mnt/d/6study/_소스레포/codex/codex-rs/core/src/safety.rs — 패치 안전성 정적 판정
  • /mnt/d/6study/_소스레포/codex/codex-rs/sandboxing/src/manager.rs — OS 샌드박스 통합
  • /mnt/d/6study/_소스레포/codex/codex-rs/sandboxing/src/seatbelt_base_policy.sbpl — macOS Seatbelt 정책
  • /mnt/d/6study/_소스레포/codex/codex-rs/linux-sandbox/src/linux_run_main.rs — bubblewrap+seccomp
  • /mnt/d/6study/_소스레포/codex/codex-rs/execpolicy/src/policy.rs — Starlark 실행정책
  • /mnt/d/6study/_소스레포/codex/codex-rs/core/src/guardian/mod.rs · ext/guardian/src/lib.rs — LLM 자동승인
  • /mnt/d/6study/_소스레포/codex/codex-rs/code-mode-protocol/src/{lib,description}.rs — code-mode(V8 JS)
  • /mnt/d/6study/_소스레포/codex/codex-rs/core/src/context_manager/updates.rs — 컨텍스트 diff 업데이트
  • /mnt/d/6study/_소스레포/codex/codex-rs/core/src/config/mod.rs — PermissionProfile 권한계약
  • /mnt/d/6study/_소스레포/codex/codex-rs/ext/extension-api/src/contributors.rs — 확장 contributor 트레이트
  • /mnt/d/6study/_소스레포/codex/codex-rs/core/src/agent/role.rs — built-in role(default/explorer/worker)
  • /mnt/d/6study/_소스레포/codex/codex-rs/core/src/tools/handlers/multi_agents_v2.rs — 멀티에이전트 V2
  • /mnt/d/6study/_소스레포/codex/codex-rs/ext/goal/src/steering.rs — 목표 지속 재주입
  • /mnt/d/6study/_소스레포/codex/codex-rs/rollout/src/recorder.rs · state/src/lib.rs — 영속성

Claude ↔ Codex 교차검증 (메타검증 기록)

불일치가 곧 학습 포인트다. Codex가 자기 코드를 읽고 짚은 지적은 대부분 타당해 그대로 반영했다. 수정 반영된 사실 오류 — guardian_approval은 Experimental이 아니라 Stable/기본 활성(features/src/lib.rs:1144) · code-mode 실행면은 TS가 아니라 V8 raw JavaScript(TS는 타입설명용) · Linux는 bubblewrap 기본+seccomp, Landlock은 legacy fallback · built-in role은 default/explorer/worker 3개(awaiter는 주석 처리). 짚인 누락 — feature lifecycle 자체가 핵심 설계 · 컨텍스트는 diff 기반 최소 업데이트 · extension API는 승인검토·턴아이템 후처리까지 개방 · 멀티에이전트는 V2+role 레이어 · 가장 저평가된 아이디어는 PermissionProfile 단일 권한 계약. 점수 보정 — 자기개선/반복 4→3 하향(memories가 Experimental/기본 비활성이고 자동 코드개선 메커니즘 없음). 나머지 9축은 양측 일치.

그래프 뷰

백링크