Codex CLI v0.115.0+
GPT-5.3-Codex / GPT-5.4 기준
Codex CLI 서브에이전트,
비용 먼저 보세요
병렬 처리가 빠르다는 말은 맞습니다. 그런데 Pro 사용자가 단 하루 만에 크레딧 20,000점을 소진했다는 실제 사례도 함께 봐야 합니다. Codex CLI 서브에이전트, 켜기 전에 알아야 할 수치를 정리했습니다.
(출처: OpenAI 공식 발표, 2026.02.05)
(출처: OpenAI 공식 문서)
(출처: GitHub 이슈 #12488)
서브에이전트가 뭔지, 공식 문서에 이렇게 나옵니다
2026년 3월 16일, Codex CLI v0.115.0이 배포되면서 서브에이전트(Subagents) 기능이 실험적 단계를 벗어나 정식 GA(General Availability)로 전환됐습니다. OpenAI 공식 개발자 문서에는 이렇게 나옵니다: “Codex can run subagent workflows by spawning specialized agents in parallel and then collecting their results in one response.” 직역하면, 여러 전문 에이전트를 동시에 띄워서 각자 작업하게 한 뒤 결과를 하나로 합쳐주는 구조입니다.
Codex에는 세 가지 내장 에이전트가 기본으로 포함돼 있습니다. default는 범용 폴백, worker는 구현·버그 수정 중심, explorer는 코드베이스 읽기 전담입니다. 여기에 TOML 파일을 작성해 커스텀 에이전트를 추가할 수도 있습니다. 예를 들어 PR 리뷰 시 보안 검토용 에이전트, 문서 조회용 에이전트, 코드 탐색용 에이전트를 동시에 띄워 각자 맡은 역할을 병렬로 처리하게 하는 식입니다.
중요한 점은, Codex는 명시적으로 요청할 때만 서브에이전트를 생성합니다. “spawn two agents”, “use one agent per point”처럼 직접 지시를 줘야 작동합니다. 자동으로 판단해서 서브에이전트를 띄우지는 않습니다. (출처: OpenAI 공식 문서 — developers.openai.com/codex/concepts/subagents)
💡 공식 문서에서 명시한 기본 동시 에이전트 수는 6개(max_threads 기본값)입니다. 재귀 깊이는 기본 1단계로 제한돼 있고, 이를 올리면 팬아웃이 지수적으로 늘어납니다.
병렬이 빠를 거라는 생각이 틀리는 순간
서브에이전트를 처음 접하면 “동시에 여러 에이전트가 움직이니 당연히 더 빠르겠지”라고 생각하게 됩니다. 그런데 OpenAI 공식 개념 문서에는 이런 경고가 함께 나옵니다: “Be more careful with parallel write-heavy workflows, because agents editing code at once can create conflicts and increase coordination overhead.” 여러 에이전트가 동시에 코드를 수정하면 충돌이 생기고 조율 비용이 오히려 늘어납니다.
공식 가이드에서 권장하는 서브에이전트 용도는 명확합니다. 읽기 중심 작업인 코드 탐색, 테스트, 로그 분석, 대용량 문서 요약이 적합합니다. 반면 코드를 동시에 편집하는 쓰기 작업에는 쓰지 말 것을 명시하고 있습니다. “빠르다”는 장점은 읽기 전용 태스크에서만 안전하게 성립합니다.
또 하나, 서브에이전트는 컨텍스트 오염(context pollution)을 줄이기 위한 구조이기도 합니다. 메인 스레드에 탐색 로그, 테스트 출력, 스택 트레이스가 쌓이면 모델 성능이 점점 떨어지는 ‘컨텍스트 부식(context rot)’ 현상이 발생합니다. 서브에이전트는 그 노이즈를 별도 스레드로 분리해 메인 스레드를 깨끗하게 유지하는 아키텍처적 선택입니다. (출처: OpenAI 공식 문서 — developers.openai.com/codex/concepts/subagents, Chroma context rot 리서치)
💡 공식 발표문과 실제 사용 패턴을 같이 놓고 보니 이런 차이가 보였습니다 — 서브에이전트는 속도 도구가 아니라 컨텍스트 관리 도구로 설계됐습니다. 빠르게 쓰려다 오히려 한도를 더 빠르게 소진할 수 있습니다.
비용 계산을 직접 해봤습니다
OpenAI 공식 Codex 요금 페이지(developers.openai.com/codex/pricing)에 나온 수치를 그대로 가져왔습니다. GPT-5.4 기준 로컬 메시지 1건의 평균 크레딧 소비는 약 7크레딧입니다. 그런데 서브에이전트를 쓰면 사정이 달라집니다.
| 시나리오 | 에이전트 수 | 예상 크레딧/1회 | Plus 주간한도 소모율 |
|---|---|---|---|
| 단일 에이전트 로컬 메시지 | 1개 | 약 7크레딧 | 소량 |
| 6개 병렬 서브에이전트 (기본값) | 6개 | 약 42크레딧+ | 빠르게 증가 |
| spawn_agents_on_csv (20행 배치) | 20개(순차 6개씩) | 140크레딧+ | 1회에 큰 폭 감소 |
| 클라우드 태스크 (별도 과금) | N/A | 약 34크레딧/건 | 로컬의 약 5배 |
※ 크레딧 단가는 공식 평균값 기준 추정. 실제 태스크 복잡도·컨텍스트 크기에 따라 크게 달라질 수 있음. (출처: OpenAI Codex 요금 페이지 — developers.openai.com/codex/pricing)
계산식을 직접 따라해볼 수 있습니다. 서브에이전트 1개는 독립적으로 모델·툴 호출을 실행하므로, 병렬 N개를 동시에 띄우면 크레딧 소비는 이론적으로 단일 에이전트 × N배가 됩니다. 기본 max_threads가 6이니, 프롬프트 한 번에 최대 6배 속도로 한도가 빠집니다.
GitHub 이슈 #12488(github.com/openai/codex/issues/12488)에는 Pro 사용자가 서브에이전트 사용 후 1주일치 한도를 초과해 $350 이상을 추가 결제했다는 사례가 공개돼 있습니다. 에이전트가 “더 싸다”는 주장이 맞더라도, 실제 비용 예측·통제 수단이 없다는 것이 진짜 문제입니다.
💡 서브에이전트는 단일 에이전트보다 작업당 토큰이 적을 수 있지만, 세션당 총 소비량은 훨씬 많습니다. 공식 문서에서도 “subagent workflows consume more tokens than comparable single-agent runs”라고 직접 명시하고 있습니다.
컨텍스트 250K 넘으면 한도 소진 속도가 달라집니다
OpenAI 커뮤니티 포럼(2026.03.17~03.25)에 접수된 여러 사례를 보면, Plus·Pro 사용자들이 공통적으로 같은 현상을 보고하고 있습니다. 컨텍스트 창이 약 250,000~258,000토큰을 넘어서는 순간부터 한도 소진 속도가 눈에 띄게 빨라진다는 겁니다.
GPT-5.4는 공식적으로 최대 100만 토큰 컨텍스트 창을 지원한다고 발표됐습니다(출처: openai.com/index/introducing-gpt-5-4/). 그런데 실사용 데이터는 다른 이야기를 합니다. 한 사용자는 “config.toml에 컨텍스트를 100만으로 설정했는데 처음 며칠은 괜찮다가 CLI 업데이트 이후부터 258K 초과 시점부터 한도가 빠르게 소진된다”고 밝혔습니다. 서브에이전트는 여러 에이전트가 각자 컨텍스트를 가지므로, 이 임계점을 훨씬 빨리 넘길 수 있습니다.
OpenAI 측에서 이 현상에 대한 공식 답변을 내놓지 않은 상황입니다. 현재로선 CLI에서 /status 명령으로 남은 한도를 수시로 확인하거나, GPT-5.4-mini로 전환해 소비 속도를 낮추는 방법이 현실적인 대안입니다. (출처: Codex 공식 요금 페이지 — developers.openai.com/codex/pricing)
⚠️ 서브에이전트 각각이 독립적인 컨텍스트를 유지하므로, 6개 병렬 에이전트가 동시에 대형 파일을 읽으면 전체 컨텍스트 소비량이 순식간에 250K 임계점을 넘길 수 있습니다.
서브에이전트 써야 하는 상황, 쓰면 안 되는 상황
공식 문서와 실사용 사례를 교차해보면 실제로 쓸 만한 상황과 피해야 하는 상황이 명확하게 갈립니다.
✅ 쓸 만한 상황
PR 리뷰에서 보안·코드 품질·테스트 커버리지를 동시에 검토할 때가 대표적입니다. 읽기 전용 에이전트들이 각자 맡은 관점에서 병렬로 코드를 분석하고 요약을 반환하면 메인 스레드에는 최종 정리만 남습니다. 실제로 공식 문서에 나온 프롬프트 예시도 이 패턴입니다: “Spawn one agent per point, wait for all of them, and summarize.” 또 spawn_agents_on_csv를 활용해 컴포넌트 목록이 담긴 CSV를 넘기고 행 단위로 리뷰를 병렬 처리하는 방식도 잘 맞습니다. (출처: developers.openai.com/codex/subagents)
❌ 피해야 하는 상황
여러 에이전트가 동시에 같은 코드베이스를 수정하는 쓰기 작업은 충돌과 조율 오버헤드가 생깁니다. 또한 재귀 깊이(max_depth)를 기본값인 1 이상으로 올리면 팬아웃이 지수적으로 불어납니다. 공식 문서에 “Raising this value can turn broad delegation instructions into repeated fan-out, which increases token usage, latency, and local resource consumption”이라고 명시돼 있습니다. 그리고 한 가지 더, Codex는 네트워크가 기본 차단된 샌드박스에서 실행됩니다. 서브에이전트도 같은 샌드박스 정책을 상속합니다. 외부 API를 호출해야 하는 작업은 서브에이전트를 아무리 늘려도 막히는 지점이 생깁니다.
💡 공식 권장 사항과 실제 커뮤니티 피드백을 같이 보니 이 흐름이 보였습니다 — “읽기는 병렬, 쓰기는 직렬”이 서브에이전트의 실질적 운용 원칙입니다.
Claude Code와 실제로 무엇이 다른가
벤치마크 수치는 비슷합니다. SWE-bench Verified에서 Claude Code(Opus 4.6) 80.8%, Codex(GPT-5.2) 80.0%로 상위 5개 모델이 1.3포인트 안에 다 모여 있습니다. Terminal-Bench 2.0에서는 Codex가 77.3%로 Claude Code(74.7%)를 앞섭니다. 숫자만 보면 비슷합니다. 그런데 아키텍처가 근본적으로 다릅니다. (출처: boredhead, Medium — Claude Code Vs Codex, 2026.03.18)
Codex는 샌드박스 우선(sandbox-first) 설계입니다. macOS는 Seatbelt, Linux는 Landlock으로 파일시스템과 네트워크를 격리하고, full-auto 모드에서도 네트워크는 기본 차단입니다. 반면 Claude Code는 신뢰 우선(trust-by-default)으로 파일시스템에 직접 접근하고 MCP 서버를 통해 외부 리소스까지 활용합니다. 결국 Codex 서브에이전트는 “분리된 채로 병렬 실행”이고, Claude Code 서브에이전트는 “연결된 채로 협력 실행”입니다.
실패 패턴도 다릅니다. Codex는 샌드박스 밖 정보가 필요할 때 막히고, Claude Code는 약 30턴 이후 컨텍스트 컴팩션이 일어나 이전 지시사항이 소실될 위험이 있습니다. 어떤 도구를 고를지는 작업 성격에 따라 나뉩니다. 외부와 완전히 격리된 코드 리뷰나 버그 수정에는 Codex가 맞고, 세션 기억이 필요한 대규모 리팩터링에는 Claude Code가 맞습니다.
| 항목 | Codex CLI | Claude Code |
|---|---|---|
| 실행 모델 | 샌드박스 격리 | 파일시스템 직접 접근 |
| 세션 메모리 | 세션 간 초기화 | 세션 간 유지 |
| 네트워크 기본 설정 | 차단 | 허용(권한 내) |
| Terminal-Bench 2.0 | 77.3% | 74.7% |
| 주요 실패 패턴 | 외부 리소스 접근 차단 | ~30턴 이후 컨텍스트 소실 |
출처: OpenAI 공식 발표(2026.02.05), boredhead Medium 분석(2026.03.18), OpenAI Codex 공식 문서
자주 묻는 것들 — Q&A
Q1. Codex CLI 서브에이전트는 Plus 플랜에서 쓸 수 있나요?
네, 쓸 수 있습니다. Plus, Pro, Business, Enterprise 모두 서브에이전트 기능이 열려 있습니다. 단, Plus는 5시간 윈도우당 GPT-5.4 로컬 메시지 한도가 33~168개로 좁습니다. 서브에이전트로 6개를 동시에 띄우면 사실상 1회 실행에 메시지 6개 몫을 소비하는 셈이라 금방 한도에 닿을 수 있습니다. (출처: developers.openai.com/codex/pricing)
Q2. 서브에이전트가 자동으로 생성되는 경우가 있나요?
없습니다. OpenAI 공식 문서에 명확히 나와 있습니다: “Codex doesn’t spawn subagents automatically.” 반드시 프롬프트에 “spawn”, “delegate in parallel”, “use one agent per point” 같은 명시적 지시가 있어야 생성됩니다. 자동 생성을 걱정할 필요는 없지만, 반대로 쓰려면 프롬프트를 정확히 작성해야 합니다.
Q3. max_threads를 올리면 더 빠르게 처리할 수 있나요?
이론적으로는 맞지만 실제로는 주의가 필요합니다. max_threads 기본값은 6입니다. 이를 올리면 더 많은 에이전트를 동시에 열 수 있지만, 토큰 소비와 지연 시간, 로컬 리소스 소비가 함께 늘어납니다. 공식 문서에는 “Keep the default unless you specifically need recursive delegation”이라고 나와 있습니다. 기본값을 유지하는 게 대부분의 경우에 더 안전합니다.
Q4. spawn_agents_on_csv는 어떤 상황에서 쓰는 건가요?
반복적으로 동일한 구조의 작업을 여러 항목에 적용할 때 씁니다. 예를 들어 프론트엔드 컴포넌트 목록 CSV를 넘기면 각 행마다 하나씩 에이전트를 띄워 리뷰하고 결과를 CSV로 돌려줍니다. per-worker 기본 타임아웃은 1,800초(30분)입니다. 배치 작업 하나가 수십 개 에이전트를 순차적으로 처리하므로 한도 소비에 각별히 주의해야 합니다.
Q5. 서브에이전트와 Claude Code 서브에이전트 중 어느 걸 써야 하나요?
작업 성격으로 나눠야 합니다. 외부 접속 없이 코드베이스 안에서 완결되는 버그 수정·코드 리뷰라면 Codex의 샌드박스 격리 구조가 맞습니다. 반면 세션을 넘나들며 프로젝트 문맥을 기억해야 하는 장기 리팩터링이나 외부 API·문서 서버가 필요한 작업이라면 Claude Code가 더 적합합니다. 두 도구의 Agent Skills 파일은 서로 호환되므로 병행해서 쓰는 것도 선택지입니다.
마치며
Codex CLI 서브에이전트는 분명 쓸모 있는 기능입니다. PR 리뷰를 보안·품질·테스트 관점으로 나눠 병렬 처리하거나, CSV 배치로 수십 개 컴포넌트를 한 번에 돌리는 건 단일 에이전트로는 흉내 내기 어렵습니다. Terminal-Bench 2.0에서 77.3%라는 수치가 나온 배경도 이런 병렬 아키텍처와 맞닿아 있습니다.
다만 켜기 전에 알아야 할 게 있습니다. 서브에이전트는 속도 도구가 아니라 컨텍스트 관리 도구입니다. 병렬로 쓴다는 건 토큰 소비도 병렬로 한다는 뜻입니다. 250K 토큰 임계점 이슈는 아직 공식 해명이 없고, 비용 사전 예측 수단도 현재로선 부족합니다. 쓸 계획이라면 /status로 잔여 한도를 수시로 확인하고, max_threads는 기본값 6을 유지하고, 쓰기 작업에는 절대 병렬을 쓰지 않는 원칙을 먼저 세우는 게 맞습니다.
솔직히 말하면, 지금 단계의 서브에이전트는 Pro 이상 사용자가 PR 리뷰나 배치 분석에 제한적으로 쓸 때 가장 합리적입니다. Plus 사용자가 일상적인 코딩에 쓰면 한도가 생각보다 빠르게 닳습니다. 기능 자체는 좋은데, 비용 투명성이 따라오지 못하고 있다는 게 지금 Codex 서브에이전트의 현실입니다.
본 포스팅 참고 자료
- ① OpenAI Codex Subagents 공식 문서 — developers.openai.com/codex/subagents/
- ② OpenAI Codex Subagent Concepts 공식 문서 — developers.openai.com/codex/concepts/subagents
- ③ OpenAI GPT-5.3-Codex 공식 발표 (2026.02.05) — openai.com/index/introducing-gpt-5-3-codex/
- ④ OpenAI Codex 공식 요금 페이지 — developers.openai.com/codex/pricing/
- ⑤ GitHub 이슈 #12488 “Sub-agent costs are too high and too opaque” (2026.02.21) — github.com/openai/codex/issues/12488
- ⑥ Chroma Context Rot 리서치 — research.trychroma.com/context-rot
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 본 포스팅은 2026년 3월 31일 기준, Codex CLI v0.115.0 및 GPT-5.3-Codex·GPT-5.4 모델을 기준으로 작성됐습니다. OpenAI의 요금·한도 정책은 예고 없이 변경될 수 있으므로 중요한 결정 전에는 공식 페이지에서 최신 내용을 직접 확인하시기 바랍니다.
댓글 남기기