Codex 서브에이전트는 메인 스레드에서 떼어 내도 되는 작업을 별도 agent thread로 보내고, 필요한 결과만 다시 받는 기능이다. 코드 검색, 테스트 실패 분류, 로그 분석, 관점별 리뷰처럼 중간 출력은 많지만 최종 판단과 분리할 수 있는 일에 특히 유용하다. 반대로 여러 agent가 같은 인터페이스와 파일을 동시에 바꿔야 한다면 병렬 실행이 오히려 조정 비용을 키운다.
현재 로컬 Codex 릴리스에서는 subagent workflow가 기본으로 활성화되어 있다. App, CLI, IDE에서 직접 위임을 요청할 수 있고, 적용되는 AGENTS.md나 skill 지시도 위임을 요구할 수 있다. 각 subagent는 별도로 모델과 도구를 사용하므로 비교 가능한 single-agent 실행보다 token 소모가 많다. OpenAI의 공식 Subagents 문서는 탐색, 테스트, triage, 요약 같은 read-heavy 작업부터 시작하고, 병렬 쓰기는 더 신중하게 다루라고 권한다.
작업을 역할이 아니라 충돌 가능성으로 나눈다
“reviewer 세 명”은 분할 기준이 아니다. 세 agent가 같은 diff를 읽고 비슷한 의견을 내면 비용만 늘고, 메인 스레드는 중복을 제거하느라 더 바빠진다. 좋은 하위 작업은 입력 범위, 완료 조건, 수정 권한, 반환 형식이 각각 다르다.
예를 들어 결제 콜백 오류를 조사한다면 다음은 어느 정도 독립적이다.
- 한 agent가 요청 진입점부터 상태 변경까지 call path를 읽는다.
- 한 agent가 관련 테스트를 실행하고 재현 가능한 실패와 환경 실패를 나눈다.
- 한 agent가 사용 중인 외부 API 계약을 직접 문서에서 확인한다.
하지만 수정은 원인이 좁혀진 뒤 하나의 worker에게 맡기는 편이 낫다. 탐색 agent 셋이 각자 다른 가설로 production code를 고치기 시작하면, 원래 버그보다 큰 diff가 생긴다.
다음 질문에 답하지 못하면 병렬화를 보류한다.
- 다른 agent의 미결정 사항 없이 끝낼 수 있는가?
- 읽기 또는 쓰기 범위가 겹치지 않는가?
- 원시 로그 대신 어떤 요약과 증거를 반환해야 하는가?
- 결과가 충돌할 때 누가 판단하는가?
프롬프트에 대기와 통합 책임까지 넣는다
직접적인 위임 요청은 아래처럼 작성할 수 있다.
text현재 branch를 main과 비교해 세 개의 subagent로 검토해 줘. - explorer: 변경된 실행 경로를 read-only로 추적 - reviewer: correctness, security, missing tests만 점검 - test_agent: 관련 test target을 실행하고 실패를 유형별로 분류 세 agent가 모두 끝날 때까지 기다려. 파일은 수정하지 마. 최종 답변은 확인된 사실, 가설, file reference, 실행 명령, 확인하지 못한 범위를 분리하고 중복 지적은 통합해 줘.
이 요청은 agent 수보다 중요한 것을 지정한다. 누가 무엇을 읽는지, 쓰기가 허용되는지, 언제 메인 스레드가 계속하는지, 어떤 증거를 같은 형식으로 돌려받는지, 최종 정리는 누가 하는지가 명확하다.
Subagent는 부모의 권한을 상속한다
로컬 subagent는 현재 sandbox 또는 permission mode를 상속한다. App과 IDE에서는 위임 전에 composer 아래의 권한 모드를 확인한다. 대화형 CLI에서는 보고 있지 않은 agent thread에서 approval이 발생할 수 있으며, overlay가 출처를 표시한다. o를 누르면 해당 thread를 열어 요청 맥락을 확인한 뒤 승인하거나 거부할 수 있다. 새 승인을 표시할 수 없는 non-interactive 실행에서는 제한된 action이 실패하고 오류가 부모 workflow로 돌아간다.
부모 turn의 live override도 spawn 시 다시 적용된다. custom agent 파일에 read-only 기본값이 있어도, 현재 부모 실행의 실제 권한 선택을 대신하지 않는다. 따라서 안전한 기본은 다음과 같다.
- explorer, reviewer, docs agent는 read-only로 둔다.
- writer는 원인과 파일 범위가 확정된 뒤에만 시작한다.
- 동시에 실행되는 writer끼리 파일 소유권을 겹치지 않는다.
- 외부 전송, 삭제, credential, 설치는 별도 승인 대상으로 남긴다.
클라이언트마다 관찰 지점이 다르다
- Codex App에서는 메인 채팅의 activity에서 subagent thread를 열고, Codex에게 실행 중인 agent를 steer·stop하거나 완료 thread를 close하라고 요청할 수 있다.
- Codex CLI에서는
/agent로 active thread 사이를 이동하며 진행 상황과 결과를 본다. - IDE extension에서는 background-agent panel이 제공될 때 상태를 펼쳐 보고, agent를 중지하거나 개별 thread를 연다.
범위를 벗어난 파일을 읽거나, 요청한 근거 대신 긴 출력만 돌려주거나, 다른 agent의 발견 때문에 전제가 무너졌다면 즉시 방향을 바꾼다. 잘못된 가정 위에서 여러 branch가 계속 달리는 것이 가장 비싼 실패다.
반복되는 책임만 custom agent로 만든다
Codex에는 default, worker, explorer가 기본 제공된다. 같은 책임이 반복되고 모델, reasoning effort, sandbox, MCP, 지시를 안정적으로 유지해야 할 때만 custom agent를 만든다. 개인 agent는 ~/.codex/agents/, 프로젝트 agent는 .codex/agents/에 둔다. 각 TOML에는 name, description, developer_instructions가 필수다.
tomlname = "test_triage" description = "테스트 실패를 재현성과 영향 범위로 분류하는 read-only agent." model = "gpt-5.6-terra" model_reasoning_effort = "high" sandbox_mode = "read-only" developer_instructions = """ 관련 test target만 실행하고 실패를 재현 가능한 순서로 정리한다. 명령, 파일 위치, 환경 조건, 불확실성을 반환한다. 소스 파일은 수정하지 않는다. """
현재 공식 권고는 어려운 다단계 판단에 gpt-5.6, 빠른 read-heavy 지원 작업에 gpt-5.6-terra, 좁고 반복적인 작업에 gpt-5.6-luna를 출발점으로 제시한다. 계정, 인증 경로, client에 따라 사용 가능 모델이 달라질 수 있으므로 저장된 값은 정기적으로 확인한다.
전역 설정은 [agents] 아래에서 활성화, 동시 thread 수, 기본 subagent 모델과 reasoning effort 등을 제어한다. 사용자·프로젝트·profile·CLI 설정의 우선순위가 문제라면 Codex config.toml 설정 가이드를 참고한다.
최종 요약은 다시 증거로 내려가야 한다
메인 스레드는 중복 결과를 합치고, 관찰·추론·제안을 분리한 뒤 중요한 근거를 다시 연다. 어떤 테스트를 실제로 돌렸는지, security 경로가 도달 가능한지, “참조 없음”이 충분한 검색 범위에서 나온 결론인지 확인한다. 상충하는 결과는 agent 수가 아니라 증거로 해결한다.
좋은 workflow에서는 요구사항과 의사결정, 최종 책임이 메인 스레드에 남는다. 서브에이전트는 경계가 있는 중간 작업을 수행하고 압축된 근거를 돌려준다. 독립성이 있을 때 시간과 context를 아낄 수 있지만, 통합 답변의 검증까지 대신하지는 않는다.
도구 자체를 고르는 단계라면 Claude Code와 Codex 비교에서 로컬 제어와 작업 분배 방식을 먼저 비교할 수 있다.
