Codex CLI 최신 버전
Codex CLI 서브에이전트, 기본 켜져 있는데 왜 안 뜰까요?
2026년 3월 16일, OpenAI가 Codex CLI 서브에이전트를 정식 출시했습니다. 그런데 업데이트한 뒤에도 “서브에이전트가 자동으로 뜨지 않는다”는 혼란이 반복됩니다. 이유가 있습니다. 공식 문서에 딱 이렇게 나옵니다 — “Codex only spawns subagents when you explicitly ask it to.” 기본 활성화가 맞지만, 명시적 요청 없이는 작동하지 않습니다. 이 글에서 그 구조와 설정, 그리고 대부분의 블로그가 빠뜨린 비용 함정까지 정리합니다.
서브에이전트가 “기본 켜짐”이지만 자동으로 뜨지 않는 이유
Codex CLI를 최신 버전으로 업데이트하면 서브에이전트가 활성화됩니다. 그런데 아무 작업을 시켜도 서브에이전트가 등장하지 않습니다. 이게 버그라고 생각하는 경우가 많은데, 사실은 공식 설계입니다.
공식 문서(developers.openai.com/codex/subagents)에는 이렇게 나옵니다. “Codex only spawns subagents when you explicitly ask it to.” — 서브에이전트는 명시적으로 요청했을 때만 생성됩니다. “기본 켜짐”은 기능 플래그 해제를 의미하는 것이고, 자동 실행을 의미하는 게 아닙니다. 두 가지를 혼동하면 계속 기다리다 끝납니다.
이게 왜 이렇게 설계됐을까요. 서브에이전트 하나가 실행될 때마다 독립적인 모델 호출과 툴 호출이 발생합니다. 비용이 배수로 늘어납니다. OpenAI가 자동 실행을 막은 이유는 사용자가 의도하지 않은 순간에 토큰이 폭발적으로 소모되는 것을 방지하기 위해서입니다. 오히려 합리적인 결정입니다.
💡 공식 발표문과 실제 동작 흐름을 같이 놓고 보니 이런 차이가 보였습니다 — “기본 활성화”와 “자동 실행”은 다른 개념입니다. 활성화는 잠금 해제를, 자동 실행은 의도 감지를 의미합니다. Codex는 후자를 의도적으로 하지 않습니다.
내장 에이전트 3종, 역할이 이렇게 나뉩니다
Codex CLI에는 처음부터 세 가지 내장 에이전트가 들어 있습니다. 이름만 보면 차이가 애매한데, 실제로 목적이 뚜렷하게 다릅니다.
| 에이전트 이름 | 주요 역할 | 적합한 작업 |
|---|---|---|
| default | 범용 폴백 에이전트 | 특정 에이전트를 지정하지 않을 때 자동 배정 |
| worker | 실행 중심 구현·수정 에이전트 | CSV 배치 작업, 반복 구현 태스크 병렬 처리 |
| explorer | 읽기 전용 코드베이스 탐색 에이전트 | 파일 구조 파악, PR 변경 범위 분석, 의존성 추적 |
실전에서 worker와 default의 차이가 제일 헷갈립니다. 공식 문서에서 직접 확인한 차이는 이렇습니다. worker는 spawn_agents_on_csv 작업처럼 “동일한 작업을 여러 행에 병렬로 실행하는” 상황에 특화돼 있습니다. default는 단일 태스크에 대한 범용 처리를 담당합니다. CSV 배치를 돌릴 게 아니면 worker를 명시적으로 부를 필요가 별로 없습니다.
explorer는 sandbox_mode가 read-only로 설정돼 있습니다. 파일을 읽고 분석만 하고 절대 수정하지 않습니다. 코드 탐색이 필요한 상황에 먼저 explorer를 투입하고, 그 결과를 바탕으로 다른 에이전트가 수정 작업을 하는 패턴이 가장 안전합니다.
서브에이전트를 실제로 쓰는 방법 — 프롬프트 패턴
서브에이전트는 명시적으로 요청해야 한다고 했으니, 어떻게 요청하는지가 핵심입니다. 공식 문서에 나온 예시 프롬프트가 구조를 이해하는 데 가장 빠릅니다.
📄 공식 예시 프롬프트 (출처: developers.openai.com/codex/subagents)
이 PR(현재 브랜치 vs main)에서 아래 항목을 검토해 줘.
항목마다 에이전트 하나씩 생성하고,
결과를 기다린 뒤 각 항목별 요약을 정리해 줘.
1. 보안 이슈
2. 코드 품질
3. 버그
4. 경쟁 조건(Race Condition)
5. 테스트 불안정성
6. 코드 유지보수성
이 프롬프트의 구조를 보면 세 가지가 명확합니다. “항목마다 에이전트 하나씩 생성”이라는 명시적 지시, “결과를 기다린 뒤”라는 동기화 지시, 그리고 “항목별 요약 정리”라는 취합 지시입니다. 이 세 요소를 다 넣어야 서브에이전트가 의도대로 움직입니다.
CLI에서 활성 에이전트 스레드를 확인하고 싶을 때는 /agent 명령어를 씁니다. 현재 열린 스레드 목록이 나오고, 원하는 스레드로 전환해서 진행 상태를 볼 수 있습니다. 비활성 스레드에서 승인 요청이 올라오면 화면 상단에 오버레이가 뜨고 o 키를 눌러 해당 스레드로 이동할 수 있습니다.
💡 실제 동작 흐름을 따라가 보면 Codex가 에이전트 완료를 기다리는 방식이 보입니다 — 모든 서브에이전트가 결과를 반환할 때까지 취합 응답이 나오지 않습니다. 하나라도 타임아웃이 나면 그 항목은 에러 상태로 취합됩니다.
토큰이 4배 더 나가는 구조 — 모르면 청구서에서 놀랍니다
서브에이전트를 처음 써보고 청구 내역을 보면 당황하는 경우가 생깁니다. 이 부분은 공식 문서가 명확하게 경고하고 있습니다. “Because each subagent does its own model and tool work, subagent workflows consume more tokens than comparable single-agent runs.”
실측 데이터가 있습니다. MorphLLM의 Figma-to-code 벤치마크에서 같은 작업을 시켰을 때 Claude Code는 약 620만 토큰을 소모했고, Codex CLI는 약 150만 토큰을 썼습니다. 4배 차이입니다. (출처: morphllm.com/comparisons/codex-vs-claude-code) 그런데 여기서 중요한 게 있습니다. 이 수치는 서브에이전트 없이 단일 에이전트로 실행한 결과입니다. 서브에이전트를 6개 스레드로 병렬 실행하면 토큰 소모량이 비례해서 늘어납니다.
토큰 폭탄 방지를 위한 설정 2가지
① agents.max_threads — 동시 실행 스레드 수를 제한합니다. 기본값이 6입니다. 비용이 걱정되면 2~3으로 내리세요.
② agents.max_depth — 에이전트가 에이전트를 낳는 중첩 깊이를 제한합니다. 기본값이 1입니다. 이 값을 올리면 팬아웃이 기하급수적으로 커질 수 있습니다. 기본값 유지를 권장합니다.
이 설정은 .codex/config.toml이나 홈 디렉토리의 ~/.codex/config.toml에서 바꿀 수 있습니다. max_depth를 1에서 2로만 올려도 의도치 않은 에이전트 트리가 형성될 수 있으니 조심이 필요합니다. 공식 문서에서도 “기본값을 유지하라”고 명시하고 있습니다.
커스텀 에이전트 만드는 법 — TOML 파일 한 장이면 됩니다
내장 에이전트 3종으로 부족하다면 직접 커스텀 에이전트를 만들 수 있습니다. 개인 전용은 ~/.codex/agents/ 에, 프로젝트 공유용은 .codex/agents/ 에 TOML 파일을 넣으면 됩니다. 파일 하나당 에이전트 하나입니다.
필수 필드는 세 가지입니다. name(에이전트 이름), description(언제 이 에이전트를 써야 하는지 설명), developer_instructions(에이전트가 어떻게 행동할지 지시)입니다. 나머지(model, sandbox_mode, mcp_servers 등)는 생략하면 부모 세션 설정을 상속합니다.
공식 문서에서 직접 가져온 PR 리뷰 에이전트 예시입니다.
.codex/agents/reviewer.toml
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible,
and avoid style-only comments unless they hide a real bug.
"""
여기서 주목할 부분이 있습니다. model_reasoning_effort를 “high”로 설정했습니다. 이 에이전트는 보안 검토를 담당하기 때문입니다. 반면 코드 탐색만 하는 explorer 역할의 에이전트는 “medium”으로 낮춰도 됩니다. 이 세분화가 토큰 절약의 핵심입니다.
커스텀 에이전트를 호출할 때는 프롬프트에 에이전트 이름을 직접 언급하면 됩니다. “reviewer가 이 파일의 보안 이슈를 점검해 줘”처럼 쓰면 Codex가 해당 에이전트를 불러옵니다. 파일명이 아니라 TOML 안의 name 필드 값이 기준입니다.
Claude Code 서브에이전트와 다른 점 — 같은 듯 다릅니다
Simon Willison이 3월 16일 정식 출시 당일 남긴 메모(simonwillison.net/2026/Mar/16/codex-subagents)에 이런 말이 있습니다. “They’re very similar to the Claude Code implementation.” 맞습니다. explorer, worker, default — 이름부터 거의 같습니다. 그런데 내부 구조가 다릅니다.
| 항목 | Codex CLI 서브에이전트 | Claude Code 서브에이전트 |
|---|---|---|
| 샌드박스 방식 | OS 커널 레벨 (Seatbelt/Landlock/seccomp) | 애플리케이션 레이어 훅 (17개 이벤트) |
| 설정 파일 형식 | TOML + AGENTS.md (크로스 툴 호환) | JSON + CLAUDE.md (Anthropic 전용) |
| 동시 실행 한도 | 기본 6개 스레드 | 별도 한도 없음 (리소스 제한 적용) |
| 기본 모델 | GPT-5.4 (1M 컨텍스트) | Claude Opus 4.6 (200K 컨텍스트) |
샌드박스 차이가 실제로 중요한 상황은 외부 코드나 외부 PR을 검토할 때입니다. Codex CLI는 OS 커널이 파일 시스템 접근 자체를 차단하기 때문에 모델이 어떤 프롬프트 인젝션을 받더라도 파일을 수정할 수 없습니다. Claude Code의 훅은 코드로 작성된 로직이기 때문에 이론적으로는 우회 경로가 존재합니다. (출처: NxCode 비교 분석, nxcode.io/resources/news/claude-code-vs-codex-cli-terminal-coding-comparison-2026)
반면 AGENTS.md 형식은 이미 Cursor, GitHub Copilot, Amp, Windsurf, Gemini CLI도 읽을 수 있는 오픈 표준입니다. 여러 AI 툴을 함께 쓰는 팀 환경에서 Codex CLI 서브에이전트 설정이 다른 툴에서도 자동으로 인식됩니다.
Q&A — 자주 막히는 지점 5가지
마치며 — 쓸 준비가 됐는지 두 가지만 확인하세요
Codex CLI 서브에이전트는 기술적으로 완성도가 높습니다. 공식 문서도 구체적이고, 커스텀 에이전트 스키마도 충분히 유연합니다. 써보니까 진입 장벽이 의외로 낮습니다. TOML 파일 하나 만들고, 프롬프트에 에이전트 이름 넣으면 됩니다.
다만 두 가지는 쓰기 전에 반드시 확인해야 합니다. 첫째, 토큰 소모 설정입니다. max_threads와 max_depth를 모르고 쓰면 청구서에서 놀라게 됩니다. 둘째, IDE 확장의 한계입니다. 지금은 CLI와 앱에서만 서브에이전트 상태가 보입니다. IDE에서만 일하는 환경이라면 모니터링이 안 됩니다.
이 기능이 정말 빛을 발하는 건 PR 리뷰, 대규모 감사 작업, 배치 스크립트 생성처럼 독립적으로 처리 가능한 태스크가 여러 개 쌓였을 때입니다. 그 상황이 아니라면 단일 에이전트로도 충분합니다. 기능이 있다고 다 써야 하는 건 아닙니다.
📚 본 포스팅 참고 자료
- OpenAI 공식 서브에이전트 문서 — developers.openai.com/codex/subagents
- Simon Willison 링크 블로그 (2026.03.16) — simonwillison.net/2026/Mar/16/codex-subagents
- NxCode — Claude Code vs Codex CLI 비교 (2026.03) — nxcode.io 원문
- Blake Crosley — Codex vs Claude Code 아키텍처 비교 — blakecrosley.com 원문
- MorphLLM — Figma-to-code 토큰 효율 벤치마크 — morphllm.com 원문
본 포스팅은 2026년 3월 31일 기준으로 작성됐습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 특히 Codex CLI는 오픈소스 프로젝트로 업데이트 주기가 빠르므로, 최신 정보는 공식 문서에서 직접 확인하시기 바랍니다.
댓글 남기기