Codex CLI v0.117.0~0.118.0
Codex CLI 서브에이전트,
써도 되는 조건 있습니다
병렬 실행이라 빠를 거라고 생각했는데, 막상 써보면 Pro 플랜 주간 한도를 이틀 안에 날리는 경우가 생깁니다. OpenAI 공식 문서와 실제 이슈 트래커에서 확인한 조건과 비용 구조를 그대로 정리했습니다.
서브에이전트가 뭔지 먼저 짚고 가겠습니다
Codex CLI 서브에이전트는 2026년 3월 16일 v0.117.0에 정식 탑재된 기능입니다. 메인 에이전트가 특정 작업을 나눠서 여러 전문화된 하위 에이전트에게 동시에 넘기고, 결과를 모아 하나의 답변으로 돌려주는 구조입니다. (출처: OpenAI Codex 공식 changelog, 2026.03.26)
기존에는 하나의 에이전트가 순차적으로 보안 검토 → 코드 품질 확인 → 버그 탐색을 처리했습니다. 서브에이전트를 쓰면 세 작업이 동시에 돌아가고, 메인 스레드는 지저분한 중간 출력 없이 요약본만 받습니다. 이걸 공식 문서는 “context pollution(컨텍스트 오염)”을 막는 방법이라고 설명합니다.
Codex에는 기본 내장 에이전트 3종이 있습니다. default(범용), worker(실행·수정 집중), explorer(읽기 중심 탐색)입니다. 여기에 TOML 파일로 커스텀 에이전트를 만들어 붙일 수 있습니다. (출처: OpenAI 공식 서브에이전트 문서)
💡 공식 발표문과 실제 사용자 이슈 리포트를 함께 놓고 보니 중요한 차이가 보였습니다. 공식 문서는 서브에이전트가 “컨텍스트를 깨끗하게 유지한다”는 장점을 강조하지만, 토큰 소비가 증가한다는 사실은 주석 수준으로만 언급합니다.
병렬이면 빠를 텐데, 왜 비용이 더 나올까요
서브에이전트가 빠르다는 말은 맞습니다. 벽시계 기준 실행 시간은 줄어듭니다. 문제는 토큰 총량입니다. 각 서브에이전트는 독립적으로 모델을 호출하고 도구 작업을 수행합니다. 에이전트 3개를 병렬로 돌리면 단일 실행 대비 토큰 소비가 2배에서 5배까지 늘어날 수 있습니다.
⚠️ 실제 사례 — GitHub Issue #12488
OpenAI Codex 공개 이슈 트래커(2026.02.21)에 Pro 플랜 사용자가 올린 내용입니다. 서브에이전트를 일상적으로 사용한 결과, 한 주 만에 Pro 플랜 한도를 $350 이상 초과했습니다. “에이전트가 시작되기 전에 비용 추정치가 전혀 보이지 않았고, 실행 중에도 서브에이전트별 소비량을 확인할 방법이 없었다”고 밝혔습니다. 비용 가시성이 없는 채 기능만 먼저 공개된 구조였습니다.
공식 문서도 이 점을 인정합니다. “각 서브에이전트는 자체 모델 및 도구 작업을 수행하기 때문에, 서브에이전트 워크플로는 동등한 단일 에이전트 실행보다 더 많은 토큰을 소비합니다.” (출처: OpenAI 서브에이전트 개념 문서, developers.openai.com/codex/subagents) 빠르다는 장점이 비싸다는 단점과 세트로 온다는 뜻입니다.
그뿐만 아니라 agents.max_depth를 기본값인 1에서 올리면 서브에이전트가 또 다른 서브에이전트를 낳는 재귀 구조가 만들어집니다. 공식 문서는 “광범위한 위임 지시가 반복적인 팬아웃으로 이어질 수 있다”며 기본값 유지를 강하게 권고하고 있습니다.
공식 문서에서 꺼낸 기본값 3가지
Codex CLI 서브에이전트를 결정하는 핵심 설정값이 3가지 있습니다. 모두 .codex/config.toml의 [agents] 섹션에 들어갑니다.
| 설정값 | 기본값 | 의미 |
|---|---|---|
agents.max_threads |
6 | 동시에 열 수 있는 에이전트 스레드 최대치 |
agents.max_depth |
1 | 서브에이전트가 또 서브에이전트를 낳는 깊이 제한 |
agents.job_max_runtime_seconds |
1,800초 | CSV 팬아웃 작업 시 서브에이전트 1개당 최대 실행 시간 |
💡 max_depth가 기본값 1인 이유를 공식 문서가 명확하게 밝히고 있는데, 기존 블로그들은 그냥 지나칩니다. 이 값을 올리면 에이전트가 재귀적으로 증식하면서 토큰 소비와 지연이 예측 불가능해집니다. max_threads는 동시 스레드를 막아주지만, 재귀 자체는 막지 못합니다. 두 값이 함께 작동해야 비용을 통제할 수 있습니다. (출처: OpenAI 서브에이전트 공식 문서)
max_threads 기본값 6은 한 세션에서 동시에 6개 에이전트가 돌 수 있다는 뜻입니다. GPT-5.4 기준 에이전트 1개의 입출력 비용이 수백 토큰 단위라는 점을 생각하면, 복잡한 작업을 6개에 맡기는 순간 단일 실행 대비 토큰 소비가 몇 배로 뛰는 구조입니다.
쓰기 작업에서 조심해야 하는 이유
서브에이전트는 읽기 중심 탐색 작업에서 제 값을 합니다. 반면 여러 에이전트가 동시에 파일을 수정하는 쓰기 작업에서는 충돌이 납니다. 공식 문서는 이 부분을 정확하게 경고합니다. “병렬 쓰기 중심 워크플로는 에이전트가 동시에 코드를 편집하면서 충돌이 생기고 조율 오버헤드가 커진다.” (출처: OpenAI 서브에이전트 개념 문서)
실제로 CLI에서 비활성 에이전트 스레드로부터 승인 요청이 갑자기 떠오르는 상황도 공식 문서에서 명시합니다. 메인 스레드를 보고 있는 동안 다른 스레드에서 권한 확인이 필요한 작업이 걸리면, 승인 오버레이가 어느 스레드에서 온 요청인지 표시합니다. 이를 무시하면 해당 서브에이전트 작업이 실패하고 에러가 상위 워크플로로 올라옵니다.
✅ 서브에이전트가 유리한 상황
- 코드베이스 탐색, 보안 리뷰, 테스트 커버리지 분석처럼 읽기만 하는 작업
- PR 여러 포인트를 동시에 검토해야 할 때
- 멀티 서비스 마이그레이션에서 각 서비스를 독립 탐색할 때
- 수백 개 파일에 동일한 패턴 검색이 필요한 대형 코드베이스 분석
❌ 서브에이전트가 불리한 상황
- 여러 에이전트가 같은 파일을 동시에 수정해야 하는 작업
- 실행 순서가 중요한 순차적 작업 (A 완료 후 B 시작)
- Pro 플랜 주간 한도가 이미 절반 이상 소진된 시점
모델 조합으로 비용 줄이는 실제 방법
서브에이전트마다 모델을 다르게 배정하면 비용을 줄일 수 있습니다. 공식 문서가 권장하는 조합이 TOML 예시에 그대로 나와 있습니다. (출처: OpenAI 서브에이전트 공식 문서) 직접 확인한 내용입니다.
| 에이전트 역할 | 권장 모델 | reasoning_effort |
|---|---|---|
| PR 탐색 (코드 경로 파악) | gpt-5.3-codex-spark | medium |
| 보안·버그 리뷰 (핵심 판단) | gpt-5.4 | high |
| API 문서 조회 (정보 확인) | gpt-5.4-mini | medium |
| 대용량 파일 스캔 | gpt-5.4-mini | low |
핵심은 모든 에이전트에 gpt-5.4를 쓰지 않는 것입니다. 탐색·조회처럼 정밀도보다 속도가 중요한 작업은 gpt-5.4-mini로 내리면 비용을 확 줄일 수 있습니다. ChatGPT Pro 플랜이라면 속도가 중요한 탐색 에이전트에 gpt-5.3-codex-spark를 배정하는 게 토큰 효율에서 유리합니다. 실제 비교 데이터 기준으로 Codex 전체 워크플로는 동급 Claude Code 실행 대비 약 3배 적은 토큰을 씁니다. (출처: Build Fast with AI — Claude Code vs Codex 2026 비교, 2026.03.30)
커스텀 에이전트 파일 만드는 법
커스텀 에이전트는 TOML 파일 하나로 정의합니다. 개인용은 ~/.codex/agents/에, 프로젝트용은 .codex/agents/에 넣으면 됩니다. 필수 필드는 딱 3개, name, description, developer_instructions입니다.
# .codex/agents/security-reviewer.toml name = "security_reviewer" description = "PR 보안 리뷰 전문 에이전트 — 인증, 인가, 입력 검증 위주" model = "gpt-5.4" model_reasoning_effort = "high" sandbox_mode = "read-only" developer_instructions = """ 코드 오너처럼 리뷰하세요. 인증 누락, 인가 우회, SQL 인젝션, XSS 위험에 집중하세요. 재현 가능한 단계를 포함한 구체적인 발견을 먼저 제시하세요. 스타일 지적은 실제 버그와 연관되지 않으면 생략하세요. """ nickname_candidates = ["Aegis", "Sentinel", "Argus"]
nickname_candidates는 같은 에이전트를 여러 인스턴스로 돌릴 때 TUI에 구분 이름을 보여주는 표시용 옵션입니다. 에이전트 식별은 name 필드가 기준이고, 닉네임은 화면 표시에만 씁니다. 커스텀 에이전트 이름이 내장 에이전트(explorer 등)와 겹치면 커스텀 에이전트가 우선합니다.
💡 공식 문서 예시에서 탐색 에이전트에는 sandbox_mode = "read-only"를, 수정 에이전트에는 sandbox_mode = "workspace-write"를 각각 지정하는 패턴이 보였습니다. 에이전트별 샌드박스 권한을 나눠주면, 탐색 에이전트가 실수로 파일을 바꾸는 상황 자체를 막을 수 있습니다. 비용보다 안전 문제로 더 중요한 설정입니다.
결론: 이 상황에서만 쓰는 게 맞습니다
솔직히 말하면, 서브에이전트는 막 꺼내 쓸 기능이 아닙니다. 공식 문서도 “Codex는 명시적으로 요청하지 않으면 서브에이전트를 자동으로 생성하지 않는다”고 못 박아두고 있습니다. 이 제약이 오히려 합리적인 이유는, 사용자가 의도하지 않은 팬아웃 비용 폭증을 막기 위해서입니다.
PR 리뷰 포인트가 6개 이상이고 각 포인트가 독립적으로 판단 가능한 상황, 혹은 멀티 서비스 코드베이스에서 서비스별 읽기 분석이 필요한 상황이라면 서브에이전트가 분명히 시간을 아껴줍니다. 반대로 작은 기능 하나를 빠르게 구현하거나 단일 파일 디버깅이 필요하다면, 단일 에이전트가 더 저렴하고 예측 가능합니다.
실전 체크리스트 — 서브에이전트 쓰기 전
- 작업이 병렬로 독립 실행 가능한가? (읽기 위주인가?)
agents.max_threads와agents.max_depth를 config에 명시했는가?- 각 에이전트에 적절한 모델을 배정했는가? (전부 gpt-5.4 아닌가?)
- 탐색 에이전트에
sandbox_mode = "read-only"를 지정했는가? - 이번 주 Pro 플랜 잔여 한도가 충분한가?
개인적으로는 config에 max_threads = 3으로 잡아두는 걸 추천합니다. 기본값 6에서 절반으로 줄이면 예상 밖의 비용 충격을 상당 부분 막을 수 있고, 대부분의 PR 리뷰 시나리오에서 3개면 충분합니다. OpenAI가 공식 비용 대시보드를 서브에이전트별로 세분화하기 전까지는 이 보수적인 설정이 가장 안전합니다.
자주 묻는 질문 Q&A
마치며
Codex CLI 서브에이전트는 기능 자체는 쓸 만합니다. PR 6개 포인트를 병렬로 돌리거나, 대형 모노레포를 서비스 단위로 쪼개서 동시에 탐색하는 시나리오에서 체감 속도가 확연히 다릅니다.
다만 무심코 켰다가 주간 한도를 이틀 만에 날린 사례가 공식 이슈 트래커에 버젓이 올라와 있고, OpenAI가 아직 서브에이전트별 비용 대시보드를 제공하지 않는다는 점이 아쉽습니다. 공식 문서가 말하지 않는 부분입니다.
결국 max_threads = 3, max_depth = 1로 보수적으로 잡고, 탐색용 에이전트에 gpt-5.4-mini를 배정하는 조합이 지금 단계에서 가장 현실적인 운영 방식입니다. 비용 가시성이 개선되면 그때 더 공격적으로 활용해도 늦지 않습니다.
본 포스팅 참고 자료
- OpenAI 공식 — Subagents (Codex Developer Docs)
- OpenAI 공식 — Subagent Concepts (context pollution, context rot)
- OpenAI 공식 — Codex Changelog (2026.03)
- GitHub openai/codex Issue #12488 — Sub-agent costs are too high and too opaque
- Build Fast with AI — Claude Code vs Codex: Which Terminal AI Tool Wins in 2026? (2026.03.30)
본 포스팅은 2026년 4월 2일 기준으로 작성되었습니다. Codex CLI는 버전 업데이트가 빠른 오픈소스 프로젝트로, 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 최신 정보는 공식 changelog에서 확인하세요.
댓글 남기기