서브에이전트가 뭔지 먼저 확인했습니다

결론부터 말씀드리면, 서브에이전트는 자동으로 켜지지 않습니다. “parallel”, “spawn two agents”, “use one agent per point”처럼 병렬 작업을 직접 요청해야만 에이전트가 스폰됩니다. (출처: OpenAI Codex 공식 문서 — Subagents, 2026.03)

이게 중요한 이유는, 많은 사람이 ‘서브에이전트 기능이 켜졌으니 Codex가 알아서 병렬화하겠지’라고 기대한다는 점입니다. 실제로는 그렇지 않습니다. 직접 지시하지 않으면 단일 에이전트로만 동작합니다.

Codex는 메인 에이전트 하나가 오케스트레이터 역할을 하고, 서브에이전트들은 탐색·리뷰·수정 등 역할을 나눠 병렬로 처리합니다. 완료되면 결과를 메인 에이전트가 취합해서 돌려줍니다. 기본 빌트인 에이전트는 세 가지입니다: default(범용), worker(구현·수정), explorer(읽기 전용 탐색).

▲ 목차로 돌아가기

6개 한도, 줄어든 이유가 있었습니다

기본 동시 실행 한도는 6개입니다. 그런데 이 숫자, 처음부터 6개가 아니었습니다. Codex CLI v0.91.0 이전에는 12개였다가 절반으로 줄었습니다. (출처: Blake Crosley — Codex 완전 레퍼런스)

12개에서 6개로 줄인 공식 이유는 OpenAI가 별도로 발표하지 않았습니다. 다만 GitHub Issues에서 “동시 서브에이전트 실행이 Pro 플랜 5시간 쿼터를 순식간에 소진한다”는 버그 리포트가 2026년 1월부터 이어진 게 배경으로 보입니다. 즉, 한도 절반 축소는 사용자 보호 차원의 조치에 가깝습니다.

이런 맥락을 모르면 “왜 6개밖에 안 되지?”에서 끝납니다. 하지만 실상은 6개도 쿼터 소진 속도가 예상보다 훨씬 빠릅니다. 이 부분은 섹션 5에서 따로 다룹니다.

▲ 목차로 돌아가기

한도를 직접 늘리는 방법 — config.toml 설정

6개가 부족하다면 ~/.codex/config.toml을 직접 수정하면 됩니다. 공식 문서에 agents.max_threads를 설정으로 조정할 수 있다고 명시되어 있습니다. (출처: OpenAI Codex 공식 문서 — Subagents Configuration, 2026.03)

[agents]
max_threads = 12   # 기본값 6 → 원하는 숫자로
max_depth = 1      # 서브에이전트의 재귀 깊이 (기본값 1 권장)
# job_max_runtime_seconds = 1800  # 워커 타임아웃, 기본 1800초

파일이 없으면 mkdir -p ~/.codex로 폴더를 만들고 새로 작성하면 됩니다. 프로젝트마다 다르게 쓰고 싶다면 레포 루트의 .codex/config.toml에 같은 내용을 작성하면 되고, 프로젝트 설정이 글로벌 설정보다 우선합니다.

실제 테스트 결과: shanepark.tistory.com의 2026년 3월 20일 포스팅에 따르면, max_threads를 25로 설정 후 20개 서브에이전트를 요청했을 때 실제로 20개가 동시에 실행되는 것을 확인했습니다. 기본값 6을 유지한 채 20개를 요청하면 6개만 생성되고 나머지 14개는 생성 실패 상태가 됩니다.

▲ 목차로 돌아가기

모델별로 쪼개 쓰면 토큰이 아껴집니다

여기가 기존 블로그 포스팅에서 거의 다루지 않는 부분입니다. 공식 발표문과 실제 사용 흐름을 같이 놓고 보니 이런 차이가 보였습니다 — 서브에이전트마다 모델을 다르게 설정하는 게 기본값으로 두는 것보다 실질적으로 토큰을 아낍니다.

공식 문서에 따르면, 각 커스텀 에이전트 파일 (~/.codex/agents/)에 model과 model_reasoning_effort를 따로 지정할 수 있습니다. (출처: OpenAI Codex 공식 문서 — Custom Agents, 2026.03)

공식 문서에 명시된 수치입니다: “gpt-5.4-mini로 전환하면 로컬 메시지 사용 한도가 약 2.5~3.3배 늘어납니다.” (출처: OpenAI Codex Pricing, 2026.03) 탐색 전용 서브에이전트에 굳이 gpt-5.4를 쓸 이유가 없다는 뜻입니다.

name = "explorer"
description = "읽기 전용 코드베이스 탐색 에이전트"
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
sandbox_mode = "read-only"
developer_instructions = """
탐색 모드만 유지하세요.
실제 실행 경로를 추적하고 파일과 심볼을 인용하세요.
수정은 제안하지 마세요.
"""

▲ 목차로 돌아가기

