[Codex] OpenAI Codex 멀티 에이전트 설정과 실행 방법

OpenAI Codex 멀티 에이전트

OpenAI Codex의 멀티 에이전트는 메인 에이전트가 전문화된 서브 에이전트를 병렬로 생성하고 결과를 수집하는 구조이다.

해결하고자 하는 문제

• 컨텍스트 오염(Context Pollution): 탐색 노트, 테스트 로그, 스택 트레이스 등 중간 출력물이 쌓여 유용한 정보가 묻히는 현상
• 컨텍스트 부패(Context Rot): 대화가 길어지면서 덜 관련된 내용으로 인해 성능이 저하되는 현상

작동 방식

• 메인 에이전트는 요구사항, 의사결정, 최종 출력에 집중
• 서브 에이전트는 탐색, 테스트, 로그 분석 등을 병렬로 수행
• 서브 에이전트는 원본 출력 대신 요약본만 반환

모델 선택 방법

• gpt-5.3-codex: 코드 리뷰, 보안 분석 등 깊은 추론이 필요한 에이전트용
• gpt-5.3-codex-spark: 탐색, 스캔, 요약 등 속도 우선 에이전트용
• model_reasoning_effort를 high/medium/low로 에이전트별 조절 가능
• 읽기 중심(탐색, 테스트, 요약) 작업에 병렬 에이전트를 사용. 하지만 여러 에이전트가 동시에 코드를 수정하는 것은 충돌 위험이 있으니 주의가 필요

Claude Code Agent Teams와 비교

Codex의 Multi-Agents는 중앙 집중식으로 서브 에이전트가 메인에게만 보고하는 구조라면, Claude Code의 Agent Teams는 팀원들이 서로 직접 대화하여 이슈를 공유하며 자율적으로 조정할 수 있는 더 분산된 협업 모델이다.

구분	OpenAI Codex Multi-Agent	Claude Code Agent Teams
에이전트 간 통신	서브 에이전트는 메인에게만 결과 반환	팀원끼리 직접 메시지 가능
조율 방식	메인 에이전트가 중앙에서 조율	공유 태스크 리스트 + 팀원 간 자율 조율
컨텍스트	서브 에이전트가 요약만 반환하여 메인 컨텍스트 보호	각 팀원이 독립 컨텍스트 윈도우 보유
모델 선택	에이전트별 다른 모델 지정 가능 (codex, spark 등)	에이전트별 모델 지정 가능 (Opus, Sonnet 등)
협업	서브 에이전트끼리 직접 소통 불가	팀원끼리 직접 소통하며 자율 조정 가능
비유	프리랜서에게 각각 심부름을 보내는 것	같은 방에서 일하는 프로젝트 팀
성숙도	공식 문서화된 기능	실험적(experimental) 기능

OpenAI Codex 멀티 에이전트 설정

1단계: 기능 활성화

멀티 에이전트는 실험적 기능이므로 먼저 활성화가 필요하다. ~/.codex/config.toml 파일에 아래와 같이 추가하거나, Codex CLI에서 /experimental 명령으로 Multi-agents를 활성화 한 후 Codex를 재시작한다.

[features]
multi_agent = true

2단계: 프로젝트 지침서 — AGENTS.md

AGENTS.md는 코딩 에이전트를 안내하기 위한 간단한 오픈 포맷이다. 에이전트를 위한 README라고 생각하면 된다. AGENTS.md는 에이전트 역할을 정의하는 파일이 아니라, 프로젝트의 빌드 방법, 테스트 명령, 코딩 컨벤션 등을 에이전트에게 알려주는 프로젝트 지침서이다.

README.md는 사람을 위한 것이고, AGENTS.md는 코딩 에이전트가 필요로 하는 빌드 단계, 테스트, 컨벤션 등 상세한 컨텍스트를 담는 파일이다.

# AGENTS.md

## 프로젝트 개요
- 버그 리포트 포털 (이미지 업로드 포함)
- 핵심 기능: 프로젝트 등록, 버그 CRUD, 스크린샷 업로드, Telegram/Email 알림

## 기술 스택
- Backend: SpringBoot, JPA, PostgreSQL, Gradle, Java 21
- Frontend: React, TypeScript, Vite, npm
- UI: TailwindCSS, Shadcn UI
- Infra: Docker Compose, GitHub Actions

## 빌드 & 테스트
- Backend: `cd backend && ./gradlew build && ./gradlew test`
- Frontend: `cd frontend && npm install && npm run build && npm test`
- 전체 환경: `docker compose up -d`

## 코딩 컨벤션
- Backend: Google Java Style Guide 준수
- Frontend: ESLint + Prettier 적용
- 커밋 메시지: Conventional Commits 형식

## 디렉토리 구조
- `backend/` — Spring Boot API 서버
- `frontend/` — React SPA
- `design/` — 디자인 토큰, 컴포넌트 스펙
- `infra/` — Docker, CI/CD 설정
- `docs/` — 요구사항, 플로우, 백로그

## PR 규칙
- 테스트 통과 필수
- 리뷰어 1인 이상 승인 필요
- 금액/인증 관련 코드 변경 시 보안 리뷰 필수

3단계: 에이전트 역할 정의 — config.toml

~/.codex/config.toml (글로벌) 또는 .codex/config.toml (프로젝트별)에서 에이전트 역할을 선언한다.

[agents]
max_threads = 4   # 동시 실행 가능한 최대 에이전트 수

[agents.default]
description = "General-purpose helper."

[agents.reviewer]
description = "Find security, correctness, and test risks in code."
config_file = "agents/reviewer.toml"

[agents.explorer]
description = "Fast codebase explorer for read-heavy tasks."
config_file = "agents/custom-explorer.toml"

3단계: 역할별 설정 파일 작성 - /agents/*.toml

깊은 추론을 하는 reviewer 역할용 설정 예시 파일 (/.codex/agents/reviewer.toml):

model = "gpt-5.3-codex"
model_reasoning_effort = "high"
developer_instructions = "Focus on high priority issues, write tests to validate hypothesis before flagging an issue. When finding security issues give concrete steps on how to reproduce the vulnerability."

빠른 읽기를 하는 explorer 역할용 설정 예시 파일 (/.codex/agents/reviewer.toml):

model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"

각 에이전트 역할은 기본 구성을 재정의할 수 있다. 에이전트 역할에 대해 재정의하는 일반적인 설정은 다음과 같다.

• model: 사용할 모델 (gpt-5.3-codex 또는 gpt-5.3-codex-spark)
• model_reasoning_effort: 추론 깊이
  • Low: 가벼운 추론으로 빠른 응답
  • Medium: 일상 작업에 적합한 속도와 추론 깊이의 균형
  • High: 복잡한 문제에 대한 더 깊은 추론
  • Extra High: 복잡한 문제에 대한 극도로 깊은 추론
• sandbox_mode: 권한 제어 (read-only 등)
• developer_instructions: 해당 에이전트의 전문 지시사항

요약 정리

• 에이전트 역할 정의: config.toml의 [agents] 섹션
• 역할별 상세 설정: 별도 .toml 파일의 developer_instructions
• AGENTS.md의 용도: 순수 프로젝트 지침 (빌드, 테스트, 컨벤션)
• 오케스트레이션: Codex가 자동 오케스트레이션
• 핸드오프: Codex가 내부적으로 처리
• 병렬 실행: Codex가 자동 판단 또는 프롬프트로 지시

참고자료

• OpenAI Developers - Overview Multi-agents
• OpenAI Developsers - Configuration Multi-agents
• Claude Code Docs - Orchestrate teams of Claude Code sessions