Codex CLI 정식 출시 (2026.03.16)
IT/AI
Codex CLI 서브에이전트, 이 조건이면 비용이 폭발합니다
OpenAI가 2026년 3월 16일 Codex CLI 서브에이전트를 정식 출시했습니다. 병렬 실행으로 코드 리뷰와 리팩토링 속도를 높일 수 있다는 점은 분명하지만, 공식 문서에 묻혀 있는 비용 구조를 먼저 이해하지 않으면 Pro 플랜 한도를 일주일도 안 돼 뚫어버립니다.
(공식 기본값)
실제 사례 (GitHub Issues)
(default·worker·explorer)
서브에이전트가 뭔지부터 — 기존 Codex와 다른 점
Codex CLI 서브에이전트는 하나의 메인 에이전트가 작업을 분해하고, 전문화된 하위 에이전트들을 병렬로 띄워 각자 처리한 뒤 결과를 하나로 합치는 구조입니다. OpenAI 공식 문서에는 이렇게 나옵니다.
“Codex can run subagent workflows by spawning specialized agents in parallel and then collecting their results in one response.”
(출처: OpenAI Developers, developers.openai.com/codex/subagents, 2026.03.16)
기존 Codex는 단일 에이전트가 한 번에 하나씩 처리하는 구조였습니다. 파일 50개를 리팩토링하면 50번 순차 실행이었죠. 서브에이전트가 도입되면서 이론상 50개를 동시에 분배해 처리할 수 있게 됐습니다. 속도는 올라가지만, 비용도 같은 비율로 올라갑니다. 병렬화는 공짜가 아닙니다.
서브에이전트 호출 방식도 중요합니다. 공식 문서에 딱 이렇게 나옵니다.
“Codex only spawns subagents when you explicitly ask it to.”
(출처: OpenAI Developers, developers.openai.com/codex/subagents, 2026.03.16)
자동으로 서브에이전트를 실행하지 않는다는 뜻입니다. “spawn two agents” 또는 “one agent per point”처럼 명시적으로 요청해야 작동합니다.
내장 에이전트 3종과 커스텀 에이전트 구성 방법
Codex는 정식 출시 시점에 3개의 내장 에이전트를 제공합니다. default(범용 폴백), worker(구현·수정 특화), explorer(코드베이스 탐색 특화)입니다. 세 가지를 조합해 바로 쓸 수 있고, 필요하면 TOML 파일로 커스텀 에이전트를 추가할 수 있습니다.
| 에이전트 | 역할 | 권장 모델 | 샌드박스 |
|---|---|---|---|
| default | 범용 처리 | gpt-5.4 | workspace-write |
| worker | 구현·수정 | gpt-5.3-codex-spark | workspace-write |
| explorer | 코드 탐색 | gpt-5.4-mini | read-only |
출처: OpenAI Developers — developers.openai.com/codex/concepts/subagents (2026.03.16)
커스텀 에이전트는 ~/.codex/agents/(개인 전역)나 .codex/agents/(프로젝트 스코프)에 TOML 파일로 추가합니다. 파일마다 name, description, developer_instructions 세 필드는 필수입니다. 모델, 추론 강도, MCP 서버는 선택 사항이며, 명시하지 않으면 부모 세션 설정을 상속합니다.
💡 공식 문서와 실제 사용 흐름을 함께 보니 이런 패턴이 보였습니다
PR 리뷰를 예로 들면 explorer로 코드 경로를 탐색하고, reviewer(커스텀)로 보안·품질을 점검하고, docs_researcher(커스텀)로 API 문서를 검증하는 3단계 파이프라인이 공식 문서 예제에 정확히 나와 있습니다. 각 역할에 다른 모델을 붙이면 비용과 품질을 동시에 조절할 수 있습니다.
빠를수록 돈이 더 나가는 구조 — 비용 함정 해부
서브에이전트의 가장 큰 함정은 속도가 오를수록 비용도 같이 오른다는 점입니다. 공식 문서에 이 문장이 있습니다.
“Subagent workflows consume more tokens than comparable single-agent runs because each subagent does its own model and tool work.”
(출처: OpenAI Developers, developers.openai.com/codex/subagents, 2026.03.16)
각 서브에이전트가 독립적인 모델 호출과 도구 작업을 수행하기 때문입니다. 작업 2개를 병렬로 돌리면 단순 2배가 아니라, 메인 에이전트 오케스트레이션 비용까지 추가됩니다.
⚠️ GitHub Issues에 올라온 실제 사례 (이슈 #12488, 2026.02.21)
“I am easily $350 over my Pro Plan for a week.”
Pro 플랜 사용자가 서브에이전트를 적극 사용했더니 일주일 만에 $350 초과. 사전 비용 경고도, 에이전트별 사후 비용 내역도 없어서 관리가 불가능했다고 보고했습니다. Pro 플랜 월 $200임을 감안하면 일주일 안에 한 달 치를 넘어선 셈입니다.
공식 설정값에도 주의해야 할 숫자가 있습니다. agents.max_threads의 기본값은 6이고, agents.max_depth의 기본값은 1입니다. 공식 문서에 이렇게 나와 있습니다.
“Keep the default unless you specifically need recursive delegation. Raising this value can turn broad delegation instructions into repeated fan-out, which increases token usage, latency, and local resource consumption.”
(출처: OpenAI Developers, developers.openai.com/codex/subagents, 2026.03.16)
max_depth를 1 이상으로 올리면 서브에이전트가 다시 서브에이전트를 낳는 재귀 위임이 가능해집니다. 비용과 지연이 기하급수적으로 늘어납니다.
💡 설정 숫자와 실제 과금 흐름을 같이 보니 이런 패턴이 보였습니다
max_threads=6, max_depth=1이 기본값이라고 해서 안전하지 않습니다. 6개 스레드가 동시에 gpt-5.4로 돌아가는 순간, 단일 에이전트 대비 토큰 비용은 6배 이상입니다. 처음에는 반드시 max_threads를 2~3으로 낮추고, 작업 범위를 좁힌 상태에서 테스트하는 게 맞습니다.
컨텍스트 오염과 컨텍스트 부패 — 병렬화가 오히려 해가 될 때
서브에이전트를 쓰는 이유 중 하나가 메인 컨텍스트를 깨끗하게 유지하기 위해서입니다. 공식 문서는 두 가지 개념을 제시합니다.
컨텍스트 오염 (Context Pollution)
유용한 정보가 탐색 로그, 테스트 결과, 스택 트레이스 같은 노이즈에 묻혀버리는 현상.
컨텍스트 부패 (Context Rot)
대화가 길어질수록 덜 관련된 내용이 쌓여 모델 성능이 떨어지는 현상.
서브에이전트는 노이즈가 많은 작업을 메인 스레드 바깥으로 빼서 이 문제를 완화합니다. 읽기 전용 코드베이스 탐색, 테스트 로그 분석, 문서 요약 같은 작업에 특히 효과적입니다. 그런데 쓰기 작업을 병렬로 돌릴 때는 오히려 문제가 생깁니다.
서로 다른 서브에이전트가 연관된 파일을 동시에 수정하면 “시맨틱 드리프트”가 생깁니다. 에이전트 A가 함수 파라미터명을 바꾸는 동안 에이전트 B는 원래 파라미터명으로 새 호출 코드를 작성합니다. 구문 충돌(merge conflict)은 메인 에이전트가 잡아내지만, 의미 충돌은 놓칩니다. 테스트가 통과해도 동작이 틀릴 수 있습니다.
💡 병렬 실행의 효과가 생각과 다를 수 있는 이유
읽기 중심 작업(탐색, 요약, 분석)은 병렬화 효과가 크고 충돌 위험이 낮습니다. 반면 쓰기 중심 작업(구현, 리팩토링)은 서브에이전트 수를 줄이거나 순차적으로 연결하는 방식이 안전합니다. 공식 문서도 “쓰기 중심 병렬 워크플로우는 더 신중하게 접근하라”고 명시했습니다.
Codex vs Claude Code 에이전트 팀 — 아키텍처가 근본적으로 다릅니다
Codex 서브에이전트와 Claude Code 에이전트 팀은 둘 다 “여러 에이전트를 병렬로 쓴다”는 점은 같지만, 격리 방식과 안전 모델이 완전히 다릅니다. 이 차이를 모르면 용도를 잘못 선택합니다.
| 항목 | Codex 서브에이전트 | Claude Code 에이전트 팀 |
|---|---|---|
| 격리 방식 | 클라우드 컨테이너 샌드박스 (커널 레벨) | git worktree (로컬 머신) |
| 에이전트 간 통신 | 없음 (결과는 메인이 수집) | 직접 메시지 + 브로드캐스트 |
| 안전 경계 | OS가 syscall 차단 (우회 불가) | 애플리케이션 훅 (17개 이벤트) |
| 컨텍스트 창 | 1M 토큰 (GPT-5.4 기준) | 200K 토큰 (Opus 4.6 기준) |
| 작업 추적 | 독립 스레드, /agent 명령으로 전환 | 공유 태스크 목록 + 의존성 추적 |
출처: blakecrosley.com/blog/codex-vs-claude-code-2026 (2026.03.10), morphllm.com/comparisons/codex-vs-claude-code
Codex는 OS 커널이 직접 파일 접근과 네트워크를 막습니다. 외부에서 받은 코드나 신뢰하기 어려운 스크립트를 리뷰할 때 강점이 있습니다. Claude Code 에이전트 팀은 훅 스크립트로 세밀한 규칙을 적용할 수 있지만, 훅이 에이전트와 같은 프로세스 경계 안에 있어 커널 수준의 차단력은 없습니다.
비용 측면에서는 동일 작업 기준으로 Claude Code가 Codex보다 토큰을 3.2~4.2배 더 사용합니다.
Figma 플러그인 빌드 기준 Codex 1,499,455 토큰 vs Claude 6,232,242 토큰 (4.2배 차이). 스케줄러 앱 기준 Codex 72,579 토큰 vs Claude 234,772 토큰 (3.2배 차이).
(출처: morphllm.com/comparisons/codex-vs-claude-code)
Claude가 더 많은 토큰을 쓰는 건 낭비가 아니라 더 꼼꼼히 생각하는 방식 때문입니다. 어떤 게 유리한지는 작업 성격에 따라 갈립니다.
실제로 쓸 만한 상황, 쓰면 안 되는 상황
서브에이전트는 모든 작업을 빠르게 처리하는 만능 도구가 아닙니다. 잘 맞는 작업과 오히려 문제를 키우는 작업이 뚜렷이 갈립니다.
✅ 서브에이전트가 잘 맞는 작업
- 테스트 코드 대량 생성 (모듈 단위로 분리 가능)
- 코드베이스 전체 탐색 후 요약
- PR 보안·품질·스타일 동시 점검
- 독립적인 파일들의 문서화 일괄 처리
- CSV 기반 반복 작업 (spawn_agents_on_csv)
❌ 서브에이전트를 쓰면 안 되는 상황
- 서로 의존하는 파일을 동시 수정
- DB 스키마나 API 계약 변경
- 인프라 코드(Terraform 등) 수정
- 예산 상한 없이 장시간 자율 실행
- 신규 아키텍처 설계나 복잡한 디버깅
비용 관리 측면에서 처음 시작할 때 권장하는 설정이 있습니다. 공식 문서 기준으로 agents.max_threads는 2~3으로 낮추고, agents.max_depth는 기본값 1을 유지하는 게 안전합니다. explorer 에이전트에는 gpt-5.4-mini를 쓰고, 실제 구현이나 리뷰 에이전트에만 gpt-5.4를 배정하면 비용 차이가 상당히 납니다.
실제로 성과를 낸 팀들의 패턴도 뚜렷합니다. 테스트 커버리지 개선, 의존성 업데이트, TODO 클리어 같은 반복적이고 잘 정의된 작업에 먼저 적용하고, 그 결과를 리뷰하면서 신뢰도를 쌓은 뒤 확장하는 방식입니다.
💡 성공 사례 데이터를 실제 설정값과 대조해 보니 나온 패턴
초기 도입팀의 테스트 커버리지 60~80% 개선 수치(aimagicx.com, 2026.03)는 전부 ‘잘 정의된 단일 작업 유형’에 집중한 사례입니다. 범위가 모호하거나 상호 의존도가 높은 작업에 동일한 설정을 적용했을 때 성공률은 15~30% 수준으로 떨어집니다. 기능의 강력함은 작업 범위를 얼마나 좁게 잡느냐에 달려 있습니다.
Q&A — 자주 묻는 5가지
마치며 — Codex CLI 서브에이전트, 쓰기 전에 알아야 할 것
Codex CLI 서브에이전트는 2026년 3월 16일 정식 출시된 기능입니다. 병렬 실행 구조 덕분에 대규모 테스트 작성, 코드베이스 탐색, 반복 리뷰 작업에서 실질적인 속도 향상을 기대할 수 있습니다.
다만 속도 향상에는 반드시 비용이 따릅니다. Pro 플랜 일주일 만에 $350 초과라는 실제 사례가 공식 GitHub Issues에 올라와 있을 정도로, 설정 없이 쓰다간 비용 폭탄을 맞습니다. 처음에는 max_threads를 2~3으로 낮추고, 읽기 전용 탐색 작업부터 시험해보는 게 맞습니다.
IDE 확장 지원이 아직 완료되지 않았고, 에이전트별 사후 비용 내역 기능도 빠져 있습니다. 기능이 강력한 만큼 아직 다듬어지는 중입니다. 지금 당장 최대치로 쓰기보다는, 작업 범위를 좁게 잡고 신뢰를 쌓으면서 단계적으로 넓혀가는 방식이 현실적입니다.
📚 본 포스팅 참고 자료
- OpenAI Developers — Subagents (developers.openai.com/codex/subagents)
- OpenAI Developers — Subagent Concepts (developers.openai.com/codex/concepts/subagents)
- Simon Willison — Use subagents and custom agents in Codex (2026.03.16)
- GitHub Issues #12488 — Sub-agent costs are too high and too opaque (2026.02.21)
- MorphLLM — Codex vs Claude Code Benchmark Comparison (2026)
- Blake Crosley — Codex CLI vs Claude Code in 2026: Architecture Deep Dive (2026.03.10)
본 포스팅은 2026년 3월 31일 기준으로 작성되었습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 최신 내용은 OpenAI 공식 문서(developers.openai.com/codex)를 통해 확인하시기 바랍니다.
댓글 남기기