Codex CLI 최신 버전
Codex CLI 서브에이전트, 6개 넘으면 막힙니다
결론부터 말씀드리면, Codex CLI 서브에이전트의 기본 병렬 한도는 6개입니다. 20개를 한 번에 요청하면 6개만 생성되고 나머지 14개는 그냥 실패로 처리됩니다. 2026년 3월 16일 정식 출시된 이 기능, 쓰기 전에 구조부터 이해하는 게 낫습니다.
서브에이전트가 뭔데 이렇게 화제인가요
Codex CLI 서브에이전트는 한마디로, 하나의 주 에이전트가 필요에 따라 전문화된 하위 에이전트를 여러 개 동시에 띄워서 작업을 나눠 처리하는 구조입니다. 2026년 3월 16일 정식 출시됐고, 출시 이틀 뒤인 3월 17일 커뮤니티에서 136개 서브에이전트 정의를 담은 오픈소스 컬렉션 awesome-codex-subagents가 공개됐습니다. 9일 만에 GitHub Stars 2,778개를 기록했습니다.
기존 단일 에이전트 방식은 보안 검토·코드 품질·버그 탐색을 순서대로 처리했습니다. 서브에이전트는 이 세 가지를 동시에 별도 컨텍스트 창에서 돌립니다. 공식 문서에 나온 표현을 그대로 옮기면 “codebase exploration or implementing a multi-step feature plan” 같은 고도로 병렬화 가능한 작업에 특히 효과적이라고 나와 있습니다. (출처: OpenAI Codex 공식 개발자 문서, developers.openai.com/codex/subagents)
중요한 전제 하나 — Codex는 사용자가 명시적으로 요청할 때만 서브에이전트를 생성합니다. 알아서 분기하지 않습니다. “PR 리뷰 포인트마다 에이전트 하나씩 만들어서 기다렸다가 결과 요약해줘”처럼 직접 지시해야 동작합니다.
6개 한도, 그냥 넘기면 안 되는 이유
가장 많이 놓치는 부분입니다. Codex CLI 서브에이전트의 동시 실행 한도(agents.max_threads)는 기본값이 6입니다. 공식 문서에 “defaults to 6 when you leave it unset”이라고 정확히 나와 있습니다. (출처: OpenAI Codex 공식 개발자 문서, developers.openai.com/codex/subagents)
💡 공식 발표문과 실제 사용 흐름을 같이 놓고 보니 이런 차이가 보였습니다
실사용자가 서브에이전트 20개를 동시에 요청한 결과, 6개만 생성되고 14개는 실패로 처리됐습니다. M5 맥북 프로(CPU 15코어)에서 벌어진 일입니다. 하드웨어 사양과 무관하게 소프트웨어 설정값이 상한을 결정합니다. (출처: Shane Park 티스토리, 2026.03.20)
한도를 늘리고 싶다면 ~/.codex/config.toml에 직접 추가하면 됩니다.
[agents] max_threads = 12 # 원하는 숫자로 조정 max_depth = 1 # 기본값 유지 권장
단, max_depth는 기본값 1을 건드리지 않는 쪽을 권합니다. 공식 문서는 “Raising this value can turn broad delegation instructions into repeated fan-out, which increases token usage, latency, and local resource consumption”이라고 명시합니다. 깊이를 올리면 토큰이 기하급수적으로 늘어납니다.
| 설정값 | 기본값 | 변경 시 주의사항 |
|---|---|---|
max_threads |
6 | 높일수록 로컬 메모리·토큰 소비 증가 |
max_depth |
1 | 올리면 재귀 fan-out 위험, 변경 비권장 |
job_max_runtime_seconds |
1800초 | CSV 배치 작업 기본 타임아웃 |
빌트인 3종 세트, 역할이 다 다릅니다
Codex CLI는 서브에이전트 기능과 함께 3가지 빌트인 에이전트를 제공합니다. 커스텀 에이전트를 만들기 전에 이 기본값부터 파악해야 불필요한 설정 중복을 피할 수 있습니다.
범용 폴백 에이전트. 별도 지시 없으면 이게 기준입니다. 읽기·쓰기 모두 가능합니다.
구현·수정 전용입니다. 실제로 코드를 건드려야 하는 작업에 할당합니다. 실행 중심 설계입니다.
읽기 전용 탐색 에이전트입니다. 코드베이스 분석, 증거 수집만 합니다. 파일을 건드리지 않습니다.
공식 문서의 PR 리뷰 예제에서는 pr_explorer를 sandbox_mode = "read-only"로 설정하고, reviewer에는 GPT-5.4(high reasoning), docs_researcher에는 GPT-5.4-mini(medium reasoning)를 씁니다. 역할마다 모델을 달리 붙일 수 있습니다. 비용 조절에 직접 영향을 미치는 부분입니다.
커스텀 에이전트를 만들 때는 ~/.codex/agents/(개인용) 또는 .codex/agents/(프로젝트용) 경로에 TOML 파일 하나로 정의합니다. name, description, developer_instructions 세 필드가 필수입니다. 커스텀 에이전트 이름이 빌트인과 겹치면 커스텀이 우선합니다.
서브에이전트 쓸수록 토큰이 더 나간다는 것
대부분이 놓치는 지점입니다. 서브에이전트를 병렬로 쓰면 속도가 빨라지는 건 맞지만, 토큰 소비는 단일 에이전트보다 늘어납니다. OpenAI 공식 문서에 이렇게 나와 있습니다: “subagent workflows consume more tokens than comparable single-agent runs.” (출처: OpenAI Codex Subagents 공식 문서, developers.openai.com/codex/subagents)
💡 빠르게 끝난다고 저렴한 건 아닙니다
각 서브에이전트는 자신만의 컨텍스트 창을 갖습니다. 6개가 동시에 돌면 컨텍스트 처리 비용도 6배에 가깝게 발생합니다. 속도와 비용은 트레이드오프 관계입니다.
이게 중요한 이유는 ChatGPT Pro 플랜과 Codex 사용량 구조 때문입니다. 실사용자 비교 기준으로, Claude Code Max x20 플랜과 ChatGPT Pro의 Codex 사용량 차이가 3~4배 수준이라는 커뮤니티 데이터가 있습니다. 서브에이전트를 무제한으로 돌리면 예상보다 빠르게 사용량 한도에 닿습니다.
비용을 통제하는 가장 실용적인 방법은 역할별로 모델을 다르게 붙이는 것입니다. 읽기 전용 탐색 에이전트에는 GPT-5.3-Codex-Spark(빠르고 가벼움), 실제 코드 수정 에이전트에는 GPT-5.4(정확도 우선) 식으로 나누면 불필요한 heavy 모델 호출을 줄일 수 있습니다. 이 구조가 공식 문서 PR 리뷰 예제에서 그대로 쓰이고 있습니다.
CSV 배치 처리, 이건 진짜 실용적입니다
기존 블로그 대부분이 PR 리뷰 예제만 언급하고 지나가는 기능이 있습니다. spawn_agents_on_csv입니다. CSV 파일 한 행당 서브에이전트 하나를 생성해서 배치로 처리하고, 결과를 다시 CSV로 내보냅니다.
💡 단순 병렬이 아니라 구조화된 결과를 받을 수 있습니다
각 서브에이전트가 report_agent_job_result를 정확히 1번 호출해야 합니다. 호출 없이 종료되면 해당 행은 에러로 표시됩니다. 이 규칙을 모르면 결과가 왜 빠졌는지 한참 헤맵니다.
실용적인 쓰임새를 예를 들면, 프론트엔드 컴포넌트 50개를 한 번에 코드 품질 검토할 때입니다. CSV 컬럼을 path, owner로 만들고 아래처럼 지시하면 됩니다.
spawn_agents_on_csv with:
- csv_path: /tmp/components.csv
- id_column: path
- instruction: "Review {path} owned by {owner}. Return JSON
with keys path, risk, summary, follow_up via
report_agent_job_result."
- output_csv_path: /tmp/components-review.csv
- output_schema: an object with required string fields
path, risk, summary, follow_up
출력 CSV에는 원본 행 데이터에 job_id, item_id, status, last_error, result_json 메타데이터가 추가됩니다. 기본 타임아웃은 워커당 1800초(30분)입니다. 이 기능은 공식 문서에서 “experimental”로 표기되어 있고 포맷이 바뀔 수 있습니다. (출처: OpenAI Codex 공식 개발자 문서, developers.openai.com/codex/subagents)
Claude Code 서브에이전트와 뭐가 다른가요
같은 서브에이전트 개념이지만 실제로 써보면 구조가 다릅니다. Claude Code는 병렬 상한이 명시적 설정값으로 관리되지 않습니다. 실사용자 기준으로 20개 이상을 동시에 요청해도 동시에 돌아가는 걸 확인한 사례가 있습니다. (출처: Shane Park 티스토리, 2026.03.20) 반면 Codex CLI는 max_threads 6이 기본 상한으로 걸려 있습니다.
| 항목 | Codex CLI | Claude Code |
|---|---|---|
| 병렬 한도 기본값 | 6개 (설정 변경 가능) | 명시 상한 없음 (실사용 20개+ 확인) |
| 에이전트 정의 방식 | TOML 파일 (에이전트별 1파일) | SKILL.md / 서브에이전트 지시 방식 |
| 빌트인 에이전트 | 3종 (default/worker/explorer) | 공식 별도 빌트인 없음 |
| CSV 배치 처리 | spawn_agents_on_csv 공식 지원 | 공식 지원 없음 |
| IDE 서브에이전트 가시성 | 앱·CLI 지원, IDE 확장 예정 | Claude Code 인터페이스 내 표시 |
성능 면에서 GPT-5.3-Codex는 Terminal-Bench 2.0 기준 77.3%를 기록했습니다. 이전 버전 GPT-5.2-Codex의 64.0%와 비교하면 13.3%p 차이입니다. (출처: OpenAI GPT-5.3-Codex 공식 소개 페이지, 2026.02.05) 터미널 작업 정확도가 단순히 조금 높아진 게 아니라, 복잡한 멀티스텝 태스크에서 실질적으로 체감되는 수준의 차이입니다.
Q&A
Q1. 서브에이전트 한도를 6개보다 많이 올리면 문제가 생기나요?
설정값 자체는 올릴 수 있습니다. 다만 공식 문서는 토큰 소비 증가, 레이턴시 증가, 로컬 리소스 소비 증가를 명시적으로 경고합니다. 특히 max_depth를 1 이상으로 올리면 에이전트가 재귀적으로 분기하면서 예상보다 훨씬 많은 토큰이 나갈 수 있습니다.
Q2. 서브에이전트가 자동으로 생성되는 경우가 있나요?
없습니다. Codex는 사용자가 명시적으로 요청할 때만 서브에이전트를 생성합니다. 공식 문서에 “Codex only spawns a new agent when you explicitly ask it to do so”라고 나와 있습니다. 자동 분기는 지원하지 않습니다.
Q3. 커스텀 에이전트 이름이 빌트인과 겹치면 어떻게 되나요?
커스텀 에이전트가 우선합니다. 예를 들어 explorer라는 이름으로 커스텀 TOML을 만들면, 빌트인 explorer 대신 커스텀 정의가 적용됩니다. 의도하지 않은 덮어쓰기를 조심해야 합니다.
Q4. IDE 확장에서는 서브에이전트가 안 보이나요?
현재(2026.03.16 기준) 서브에이전트 가시성은 Codex 앱과 CLI에서만 지원됩니다. IDE 확장에서의 표시는 “coming soon”으로 공식 문서에 예고되어 있습니다. 출시 시점은 공식 발표를 확인해야 합니다.
Q5. CSV 배치 처리에서 에이전트가 결과를 보내지 않으면 어떻게 되나요?
report_agent_job_result를 호출하지 않고 서브에이전트가 종료되면, 해당 행은 출력 CSV에서 에러로 표시됩니다. 결과 누락이 발생할 수 있으니 커스텀 에이전트 작성 시 이 호출을 반드시 포함해야 합니다.
마치며
Codex CLI 서브에이전트는 병렬 코딩 작업의 상한을 끌어올리는 기능임은 맞습니다. 하지만 “많이 쓸수록 빠르고 효율적”이라는 말이 전부는 아닙니다. 기본 6개 한도, 토큰 소비 증가, max_depth의 재귀 위험 — 이 세 가지를 모르고 쓰면 생각보다 빠르게 사용량 한도에 닿거나, 비용이 올라가거나, 실패한 에이전트 14개를 보고 당황하게 됩니다.
솔직히 말하면, 지금 시점에서 서브에이전트가 가장 빛나는 쓰임새는 PR 리뷰나 반복 감사처럼 명확하게 병렬화할 수 있는 작업입니다. 단순한 코드 수정이나 대화형 작업에 억지로 서브에이전트를 끼워 넣으면 오히려 토큰만 낭비합니다. CSV 배치 처리(spawn_agents_on_csv)는 아직 experimental이지만, 파일 단위 대규모 감사에서는 실제로 시간을 크게 단축할 수 있는 기능입니다.
기능이 나온 지 2주도 안 됐습니다. 포맷은 계속 바뀔 수 있고, IDE 확장 지원도 아직 예고 단계입니다. 공식 문서를 직접 확인하면서 따라가는 게 가장 안전합니다.
📚 본 포스팅 참고 자료
⚠️ 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 본 포스팅은 2026년 3월 16일 Codex CLI 서브에이전트 정식 출시 기준으로 작성됐습니다. OpenAI는 서브에이전트 관련 기능을 “experimental”로 표기하고 있으며, CSV 배치 처리 포맷 등은 향후 업데이트로 달라질 수 있습니다. 최신 내용은 OpenAI 공식 개발자 문서에서 확인하시기 바랍니다.
댓글 남기기