Codex CLI 서브에이전트, 빠를수록 돈이 더 나갑니다
OpenAI가 2026년 3월 16일 Codex CLI에 서브에이전트 기능을 정식 출시했습니다. 병렬로 여러 에이전트를 돌리면 빠르다는 건 맞습니다. 그런데 공식 문서에는 이렇게 나옵니다. “각 서브에이전트가 독립적인 모델·툴 작업을 수행하기 때문에, 단일 에이전트 실행보다 토큰을 더 많이 소비합니다.” 빠른 만큼 청구서도 빠르게 불어납니다.
동시 오픈 스레드 6개
중첩 깊이 1단계만 허용
gpt-5.4 (코디네이터)
서브에이전트가 뭔지 먼저 짚고 갑니다
Codex CLI 서브에이전트는 하나의 복잡한 작업을 여러 전문 에이전트에게 동시에 분배해 처리하는 기능입니다. “PR 보안 검토는 A 에이전트, 코드 품질은 B 에이전트, 테스트 누락은 C 에이전트”처럼 각자 독립 컨텍스트 창을 가지고 병렬로 일합니다. 2026년 3월 16일 기능이 정식 출시됐고, 0.117.0 버전(2026.03.26)에서 서브에이전트끼리 경로 기반 주소(/root/agent_a)로 메시지를 주고받는 구조로 개편됐습니다. (출처: OpenAI Codex Changelog, 2026.03.26)
Codex에는 내장 에이전트가 세 가지 있습니다. default(범용 폴백), worker(구현·수정 집중), explorer(코드베이스 탐색 집중). 이것만으로 충분한 경우가 많고, 커스텀 에이전트는 TOML 파일을 직접 만들어 정의할 수 있습니다.
서브에이전트는 내가 명시적으로 요청할 때만 생성됩니다. 공식 문서에 “Codex only spawns subagents when you explicitly ask it to”라고 딱 나와 있습니다. (출처: OpenAI Codex Subagents 공식 문서) 알아서 분기하지 않습니다.
context rot — 문제를 풀기 위해 문제를 만드는 구조
서브에이전트를 쓰는 핵심 이유는 context pollution과 context rot을 막기 위해서입니다. 대화가 쌓일수록 모델 성능이 떨어지는 현상, 흔히 “세션이 길어지면 에이전트가 멍청해진다”고 느끼는 바로 그겁니다. 탐색 로그, 스택 트레이스, 명령 출력이 메인 컨텍스트를 채우면 정작 중요한 결정 정보가 묻힙니다. 이게 context pollution이고, 이로 인해 답변 품질이 저하되는 게 context rot입니다. (출처: OpenAI Codex Subagents Concepts)
💡 공식 발표문과 실제 사용 흐름을 같이 놓고 보니 이런 차이가 보였습니다.
서브에이전트는 context rot 해결책으로 소개되지만, 각 서브에이전트 자체도 독립 컨텍스트를 채워가며 작동합니다. 즉, 메인 스레드의 오염은 줄지만, 전체 시스템이 소비하는 토큰 총량은 늘어납니다. 이 역설이 실제 비용 계획에서 자주 빠집니다.
서브에이전트는 노이즈 작업을 메인 스레드에서 분리해 이 문제를 해결합니다. 탐색·테스트·로그 분석 같은 읽기 집중 작업은 서브에이전트에 맡기고, 메인 에이전트는 요구사항·결정·최종 출력에만 집중하는 구조입니다. 서브에이전트는 날것의 중간 출력이 아닌 요약만 메인으로 돌려보냅니다.
빠른데 왜 비용이 늘어나는지 수치로 봤습니다
서브에이전트 PR 리뷰 한 번(보안·코드품질·버그·레이스컨디션·테스트·유지보수 6개 포인트)을 돌리면 에이전트 6개가 동시에 모델·툴 작업을 합니다. 메시지 하나로 단일 에이전트가 같은 리뷰를 하는 것보다 토큰 소비가 당연히 큽니다. GitHub 이슈 #12488(2026.02.21)에는 이에 관한 공개 질의가 올라왔고, OpenAI 측은 “서브에이전트 토큰 사용량은 메인 에이전트와 동일하게 과금된다”고 답했습니다. (출처: GitHub openai/codex #12488) 별도 요금이 아닌, 그냥 쓴 만큼 다 나옵니다.
| 작업 유형 | Codex 단일 에이전트 토큰 | Codex 멀티 에이전트 비율 |
|---|---|---|
| PR 리뷰 (6포인트) | 기준값 1x | 약 4~6x 증가 (추정) |
| Figma 플러그인 빌드 | 1,499,455 토큰 | Claude 대비 1/4 수준 |
| 스케줄러 앱 빌드 | 72,579 토큰 | Claude 대비 1/3 수준 |
출처: morphllm.com/comparisons/codex-vs-claude-code, 2026.02 기준 벤치마크 / PR 리뷰 멀티에이전트 배율은 에이전트 수 기반 추정치
💡 기존 비교 글 대부분이 “Codex vs Claude 토큰 효율”로 비교하는데, 서브에이전트 온오프 전후의 Codex 내부 비용 차이는 잘 다루지 않습니다. Medium 분석(2026.03.21)에서 직접 밝혔습니다. “A three-agent PR review costs more than a single-agent PR review. The value proposition is speed and specialization, not cost reduction.” 속도와 전문화가 목적이지, 비용 절감이 아닙니다.
ChatGPT Plus($20/월) 기준 5시간 윈도우당 30~150개 메시지 한도인데, 서브에이전트 워크플로는 이 한도를 훨씬 빠르게 소모합니다. 한 번에 6개 에이전트를 돌리면 메시지 계산 방식에 따라 6배 빠르게 한도에 닿을 수 있습니다.
max_depth 기본값 1, 그냥 놔두면 안 되는 이유
공식 문서에 이렇게 나옵니다. “agents.max_depth defaults to 1, which allows a direct child agent to spawn but prevents deeper nesting.” (출처: OpenAI Codex Subagents 공식 문서) 서브에이전트가 또 다른 서브에이전트를 낳는 재귀 구조를 기본적으로 막아둔 겁니다. 루트 세션에서 1단계 자식 에이전트까지만 허용합니다.
💡 max_depth를 높이면 “더 똑똑하게” 분기할 것 같지만, 공식 문서는 반대로 경고합니다.
“Raising this value can turn broad delegation instructions into repeated fan-out, which increases token usage, latency, and local resource consumption.”
넓게 위임하는 프롬프트가 반복 팬아웃으로 바뀌어 오히려 통제 불가 상태가 됩니다.
max_depth를 올리면 “에이전트가 에이전트를 낳고 그 에이전트가 또 에이전트를 낳는” 상황이 됩니다. 이걸 제어하는 게 max_threads(기본값 6)이지만, 스레드 수를 막는다고 깊이로 인한 비용 폭증을 완전히 막지는 못합니다. 공식 문서 원문이 “특별히 재귀 위임이 필요할 때만 올려라”고 명시한 이유가 여기에 있습니다.
실제로 max_depth를 올려서 쓸 만한 케이스는 문서 조사 에이전트가 세부 검색 에이전트를 직접 호출해야 할 때 정도입니다. 그 외에는 기본값 1을 유지하는 게 비용·예측 가능성 모두에서 유리합니다.
CSV fan-out 쓸 때 조심해야 할 것
spawn_agents_on_csv는 CSV 한 행당 워커 서브에이전트 하나를 생성해 대규모 반복 작업을 자동화하는 기능입니다. 파일 100개를 각각 리뷰한다면 에이전트 100개를 띄워 한꺼번에 처리하는 구조입니다. 그러나 공식 문서에는 한 가지 조건이 명시돼 있습니다. “Each worker must call report_agent_job_result exactly once. If a worker exits without reporting a result, Codex marks that row with an error in the exported CSV.” (출처: OpenAI Codex Subagents 공식 문서)
⚠️ 실전에서 놓치기 쉬운 함정
워커 하나가 결과 보고 없이 종료되면 해당 행은 오류로 처리됩니다. 그런데 morphllm.com 비교 분석(2026.02)에서 Codex의 CSV fan-out 실패 패턴으로 직접 언급된 내용이 있습니다. “No mid-batch error recovery, one failure can stall the pipeline.” 배치 중간 오류 복구가 없어서 한 행 실패가 파이프라인 전체를 멈출 수 있습니다. 50개 파일 중 3개 행 오류가 나면 47개 결과만 받고 나머지는 수동으로 재처리해야 합니다.
이 문제를 줄이려면 워커 프롬프트에 report_agent_job_result 호출을 명시적으로 포함시키고, 오류 발생 시에도 에러 메시지를 담아 반드시 한 번 호출하도록 지시해야 합니다. 결과 보고를 조건부로 두지 말고 무조건 마지막에 실행되도록 설계해야 안전합니다.
커스텀 에이전트 설정, 실제로 써보니 이게 핵심이었습니다
커스텀 에이전트는 ~/.codex/agents/(개인) 또는 .codex/agents/(프로젝트)에 TOML 파일로 정의합니다. name, description, developer_instructions 세 가지가 필수입니다. 모델은 생략하면 Codex가 작업에 맞게 자동 선택하지만, 비용을 통제하려면 직접 지정하는 게 낫습니다.
# .codex/agents/pr-explorer.toml 예시 (공식 문서 기반)
name = “pr_explorer”
description = “Read-only codebase explorer…”
model = “gpt-5.4-mini”
model_reasoning_effort = “medium”
sandbox_mode = “read-only”
모델 선택에 원칙이 있습니다. 공식 문서 기준(Codex CLI v0.117.0): 탐색·읽기 집중 서브에이전트는 gpt-5.4-mini, 코디네이터·복잡 추론은 gpt-5.4, ChatGPT Pro가 있다면 텍스트 전용 고속 작업에 gpt-5.3-codex-spark(리서치 프리뷰)를 쓸 수 있습니다. gpt-5.4-mini를 워커 에이전트로 쓰면 gpt-5.4 대비 속도가 빠르고 토큰당 비용이 낮아 멀티 에이전트 비용을 의미 있게 줄일 수 있습니다.
sandbox_mode를 에이전트별로 다르게 설정할 수 있다는 점도 놓치기 쉽습니다. 탐색 에이전트는 read-only, 수정 에이전트는 workspace-write로 분리하면 의도치 않은 파일 수정 위험을 줄이면서 병렬 작업이 가능합니다. 이 분리가 실제로 제일 유용했습니다.
Q&A
마치며
Codex CLI 서브에이전트 기능은 분명 실용적입니다. PR 리뷰 6포인트를 동시에 돌리거나, 프론트엔드 컴포넌트 50개를 병렬로 감사하는 작업은 단일 에이전트로는 현실적으로 힘들었습니다. 기능 자체는 잘 만들어졌습니다.
그런데 써보면서 가장 많이 느낀 건, 서브에이전트가 “더 싸게” 일하는 방법이 아니라는 점입니다. 속도를 사는 대신 토큰을 씁니다. max_depth를 올리면 어떤 일이 생길지, CSV fan-out에서 워커 하나가 결과 보고를 안 하면 어떻게 되는지, 이 부분은 공식 문서에 나와 있어도 실제로 써보기 전까지 실감하기 어렵습니다.
결론부터 말하면, 탐색·분석처럼 읽기 집중 작업에 gpt-5.4-mini 워커 + max_depth 기본값 유지 조합으로 시작하는 게 무난합니다. 비용과 예측 가능성 모두 여기서 잡힙니다.
📎 본 포스팅 참고 자료
- OpenAI Codex Subagents 공식 문서
- OpenAI Codex Changelog (v0.117.0, 2026.03.26)
- GitHub openai/codex #12488 — Sub-agent costs are too high and too opaque (2026.02.21)
- morphllm.com — Codex vs Claude Code 벤치마크 비교 (2026.02 기준)
- Medium — Codex Gets Subagents: The Parallel AI Coding Pattern (2026.03.21)
- OpenAI Codex Subagents Concepts (context pollution · context rot)
본 포스팅은 2026년 3월 30일 Codex CLI v0.117.0 기준으로 작성됐습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 공식 문서(developers.openai.com/codex)에서 최신 내용을 확인하세요.
댓글 남기기