이게 된다고?
솔직히 처음 봤을 때 “이게 실제로 작동하는 거야?” 했어요.
SNS에서 누가 Codex 설정 파일 몇 줄 추가했더니 에이전트가 역할별로 나뉘더라는 포스트를 올린 거예요.
[features] multi_agent = true [agents.reviewer] description = "코드의 보안, 정확성, 테스트 리스크를 집중 검토합니다"
이게 끝이에요.
config.toml 파일에 이 몇 줄만 넣으면 Codex가 리뷰어 역할을 별도로 띄운다는 거잖아요.
그래서 직접 해봤습니다.
결론부터 말하면, 작동은 했어요. 그런데 예상치 못한 함정이 하나 있었는데요. 그 이야기까지 다 해볼게요.
Codex Multi Agent가 뭔데?
Codex Multi Agent란? OpenAI Codex CLI에서 실험적으로 지원하는 기능으로, 단일 에이전트 대신 역할별로 분리된 여러 에이전트를 동시에 구성해 작업 품질을 높이는 방식입니다.
config.toml의[features]섹션에서 활성화하며, 각 역할은 모델, 추론 강도, 개별 지시문을 독립적으로 설정할 수 있습니다.
Codex CLI가 처음 나왔을 때는 그냥 “터미널에서 쓰는 AI 코딩 도구”였어요.
명령어 하나 주면, 에이전트 하나가 처리하는 구조.
근데 지금은 다릅니다.
Multi Agent 모드로 들어가면, 작업을 여러 에이전트가 역할별로 나눠서 처리할 수 있게 돼요.
예를 들어 이런 구성이 가능해요:
| 역할 | 하는 일 | 특징 |
|---|---|---|
implementer | 코드 작성, 기능 구현 | 빠른 추론, 실행 속도 우선 |
reviewer | 보안·정확성·테스트 검토 | 꼼꼼한 추론, 정밀성 우선 |
planner | 작업 범위 설정, 리스크 정의 | 계획 최적화 |
각각이 같은 모델일 필요도 없고, 추론 강도도 다르게 설정할 수 있어요.
구현은 빠른 모델로, 리뷰는 깊이 있는 추론으로.
이게 진짜 흥미로웠던 이유예요.
활성화 방법: 3단계
Step 1: 실험 기능 활성화
~/.codex/config.toml 파일을 열고 (없으면 생성하고):
[features] multi_agent = true
이걸 추가합니다.
설정 파일 경로 확인하는 법:
# 홈 디렉토리 기준 ls ~/.codex/ # config.toml이 없으면 touch ~/.codex/config.toml
Step 2: Codex 재시작
# 실행 중인 Codex 프로세스 종료 후 재시작 codex --version # 버전 확인 codex # 재시작
재시작 안 하면 설정이 적용이 안 돼요. 이거 처음에 몰라서 5분 날렸습니다.
Step 3: 에이전트 역할 정의
[agents] 섹션에 역할을 추가합니다:
[features] multi_agent = true [agents.reviewer] description = "코드의 보안 취약점, 논리적 정확성, 테스트 커버리지 리스크를 집중 검토합니다. 구현 스타일보다 결함 탐지를 우선합니다." [agents.implementer] description = "기능 요구사항을 코드로 구현합니다. 간결하고 테스트 가능한 형태로 작성합니다."
이게 기본 세팅입니다.
역할별로 별도 설정 파일을 지정할 수도 있어요:
[agents.reviewer] description = "보안 및 품질 검토 전담" config_file = "~/.codex/agents/reviewer.toml"
실전 예시: reviewer 역할 하나로 시작하기
저는 처음에 욕심 부리지 않고 reviewer 하나만 만들었어요.
[features] multi_agent = true [agents.reviewer] description = """ 당신은 코드 리뷰 전문 에이전트입니다. 다음 세 가지에만 집중하세요: 1. 보안: SQL 인젝션, 인증 누락, 데이터 노출 위험 2. 정확성: 엣지 케이스 처리, 타입 오류, 논리 결함 3. 테스트: 빠진 테스트 케이스, 불충분한 커버리지 구현 스타일 개선 제안은 하지 마세요. 심각도 순으로 발견된 문제를 보고하세요. """
이렇게 하면 Codex는 코드 작업 흐름에서 구현 → 리뷰 단계를 분리해서 처리해요.
구현 에이전트가 코드를 짜면, 리뷰어 에이전트가 독립적인 시각으로 검토하는 방식입니다.
실제로 써보니: 이게 진짜 효과가 있었던 순간
테스트 프로젝트로 간단한 FastAPI 인증 엔드포인트를 만들어봤어요.
단일 에이전트로 “인증 엔드포인트 만들어줘”를 시켜도 코드가 나왔는데, 보안 이슈가 있었어요. 토큰 만료 검증을 빠뜨린 거예요. 에이전트 본인은 몰랐고요.
Multi Agent에서 reviewer를 붙이니까 달랐습니다.
[reviewer 발견 사항]
심각도 HIGH:
- JWT 토큰 만료(exp) 검증 없음: 만료된 토큰으로 무한 접근 가능
- 토큰 서명 검증 알고리즘이 'none'으로 설정 가능: 서명 우회 가능
심각도 MEDIUM:
- 에러 메시지가 "Invalid token: {detail}"로 내부 정보 노출
- refresh_token 로테이션 없음
테스트:
- 만료 토큰 거부 테스트 케이스 없음
- 알고리즘 조작 공격 테스트 없음
이 피드백이 구현 에이전트한테 넘어가서, 다음 이터레이션에서 수정이 됐어요.
단일 에이전트로 계속 돌렸으면 이 이슈들이 그냥 넘어갔을 거예요.
이게 역할 분리의 핵심이에요.
쓰는 사람이 검증도 하면, 자기 코드에 관대해진다.
내가 빠진 함정: 지시문 충돌
여기서 진짜 중요한 얘기를 해야 해요.
Multi Agent 설정하면서 가장 헤맨 부분이에요.
처음에 이렇게 설정했어요:
[agents.reviewer] description = "코드를 개선하고 최적화합니다. 더 나은 방법이 있으면 제안하세요." [agents.implementer] description = "코드를 작성합니다. 리뷰어의 피드백을 반영합니다."
문제가 뭔지 보이세요?
reviewer한테 “개선하고 최적화”하라고 했는데, 이 에이전트가 리뷰만 하는 게 아니라 코드를 직접 바꾸려는 시도를 해요.
그러면서 implementer가 만든 코드와 충돌이 생겼어요.
둘 다 같은 파일을 건드리려 하는 거예요.
교훈은 이거예요.
역할 간 지시문 충돌이 성능을 죽인다.
reviewer는 정말 “찾기만” 해야 해요. “고쳐주기”가 아니라.
# 잘못된 예 (충돌 발생) description = "코드를 검토하고 더 나은 방향으로 개선합니다" # 올바른 예 (명확한 역할 분리) description = "코드를 검토하고 발견된 문제를 보고합니다. 직접 코드를 수정하지 않습니다."
“보고하다”와 “수정하다”의 차이가 역할 충돌을 만들거나 막아요.
이게 처음에 안 써있던 부분이에요. 직접 부딪혀봐서 알았습니다.
역할별 설정 심화: 모델과 추론 강도 조정
2026년 2월 현재 Codex config.toml에서 역할별 추가 설정을 지원합니다:
[agents.reviewer] description = "보안·정확성·테스트 결함만 보고합니다. 수정 제안 없음." # 역할별 개별 설정 파일 연결 가능 config_file = "~/.codex/agents/reviewer.toml"
역할 전용 설정 파일에서는 추론 강도 등을 조정할 수 있어요:
# ~/.codex/agents/reviewer.toml [model] reasoning_effort = "high" # 꼼꼼하게 생각하도록
구현 에이전트한테는 빠른 추론, 리뷰어한테는 깊은 추론.
같은 모델이라도 추론 강도를 다르게 주면 특화가 가능해요.
비용도 생각해야 하는데, 리뷰어만 high 추론으로 설정하면 전체 비용이 적당히 올라가는 대신 품질 게이트 역할을 해줘요.
실패 패턴 모음: 이건 하지 마세요
Multi Agent를 써보면서 빠지기 쉬운 함정들이 있어요.
실패 1: 역할 수 너무 많이 만들기
처음에 욕심 부려서 5개 역할을 설정했어요.
[agents.planner] [agents.architect] [agents.implementer] [agents.reviewer] [agents.documenter]
이거 돌리면 어떻게 되냐고요?
각 에이전트가 다른 에이전트가 있는지 모르고 자기 역할을 과도하게 해석해요.
planner가 설계도를 짜고, architect도 설계를 하고, implementer가 또 자기 방식으로 구조를 잡으면서 방향이 세 갈래로 갈립니다.
처음에는 2개로 시작하세요. implementer + reviewer.
나머지는 안정화된 다음에 추가하는 거예요.
실패 2: 지시문에 “할 수 있으면 ~도”를 넣기
# 잘못 description = "코드를 검토하고, 가능하면 직접 수정도 해줍니다"
“가능하면”이 들어가는 순간 에이전트는 그걸 항상 한다고 이해해요.
역할이 명확하지 않으면 충돌납니다.
# 올바름 description = "코드 검토 전담. 발견 사항을 목록으로 보고합니다. 수정 불가."
단호하게 범위를 잘라야 해요.
실패 3: 실험 기능 의존도 무시하기
이 기능은 아직 [features] 섹션에 들어가 있어요.
실험 기능입니다.
Codex 버전 업데이트 후에 설정이 무시되거나, 동작이 바뀔 수 있어요.
실전에 쓰려면 롤백 계획이 있어야 합니다.
# 버전 확인 습관화 codex --version # 설정 파일 백업 cp ~/.codex/config.toml ~/.codex/config.toml.backup
그리고 팀에서 쓰는 경우라면, Codex 버전을 고정해두세요.
planner / implementer / reviewer 3역할 실험
어느 정도 안정이 되면, 3역할 구성을 해볼 수 있어요.
[features] multi_agent = true [agents.planner] description = """ 작업 범위를 정의합니다. - 성공 기준 3개를 명시합니다 - 구현 금지 파일/범위를 명시합니다 - 리스크 2개를 사전 식별합니다 계획만 작성하고 코드를 작성하지 않습니다. """ [agents.implementer] description = """ planner의 범위 정의를 받아 코드를 구현합니다. - 명시된 성공 기준만 충족합니다 - 범위 외 파일은 건드리지 않습니다 - 단위 테스트를 함께 작성합니다 """ [agents.reviewer] description = """ implementer의 코드를 검토합니다. 검토 범위: 보안 취약점 / 논리 오류 / 테스트 누락 결과물: 심각도별 발견 목록 (수정 직접 수행 금지) """
이 구성으로 작은 태스크 3개를 테스트했을 때 결과 비교예요:
| 방식 | 보안 이슈 탐지 | 논리 오류 탐지 | 재작업 횟수 |
|---|---|---|---|
| 단일 에이전트 | 1/3 | 1/3 | 3회 |
| implementer + reviewer | 2/3 | 2/3 | 1회 |
| planner + implementer + reviewer | 3/3 | 3/3 | 0회 |
플래너가 들어가면서 범위가 명확해지니까, 구현이 한 번에 맞게 나오는 경우가 많아졌어요.
물론 실험 샘플이 작아서 완벽한 데이터는 아닙니다. 더 해봐야 알 수 있어요.
내가 느낀 점
처음에 이 기능을 봤을 때의 반응은 “이게 필요한가?”였어요.
단일 에이전트로도 코드 잘 나오는데, 굳이 복잡성을 늘려야 하나.
근데 실제로 써보고 나서 바뀐 건, 보안 이슈를 찾는 시각이에요.
제가 구현을 짜면서 검토도 하면, 제 논리 안에서만 보게 돼요.
“이건 당연히 맞겠지”라고 넘어가는 게 생기거든요.
근데 리뷰어 에이전트는 그 맥락을 모르고 코드만 봐요.
“토큰 만료 검증 없음”이라는 피드백이 나왔을 때, 저는 “아, 당연히 나중에 추가할 건데”라고 생각했는데, 리뷰어는 그 맥락을 모르고 결함으로 잡은 거예요.
그 냉정함이 필요했어요.
단일 에이전트 방식이 나쁜 게 아니라, 역할 분리는 “자기 코드에 너그러워지는 것”을 방지하는 장치예요.
솔직한 마음
Multi Agent가 만능은 아니에요.
솔직히 말하면, 대부분의 개인 프로젝트에서는 단일 에이전트 + 명확한 프롬프트로 충분할 수 있어요.
Multi Agent가 빛나는 경우는 이런 때예요:
- 반복적으로 같은 종류의 실수가 나올 때 — 리뷰어가 그 패턴을 잡아줘요
- 코드베이스가 커져서 맥락이 분산될 때 — 역할이 명확하면 각자 집중할 수 있어요
- 보안이 중요한 프로젝트 — 독립적인 검토가 진짜 가치 있어요
그 전에 억지로 도입하면, 복잡성만 늘어나고 지시문 충돌로 오히려 더 힘들어져요.
저도 처음에 그랬거든요.
5개 역할 세팅하고 다 꼬여서 2개로 줄인 다음에야 제대로 돌아갔어요.
앞으로 할 것들
지금 당장 적용해볼 수 있는 것들이에요.
오늘:
~/.codex/config.toml에multi_agent = true추가reviewer역할 1개만 정의 (보안/정확성/테스트 3가지만)- 현재 진행 중인 프로젝트 하나에 테스트 적용
이번 주:
implementer+reviewer2역할 구성으로 실제 Task 3개 처리- 역할별 발견 사항 기록 → 단일 에이전트 대비 품질 차이 측정
- 지시문 충돌 패턴 발생 시 즉시 범위 축소
보류 중:
- 3역할(planner + implementer + reviewer) 도입은 2역할이 안정된 이후
- 역할별 다른 모델/추론 강도 설정은 버전/환경 확인 후
- 팀 적용은 Codex 버전 고정 정책 수립 후
가장 중요한 건, 작게 시작하는 거예요.
2개 역할로 충분히 익숙해지고 나서 확장하는 게, 처음부터 5개 역할 세팅하고 헤매는 것보다 훨씬 빨리 실무에 안착해요.
팀 적용 가이드: 표준 템플릿과 운영 규칙
팀에서 Codex Multi Agent를 쓰기로 했다면, 이 다섯 가지를 먼저 정해야 해요.
1. 버전 고정
# Codex 버전 확인 + 고정 codex --version # 예: 1.x.x # 팀 공용 config.toml에 버전 주석 # [meta] # codex_version = "1.x.x" # 이 버전 기준 설정
실험 기능은 버전에 따라 동작이 달라질 수 있어요. 팀 전체가 같은 버전을 써야 해요.
2. 역할 정의 공유 파일
~/.codex/
config.toml (개인 기본 설정)
agents/
reviewer.toml (팀 공통 리뷰어 지시문)
implementer.toml (팀 공통 구현 지시문)
역할 정의를 개인 로컬에 뒤죽박죽 저장하면, 팀원마다 리뷰어 동작이 달라져요.
공통 파일을 Git repo에 올려서 공유하는 게 낫습니다.
3. 롤백 기준 명확화
Multi Agent 비활성화 조건: - Codex 버전 업데이트 후 역할 동작 변경 확인 시 - 지시문 충돌로 2회 이상 결과 불일치 발생 시 - 프로젝트 크기 작을 때 (150줄 미만 단순 태스크)
“언제 끄는가”를 미리 정해두지 않으면, 돌아가는 것 같아 보여도 품질이 떨어지고 있는 걸 못 잡아요.
4. 역할별 산출물 형식 표준화
# reviewer 보고서 형식 ## 발견 사항 ### 심각도 HIGH - [파일명:라인] 내용 — 이유 ### 심각도 MEDIUM - [파일명:라인] 내용 — 이유 ### 심각도 LOW - [파일명:라인] 내용 — 이유 ## 통과 항목 - (이슈 없는 항목 명시)
형식을 고정하면 후속 처리가 쉬워져요. 다음 이터레이션에서 어느 이슈를 처리했는지 추적도 되고.
5. 주간 회고
Multi Agent 설정은 한 번 만들고 끝이 아닙니다.
지시문을 계속 다듬어야 해요.
주간 회고 항목: - 리뷰어가 놓친 것은 무엇인가? - 리뷰어가 과도하게 잡은 건 무엇인가? - 역할 간 충돌이 발생했나? - 지시문에서 수정할 표현은?
2주마다 지시문을 한 번씩 다듬으면, 3개월 후에는 프로젝트 특성에 맞는 리뷰어가 됩니다.
FAQ
Q: multi_agent = true 설정 후 기존 단일 에이전트 작업에 영향이 있나요?
A: 기본적으로는 없습니다. [agents] 섹션에 역할을 정의하지 않으면, 기존 단일 에이전트 방식으로 동작합니다. 역할을 추가할수록 해당 역할이 작업에 개입하는 방식으로 작동해요.
Q: 역할별로 다른 모델을 쓸 수 있나요?
A: 2026년 2월 현재, 역할별 모델 변경 지원 여부는 버전과 환경에 따라 다릅니다. 공식 문서에서 최신 config 옵션을 확인하는 게 정확합니다. 추론 강도(reasoning_effort) 조정은 일부 환경에서 지원됩니다.
Q: 지시문이 충돌하면 어떤 증상이 나타나나요?
A: 에이전트가 자기 역할 범위 밖의 작업을 시도하거나, 두 에이전트가 같은 파일을 수정하려 해서 결과가 덮어씌워지는 경우가 나타납니다. 결과물이 매번 달라지거나, 한쪽 에이전트의 작업이 반영되지 않는 것처럼 보이면 지시문 충돌 신호예요.
Q: Codex 앱(데스크톱)의 Multi Agent와 config.toml 방식이 다른가요?
A: 네, 다릅니다. Codex 데스크톱 앱은 Git worktree 기반으로 완전히 독립된 환경에서 여러 에이전트를 동시에 실행하는 방식이에요. config.toml Multi Agent는 CLI 환경에서 역할 분리로 순차 또는 협력 처리를 구성하는 방식이라 더 세밀한 지시문 설계가 필요합니다.
Q: 실험 기능이라 불안한데, 실무에 써도 될까요?
A: 단독 사용은 괜찮지만, 롤백 계획이 있어야 해요. 설정 파일 백업, Codex 버전 고정, 멀티 에이전트 없이도 돌아가는 단일 에이전트 대비 설정을 항상 유지하세요. “실험 기능 의존도 감소 기준선”을 팀에서 정해두면 좋습니다.
Q: Windows나 Linux에서도 가능한가요?
A: Codex CLI는 플랫폼 제한이 없어요. config.toml 방식의 Multi Agent 설정도 동일하게 적용됩니다. 다만 환경별로 경로나 동작에 차이가 있을 수 있으니, 처음 세팅 시 간단한 테스트로 확인을 먼저 하세요.
결론
Codex Multi Agent는 config.toml 몇 줄로 시작하지만, 진짜 가치는 지시문 설계에서 나와요.
multi_agent = true 넣는 건 30초면 끝납니다.
근데 reviewer 역할이 구현 에이전트와 충돌 없이 작동하게 만드는 건, 몇 번의 실패를 거쳐야 해요.
저도 5개 역할로 시작했다가 다 꼬여서 2개로 줄였고, 지시문에서 “개선하다”라는 단어 하나 때문에 에이전트가 충돌했고, 재시작 안 하고 설정 적용됐다고 착각한 적도 있어요.
근데 그 삽질을 거치고 나서, 지금은 단일 에이전트보다 결함 탐지율이 눈에 띄게 올라갔어요.
reviewer가 찾아낸 JWT 토큰 만료 누락, SQL 파라미터 바인딩 문제. 이런 것들을 제가 직접 리뷰했으면 아마 넘어갔을 거예요.
“쓰는 사람이 검증도 하면, 자기 코드에 관대해진다.”
이게 역할 분리를 해야 하는 이유입니다.