OMX - Codex CLI Foundation

시리즈: oh-my-codex 아키텍처 해부

이 시리즈는 OpenAI Codex CLI 확장 런타임인 oh-my-codex(OMX)의 내부 구조를 단계별로 해부하는 과정이다.

편	내용	핵심
0편	Overview	3-Plane 아키텍처, OMC와의 차이, 전체 흐름
1편 (본문)	Codex CLI Foundation	Codex CLI 자체의 구조와 확장 포인트
2편	OMX Integration	OMX가 Codex에 어떻게 연결되나
3편	Skill System	워크플로우를 어떻게 정의하나
4편	Prompt & Agent System	에이전트는 뭐고 어떻게 선택되나
5편	MCP Servers	어떤 MCP 도구를 쓸 수 있나
6편	State & Lifecycle	상태를 어떻게 유지하나
7편	Team Orchestration	Team 모드는 어떻게 동작하나
8편	Native & Spark	Rust 네이티브 도구는 뭔가

---

• Codex CLI는 OpenAI가 제공하는 터미널 기반 로컬 코딩 에이전트
• Rust 96.2%로 구현된 경량 CLI로, 대화형 REPL에서 코드 생성·수정·실행을 수행하는 단일 세션 에이전트
• OMX가 확장하는 실행 엔진(Execution Plane) — OMX를 이해하려면 Codex CLI의 구조와 확장 포인트를 먼저 알아야 함

해당 개념이 필요한 이유

• OMC 학습에서는 Claude Code를 이미 쓰고 있었기 때문에 별도 설명이 불필요했음
• OMX 학습에서는 Codex CLI가 처음이므로, 이것이 뭐고 어떤 확장 포인트를 제공하는지 알아야 OMX의 설계 선택을 이해할 수 있음
• Codex CLI의 확장 채널(AGENTS.md, config.toml, MCP)이 곧 OMX의 통합 경로

AS-IS (Claude Code — 이미 아는 것)

graph TB
    subgraph ClaudeCode["Claude Code (Anthropic)"]
        Plugin["plugin.json"]
        Hook["hooks.json — 21개 이벤트"]
        MCP_CC["MCP 서버"]
        Skill_CC["Skill tool"]
    end

    Plugin --> Hook
    Plugin --> MCP_CC
    Plugin --> Skill_CC

    style ClaudeCode fill:#e8f0fe

TO-BE (Codex CLI — 새로 배울 것)

graph TB
    subgraph CodexCLI["Codex CLI (OpenAI)"]
        AGENTS["AGENTS.md — 계층적 지침"]
        Config["config.toml — 설정·MCP·프로바이더"]
        Sandbox["Sandbox — Seatbelt / Landlock"]
        Approval["Approval + Sandbox 2축 제어"]
    end

    AGENTS --> Config
    Config --> Sandbox
    Config --> Approval

    style CodexCLI fill:#fef7e0

승인(Approval)과 샌드박스(Sandbox) — 2축 보안 모델

학습 원문에서는 suggest / auto-edit / full-auto 3가지로 설명하지만, 실제 Codex CLI는 Approval Policy와 Sandbox Mode 두 축을 독립적으로 제어한다.

Approval Policy — “언제 사람의 허락을 구하나”

모드	동작
on-request (기본)	워크스페이스 외부 수정, 네트워크 접근 시 승인 요청
untrusted	읽기 전용 자동, 상태 변경 명령은 승인 필요
never	승인 없음 (CI/CD 자동화용)

Sandbox Mode — “파일/네트워크 접근을 어디까지 허용하나”

모드	파일 접근	네트워크
read-only	읽기만 허용	차단
workspace-write	작업 디렉토리 + temp 쓰기 허용, .git/.codex 보호	기본 차단 (설정으로 허용 가능)
danger-full-access	무제한	무제한

편의 플래그

플래그	실제 의미
--full-auto	--sandbox workspace-write + --ask-for-approval on-request
--yolo	danger-full-access + never (모든 제어 해제, 비권장)