Pro 플랜 쿼터가 즉시 소진되는 경우

이게 현재 가장 조심해야 할 부분입니다. Pro 플랜 기준, 서브에이전트 6개를 동시에 실행하면 5시간 쿼터가 순식간에 100% 소진될 수 있습니다. 2026년 1월부터 GitHub Issues에 동일한 현상의 버그 리포트가 이어지고 있고, OpenAI는 아직 공식 답변을 내놓지 않은 부분입니다.

공식 문서에도 “서브에이전트 워크플로우는 각 서브에이전트가 자체 모델과 툴 작업을 수행하므로 단일 에이전트 실행보다 더 많은 토큰을 소비합니다”라고 명시되어 있습니다. (출처: OpenAI Codex 공식 문서) 단일 에이전트 대비 토큰 소비량이 에이전트 수에 비례해서 증가하는 구조입니다.

현실적인 사용 권장 방법: Plus 기준 GPT-5.4로 로컬 메시지 5시간당 33~168개, Pro 기준 223~1,120개가 할당됩니다. (출처: OpenAI Codex Pricing, 2026.03) 서브에이전트 6개를 한 번에 돌리면 이 범위의 상단치를 단 한 턴에 소진할 수 있습니다. 쿼터 여유가 없다면 탐색 에이전트에 gpt-5.4-mini를 쓰거나, 동시 에이전트 수를 2~3개로 줄이는 편이 안전합니다.

▲ 목차로 돌아가기

CSV 팬아웃 — 아직 알려지지 않은 기능

공식 문서에 들어있는데 한국어 포스팅으로는 아직 정리된 글이 없는 기능입니다. spawn_agents_on_csv라는 도구로, CSV 파일 한 행당 서브에이전트 하나를 스폰해서 배치 처리를 자동화합니다. (출처: OpenAI Codex 공식 문서 — spawn_agents_on_csv, 2026.03)

예를 들어 프런트엔드 컴포넌트 목록이 담긴 CSV가 있다면, 컴포넌트마다 에이전트 하나씩 붙여서 보안·품질·테스트 커버리지를 병렬 점검하고 결과를 다시 CSV로 내보낼 수 있습니다. 수십 개 파일을 순차적으로 처리하는 대신 동시에 처리하는 구조입니다.

/tmp/components.csv 파일을 만들어줘.
columns: path, owner
프런트엔드 컴포넌트마다 한 행씩.
그다음 spawn_agents_on_csv를 호출해줘:
- csv_path: /tmp/components.csv
- id_column: path
- instruction: "{path}를 {owner} 기준으로 리뷰해줘.
JSON으로 path, risk, summary, follow_up을 반환해."
- output_csv_path: /tmp/review.csv

결과는 output_csv_path에 지정한 파일로 자동 저장됩니다. 각 행에 status, result_json, last_error 같은 메타데이터도 포함됩니다. 워커 타임아웃은 기본 1,800초이며 max_runtime_seconds로 조정 가능합니다.

▲ 목차로 돌아가기

Q&A

▲ 목차로 돌아가기

마치며

Codex CLI 서브에이전트는 분명히 강력한 기능입니다. PR 리뷰를 6개 에이전트로 쪼개서 동시에 돌리면 시간을 크게 아낄 수 있습니다. 그런데 막상 써보면 두 가지가 먼저 발목을 잡습니다 — 6개 한도와 쿼터 폭주.

핵심을 정리하면 이렇습니다: 서브에이전트는 명시적으로 요청해야만 작동하고, 6개 한도는 config.toml 한 줄로 늘릴 수 있지만, 늘릴수록 쿼터 소진 속도도 함께 늘어납니다. 탐색 에이전트에 gpt-5.4-mini를 붙이는 것만으로 토큰을 2.5배 이상 아낄 수 있고, CSV 팬아웃 기능은 대규모 배치 작업에서 진가가 드러납니다.

아직 실험적 기능이라 릴리스마다 동작이 바뀔 수 있습니다. 쓰기 전에 /status로 남은 쿼터를 먼저 확인하는 습관이 필요합니다.

▲ 목차로 돌아가기

📌 본 포스팅 참고 자료

1. OpenAI Codex 공식 문서 — Subagents (2026.03)
2. OpenAI Codex 공식 문서 — Pricing (2026.03)
3. OpenAI Codex 공식 문서 — Subagent Concepts (2026.03)
4. GitHub openai/codex Issues #9748 — Subagent usage quota drain (2026.01.22)
5. GitHub openai/codex Issues #9833 — Subagent Pro plan usage drain (2026.01.24)
6. GitHub openai/codex Issues #11965 — MAX_THREADS configurable request (2026.02.16)
7. shanepark.tistory.com — Codex 서브에이전트 최대 스레드 수 늘리기 (2026.03.20)
8. Blake Crosley — Codex CLI 완전 레퍼런스 (한국어)