Codex Subagents

• Codex에서 특정 작업을 전담하는 특수화된 하위 AI 에이전트
• 각 subagent는 독립된 스레드에서 병렬 실행되며, 결과를 하나로 모아 반환
• 명시적 요청 시에만 생성 — Codex가 임의로 subagent를 생성하지 않음
• TOML 파일로 커스텀 에이전트 정의 가능 (모델, 샌드박스, MCP Server 등 개별 설정)

해당 개념이 필요한 이유

• 병렬 처리: 코드베이스 탐색, PR 리뷰, 디버깅 등 독립 작업을 동시에 실행
• 컨텍스트 격리: 대량 출력이 메인 스레드를 오염시키지 않음
• 역할 분리: 에이전트별로 모델, 도구, 샌드박스를 다르게 설정하여 비용과 보안 최적화
• 확장성: CSV 기반 배치 처리로 수십 개 작업을 워커 단위로 병렬 실행 가능

AS-IS (Subagent 없이)

sequenceDiagram
    autonumber
    actor User
    participant Main as 메인 스레드

    User->>Main: "PR 리뷰해줘"
    Main->>Main: 코드 탐색 + 보안 분석 + 문서 확인
    Note over Main: 모든 작업이 순차 실행<br/>대량 출력이 컨텍스트에 축적
    Main-->>User: 리뷰 결과
    Note over Main: ⚠️ 시간 소요 + 컨텍스트 오염

TO-BE (Subagent 사용)

sequenceDiagram
    autonumber
    actor User
    participant Main as 메인 스레드
    participant A1 as pr_explorer (Subagent)
    participant A2 as reviewer (Subagent)
    participant A3 as docs_researcher (Subagent)

    User->>Main: "PR 리뷰해줘, 에이전트별로 나눠서"
    par 병렬 실행
        Main->>A1: 코드 경로 탐색
        Main->>A2: 정확성/보안 분석
        Main->>A3: API 문서 검증
    end
    A1-->>Main: 관련 코드 요약
    A2-->>Main: 리스크 체크리스트
    A3-->>Main: 문서 정합성 결과
    Main->>Main: 3개 결과 통합
    Main-->>User: 통합 리뷰 결과
    Note over Main: ✅ 병렬 실행 + 컨텍스트 깨끗

빌트인 Subagents

Agent	용도
default	범용 폴백 에이전트
worker	구현, 수정 등 실행 중심 작업
explorer	읽기 중심 코드베이스 탐색

Subagent 정의 방법

커스텀 에이전트는 TOML 파일로 정의한다:

위치	경로	적용 범위
Personal	~/.codex/agents/<name>.toml	내 모든 프로젝트
Project	.codex/agents/<name>.toml	해당 프로젝트만

# .codex/agents/code-reviewer.toml
name = "code-reviewer"
description = "코드 품질과 보안을 리뷰하는 전문가"
developer_instructions = """
당신은 코드 리뷰어입니다. 호출되면 코드를 분석하고
품질, 보안, 모범 사례에 대한 피드백을 제공하세요.
"""
sandbox_mode = "read-only"
model = "gpt-5.4"

주요 필드

필수 필드

필드	설명
name	에이전트 식별자 (스폰 시 사용)
description	사용자 안내용 설명
developer_instructions	핵심 행동 지시사항 (system prompt 역할)

선택 필드 (생략 시 부모 세션 상속)

필드	설명	예시
nickname_candidates	UI 표시용 읽기 쉬운 이름 목록	["Code Scout", "Explorer"]
model	사용할 모델	"gpt-5.4", "gpt-5.4-mini"
model_reasoning_effort	추론 수준	low / medium / high
sandbox_mode	실행 권한	"read-only", "workspace"
mcp_servers	MCP Server 설정	아래 예시 참조
skills.config	바인딩할 스킬	아래 예시 참조

글로벌 설정

~/.codex/config.toml의 [agents] 섹션에서 전체 동작을 제어한다:

필드	타입	설명	기본값
agents.max_threads	number	동시 실행 가능한 스레드 수	6
agents.max_depth	number	에이전트 중첩 깊이	1
agents.job_max_runtime_seconds	number	워커 타임아웃	1800

중첩 깊이 (max_depth)

기본값 1은 직접 자식 에이전트만 생성 가능하고, 그 자식이 또 다른 에이전트를 생성하는 것은 차단한다. 값을 높이면 토큰 사용량과 레이턴시가 급증할 수 있다.

flowchart TD
    Main["Main Thread"]
    A["Agent A (depth 1)"]
    B["Agent B (depth 1)"]
    C["Agent C (depth 2)"]

    Main --> A
    Main --> B
    A -.->|"max_depth=1 → ❌ 차단"| C

    style C stroke-dasharray: 5 5

