# Codex, Subagents 지원 시작

> Clean Markdown view of GeekNews topic #27566. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=27566](https://news.hada.io/topic?id=27566)
- GeekNews Markdown: [https://news.hada.io/topic/27566.md](https://news.hada.io/topic/27566.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2026-03-17T09:01:01+09:00
- Updated: 2026-03-17T09:01:01+09:00
- Original source: [developers.openai.com](https://developers.openai.com/codex/subagents)
- Points: 13
- Comments: 4

## Summary

OpenAI **Codex**가 서브에이전트 워크플로를 도입해, 복잡한 개발 작업을 여러 전문 에이전트에 병렬 분배하고 결과를 자동 통합할 수 있게 되었습니다. 각 서브에이전트는 독립된 모델과 도구 구성을 가질 수 있으며, TOML 기반 **커스텀 에이전트 정의**로 프로젝트별 역할을 세밀하게 조정할 수 있습니다.

## Topic Body

- OpenAI Codex가 **서브에이전트 워크플로**를 지원하여, 복잡한 작업을 여러 전문 에이전트에 **병렬 분배하고 결과를 하나로 통합**하는 기능 제공  
- 사용자가 명시적으로 요청할 때만 서브에이전트를 생성하며, 각 에이전트가 독립적으로 모델과 도구를 사용하므로 **토큰 소비량이 단일 에이전트보다 증가**  
- **커스텀 에이전트**를 TOML 파일로 정의하여 모델, 샌드박스 모드, MCP 서버 등을 에이전트별로 독립 설정 가능  
- CSV 파일의 각 행을 하나의 작업 단위로 삼아 워커 에이전트를 일괄 생성하는 **spawn_agents_on_csv** 실험적 기능도 포함  
- 코드 리뷰, 프론트엔드 디버깅 등 실전 시나리오별 **커스텀 에이전트 조합 패턴**을 공식 문서에서 직접 안내  
  
---  
  
### 서브에이전트 개요 및 가용성  
- Codex는 전문화된 에이전트를 **병렬로 생성(spawn)** 하고 결과를 하나의 응답으로 수집하는 서브에이전트 워크플로 지원  
- 코드베이스 탐색이나 다단계 기능 구현 계획처럼 **높은 병렬성**이 필요한 복잡한 작업에 특히 유용  
- 서브에이전트 워크플로에서는 작업에 따라 **서로 다른 모델 설정과 지시사항**을 가진 커스텀 에이전트도 정의 가능  
- 현재 Codex 릴리스에서는 서브에이전트 워크플로가 **기본 활성화** 상태  
- 서브에이전트 활동은 현재 **Codex 앱과 CLI**에서 확인 가능하며, IDE Extension에서의 가시성은 곧 추가 예정  
- 사용자가 명시적으로 요청할 때만 서브에이전트를 생성하며, 각 서브에이전트가 자체 모델·도구 작업을 수행하므로 **단일 에이전트 실행보다 토큰 소비가 많음**  
  
### 일반적인 워크플로  
- Codex가 에이전트 간 **오케스트레이션**을 처리: 새 서브에이전트 생성, 후속 지시 라우팅, 결과 대기, 에이전트 스레드 종료 포함  
- 여러 에이전트가 실행 중일 때, Codex는 모든 요청 결과가 준비될 때까지 **대기 후 통합 응답** 반환  
- 예시 프롬프트: 현재 PR에 대해 보안 이슈, 코드 품질, 버그, 레이스 컨디션, 테스트 불안정성, 유지보수성 각각에 **에이전트 하나씩 생성**하고 전체 결과를 요약하도록 요청  
  
### 서브에이전트 관리  
- CLI에서 `/agent` 명령으로 **활성 에이전트 스레드 간 전환** 및 진행 중인 스레드 검사 가능  
- Codex에 직접 요청하여 실행 중인 서브에이전트를 **조종, 중지, 또는 완료된 스레드를 종료** 가능  
  
### 승인 및 샌드박스 제어  
- 서브에이전트는 사용자의 현재 **샌드박스 정책을 상속**  
- 대화형 CLI 세션에서는 비활성 에이전트 스레드의 승인 요청이 메인 스레드 사용 중에도 표시될 수 있으며, 승인 오버레이에 **소스 스레드 레이블**이 표시됨  
  - `o`를 눌러 해당 스레드를 열고, 승인·거부·응답 가능  
- 비대화형 흐름에서는 새로운 승인을 표시할 수 없어, 승인이 필요한 작업이 **실패하고 오류가 상위 워크플로에 전달**됨  
- 자식 에이전트 생성 시 부모 턴의 **라이브 런타임 오버라이드**를 재적용: `/approvals` 변경이나 `--yolo` 같은 대화형 설정 포함  
  - 선택된 커스텀 에이전트 파일이 다른 기본값을 설정하더라도 부모의 설정이 우선  
- 개별 커스텀 에이전트에 대해 **샌드박스 설정을 별도로 오버라이드** 가능 (예: 특정 에이전트를 읽기 전용 모드로 지정)  
  
### 커스텀 에이전트  
- Codex에 기본 내장된 에이전트 3종 제공  
  - `default`: 범용 **폴백 에이전트**  
  - `worker`: 구현과 수정에 초점을 맞춘 **실행 중심 에이전트**  
  - `explorer`: 코드베이스 탐색을 위한 **읽기 중심 에이전트**  
- 커스텀 에이전트 정의 시 `~/.codex/agents/`(개인용) 또는 `.codex/agents/`(프로젝트 범위)에 **독립 TOML 파일** 추가  
- 각 파일이 하나의 커스텀 에이전트를 정의하며, Codex가 이를 생성 세션의 **설정 레이어로 로드**  
- 모든 커스텀 에이전트 파일에 반드시 포함해야 하는 필수 필드:  
  - `name`, `description`, `developer_instructions`  
- 선택 필드: `nickname_candidates`, `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, `skills.config` 등은 생략 시 **부모 세션에서 상속**  
  
### 글로벌 설정  
- 서브에이전트 글로벌 설정은 configuration 파일의 `[agents]` 섹션에 정의  
- `agents.max_threads`: 동시 오픈 에이전트 스레드 **상한** (기본값 `6`)  
- `agents.max_depth`: 생성된 에이전트의 **중첩 깊이** (기본값 `1`, 직접 자식 에이전트만 생성 허용, 더 깊은 중첩 방지)  
- `agents.job_max_runtime_seconds`: `spawn_agents_on_csv` 작업의 **워커별 기본 타임아웃** (미설정 시 호출당 기본 1800초)  
- 커스텀 에이전트 이름이 `explorer` 같은 내장 에이전트와 동일하면 **커스텀 에이전트가 우선**  
  
### 커스텀 에이전트 파일 스키마  
- `name` (string, 필수): Codex가 에이전트를 생성하거나 참조할 때 사용하는 **에이전트 이름**  
- `description` (string, 필수): Codex가 이 에이전트를 언제 사용해야 하는지에 대한 **사람 대상 가이드**  
- `developer_instructions` (string, 필수): 에이전트의 **동작을 정의하는 핵심 지시사항**  
- `nickname_candidates` (string[], 선택): 생성된 에이전트의 **표시 닉네임 풀**  
- 기타 지원되는 `config.toml` 키도 포함 가능: `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, `skills.config` 등  
- Codex는 `name` 필드로 에이전트를 식별하며, 파일명과 에이전트 이름을 일치시키는 것이 가장 단순한 관례이나 **`name` 필드가 진본(source of truth)**  
  
### 표시 닉네임  
- `nickname_candidates`는 동일 커스텀 에이전트를 여러 인스턴스로 실행할 때 UI에서 **구별 가능한 레이블**을 표시하기 위한 용도  
- 닉네임은 **표시 전용**이며, Codex는 여전히 `name`으로 에이전트를 식별·생성  
- 닉네임 후보는 비어 있지 않은 고유 이름 목록이어야 하며, ASCII 문자·숫자·공백·하이픈·밑줄 사용 가능  
- 예시: `reviewer` 에이전트에 `["Atlas", "Delta", "Echo"]` 닉네임을 설정하면, 앱과 CLI에서 **닉네임이 표시**되지만 기본 에이전트 타입은 `reviewer`로 유지  
  
### 예시 1: PR 리뷰 패턴  
- 리뷰를 세 개의 **특화된 커스텀 에이전트**로 분할하는 패턴  
  - `pr_explorer`: 코드베이스를 매핑하고 **증거를 수집**하는 읽기 전용 에이전트 (모델: `gpt-5.3-codex-spark`, reasoning effort: medium)  
  - `reviewer`: 정확성, 보안, **테스트 리스크**를 찾는 PR 리뷰어 (모델: `gpt-5.4`, reasoning effort: high)  
  - `docs_researcher`: 전용 MCP 서버를 통해 프레임워크나 API **문서를 확인**하는 문서 전문가 (모델: `gpt-5.3-codex-spark`, 읽기 전용)  
- 프로젝트 설정: `max_threads = 6`, `max_depth = 1`  
- `pr_explorer`의 지시사항: 탐색 모드 유지, 실제 실행 경로를 추적, 파일과 심볼을 인용하며 부모 에이전트가 요청하지 않는 한 **수정 제안 자제**  
- `reviewer`의 지시사항: 소유자 관점에서 리뷰, 정확성·보안·동작 회귀·누락된 테스트 커버리지 우선, 가능한 경우 **재현 단계 포함**, 스타일 전용 코멘트는 실제 버그를 숨기지 않는 한 회피  
- `docs_researcher`의 지시사항: docs MCP 서버를 사용해 API, 옵션, 버전별 동작을 확인하고 **링크나 정확한 참조와 함께 간결하게 응답**, 코드 변경 금지  
- 사용 예시 프롬프트: "이 브랜치를 main과 비교 리뷰. pr_explorer가 영향 받는 코드 경로를 매핑, reviewer가 실질적 리스크를 찾고, docs_researcher가 패치가 의존하는 프레임워크 API를 검증"  
  
### CSV 배치 처리: spawn_agents_on_csv (실험적)  
- **실험적 기능**으로 향후 변경 가능  
- 유사한 작업이 많을 때, CSV의 **한 행을 하나의 작업 단위**로 삼아 워커 서브에이전트를 일괄 생성  
- Codex가 CSV를 읽고, 행당 워커 에이전트를 생성, 전체 배치 완료를 기다린 뒤 **결과를 CSV로 내보내기**  
- 적합한 사용 사례:  
  - 행당 파일, 패키지, 서비스 하나를 **리뷰**  
  - 인시던트, PR, 마이그레이션 대상 목록을 **점검**  
  - 유사한 다수 입력에 대해 **구조화된 요약 생성**  
- 도구 입력 파라미터: `csv_path`(소스 CSV), `instruction`(워커 프롬프트 템플릿, `{column_name}` 플레이스홀더 사용), `id_column`(안정적 항목 ID), `output_schema`(고정 JSON 형태), `output_csv_path`, `max_concurrency`, `max_runtime_seconds`  
- 각 워커는 `report_agent_job_result`를 **정확히 한 번 호출**해야 하며, 결과 보고 없이 종료되면 해당 행이 오류로 표시  
- `codex exec`으로 실행 시 배치 진행 중 `stderr`에 **한 줄 진행 상황 업데이트** 표시  
- 내보내기된 CSV에는 원본 행 데이터와 `job_id`, `item_id`, `status`, `last_error`, `result_json` 등 **메타데이터 포함**  
- 관련 런타임 설정: `agents.max_threads`(동시 스레드 상한), `agents.job_max_runtime_seconds`(워커별 타임아웃, 호출별 `max_runtime_seconds`가 우선), `sqlite_home`(에이전트 작업과 내보내기 결과에 사용되는 **SQLite 상태 저장 경로**)  
  
### 예시 2: 프론트엔드 통합 디버깅 패턴  
- UI 회귀, 불안정한 브라우저 흐름, 애플리케이션 코드와 실행 중인 제품을 **교차하는 통합 버그**에 유용한 패턴  
- 세 개의 커스텀 에이전트 조합:  
  - `code_mapper`: 관련 프론트엔드·백엔드 코드 경로를 찾는 **읽기 전용 탐색 에이전트** (모델: `gpt-5.3-codex-spark`, reasoning effort: medium)  
  - `browser_debugger`: 브라우저 도구를 사용해 이슈를 재현하고 **증거를 캡처**하는 UI 디버거 (모델: `gpt-5.4`, reasoning effort: high, sandbox: workspace-write)  
    - 스크린샷, 콘솔 출력, 네트워크 증거를 위해 **브라우저 도구 활용**, 애플리케이션 코드 편집 금지  
    - Chrome DevTools **MCP 서버** 연결 (`http://localhost:3000/mcp`, startup_timeout_sec: 20)  
  - `ui_fixer`: 이슈가 파악된 후 작고 타겟된 수정을 담당하는 **구현 중심 에이전트** (모델: `gpt-5.3-codex-spark`, reasoning effort: medium)  
    - 가장 작은 방어 가능한 변경을 수행, 관련 없는 파일은 건드리지 않으며 **변경한 동작만 검증**  
- 사용 예시 프롬프트: "설정 모달이 저장에 실패하는 이유를 조사. browser_debugger가 재현, code_mapper가 해당 코드 경로를 추적, ui_fixer가 실패 모드 파악 후 **최소한의 수정 구현**"

## Comments



### Comment 53249

- Author: kgcrom
- Created: 2026-03-17T22:47:05+09:00
- Points: 1

agent가 GPT-5.1-Codex-Mini 모델만 사용해서   
Codex App Custom instructions에  
아래 프롬프트 추가하니까 GPT-5.3-Codex-Spark로 agent동작하네요.  
  
"- when it spawns agents, use models "GPT-5.3-Codex-Spark" or higher."  
  
또는 agent 생성할 때 모델 지정하는 재미도 쏠쏠하고  
Codex App에서 하위폴더구조로 보여주는거 좋습니다.

### Comment 53185

- Author: hmmhmmhm
- Created: 2026-03-17T10:41:07+09:00
- Points: 1

카톡에서 파격할인 행사 할 때 올라타서 너무 잘 쓰고 있습니다 ㅎㅎㅎ

### Comment 53225

- Author: shakespeares
- Created: 2026-03-17T15:58:59+09:00
- Points: 1
- Parent comment: 53185
- Depth: 1

아쉽네여 또 행사 안하려나여 ㅠㅠ

### Comment 53182

- Author: xguru
- Created: 2026-03-17T10:18:19+09:00
- Points: 1

코덱스도 얼릉 리모트 콘트롤을 만들어 주세요!