플랫폼별 샌드박스 구현

플랫폼	메커니즘	특징
macOS	Seatbelt (sandbox-exec -p)	커널 레벨 정책 프로파일 적용
Linux	Landlock + seccomp (기본)	커널 보안 모듈 조합
Linux (대안)	bwrap	프록시 브릿지 경유 egress, 실패 시 폐쇄
Windows	네이티브 + WSL 위임	IDE에서 WSL로 라우팅 가능

AGENTS.md — 계층적 지침 시스템

Codex CLI가 세션 시작 시 읽는 마크다운 기반 지침 파일. OMX가 가장 핵심적으로 활용하는 확장 포인트이다.

탐색 순서 (top-down 머지)

graph TD
    A["~/.codex/AGENTS.override.md"] -->|1순위| MERGE["최종 지침 체인"]
    B["~/.codex/AGENTS.md"] -->|2순위 fallback| MERGE
    C["repo-root/AGENTS.override.md"] -->|3순위| MERGE
    D["repo-root/AGENTS.md"] -->|4순위 fallback| MERGE
    E["repo-root/subdir/AGENTS.md"] -->|5순위| MERGE
    F["... → cwd/AGENTS.md"] -->|N순위| MERGE

    MERGE -->|"blank-line 구분자로 연결"| CX["Codex CLI 세션"]

    style A fill:#ff9999
    style MERGE fill:#99ff99

핵심 규칙

• 각 디렉토리에서 AGENTS.override.md → AGENTS.md 순으로 확인, 첫 번째 비어있지 않은 파일만 사용
• 하위 파일이 상위를 오버라이드하는 것이 아니라, 뒤에 연결(concatenate) — 나중에 나온 지침이 우선
• 기본 크기 제한: project_doc_max_bytes = 32 KiB (config.toml에서 조정 가능)
• --no-project-doc 또는 model_instructions_file로 비활성화/대체 가능
  • 주의: model_instructions_file을 설정하면 위의 계층적 탐색·머지가 전부 무력화되고, 지정된 단일 파일만 모델 지침으로 사용됨. OMX는 런타임 오버레이 주입을 위해 이 키를 사용하는데, 네이티브 머지가 꺼지므로 agents-overlay.ts(src/hooks/)에서 user/project AGENTS.md를 직접 재머지하여 세션 합본 파일(.omx/state/{sessionId}/AGENTS.md)을 생성한다 (2편 Integration 참조).
• 지침 체인은 세션당 1회 빌드 (TUI에서는 세션 시작 시)

실전 예시 — 규칙 A와 규칙 B가 있을 때 어떻게 되나

핵심 질문: 1순위 파일에 Rule A, 2순위 파일에 Rule B가 있으면 A만 적용되나, A+B 모두 적용되나?

답: A+B 모두 적용된다. 선택된 파일들은 전부 concatenate된다. “우선순위”는 파일을 제거하는 개념이 아니라, 내용이 충돌할 때만 나중 파일이 이기는 개념이다.

---

시나리오: ~/projects/myapp/src/ 에서 codex 실행. 아래 파일들이 존재한다.

~/.codex/AGENTS.override.md    ← Rule A (전역 개인화)
~/.codex/AGENTS.md             ← 내용 있음 (OMX 글로벌 주입본)
~/projects/myapp/AGENTS.md     ← Rule B (프로젝트 지침)
~/projects/myapp/src/AGENTS.md ← Rule C (서브모듈 지침)

Step 1 — 디렉토리별 파일 선택 (같은 디렉토리 안에서 override가 있으면 AGENTS.md 건너뜀):

디렉토리	override 존재?	선택된 파일	건너뜀
~/.codex/	✅	AGENTS.override.md (Rule A)	AGENTS.md ❌
~/projects/myapp/	❌	AGENTS.md (Rule B)	—
~/projects/myapp/src/	❌	AGENTS.md (Rule C)	—

Step 2 — 선택된 파일 전부 concatenate (A + B + C 모두 적용):