샌드박스와 권한

• Subagent는 부모 세션의 샌드박스 정책을 상속
• 커스텀 에이전트 파일에 다른 기본값을 지정해도, 부모의 런타임 오버라이드(sandbox 선택, 승인, --yolo)가 우선 적용
• Non-interactive 모드에서는 새로운 승인이 필요한 액션은 에러로 실패하며, 부모 워크플로우에 에러가 전파됨

실행 중 사용자 개입

Codex subagent는 실행 중에 사용자가 직접 개입할 수 있다. 이것은 Claude Code subagent와의 가장 큰 설계 차이이다.

스레드 전환과 모니터링

/agent          # 활성 에이전트 스레드 목록 표시 + 전환

• /agent 명령으로 실행 중인 subagent 스레드 간 자유롭게 전환
• 실행 중인 subagent에 직접 말을 걸어 방향 조정, 중단, 스레드 종료 가능

승인 요청 오버레이

subagent가 권한이 필요한 작업(파일 수정, 명령 실행 등)을 시도하면, 사용자가 다른 스레드를 보고 있더라도 승인 요청이 오버레이로 표시된다:

sequenceDiagram
    autonumber
    actor User
    participant Main as 메인 스레드
    participant A1 as reviewer (Subagent)

    User->>Main: 메인 스레드에서 작업 중
    A1->>User: ⚠️ 승인 요청 오버레이<br/>[source: reviewer]
    Note over User: `o` 키로 reviewer 스레드 열기
    User->>A1: approve / reject / answer

Claude Code와의 개입 모델 비교

	Codex	Claude Code
실행 중 사용자 개입	가능 — 스레드 전환, 방향 조정(steer), 중단(stop)	불가 — 결과만 반환
승인 요청	오버레이로 실시간 표시, o 키로 전환 후 approve/reject/answer	사전에 필요한 퍼미션 승인 후 시작
요청에 응답	subagent의 요청에 answer 가능 (공식 문서 명시)	불가 → Skill이 오케스트레이터 역할 필요
오케스트레이션 패턴	메인 스레드가 직접 조율 가능	반드시 Skill이 Agent를 조율 (Agent → Agent 불가)

Claude Code에서는 subagent가 사용자와 상호작용할 수 없어서, Skill이 오케스트레이터 역할을 맡아 “Agent 호출 → 결과 받기 → 사용자 확인 → 다음 Agent 호출” 루프를 구현해야 한다. Codex에서는 사용자가 subagent 스레드에 개입(steer, stop, approve/reject/answer)할 수 있으므로, 이런 오케스트레이션 패턴의 필요성이 상대적으로 낮을 수 있다. (단, 공식 문서에서 이 비교를 직접 언급하지는 않으며, steer/answer의 구체적 동작 범위도 명시되지 않았다.)

실행 패턴: 병렬 위임

사용자가 명시적으로 에이전트 분리를 요청하면 Codex가 서브에이전트를 생성한다:

User: "Spawn one agent per point, wait for all of them, and summarize results."

sequenceDiagram
    autonumber
    actor User
    participant Main as Codex (Main)
    participant A as Agent A
    participant B as Agent B
    participant C as Agent C

    User->>Main: "3가지 관점으로 분석해줘,<br/>에이전트별로 나눠서"
    par 병렬 스폰
        Main->>A: 관점 1 분석
        Main->>B: 관점 2 분석
        Main->>C: 관점 3 분석
    end
    A-->>Main: 결과 1
    B-->>Main: 결과 2
    C-->>Main: 결과 3
    Main->>Main: 3개 결과 통합
    Main-->>User: 통합 응답

CLI에서 스레드 관리: /agent 명령으로 활성 스레드 간 전환 및 모니터링

배치 처리: spawn_agents_on_csv

일반 subagent 워크플로우는 정식 기능이지만, spawn_agents_on_csv는 실험적 기능으로 향후 변경될 수 있다. CSV의 각 행을 워커 1개가 처리하고, 결과를 합쳐서 내보낸다:

flowchart LR
    CSV["input.csv<br/>(N rows)"] --> W1["Worker 1"]
    CSV --> W2["Worker 2"]
    CSV --> W3["Worker N"]
    W1 --> OUT["output.csv"]
    W2 --> OUT
    W3 --> OUT

파라미터	설명
csv_path	입력 CSV 경로
instruction	워커 프롬프트 ({column_name} 플레이스홀더 사용)
id_column	행 식별자 컬럼 (선택)
output_schema	워커별 JSON 출력 형태 (선택)
output_csv_path	결과 CSV 경로
max_concurrency	동시 워커 수 제한
max_runtime_seconds	워커별 타임아웃

