2026.03.16 정식 출시
Codex CLI 서브에이전트, 써봤더니 토큰이 달랐습니다
병렬 실행은 되는데, 토큰 소모가 예상보다 훨씬 많습니다. 공식 문서에 명시된 경고와 실사용자 사례를 같이 놓고 보니 이런 차이가 보였습니다.
서브에이전트가 생긴 이유 — 컨텍스트 오염 문제
Codex CLI 서브에이전트는 2026년 3월 16일, 버전 0.115.0에서 정식 출시됐습니다. 그런데 OpenAI가 이 기능을 만든 이유가 흥미롭습니다. 단순히 “병렬 처리”가 목적이 아니라, 컨텍스트 오염(Context Pollution)과 컨텍스트 부패(Context Rot)라는 구조적 문제를 해결하려는 시도입니다.
💡 공식 발표문과 개발자 문서를 같이 놓고 보니 이런 차이가 보였습니다 — 서브에이전트의 진짜 목적은 속도가 아니라 맥락 보호입니다.
공식 문서에서는 이를 이렇게 정의합니다. “컨텍스트 오염이란 유용한 정보가 중간 출력물(탐색 노트, 테스트 로그, 스택 트레이스 등)에 파묻히는 현상이고, 컨텍스트 부패란 대화가 쌓이면서 모델 성능이 점진적으로 저하되는 현상”이라고 돼 있습니다. (출처: OpenAI Codex Subagents Concepts 문서, 2026.03.16) 대규모 코드베이스에서 하나의 에이전트가 모든 것을 처리하면 이 두 문제가 동시에 발생합니다.
3종 내장 에이전트와 역할 분리
Codex CLI에는 처음부터 세 가지 내장 에이전트가 들어있습니다. 각각 역할이 명확하게 나뉘어 있습니다.
| 에이전트명 | 역할 | 샌드박스 모드 | 추천 사용처 |
|---|---|---|---|
| explorer | 읽기 전용 코드베이스 탐색 | read-only | 코드 구조 파악, PR 분석 |
| worker | 구현·수정 실행 | workspace-write | 실제 코드 수정, 빌드 |
| default | 범용 폴백 | 설정 상속 | 분류하기 애매한 작업 |
핵심은 읽기 작업(explorer)과 쓰기 작업(worker)을 분리하는 데 있습니다. 공식 문서는 “병렬 쓰기 작업은 코드 충돌과 조율 오버헤드를 유발하므로 읽기 전용 병렬화를 먼저 시도하라”고 명시합니다. (출처: OpenAI Codex Subagents Concepts 문서, 2026.03.16) 코드 여러 파일을 동시에 수정하는 병렬화는 생각보다 위험합니다.
기본 설정 수치, 공식 문서에서 직접 확인했습니다
서브에이전트 관련 설정값을 공식 문서에서 그대로 가져왔습니다. 블로그에서 흔히 “무제한 병렬 실행”이라고 소개하는 것과 실제는 다릅니다.
⚠️ max_depth 기본값이 1이라는 것, 대부분 모릅니다
서브에이전트가 또 다른 서브에이전트를 생성하는 재귀 구조는 기본값에서 막혀 있습니다. 자식 에이전트(depth=1)는 손자 에이전트(depth=2)를 직접 생성할 수 없습니다. 이 값을 올리면 토큰 사용량이 기하급수적으로 늘 수 있다고 공식 문서가 별도로 경고하고 있습니다. (출처: OpenAI Codex Subagents 문서, 2026.03.16)
설정은 프로젝트 폴더의 .codex/config.toml 또는 사용자 홈의 ~/.codex/config.toml에서 변경 가능합니다. 기본값을 올리기 전에 비용 계획부터 세우는 게 낫습니다.
토큰 비용, 생각보다 훨씬 많이 나갑니다
🔴 Pro 플랜($200/월) 사용자의 실제 보고
“서브에이전트를 적극 활용했더니 주간 Pro 한도를 이틀 만에 소진했고, 당주에만 $350 초과 과금이 발생했다.” — GitHub Issues #12488 (2026.02.21)
이게 단순 과소비가 아닙니다. 공식 문서가 직접 이렇게 씁니다: “서브에이전트 워크플로는 각 에이전트가 자체적으로 모델·툴 작업을 수행하기 때문에 단일 에이전트 대비 토큰을 더 많이 소모합니다.” (출처: OpenAI Codex Subagents 문서, 2026.03.16) 6개 에이전트가 동시에 돌면 최대 6배의 토큰이 소모된다는 이야기입니다.
💡 실제로 계산해보면 이렇습니다
PR 리뷰를 예로 들면, 단일 에이전트로 처리할 때 토큰이 T라면 6개 서브에이전트를 병렬로 돌릴 경우 이론적으로 최대 6×T가 됩니다. gpt-5.4를 메인·검토 에이전트로, gpt-5.4-mini를 탐색 에이전트로 쓰면 비용을 줄일 수 있지만, 제로에 가깝게 만들 수는 없습니다. 더 빠른 대신 더 비싸다는 트레이드오프입니다.
현재 Codex 앱과 CLI에서는 서브에이전트별 비용 내역이 따로 표시되지 않습니다. GitHub Issues에서 여러 사용자가 에이전트별 비용 분류 기능을 요청한 상태지만, 2026년 3월 29일 기준 OpenAI가 공식 답변을 내놓지 않은 부분입니다.
CSV 배치 처리 — 실무에서 가장 실용적인 패턴
서브에이전트 기능 중 가장 실용적이고, 다른 블로그에서 잘 다루지 않는 기능이 spawn_agents_on_csv입니다. CSV 파일의 각 행을 작업 단위로 삼아, 행마다 서브에이전트 1개를 자동으로 생성하고 결과를 다시 CSV로 받아오는 구조입니다.
예를 들어 프론트엔드 컴포넌트 50개를 동시에 리뷰해야 한다면 이런 프롬프트를 씁니다:
/tmp/components.csv를 만들고 path, owner 컬럼에 컴포넌트 목록을 채워.
그런 다음 spawn_agents_on_csv를 이렇게 호출해:
- csv_path: /tmp/components.csv
- instruction: "{path}를 {owner} 관점에서 검토해. JSON으로 path, risk, summary를 report_agent_job_result로 반환해."
- output_csv_path: /tmp/components-review.csv
💡 이 패턴의 핵심은 결과물 형태가 통제된다는 점입니다. output_schema를 지정하면 모든 서브에이전트가 같은 JSON 구조로 응답을 반환하고, 내보내는 CSV에는 job_id·status·result_json이 자동으로 추가됩니다. 50개를 하나씩 돌리는 것보다 빠르고, 결과 집계도 자동으로 됩니다.
단, 각 워커 서브에이전트는 반드시 report_agent_job_result를 정확히 한 번만 호출해야 합니다. 호출 없이 종료되면 해당 행은 오류로 처리됩니다. (출처: OpenAI Codex Subagents 문서, 2026.03.16) 프롬프트에 이 조건을 명시하지 않으면 조용히 실패합니다.
커스텀 에이전트 파일 직접 작성하는 법
내장 에이전트 세 가지만으로 부족하다면, TOML 파일로 커스텀 에이전트를 직접 만들 수 있습니다. 경로는 두 가지입니다.
- ~/.codex/agents/ — 사용자 전체 적용 (개인용)
- .codex/agents/ — 프로젝트 단위 적용 (팀 공유용)
파일마다 name, description, developer_instructions 세 가지 필드가 필수입니다. 나머지(model, sandbox_mode, mcp_servers 등)는 생략하면 부모 세션에서 상속됩니다. 아래는 공식 문서에서 가져온 최소 구성 예시입니다. (출처: OpenAI Codex Subagents 문서, 2026.03.16)
name = "reviewer" description = "PR 리뷰어: 정확성·보안·테스트 누락 중심" model = "gpt-5.4" model_reasoning_effort = "high" sandbox_mode = "read-only" developer_instructions = """ 코드를 오너 관점에서 리뷰할 것. 정확성·보안·동작 회귀·테스트 누락에 집중하고 구체적 재현 단계를 포함할 것. 스타일 지적은 실제 버그 가능성이 있을 때만 할 것. """ nickname_candidates = ["Atlas", "Delta", "Echo"]
nickname_candidates는 같은 에이전트 여러 개가 동시에 뜰 때 UI에서 구분하기 쉽도록 표시 이름을 지정하는 기능입니다. 실제 식별은 name 필드로만 합니다. 파일 이름을 reviewer.toml처럼 맞추는 게 일관성 유지에 유리합니다.
Claude Code 서브에이전트와 뭐가 다를까
같은 시기에 서브에이전트 기능을 갖춘 Claude Code와 비교해보면 설계 철학 차이가 보입니다. 두 도구 모두 병렬 실행을 지원하지만, 방향이 조금 다릅니다.
| 항목 | Codex CLI 서브에이전트 | Claude Code 서브에이전트 |
|---|---|---|
| 기본 동시 실행 | 6개 (max_threads) | 별도 worktree 격리 방식 |
| 재귀 깊이 기본값 | 1 (손자 에이전트 불가) | P2P 협력 모델 지원 |
| 배치 처리 | CSV 파일 기반 자동화 | 별도 지원 없음(수동 구성) |
| 비용 투명성 | 에이전트별 분류 없음 | 토큰 사용량 개별 추적 |
| IDE 서브에이전트 가시성 | 곧 지원 예정(2026.03 기준) | 지원 중 |
Codex가 우위인 지점은 클라우드 인프라 통합과 CSV 배치 처리입니다. Claude Code는 worktree 격리와 피어-투-피어 에이전트 협력 면에서 앞서 있습니다. (출처: Medium, R. Hightower, 2026.03.21) 어느 쪽이 낫다기보다 작업 성격에 따라 선택이 달라집니다. 코드베이스 전체를 체계적으로 스캔하는 배치 작업은 Codex가, 여러 에이전트가 실시간으로 서로 결과를 주고받아야 하는 협업형 작업은 Claude Code가 더 자연스럽습니다.
Q&A
마치며 — 써볼 만하지만, 비용 감각을 먼저 잡아야 합니다
Codex CLI 서브에이전트는 컨텍스트 오염 문제를 구조적으로 해결하는 잘 설계된 기능입니다. 특히 CSV 배치 처리 패턴은 대규모 코드베이스 감사나 반복 검토 작업에서 실질적인 시간 절감이 됩니다. 병렬 실행이라는 개념 자체는 Claude Code에서 먼저 자리잡은 패턴이지만, Codex의 배치 자동화와 클라우드 통합은 나름의 강점입니다.
막상 써보니 가장 신경 써야 할 부분은 성능보다 비용입니다. max_threads 기본값 6에 gpt-5.4를 그대로 쓰면 토큰이 배수로 나갑니다. 탐색·스캔 작업은 gpt-5.4-mini로, 판단·수정이 필요한 에이전트에만 gpt-5.4를 쓰는 식으로 모델을 역할별로 나누는 게 현실적입니다. 0.117.0에서 플러그인과 멀티에이전트 v2가 더 정비됐으니 앞으로 비용 투명성도 개선될 가능성은 있지만, 지금 당장 비용 내역을 에이전트별로 볼 수는 없습니다.
핵심 요약
- 서브에이전트는 명시적으로 요청해야만 생성됩니다 — 자동 발동 없음
- max_depth 기본값 1 — 손자 에이전트는 기본 차단됩니다
- 토큰 소모는 에이전트 수에 비례해 증가 — Pro 플랜도 이틀 만에 초과 사례 있음
- CSV 배치 처리가 가장 실용적인 패턴입니다
- IDE 확장에서 서브에이전트 가시성은 아직 지원 전
본 포스팅 참고 자료
- OpenAI Codex Subagents 공식 문서 — developers.openai.com
- OpenAI Codex Subagent Concepts — 컨텍스트 오염·부패 개념 — developers.openai.com
- OpenAI Codex 공식 changelog (0.115.0~0.117.0) — developers.openai.com
- GitHub Issues #12488 — Sub-agent costs are too high and too opaque — github.com/openai/codex
- Codex Gets Subagents — Medium (R. Hightower, 2026.03.21)
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Codex CLI는 활발하게 업데이트 중인 오픈소스 도구이므로 최신 정보는 공식 changelog 및 GitHub를 직접 확인하시기 바랍니다.
댓글 남기기