Codex CLI v0.107+ 기준
gpt-5.4 / gpt-5.4-mini 기준
Codex CLI 서브에이전트, 실제로 따져봤습니다 — 토큰 6배 폭발의 진실
2026년 3월 16일 OpenAI가 Codex CLI 서브에이전트(Subagents)를 정식 출시했습니다. “병렬로 돌리면 빠르고 효율적”이라는 게 첫 인상이었는데, 공식 문서를 직접 뜯어보니 생각과 꽤 달랐습니다. 토큰 소비 구조, 기본값의 함정, Plus 플랜에서 주 할당량을 하루 만에 소진하는 실제 사례까지 정리했습니다.
서브에이전트가 정확히 무엇인지, 정의부터 짚고 갑니다
Codex CLI 서브에이전트는 하나의 메인 에이전트가 특정 작업을 위해 전문화된 에이전트를 병렬로 실행하고 결과를 모아 응답하는 워크플로우입니다. 예를 들어 PR 리뷰를 시킬 때 보안, 코드 품질, 버그, 테스트 안정성을 각각 다른 에이전트에게 동시에 맡기고 요약을 받을 수 있습니다. OpenAI가 공식 문서에서 직접 설명한 구조입니다.
기본 내장 에이전트는 세 종류입니다. default(범용 폴백), worker(실행·수정 중심), explorer(읽기 전용 코드베이스 탐색)입니다. 여기에 TOML 파일로 커스텀 에이전트를 추가할 수 있고, 각 에이전트마다 모델과 reasoning effort를 별도로 지정할 수 있습니다. (출처: OpenAI Codex 공식 문서 — Subagents, developers.openai.com/codex/subagents)
중요한 포인트가 하나 있습니다. Codex는 서브에이전트를 자동으로 실행하지 않습니다. 프롬프트에서 명시적으로 “spawn two agents” 또는 “병렬로 처리해” 같은 지시가 있을 때만 작동합니다. 이 점은 이후 Plus 플랜 토큰 폭발 문제와 직결되는 부분입니다.
💡 공식 문서와 커뮤니티 사례를 같이 놓고 보니, 서브에이전트가 “자동으로 알아서 잘 쓴다”는 인식이 얼마나 위험한지 보였습니다.
빠르다는 말이 맞긴 한데 — 토큰이 그만큼 더 나갑니다
서브에이전트를 쓰면 분명 시간이 단축됩니다. 6개 에이전트가 동시에 돌면 순차 처리보다 빠를 수 있습니다. 그런데 OpenAI 공식 문서에는 이런 문장이 그대로 적혀 있습니다. “각 서브에이전트가 자체 모델 및 툴 작업을 수행하므로, 서브에이전트 워크플로우는 단일 에이전트 실행보다 더 많은 토큰을 소비합니다.” (출처: OpenAI Codex 공식 문서 — Subagents, developers.openai.com/codex/subagents)
얼마나 더 나가는지 실측 수치가 있습니다. morphllm.com의 Codex vs Claude Code 비교 데이터(2026.02.28 기준)에 따르면, 동일 작업에서 Figma 플러그인 빌드 시 단일 에이전트가 약 150만 토큰을 쓸 때 서브에이전트 병렬 구성을 쓰면 최대 620만 토큰 이상으로 올라갑니다. 서브에이전트 수 × 각자의 컨텍스트 소비가 그대로 합산되는 구조이기 때문입니다. 이것은 속도와 비용을 동시에 사는 게 아니라, 속도를 위해 토큰을 더 사는 트레이드오프입니다. (출처: morphllm.com/comparisons/codex-vs-claude-code)
💡 “서브에이전트 6개를 병렬로 돌리면 토큰도 최대 6배가 될 수 있다”는 단순 계산이 실제로 맞습니다. 병렬 실행은 latency를 줄이지만 total token consumption은 늘립니다.
| 작업 유형 | 단일 에이전트 | 서브에이전트 병렬 | 배율 |
|---|---|---|---|
| Figma 플러그인 빌드 | 약 150만 토큰 | 약 620만 토큰 | 4.2× |
| 스케줄러 앱 | 약 7만 3천 토큰 | 약 23만 5천 토큰 | 3.2× |
| API 통합 작업 | 약 18만 토큰 | 약 65만 토큰 | 3.6× |
출처: morphllm.com/comparisons/codex-vs-claude-code (2026.02.28 기준), 서브에이전트 병렬 구성 시 측정값
기본값만 믿으면 생기는 일 — max_depth=1의 의미
Codex CLI 서브에이전트의 전역 설정에는 두 가지 핵심 기본값이 있습니다. agents.max_threads는 기본 6, agents.max_depth는 기본 1입니다. (출처: OpenAI Codex 공식 문서 — Subagents, developers.openai.com/codex/subagents)
max_threads=6은 동시에 열린 에이전트 스레드 수 상한입니다. max_depth=1은 자식 에이전트(서브에이전트)가 또 다른 서브에이전트를 부를 수 있는 재귀 깊이입니다. 기본값 1이면 메인 에이전트 → 서브에이전트까지는 되지만, 서브에이전트가 다시 서브에이전트를 부르는 건 막힙니다. 공식 문서는 “특별히 재귀 위임이 필요한 경우가 아니면 기본값을 유지하라”고 못 박고 있습니다.
왜 이걸 강조할까요? max_depth를 2 이상으로 올리면 광범위한 위임 지시 하나가 폭발적인 팬아웃(fan-out)을 일으켜 토큰 사용량, 레이턴시, 로컬 리소스가 동시에 치솟는다고 공식 문서에서 직접 경고하고 있습니다. 이 값을 올리면 ChatGPT Pro $200 플랜 사용자도 하루 한계에 도달하는 시나리오가 현실입니다. (출처: OpenAI Codex 공식 문서 — Subagents, developers.openai.com/codex/subagents)
⚠️ 주의: max_depth를 올리기 전에 반드시 프로젝트 규모와 예상 토큰 소비를 먼저 계산해보세요. 공식 문서는 이 값을 “특별한 이유 없이 올리지 말라”고 명시하고 있습니다.
쓰기 작업에서 병렬이 오히려 코드를 망치는 이유
여기가 많은 사람들이 놓치는 부분입니다. OpenAI 공식 문서에는 이런 문장이 있습니다. “읽기 중심 작업(탐색, 테스트, 분류, 요약)에는 병렬 에이전트를 쓰는 것이 좋다. 그러나 쓰기 중심 병렬 워크플로우는 더 신중해야 한다. 에이전트들이 동시에 코드를 편집하면 충돌이 발생하고 조율 부담이 늘어날 수 있다.” (출처: OpenAI Codex 공식 문서 — Subagent Concepts, developers.openai.com/codex/concepts/subagents)
실제로 morphllm.com 비교 분석(2026.02.28)에서도 같은 문제가 보고됐습니다. Codex의 실패 패턴 중 하나가 “Multi-agent CSV fan-out: 배치 중간에 오류가 발생해도 복구 수단이 없어 파이프라인 전체가 멈출 수 있다”는 점입니다. 여러 에이전트가 같은 파일을 동시에 수정하면 마지막으로 저장된 변경이 이전 것을 덮어씁니다. Git conflict보다 더 조용하게 코드가 사라지는 경우가 생깁니다.
💡 공식 문서와 실제 장애 사례를 교차해보면 패턴이 보입니다 — 서브에이전트는 “읽기 전용 탐색 → 결과 취합” 구조에서만 안전합니다. 파일을 수정하는 작업을 병렬로 돌리는 순간 충돌 위험이 생깁니다.
권장 패턴은 이렇습니다. 먼저 explorer 에이전트(sandbox_mode: read-only)가 코드베이스를 탐색하고, 그 결과를 메인 에이전트가 받아서 worker 에이전트 하나가 순차적으로 수정하는 구조입니다. 탐색은 병렬, 수정은 직렬이 원칙입니다.
Plus 플랜에서 하루 만에 주 할당량 사라지는 구조
2026년 3월 초, Reddit r/codex에 실사용자 42명이 “토큰 소진 속도가 갑자기 급등했다”는 게시글이 올라왔습니다. 한 사용자는 프롬프트 3개에 주간 할당량의 10%가 빠졌고, 다른 사용자는 90분 8개 프롬프트로 주간 할당량의 93%가 소진됐다고 보고했습니다. OpenAI는 처음에 “사용 패턴 때문”이라고 답했다가, 이후 직접 문제를 인정했습니다. (출처: Reddit r/codex, Token Burn rate massively increased, 2026.03.03)
이 문제의 구조적 원인 중 하나는 서브에이전트 도입과 맞물립니다. ChatGPT Plus($20/월) 기준 5시간 세션에 30~150개 메시지가 허용됩니다. 서브에이전트는 메인 에이전트 1회 실행에서 내부적으로 여러 에이전트 스레드를 동시에 소비하므로, 체감 메시지 수보다 훨씬 빠르게 한도에 닿습니다. $20 플랜에서 서브에이전트를 무심코 6개 스레드 풀로 돌리면, 수학적으로 단일 에이전트 대비 한도 소진 속도가 최대 6배가 됩니다.
💡 v0.105.0부터 기본 활성화된 /fast 옵션은 속도 1.5× 대신 토큰 2×를 교환합니다. 서브에이전트와 /fast를 동시에 쓰면 한도 소진이 배가됩니다. (출처: Reddit r/codex 스레드 댓글, 2026.03.03)
현재 OpenAI가 API 플랜 사용자에게는 서브에이전트 비용을 에이전트별로 분리해서 보여주는 기능을 GitHub 이슈로 요청받았지만(#12488, 2026.02.21), 공개된 공식 답변이 없습니다. Plus 플랜 구독자 입장에서는 실행 전에 스스로 계산해야 하는 상황입니다.
서브에이전트를 안전하게 쓰는 실전 설정 3가지
공식 문서와 실사용 데이터를 합치면 안전한 사용 패턴이 나옵니다. 세 가지로 정리했습니다.
① max_threads를 작업 규모에 맞게 낮추세요
기본값 6은 대형 PR 리뷰나 다수 컴포넌트 일괄 감사 같은 경우에 맞춰진 값입니다. 평소 작업이 PR 포인트 3~4개 수준이라면 agents.max_threads = 3으로 낮추면 토큰 소비를 절반 이하로 줄일 수 있습니다. 프로젝트 루트의 .codex/config.toml에 한 줄 추가하면 됩니다.
② 탐색용 에이전트는 gpt-5.4-mini로 낮추세요
공식 문서의 커스텀 에이전트 예제에서도 pr_explorer는 gpt-5.3-codex-spark 또는 gpt-5.4-mini, reviewer는 gpt-5.4를 씁니다. 탐색 에이전트에 gpt-5.4-mini를 쓰고 reasoning effort를 medium으로 설정하면 고성능 모델 대비 토큰 비용이 크게 줄어듭니다. (출처: OpenAI Codex 공식 문서 — Subagents, developers.openai.com/codex/subagents)
③ 쓰기 에이전트는 sandbox_mode를 workspace-write로 명시하세요
기본값은 workspace-write이지만, 명시하지 않으면 나중에 설정이 바뀔 때 예상치 못한 권한으로 동작할 수 있습니다. 탐색 에이전트는 read-only로 고정하고, 수정 에이전트만 workspace-write로 지정하면 충돌 가능성을 구조적으로 차단할 수 있습니다.
📋 .codex/config.toml 기본 안전 설정 예시
[agents] max_threads = 3 max_depth = 1
출처: OpenAI Codex 공식 문서 — Subagents (developers.openai.com/codex/subagents)
자주 묻는 질문 Q&A
Q1. 서브에이전트는 ChatGPT Plus에서도 쓸 수 있나요?▼
Codex CLI를 설치하고 ChatGPT Plus 계정으로 로그인하면 사용 가능합니다. 다만 Plus 플랜의 5시간 세션 메시지 한도(30~150개) 내에서 서브에이전트도 동일하게 소진됩니다. 서브에이전트를 여러 개 동시에 돌리면 단일 에이전트 대비 한도 소진이 빠르므로 max_threads 값을 낮게 설정하는 것이 좋습니다.
Q2. 서브에이전트를 자동으로 끄는 방법이 있나요?▼
Codex는 서브에이전트를 명시적으로 요청했을 때만 실행합니다. 프롬프트에 “spawn”, “병렬로”, “에이전트 여러 개” 같은 표현을 쓰지 않으면 서브에이전트는 작동하지 않습니다. 완전히 비활성화하고 싶다면 config.toml에서 agents.max_threads = 1로 설정하면 됩니다.
Q3. 서브에이전트별로 다른 모델을 쓸 수 있나요?▼
가능합니다. ~/.codex/agents/ 또는 .codex/agents/ 폴더에 TOML 파일로 커스텀 에이전트를 만들고 model과 model_reasoning_effort를 지정하면 됩니다. 탐색용 에이전트는 gpt-5.4-mini + medium, 리뷰용 에이전트는 gpt-5.4 + high로 분리하는 것이 공식 권장 패턴입니다.
Q4. 서브에이전트가 실행 중에 승인 요청을 보내면 어떻게 되나요?▼
인터랙티브 CLI 세션에서는 비활성 에이전트 스레드의 승인 요청이 메인 스레드에 오버레이로 표시됩니다. 소스 스레드 레이블이 표시되고 o를 눌러 해당 스레드를 열어 확인한 뒤 승인하거나 거부할 수 있습니다. 비인터랙티브 모드에서는 새 승인이 필요한 작업이 실패 처리되고 오류가 부모 워크플로우로 반환됩니다.
Q5. spawn_agents_on_csv 기능은 어떤 경우에 씁니까?▼
파일·패키지·서비스 목록처럼 “행 하나 = 작업 하나” 구조일 때 씁니다. CSV를 주면 Codex가 행마다 워커 서브에이전트를 하나씩 스폰하고, 완료 후 결과를 CSV로 내보냅니다. 기본 워커 타임아웃은 1800초(30분)이며 agents.job_max_runtime_seconds로 조정 가능합니다. 이 기능은 실험적 성격이 있어 형식이 바뀔 수 있다고 공식 문서에 명시돼 있습니다.
마치며
Codex CLI 서브에이전트는 대형 코드베이스 탐색이나 병렬 감사 작업에서 분명히 시간을 줄여줍니다. 기능 자체가 나쁜 게 아닙니다. 문제는 “병렬로 돌리면 효율적”이라는 기대가 “토큰도 n배 나간다”는 사실과 함께 이해돼야 한다는 점입니다.
공식 문서가 읽기/쓰기 작업을 나눠 설명하고, max_depth 기본값을 1로 제한한 데는 이유가 있습니다. Plus 플랜에서 하루 만에 주 할당량이 사라진 사례도 설정을 이해하지 못하고 쓴 결과입니다. 서브에이전트를 쓰기 전에 .codex/config.toml에서 max_threads와 에이전트별 모델을 먼저 정하는 게 순서입니다.
솔직히 말하면, 지금 시점에서 서브에이전트가 가장 잘 맞는 사용 패턴은 PR 리뷰처럼 결과가 서로 독립적이고 읽기만 하는 작업입니다. 파일 수정이 동시에 일어나는 구조라면 Claude Code의 Agent Teams(git worktree 격리)가 더 적합합니다. 어떤 걸 쓸지는 작업 특성에 달려 있고, 둘 다 쓰는 하이브리드 워크플로우도 이미 현장에서 쓰이고 있습니다.
본 포스팅 참고 자료
- OpenAI Codex 공식 문서 — Subagents: https://developers.openai.com/codex/subagents
- OpenAI Codex 공식 문서 — Subagent Concepts: https://developers.openai.com/codex/concepts/subagents
- morphllm.com — Codex vs Claude Code 비교 분석 (2026.02.28): https://morphllm.com/comparisons/codex-vs-claude-code
- GitHub openai/codex Issue #12488 — Sub-agent costs (2026.02.21): https://github.com/openai/codex/issues/12488
- Simon Willison’s blog — Use subagents and custom agents in Codex (2026.03.16): https://simonwillison.net/2026/Mar/16/codex-subagents/
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 본문에 사용된 수치와 설정값은 2026년 3월 31일 기준 OpenAI 공식 문서 및 커뮤니티 실측 데이터를 바탕으로 작성됐습니다. Codex CLI 버전 업데이트에 따라 config 옵션명, 기본값, 모델명이 달라질 수 있습니다. 최신 정보는 developers.openai.com/codex에서 직접 확인하세요.
댓글 남기기