Codex CLI v0.118.0
GPT-5.4 기준
Codex CLI 서브에이전트, 빠르다고요? 이 수치 먼저 보세요
2026년 3월 16일, OpenAI가 Codex CLI에 서브에이전트를 정식 출시했습니다. 커뮤니티는 “병렬로 6개 에이전트가 동시에 달린다”며 흥분했고, 공개 9일 만에 136개 에이전트 TOML 컬렉션이 GitHub 스타 2,778개를 찍었습니다. 근데 여기서 아무도 잘 얘기 안 하는 게 있습니다 — 토큰이 얼마나 나가는지. Pro 플랜 200달러/월 구독자가 서브에이전트를 켠 뒤 하루도 못 버텼다는 GitHub 이슈가 올라왔고, 공식 문서에는 이 비용 구조를 설명하는 조용한 경고문이 있습니다. 직접 수치를 따져봤습니다.
서브에이전트가 뭔지 30초 정리
Codex CLI 서브에이전트는 간단히 말하면 하나의 메인 세션이 여러 개의 전문화된 보조 에이전트를 병렬로 생성하고, 결과를 모아 하나의 응답으로 돌려주는 구조입니다. 코드베이스 탐색, 버그 수정, PR 리뷰처럼 각각 독립적으로 처리할 수 있는 작업에 특히 유용합니다.
공식 문서(developers.openai.com/codex/subagents)에는 이렇게 나옵니다. “Codex handles orchestration across agents, including spawning new subagents, routing follow-up instructions, waiting for results, and closing agent threads.” 오케스트레이션 전체를 Codex가 담당하고, 결과가 다 모일 때까지 기다렸다가 한꺼번에 돌려줍니다.
주의할 점이 있습니다. 서브에이전트는 직접 명령하지 않으면 생성되지 않습니다. 공식 문서에 “Codex only spawns subagents when you explicitly ask it to”라고 명확하게 나옵니다. 설정에 `multi_agent = true`를 켜둔다고 자동으로 에이전트가 쏟아지는 게 아니라는 뜻입니다. 프롬프트에서 직접 요청해야 실제로 작동합니다.
💡 공식 문서와 실제 작동 흐름을 같이 놓고 보면 이런 차이가 보입니다 — “자동 병렬화”가 아니라 “사용자가 명시한 작업 단위별 분기”에 가깝습니다.
3가지 빌트인 에이전트와 TOML 구조
Codex는 설치 즉시 세 가지 빌트인 에이전트를 제공합니다. default(범용), worker(구현·수정 특화), explorer(읽기 전용 코드베이스 탐색)입니다. 커스텀 에이전트는 `~/.codex/agents/` (개인용) 또는 `.codex/agents/` (프로젝트 범위)에 TOML 파일을 두면 됩니다.
필수 필드는 세 가지입니다. `name`, `description`, `developer_instructions`. 여기에 `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, `skills.config` 같은 선택 필드를 추가할 수 있습니다. 모델을 명시하지 않으면 부모 세션 설정을 그대로 상속합니다.
한 가지 실용적인 팁 — `nickname_candidates` 필드를 쓰면 동일한 에이전트를 여러 개 동시에 띄울 때 “Atlas”, “Delta”, “Echo”처럼 구별 가능한 이름이 붙습니다. 공식 문서에 예시가 그대로 나와 있습니다. 단순한 UX 기능처럼 보이지만, 6개 스레드가 동시에 돌아갈 때 어느 스레드에서 승인 요청이 왔는지 구분하는 데 실제로 중요합니다.
| 필드 | 필수 여부 | 설명 |
|---|---|---|
| name | 필수 | 에이전트 식별자. 파일명과 달라도 됨 |
| description | 필수 | Codex가 언제 이 에이전트를 쓸지 판단하는 기준 |
| developer_instructions | 필수 | 에이전트 행동 정의 핵심 지시문 |
| model | 선택 | 미설정 시 부모 세션 모델 상속 |
| sandbox_mode | 선택 | read-only / workspace-write 등 개별 지정 가능 |
| nickname_candidates | 선택 | 동일 에이전트 다중 인스턴스 구분용 표시명 |
(출처: OpenAI Codex 공식 문서 — developers.openai.com/codex/subagents, 2026.03.31 기준)
병렬이 빠른 건 맞는데, 비용은 다른 계산입니다
여기가 핵심입니다. 공식 문서에 이런 문장이 있습니다. “each subagent does its own model and tool work, subagent workflows consume more tokens than comparable single-agent runs.” 에이전트를 6개 띄우면 토큰 소모도 단순히 6배가 됩니다. 각 에이전트는 자신만의 컨텍스트를 독립적으로 쌓기 때문입니다.
실제 수치로 보면 이렇습니다. 공식 가격 페이지(developers.openai.com/codex/pricing)에서 GPT-5.4 기준 로컬 메시지 1건의 평균 크레딧 비용은 약 7 크레딧입니다. GPT-5.4-mini로 전환하면 사용 한도가 2.5배~3.3배 늘어납니다. 그런데 서브에이전트 6개를 동시에 실행하면 메시지 1건처럼 보여도 내부에서 최대 6개 에이전트가 각각 모델 호출과 도구 작업을 합니다. 한도 소진 속도는 그만큼 빨라집니다.
⚠️ 실제 사례 — GitHub Issue #13179 (2026.03.01)
Pro 플랜($200/월) 구독자가 `max_threads = 6`으로 서브에이전트를 켠 뒤 1시간에 주간 Pro 한도의 약 20%를 소진했습니다. 주간 단위로 보면 하루도 안 되는 속도입니다. 해당 사용자는 “200달러/월인데 5시간짜리 플랜으로 전락했다”고 직접 표현했습니다. 서브에이전트를 끄면 소진 속도가 줄어들었지만, 에이전틱 워크플로우 자체를 포기해야 하는 상황이었습니다.
공식 가격 페이지 기준으로 Pro 플랜은 5시간 단위 기준 GPT-5.4 로컬 메시지를 223~1,120건 사용할 수 있습니다. 작업 규모에 따라 편차가 크지만, 서브에이전트 6개를 한꺼번에 써서 PR 리뷰 같은 복잡한 작업을 돌리면 5시간 한도가 단숨에 증발할 수 있습니다. 비용 감각 없이 켜면 돈부터 나갑니다.
💡 GPT-5.4-mini로 탐색용 에이전트(explorer)를 돌리고, 리뷰어(reviewer)만 GPT-5.4로 지정하는 식으로 모델을 나눠 쓰면 비용을 눈에 띄게 줄일 수 있습니다. 공식 문서 PR 리뷰 예시에서도 explorer는 gpt-5.3-codex-spark, reviewer는 gpt-5.4로 따로 설정합니다.
max_depth를 올리면 생기는 문제
공식 문서에 `max_depth`가 기본값 1이고, 이를 올리면 생기는 위험에 대한 경고가 조용히 삽입되어 있습니다. “Raising this value can turn broad delegation instructions into repeated fan-out, which increases token usage, latency, and local resource consumption.” 이를 의역하면 이렇습니다. 에이전트가 에이전트를 낳고, 그 에이전트가 또 에이전트를 낳는 재귀적 팬아웃이 발생합니다.
기본값인 depth=1은 “자식 에이전트는 낳을 수 있지만 손자 에이전트는 생성 불가”입니다. 이 제한을 depth=2로 올리면 한 번의 프롬프트가 이론상 6(자식) × 6(손자) = 36개 에이전트까지 팬아웃될 수 있습니다. `max_threads = 6`이 총 동시 실행 상한을 막아주긴 하지만, 큐에 쌓인 작업이 순차적으로 처리되므로 비용 자체는 계속 쌓입니다.
문서에서 명확하게 권고합니다. “Keep the default unless you specifically need recursive delegation.” 재귀 위임이 진짜 필요한 경우가 아니면 1을 유지하라는 겁니다. 처음 써보는 단계에서 max_depth를 높이는 건 추가 비용을 예측할 수 없게 만드는 설정입니다.
💡 실제 PR 리뷰 워크플로우에서 공식 권장 설정은 max_threads=6, max_depth=1입니다. 이 조합으로도 pr_explorer → reviewer → docs_researcher 세 에이전트가 병렬로 충분히 작동합니다.
Claude Code 서브에이전트와 구조가 다른 이유
Codex와 Claude Code 모두 서브에이전트 기능을 지원하지만 설계 방향이 다릅니다. 이 차이를 모르면 “왜 Codex는 컨텍스트 오염 이슈가 적냐”는 질문에 답할 수 없습니다.
Codex는 격리 실행이 기본입니다. 각 서브에이전트는 독립된 컨텍스트 창을 가지고 작업합니다. 컨텍스트 오염(context pollution) 방지가 이 구조의 핵심 목적입니다. 단일 에이전트로 긴 작업을 돌릴 때 맥락이 쌓여 판단이 흐려지는 문제를 피하기 위해 처음부터 격리합니다. Claude Code의 Task 도구 방식은 부모 컨텍스트를 일부 공유하며 명시적으로 위임하는 구조입니다. 어느 쪽이 더 좋다기보다, 용도가 다릅니다.
실제 비교 테스트에서 흥미로운 수치가 나왔습니다. Composio 벤치마크 기준으로 Figma 플러그인 작업에서 Claude Code는 6.2M 토큰을 썼고 Codex는 1.5M 토큰을 소진했습니다. (출처: morphllm.com/comparisons/codex-vs-claude-code) 약 4배 차이입니다. 단일 작업 기준으로는 Codex가 토큰 효율이 높지만, 서브에이전트를 여러 개 동시에 켜면 이 효율 이점이 빠르게 상쇄됩니다.
💡 서브에이전트 병렬 실행 시 Codex의 격리 구조는 오히려 각 에이전트가 공유 컨텍스트를 참조하지 못해 중복 작업이 발생할 수 있습니다. 에이전트 간 결과를 조율하는 지시문을 프롬프트에 명확히 포함해야 합니다.
실제로 쓸 만한 상황과 피해야 할 상황
서브에이전트가 진짜 빛을 발하는 건 작업들이 서로 독립적이고 병렬로 처리해도 결과에 영향이 없을 때입니다. 공식 문서에서 권장하는 PR 리뷰가 좋은 예입니다. 보안 검토, 코드 품질, 버그, 레이스 컨디션, 테스트 불안정성, 유지보수성 — 이 여섯 항목은 독립적으로 검토할 수 있습니다. 병렬로 돌려도 서로 간섭이 없습니다. 반면 기능 구현처럼 앞 단계 결과가 뒤 단계에 영향을 주는 순차적 작업은 서브에이전트 병렬화 효과가 거의 없습니다.
`spawn_agents_on_csv` 도구는 실용적인 배치 처리 시나리오입니다. 수십~수백 개의 파일이나 서비스를 동일한 기준으로 감사할 때 CSV 한 행당 에이전트 하나가 배정됩니다. 각 에이전트는 처리 완료 시 `report_agent_job_result`를 호출하고, 결과가 CSV로 내보내집니다. 마이그레이션 대상 목록 점검이나 의존성 감사 같은 반복적 작업에 적합합니다. 단, 워커당 기본 타임아웃이 1,800초(30분)입니다. 그 안에 결과를 보고하지 못한 행은 오류로 기록됩니다.
피해야 할 상황은 명확합니다. 첫째, 비용을 미리 계산하지 않은 상태에서 Pro 이하 플랜으로 `max_threads = 6` 풀 활성화. 둘째, 재귀 위임 필요 없이 `max_depth`를 2 이상으로 올리는 것. 셋째, 탐색·검토·구현을 한 번에 묶어 하나의 서브에이전트 프롬프트로 처리하는 것 — 에이전트 역할이 좁고 명확할수록 결과가 좋다는 게 공식 문서의 일관된 권고입니다.
| 구분 | 적합한 작업 | 주의할 작업 |
|---|---|---|
| 병렬성 | 독립 항목 다수 (PR 리뷰 포인트, 파일 목록 감사) | 순차 의존 작업 (구현 → 테스트 → 배포) |
| 에이전트 수 | 3~4개 역할 분리, 역할당 1개 | 6개 이상 동시 + 복잡한 컨텍스트 |
| 모델 선택 | 탐색: gpt-5.3-codex-spark / 리뷰: gpt-5.4 | 모든 에이전트에 gpt-5.4 high reasoning |
| 플랜 | Business 이상 또는 API Key 사용 | Plus에서 max_threads=6 풀 활성화 |
(출처: OpenAI Codex 공식 문서 서브에이전트 권장 설정 + GitHub Issue #13179 실사례 종합)
자주 나오는 질문 5가지
Q1. 서브에이전트를 켜면 Pro 플랜이 정말 하루도 못 버팁니까?
모든 경우가 그런 건 아닙니다. 작업 크기와 모델 선택에 따라 편차가 큽니다. 공식 가격 페이지 기준 GPT-5.4로 로컬 메시지 1건당 평균 약 7 크레딧이 나가는데, 서브에이전트 6개가 동시에 붙으면 사실상 메시지 1건에 여러 배 비용이 발생합니다. GitHub Issue #13179처럼 복잡한 작업을 풀 스레드로 돌리면 Pro 주간 한도 20%가 1시간 만에 빠지는 사례가 실제로 있었습니다. GPT-5.4-mini로 탐색 에이전트를 돌리는 식으로 모델을 분리하면 훨씬 오래 씁니다.
Q2. `max_threads = 6`은 왜 기본값이고, 늘릴 수 있습니까?
공식 문서에서 별도 이유를 밝히지 않았습니다. 설정에서 숫자를 바꾸면 늘릴 수는 있지만, 늘릴수록 동시 비용이 선형적으로 증가하고 로컬 자원 소모도 늘어납니다. 현재 IDE Extension에서는 서브에이전트 가시성이 아직 지원되지 않아 CLI와 앱에서만 확인 가능하다는 점도 염두에 두세요.
Q3. 커스텀 에이전트는 어떻게 만듭니까?
개인 에이전트는 `~/.codex/agents/에이전트명.toml`, 프로젝트 에이전트는 `.codex/agents/에이전트명.toml`에 파일을 두면 됩니다. TOML 파일 안에 `name`, `description`, `developer_instructions` 세 필드가 필수입니다. 빌트인 에이전트(default, worker, explorer)와 같은 이름을 사용하면 커스텀 에이전트가 우선 적용됩니다.
Q4. 서브에이전트에서 승인(approval) 요청은 어떻게 처리됩니까?
비활성 스레드에서도 승인 요청이 올라올 수 있습니다. TUI에서 승인 오버레이가 표시되면 어느 스레드에서 온 요청인지 레이블이 붙고, `o` 키를 누르면 해당 스레드로 이동해서 맥락을 확인한 뒤 승인·거부할 수 있습니다. 비대화형 모드에서는 승인이 필요한 작업이 자동으로 실패 처리되고 상위 워크플로우로 오류가 반환됩니다.
Q5. Claude Code와 Codex CLI 중 어느 걸 써야 합니까?
신뢰할 수 없는 코드베이스(외부 PR 등)를 다루거나 커널 수준의 샌드박스가 필요하면 Codex, 복잡한 거버넌스 훅이나 깊은 리팩토링 작업에는 Claude Code가 더 적합합니다. Composio 토큰 효율 벤치마크에서 동일 작업 기준 Codex가 Claude Code보다 약 4배 토큰을 덜 썼지만, 서브에이전트를 풀로 켜면 이 효율 차이는 빠르게 좁혀집니다. 둘 다 같은 프로젝트에서 함께 쓸 수 있습니다. CLAUDE.md와 AGENTS.md는 충돌하지 않습니다.
마치며 — 병렬의 매력, 비용의 현실
Codex CLI 서브에이전트는 실제로 쓸 수 있는 기능입니다. PR 리뷰를 6개 포인트로 나눠 동시에 돌리거나, 수십 개 파일을 CSV 배치로 감사하는 시나리오에서는 명확한 시간 이득이 있습니다. 3월 16일 GA 이후 136개 에이전트 TOML 컬렉션이 일주일 만에 스타 2,778개를 찍을 만큼 커뮤니티 반응도 뜨겁습니다.
그런데 솔직히 말하면, 지금 나온 한국어 글들은 “이렇게 쓰면 병렬로 빠르다”는 얘기만 합니다. 토큰 비용이 에이전트 수에 비례해서 쌓인다는 것, max_depth를 올리면 팬아웃이 기하급수적으로 커진다는 것, Pro 플랜이 1시간 만에 주간 한도 20%를 태울 수 있다는 것 — 이 세 가지는 공식 문서에 있는 내용인데 정작 아무도 얘기 안 합니다.
시작할 때 추천하는 설정은 간단합니다. `max_threads = 6`, `max_depth = 1`, 탐색 에이전트에는 gpt-5.3-codex-spark, 리뷰·구현 에이전트에는 gpt-5.4를 분리해서 사용하세요. 그리고 `/status` 명령어로 남은 한도를 주기적으로 확인하는 습관을 들이면, 잔고가 증발하는 불상사를 막을 수 있습니다.
본 포스팅 참고 자료
본 포스팅은 2026년 4월 2일 작성되었으며, Codex CLI v0.118.0 / GPT-5.4 기준입니다.
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다.
수치 및 내용은 OpenAI 공식 문서 기준이며, 업데이트 여부는 공식 changelog에서 확인하시기 바랍니다.
댓글 남기기