[Rule A — ~/.codex/AGENTS.override.md]
"항상 TypeScript로 코드를 작성하라"

[Rule B — ~/projects/myapp/AGENTS.md]
"이 프로젝트에서는 snake_case 네이밍을 사용하라"

[Rule C — ~/projects/myapp/src/AGENTS.md]
"src/ 안에서는 함수형 스타일을 우선하라"

→ Codex CLI는 세 규칙 모두를 동시에 따른다. TypeScript + snake_case + 함수형 스타일.

Step 3 — 충돌 시에만 나중 파일이 이긴다:

[Rule A — ~/.codex/AGENTS.override.md]
"항상 영어로 응답하라"          ← 충돌!

[Rule B — ~/projects/myapp/AGENTS.md]
"항상 한국어로 응답하라"        ← 충돌! (더 나중 → 이김)

→ 같은 주제로 충돌하면 나중(= cwd에 가까울수록) 파일이 이긴다. 이 경우 한국어 응답.

주의: ~/.codex/AGENTS.md (OMX 글로벌 주입본)는 이 시나리오에서 체인에 포함되지 않는다. 같은 디렉토리(~/.codex/)에 AGENTS.override.md가 존재하기 때문에 Step 1에서 건너뛰어지며, OMX가 주입한 Operating Principles, Keyword Detection Table 등 모든 글로벌 지침이 무효가 된다. OMX 글로벌 지침을 유지하려면 AGENTS.override.md를 두지 않거나, 그 안에 OMX 지침을 포함시켜야 한다.

실제 AGENTS.md 내용 — OMX가 주입하는 것

omx setup 후 ~/.codex/AGENTS.md에 주입되는 핵심 구조:

# OMX Orchestration Contract
 
## Role & Intent
You are an orchestration-aware coding agent. Solve development tasks directly
when possible. Delegate to specialized agents only when it materially improves
quality, speed, or correctness.
 
## Operating Principles
1. Solve the task directly when you can do so safely and well.
2. Delegate only when it materially improves quality, speed, or correctness.
3. Keep progress short, concrete, and useful.
4. Prefer evidence over assumption; verify before claiming completion.
5. Use the lightest path: direct action → MCP → delegation.
 
## Keyword Detection Table
When you detect any of the following keywords in user input, activate the
corresponding skill or agent **immediately before any other action**.
Keywords are case-insensitive and match anywhere in the message.
 
| Keyword    | Priority | Action                         |
|------------|----------|--------------------------------|
| ralplan    | 11       | Load skills/ralplan/SKILL.md   |
| autopilot  | 10       | Load skills/autopilot/SKILL.md |
| ultrawork  | 10       | Load skills/ultrawork/SKILL.md |
| ralph      | 9        | Delegate to /prompts:ralph     |
| explore    | 8        | Load skills/explore/SKILL.md   |
| team       | 8        | Load skills/team/SKILL.md      |
| ...        | ...      | (30+ keywords total)           |
 
## Delegation Rules
- Prefer `/prompts:executor` for implementation tasks
- Prefer `/prompts:architect` for design/planning tasks
- Always write delegation intent to MCP state before delegating
 
## Verification Protocol
Before claiming completion:
1. Run the relevant tests or build command
2. Confirm output matches the stated goal
3. Mark state as complete via MCP state_write

이것이 Codex CLI의 시스템 프롬프트에 삽입되는 방식으로, Claude Code의 hooks.json 21개 이벤트를 대체하는 핵심 메커니즘이다.

OMX가 AGENTS.md를 활용하는 방식

OMX는 이 파일에 키워드 매핑 테이블, Operating Principles, Delegation Rules, Verification Protocol을 주입하여, Codex CLI의 행동을 오케스트레이션한다. Claude Code의 Hook 이벤트 21개를 대체하는 핵심 메커니즘이다.

config.toml — 설정 허브

~/.codex/config.toml에 위치하며, Codex CLI의 모든 설정을 관리한다.

주요 섹션