각 워커는 반드시 report_agent_job_result를 정확히 1회 호출해야 한다. 미호출 시 에러로 처리.

활용 예시: 파일/패키지 행별 리뷰, 인시던트 목록 분석, 마이그레이션 대상 점검, 구조화된 요약 생성

커스텀 에이전트 패턴 예시

패턴 1: PR 리뷰 분업

# .codex/agents/pr_explorer.toml — 읽기 전용 탐색
name = "pr_explorer"
description = "코드베이스를 읽기 전용으로 탐색하여 변경 근거 수집"
sandbox_mode = "read-only"
model = "gpt-5.3-codex-spark"

# .codex/agents/reviewer.toml — 리스크 평가
name = "reviewer"
description = "정확성, 보안, 누락 테스트 관점의 PR 리뷰어"
sandbox_mode = "read-only"
model = "gpt-5.4"

# .codex/agents/docs_researcher.toml — API 문서 검증
name = "docs_researcher"
description = "API 문서와 코드 변경의 정합성 검증"
sandbox_mode = "read-only"
model = "gpt-5.4-mini"
 
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

패턴 2: 프론트엔드 디버깅 분업

에이전트	역할	sandbox	model
code_mapper	관련 코드 경로 탐색	read-only	경량 모델
browser_debugger	브라우저 도구로 이슈 재현	workspace (쓰기)	높은 추론
ui_fixer	타겟 수정 구현	workspace (쓰기)	경량 모델

Skills와의 관계

방향	설명
Skill → Subagent	Skill의 dependencies.tools로 에이전트에 필요한 도구 선언. 별도 에이전트 정의 파일(.codex/agents/)에서 실행
Subagent → Skill	에이전트 TOML의 skills.config로 스킬을 바인딩하여 에이전트 컨텍스트에 주입

Claude Code Subagent와 비교

항목	Codex Subagents	Claude Code Subagents
정의 형식	TOML 파일	Markdown 파일
저장 위치	.codex/agents/	.claude/agents/
개인 에이전트	~/.codex/agents/	~/.claude/agents/
생성 조건	사용자 명시적 요청 시에만	사용자 명시적 요청 시에만
실행 중 사용자 개입	가능 (스레드 전환, 방향 조정, 승인/거부)	불가 (결과만 반환)
중첩 생성	max_depth 설정으로 제어 (기본 1)	불가 (공식 제한)
빌트인	default, worker, explorer	Explore, Plan, general-purpose, Bash
병렬 스레드 수	max_threads (기본 6)	제한 없음 (Task 도구)
배치 처리	spawn_agents_on_csv 지원	해당 없음
UI 닉네임	nickname_candidates 지원	해당 없음
스킬 연동	skills.config (TOML)	skills (frontmatter)
Skill에서 위임	별도 에이전트 파일 정의 필요	context: fork + agent (frontmatter 내)
설정 파일	~/.codex/config.toml	settings.json / 에이전트 frontmatter

핵심 설계 차이

flowchart TD
    subgraph Codex["Codex 방식"]
        CS["Skill (SKILL.md)"] -.->|"별도 파일 참조"| CA["Agent (TOML)"]
        CA -->|"독립 정의"| CE["실행"]
    end

    subgraph Claude["Claude Code 방식"]
        CCS["Skill (SKILL.md)"] -->|"context: fork<br/>agent: Explore"| CCA["Subagent 위임"]
        CCA --> CCE["실행"]
    end

• Codex: Skill과 Agent가 완전히 분리된 파일로 정의. Skill은 워크플로우, Agent는 실행 주체
• Claude Code: Skill의 frontmatter 안에서 context: fork + agent로 subagent 위임을 선언. 하나의 파일에서 모두 제어

안티패턴

하지 말 것	이유	대안
모든 작업에 에이전트 생성	토큰 비용 급증	단순 작업은 메인 스레드에서 직접
max_depth를 높게 설정	팬아웃으로 비용/레이턴시 폭발	기본값 1 유지, 필요 시만 2
에이전트 파일에 너무 넓은 역할	역할이 모호하면 품질 저하	좁고 명확한 단일 역할 정의
sandbox_mode 없이 배포	의도치 않은 파일 수정/삭제	탐색 에이전트는 read-only 필수

참고 문서

• Codex Subagents 공식 문서
• Codex Best Practices
• Codex Skills - 재사용 가능한 워크플로우 패키지
• AGENTS.md 가이드 - 영구 컨텍스트 관리