Codex 서브에이전트 설정과 실전 활용: 탐색·검증·구현을 안전하게 나누는 법
Codex CLI에서 역할별 서브에이전트를 구성하고 병렬 탐색, 검증, 안전한 구현 워크플로를 운영하는 실전 가이드입니다.
Codex 서브에이전트 설정과 실전 활용
큰 작업을 한 대화에 모두 넣으면 요구사항, 검색 결과, 테스트 로그가 서로 섞입니다. Codex의 서브에이전트는 **메인 스레드는 판단과 통합에 집중하고, 경계가 분명한 조사·검증·구현을 별도 스레드에 위임**하도록 돕습니다. 현재 Codex 릴리스는 서브에이전트 워크플로를 기본 제공하며 CLI에서는 `/agent`로 실행 중인 스레드를 살펴볼 수 있습니다.
> 이 글의 예시는 2026-09-08에 Codex CLI 0.153.4와 공식 문서로 확인했습니다. 에이전트 설정 키와 모델 제공 범위는 버전·계정에 따라 바뀔 수 있습니다. 복사 후 반드시 `codex exec --strict-config ...`로 검증하세요.
1. 언제 나누면 좋은가
병렬화의 좋은 후보는 서로 독립적인 읽기 작업입니다. 예를 들어 보안 위험, 테스트 누락, 문서 API 확인은 동시에 조사할 수 있습니다. 반대로 여러 에이전트가 같은 파일을 수정하면 충돌과 조정 비용이 커집니다. 원칙은 간단합니다.
• **Explorer:** 파일 위치, 호출 경로, 영향 범위만 읽기 전용으로 조사
• **Verifier:** 테스트·린트·빌드를 실행하고 실제 실패 원인을 증거와 함께 보고
• **Worker:** 소유 파일을 명확히 정한 뒤 최소 변경만 구현
• **Main:** 요구사항, 우선순위, 최종 diff와 결론을 소유
서브에이전트는 각각 모델과 도구 작업을 수행하므로 단일 에이전트보다 토큰을 더 사용합니다. “병렬이면 무조건 빠르다”가 아니라, 독립성이 높고 결과를 짧게 요약할 수 있을 때 사용하세요.
2. 전역 설정과 이름 있는 역할
사용자 전역 설정은 `~/.codex/config.toml`, 신뢰한 프로젝트의 설정은 `.codex/config.toml`에 둘 수 있습니다. 다음은 로컬에서 실제 사용할 수 있는 모델 슬러그로 구성한 예입니다.
```toml
~/.codex/config.toml
[agents]
default_subagent_model = "gpt-5.4-mini"
default_subagent_reasoning_effort = "low"
max_concurrent_threads_per_session = 4
[agents.explorer]
description = "Read-only codebase mapping and evidence gathering."
config_file = "agents/explorer.toml"
[agents.verifier]
description = "Run tests, lint, build, and report exact failures."
config_file = "agents/verifier.toml"
```
`config_file`의 상대 경로는 그 역할을 선언한 설정 파일을 기준으로 해석됩니다. 공식 문서는 개인 역할 파일을 `~/.codex/agents/`, 프로젝트 역할 파일을 `.codex/agents/`에 두는 독립형 방식도 설명합니다. 최신 독립형 역할 파일은 `name`, `description`, `developer_instructions`를 요구합니다. 버전별 형식 차이가 있으므로 기존 레지스트리 방식과 자동 발견 방식을 섞기 전에 strict validation을 통과시키는 것이 안전합니다.
Explorer: 읽기 전용
```toml
~/.codex/agents/explorer.toml
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
sandbox_mode = "read-only"
```
독립형 최신 스키마를 쓰는 버전이라면 역할 메타데이터도 같은 파일에 둡니다.
```toml
name = "explorer"
description = "Read-only explorer for locating code and tracing behavior."
developer_instructions = """
Inspect only. Cite files and symbols. Do not edit or propose broad refactors.
Return a concise evidence map to the parent.
"""
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
sandbox_mode = "read-only"
```
Verifier: 제한된 쓰기 허용
테스트는 캐시나 스냅샷을 쓸 수 있어 `workspace-write`가 현실적일 수 있습니다. 그러나 “검증만 하고 제품 코드는 수정하지 말라”는 지침을 명시하세요.
```toml
model = "gpt-5.4"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
developer_instructions = """
Run the requested checks. Do not fix application code.
Report the command, exit status, failing assertion, and likely root cause.
"""
```
중요한 예외가 있습니다. 자식은 부모 턴의 현재 sandbox/approval 정책을 상속하고, CLI에서 실시간으로 바꾼 권한은 역할 파일의 기본값보다 우선할 수 있습니다. 역할 파일을 보안 경계 자체로 보지 말고 **부모 세션의 권한을 먼저 최소화**하세요.
3. 설정 검증과 시작
```bash
codex --version
codex features list
codex exec --strict-config -s read-only \
"Inspect the repository configuration and return a short summary. Do not edit files."
```
`--strict-config`는 현재 바이너리가 모르는 필드를 오류로 처리합니다. 실패 예시는 보통 세 가지입니다.
1. `reasoning_effort`처럼 비슷하지만 지원되지 않는 키 사용 → `model_reasoning_effort` 확인
2. 존재하지 않는 `config_file` 경로 → 선언 파일 기준 상대 경로 확인
3. 계정에 없는 모델 슬러그 → `/model`, 로컬 모델 카탈로그 또는 실제 실행으로 확인
설정을 바꾼 뒤에는 새 세션을 시작하세요. 오래 열린 세션은 시작 시점 설정을 계속 들고 있을 수 있습니다.
4. 호출 패턴
CLI에서는 구현 세부 API를 외우기보다 프롬프트로 분할 기준과 완료 조건을 분명히 지정하는 편이 안정적입니다.
```text
이 브랜치를 main과 비교해 검토해줘.
1) explorer는 변경 경로와 영향 범위를 읽기 전용으로 조사
2) verifier는 관련 테스트와 빌드를 실행
둘을 병렬 실행하고 모두 끝날 때까지 기다린 뒤,
파일 경로·명령·실패 증거를 포함한 하나의 요약을 반환해줘.
코드는 수정하지 마.
```
구현까지 맡길 때는 단계형으로 운영합니다.
```text
먼저 explorer와 verifier를 병렬 실행한다.
메인 에이전트가 실패 원인을 확정한 뒤에만 worker를 시작한다.
worker는 src/parser.ts만 소유하고 최소 수정한다.
마지막으로 verifier가 동일 명령을 다시 실행한다.
```
활성 스레드는 `/agent`로 열어 진행 상태를 보고, 필요하면 특정 에이전트를 중단하거나 방향을 수정할 수 있습니다.
5. Claude Code에서 같은 역할 분리를 구현하려면
Claude Code에도 커스텀 서브에이전트 기능은 있지만 Codex의 TOML 에이전트 설정을 그대로 사용하지는 않습니다. 프로젝트 범위 역할은 보통 `.claude/agents/explorer.md`와 `.claude/agents/verifier.md`처럼 Markdown 파일로 정의합니다. 즉 “Claude에는 에이전트가 없다”기보다 **동일한 Codex TOML 구조가 없어서 Markdown 역할 파일로 비슷한 분리를 구성한다**고 이해하는 편이 정확합니다.
```markdown
name: explorer
description: 코드 위치와 호출 경로를 읽기 전용으로 조사합니다.
tools: Read, Grep, Glob
model: haiku
파일을 수정하지 마세요. 관련 파일과 근거를 짧게 정리해 부모에게 반환하세요.
```
```markdown
name: verifier
description: 테스트와 빌드를 실행하고 실패 근거를 보고합니다.
tools: Read, Grep, Glob, Bash
애플리케이션 코드는 고치지 말고 명령, 종료 코드, 실패 지점을 보고하세요.
```
개인 전역 역할은 `~/.claude/agents/`, 저장소와 함께 공유할 역할은 `.claude/agents/`에 둡니다. Claude Code의 frontmatter 키와 허용 도구 이름도 버전에 따라 달라질 수 있으므로 공식 문서와 실제 설치 버전으로 확인해야 합니다.
6. 안전한 병렬화 체크리스트
• 읽기 작업은 병렬, 동일 파일 쓰기는 직렬
• 에이전트마다 질문 하나, 산출물 하나, 종료 조건 하나
• “성공했다”는 자기 보고 대신 명령·exit code·diff를 확인
• 승인 프롬프트가 표시될 수 없는 비대화형 실행에서는 권한이 필요한 동작이 실패할 수 있음을 예상
• `danger-full-access`나 승인 우회는 외부 샌드박스가 보장된 경우가 아니면 피하기
• 비밀, 인증 파일, 개인 경로를 프롬프트나 로그에 복사하지 않기
• 동시 스레드 수는 작게 시작하고 실제 병목이 확인될 때만 늘리기
7. 실전 운영 레시피
가장 재현성 높은 흐름은 **Map → Decide → Change → Verify**입니다.
1. Explorer 두 개가 독립 영역을 조사한다.
2. Main이 중복을 제거하고 하나의 가설과 변경 범위를 정한다.
3. Worker 하나만 지정 파일을 수정한다.
4. Verifier가 깨끗한 명령으로 테스트하고 diff를 검토한다.
5. Main이 증거를 읽고 완료 여부를 결정한다.
서브에이전트의 핵심은 에이전트 수가 아니라 **역할의 경계**입니다. 탐색은 읽기 전용, 검증은 증거 중심, 구현은 파일 소유권 중심으로 설계하면 메인 컨텍스트가 깨끗해지고 실패 원인도 추적하기 쉬워집니다.
참고 자료
• OpenAI Codex Subagents: https://developers.openai.com/codex/subagents
• Codex Configuration Reference: https://developers.openai.com/codex/config-reference
• Codex Advanced Configuration: https://developers.openai.com/codex/config-file/config-advanced
• Codex CLI: https://developers.openai.com/codex/cli