# 모델 설정
model = "gpt-5-codex"
model_provider = "openai"
model_reasoning_effort = "medium"  # minimal/low/medium/high/xhigh
 
# 승인/샌드박스
approval_policy = "on-request"
sandbox_mode = "workspace-write"
 
# MCP 서버 등록 — OMX가 5개 서버를 여기 등록
[mcp_servers.omx_state]
command = "node"
args = ["path/to/state-server.js"]
startup_timeout_sec = 10
 
[mcp_servers.omx_memory]
command = "node"
args = ["path/to/memory-server.js"]
 
# 프로바이더 설정 — 멀티 프로바이더 지원
[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://your-resource.openai.azure.com"
env_key = "AZURE_OPENAI_API_KEY"
wire_api = "responses"
 
# AGENTS.md 관련
project_doc_max_bytes = 32768
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
 
# 에이전트 설정
agents.max_threads = 6
agents.max_depth = 1

프로젝트 스코프 config

프로젝트루트/.codex/config.toml도 지원하며, 신뢰된 경우에만 로드된다. 우선순위: CLI 플래그 > 프로파일 > 루트 config.

실전 예시 — omx setup 전후 비교

Before (vanilla Codex CLI, ~/.codex/config.toml):

model = "o4-mini"
model_provider = "openai"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

After omx setup --user (OMX가 MCP 서버 5개를 자동 추가):

model = "o4-mini"
model_provider = "openai"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
 
# ──── OMX가 추가한 섹션 ────
 
[mcp_servers.omx_state]
command = "node"
args = ["/Users/you/.omx/servers/state-server.js"]
startup_timeout_sec = 10
 
[mcp_servers.omx_memory]
command = "node"
args = ["/Users/you/.omx/servers/memory-server.js"]
startup_timeout_sec = 10
 
[mcp_servers.omx_code_intel]
command = "node"
args = ["/Users/you/.omx/servers/code-intel-server.js"]
startup_timeout_sec = 10
 
[mcp_servers.omx_trace]
command = "node"
args = ["/Users/you/.omx/servers/trace-server.js"]
startup_timeout_sec = 10
 
[mcp_servers.omx_team]
command = "node"
args = ["/Users/you/.omx/servers/team-server.js"]
startup_timeout_sec = 10
 
agents.max_threads = 6
agents.max_depth = 1

이후 codex를 실행하면, Codex CLI가 시작 시 이 5개 MCP 서버를 자동으로 기동시킨다.

실전 예시 — 우선순위 충돌 시 어떤 값이 적용되나

시나리오: 같은 키 model이 여러 곳에 지정된 경우

CLI 플래그: --model o3
~/.codex/config.toml: model = "o4-mini"        ← 글로벌 설정
.codex/config.toml:   model = "gpt-5-codex"    ← 프로젝트 설정 (신뢰된 경우만)

우선순위: CLI 플래그 > 프로젝트 config > 글로벌 config

상황	적용되는 model
codex --model o3	o3 (CLI 플래그 최우선)
codex (프로젝트 config 신뢰됨)	gpt-5-codex (프로젝트 config)
codex (프로젝트 config 신뢰 안됨)	o4-mini (글로벌 config)
codex (config 없음)	o4-mini (Codex CLI 기본값)

프로젝트 스코프 config는 보안상 사용자가 명시적으로 신뢰(trust)를 부여해야 로드된다.

멀티 프로바이더

Codex CLI는 OpenAI 전용이 아니라, model_providers 섹션을 통해 다양한 LLM 백엔드에 연결된다.

프로바이더	설정 키	비고
OpenAI	기본값	gpt-5-codex, o4-mini 등
Azure OpenAI	base_url + env_key	엔터프라이즈 배포
Ollama	--oss 플래그	로컬 오픈소스 모델
OpenRouter	base_url 커스텀	멀티 모델 라우터
Gemini, Mistral, DeepSeek, xAI, Groq	base_url + env_key	각각 별도 프로바이더 설정

CLI 명령어 체계

명령어	용도
codex	대화형 TUI 실행
codex "prompt"	프롬프트와 함께 TUI 실행
codex exec "prompt"	비대화형 실행 (CI/스크립팅용)
codex resume [session_id]	이전 세션 이어서 작업
codex fork [session_id]	이전 세션 복제하여 분기
codex mcp list/add/remove	MCP 서버 관리
codex completion	셸 자동완성 스크립트 생성
codex features enable/disable	기능 플래그 토글
codex app	데스크톱 앱 실행 (macOS)

Codex CLI의 확장 포인트 — OMX가 활용하는 것

확장 포인트	OMX 활용 방식
AGENTS.md	키워드 매핑, Operating Principles, Delegation Rules 주입
config.toml [mcp_servers]	5개 MCP 서버(state, memory, code-intel, trace, team) 등록
config.toml [agents]	에이전트 메타데이터 및 역할 정의
prompts/ 디렉토리	33개 역할별 에이전트 프롬프트 설치
skills/ 디렉토리	35+ 워크플로우 스킬 설치
codex exec	Team 모드 Worker를 비대화형으로 실행

Claude Code와의 비교

항목	Claude Code	Codex CLI
개발사	Anthropic	OpenAI
언어	TypeScript	Rust 96.2% (codex-rs)
기본 모델	Claude 시리즈	gpt-5-codex
확장 채널	Plugin + Hook(21 이벤트) + MCP + Skill tool	AGENTS.md + config.toml + MCP
보안 모델	자체 Permission 시스템	Approval + Sandbox 2축
Hook 이벤트	21개 (stdin/stdout JSON)	없음 (AGENTS.md로 대체)
Skill 호출	Skill tool (plugin 등록)	$name (파일 직접 읽기)
Agent 호출	Task(subagent_type=...)	/prompts:name
세션 재개	컨텍스트 자동 압축	codex resume 명시 명령

우리 서비스에 적용한다면

OMX는 --user 스코프로 ~/.codex/를 직접 수정하지만, 우리 서비스는 사용자 로컬 환경을 건드리지 않는 방향이 맞다. 서비스의 workingDirectory 안에 모든 설정을 격리한다.

선택: 방법 1 (project-scoped, --project와 동일)

CODEX_HOME으로 완전 격리(방법 2)도 가능하지만, 방법 1이 더 적합하다.

• 사용자의 OPENAI_API_KEY 등 env var를 그대로 상속 — 별도 인증 처리 불필요
• 사용자의 ~/.codex/config.toml에 저장된 모델 선호, 프로바이더 설정도 유지 — 사용자 경험 존중
• 서비스 전용 설정(MCP 서버, 지침 등)만 프로젝트 스코프로 추가하는 구조

워킹 디렉토리 구조

{service-workingDirectory}/
├── AGENTS.md                  ← 서비스 오케스트레이션 지침 (체인 최우선)
├── .codex/
│   └── config.toml            ← 서비스 전용 MCP 서버, 에이전트 설정만 추가
└── .agents/
    └── skills/                ← 서비스 전용 스킬

Codex CLI는 cwd를 기준으로 탐색하므로, workingDirectory를 cwd로 설정하여 실행하면 이 파일들이 자동으로 로드된다.

설정 레이어 최종 그림

~/.codex/config.toml          (사용자 글로벌 — 건드리지 않음)
    + {workdir}/.codex/config.toml  (서비스 전용 — MCP 서버만 추가)
    + CLI 플래그               (런타임 오버라이드)

~/.codex/AGENTS.md            (사용자 글로벌 — 건드리지 않음)
    + {workdir}/AGENTS.md     (서비스 지침 — 최우선 적용)

OPENAI_API_KEY (env var)      (사용자 shell — 방법 무관하게 상속)

사용자가 자신의 API key와 모델 설정을 그대로 쓰면서, 서비스가 주입한 지침과 MCP 서버만 추가로 얹히는 구조다.

참고 문서

• Codex CLI GitHub
• Codex CLI Features
• Codex CLI Reference
• Codex config.toml Reference
• Codex Security
• AGENTS.md Guide