하위 에이전트

이용 요건을 충족하는 계정은 ChatGPT Work에서 하위 에이전트 워크플로우를 사용하고 에이전트의 활동을 확인할 수 있습니다.

현재 Codex 릴리스에서는 하위 에이전트 워크플로우가 기본으로 활성화되어 있습니다. ChatGPT 데스크톱 앱, Codex CLI, IDE 확장 프로그램에서 하위 에이전트의 활동을 확인할 수 있습니다.

ChatGPT Work에서는 독립적으로 진행할 수 있는 작업을 하위 에이전트에 위임해 달라고 ChatGPT에 요청하세요. 에이전트는 ChatGPT가 호스팅하는 환경에서 실행되며, 채팅에서 활동과 결과를 확인할 수 있습니다. 대부분의 추론 수준에서는 위임을 명시적으로 요청하세요. Ultra 설정에서는 여러 에이전트를 병렬로 실행해 속도나 품질을 크게 높일 수 있을 때 ChatGPT가 스스로 작업을 위임할 수 있습니다.

앱 채팅에서 독립적으로 진행할 수 있는 부분을 하위 에이전트에 위임해 달라고 Codex에 요청하세요. 현재 로컬 Codex 릴리스에서는 사용자가 직접 요청하거나 해당 작업에 적용되는 AGENTS.md 또는 스킬 지침에서 위임을 요청하면 작업을 위임합니다. 앱에서 각 하위 에이전트의 스레드를 열어 작업 내용과 기본 채팅에 반환된 요약을 확인할 수 있습니다.

대화형 CLI 세션에서 하위 에이전트를 사용해 달라고 Codex에 요청하세요. Codex는 해당 작업에 적용되는 AGENTS.md 또는 스킬 지침에 따라 작업을 위임할 수도 있습니다. 에이전트가 실행되는 동안 /subagents로 에이전트 스레드를 확인하거나 다른 스레드로 전환할 수 있습니다. 기본 스레드는 하위 에이전트의 결과를 모아 최종 응답을 작성합니다.

IDE 채팅에서 독립적으로 진행할 수 있는 부분을 하위 에이전트에 위임해 달라고 Codex에 요청하세요. Codex는 해당 작업에 적용되는 AGENTS.md 또는 스킬 지침에 따라 작업을 위임할 수도 있습니다. 백그라운드 에이전트 UI를 사용할 수 있으면 실행 중인 하위 에이전트가 Composer 위에 표시됩니다. 패널을 펼치면 상태를 확인하거나, 실행 중인 하위 에이전트를 모두 중지하거나, 개별 하위 에이전트 스레드를 열 수 있습니다.

대부분의 추론 수준에서는 하위 에이전트를 사용하거나 여러 에이전트로 병렬 작업을 진행해 달라고 직접 요청하세요. Ultra 설정에서는 ChatGPT가 별도 요청 없이도 독립적으로 진행하기에 적합한 작업을 위임할 수 있습니다.

하위 에이전트를 사용하거나 여러 에이전트로 병렬 작업을 진행해 달라고 직접 요청하세요. 해당 작업에 적용되는 프로젝트 또는 스킬 지침에서 위임을 요청하면 Codex가 작업을 위임할 수도 있습니다.

ChatGPT Work에서는 Composer에서 모델과 추론 수준을 선택하세요. 선택한 모델에 따라 Light, Medium, High, Extra High, Max 등의 추론 수준을 사용할 수 있습니다. Ultra 설정은 이용 요건을 충족하는 계정에서 지원 모델을 사용할 때만 선택할 수 있습니다. 이 설정에서는 추론 강도를 최대로 높이고, ChatGPT가 적합한 작업을 스스로 하위 에이전트에 위임할 수 있습니다.

다른 추론 수준에서 작업을 나눠 병렬로 위임하려면 하위 에이전트 사용을 명시적으로 요청하세요.

하위 에이전트의 모델과 model_reasoning_effort를 모두 설정하지 않으면 하위 에이전트는 상위 에이전트의 모델과 추론 강도를 상속합니다. 에이전트 생성 요청에서 모델을 명시하거나 [agents] 기본값으로 모델을 선택했는데 요청과 설정 어디에도 추론 강도가 지정되어 있지 않으면 해당 모델의 기본 추론 강도를 사용합니다. 작업별로 모델 성능, 속도, 비용을 조절하려면 프롬프트에서 특정 모델이나 추론 강도를 요청하거나, [agents] 기본값을 config.toml에 지정하거나, 사용자 지정 에이전트 파일에 model과 model_reasoning_effort를 직접 설정하세요. 예를 들어 빠르게 훑어볼 때는 gpt-6-luna를 사용하고, 더 깊은 추론이 필요할 때는 gpt-6.1-sol의 추론 강도를 높여 사용하세요.

모델 선택

• gpt-6.1-sol: 까다로운 작업을 맡는 에이전트에는 이 모델부터 사용하세요. 요구 사항이 모호하고 여러 단계에 걸쳐 진행해야 하는 작업에 적합합니다. 넓은 컨텍스트를 유지하면서 계획을 세우고, 도구를 사용하고, 결과를 검증하며 끝까지 수행해야 할 때 사용하세요.
• gpt-6-luna: 작업 범위가 좁고 빠른 처리가 필요한 에이전트에 사용하세요. 지시가 명확하거나 반복 가능한 작업, 처리할 양이 많은 작업에 적합합니다.

추론 강도(model_reasoning_effort)

GPT-6.1 Sol에서는 클라이언트와 선택한 모델이 모두 지원하는 추론 강도를 사용하세요. 모델 설정을 직접 지정할 때 GPT-6 Luna는 high, GPT-6 Astra는 low부터 시작하세요. 이후 선택한 모델이 지원하는 범위에서 작업에 맞게 조정하세요.

• ultra: 가장 깊은 추론이 필요하고 선택한 모델이 이 수준을 지원할 때 사용하세요.
• max 및 xhigh: 특히 까다로운 추론이 필요하고 선택한 모델이 해당 수준을 지원할 때 사용하세요.
• high: 코드 리뷰나 보안 점검을 맡는 에이전트처럼 복잡한 로직을 추적하거나 가정을 검증하거나 경계 사례를 분석해야 할 때 사용하세요.
• medium: 속도와 추론 깊이의 균형을 맞춥니다.
• low: 작업이 단순하고 속도가 가장 중요할 때 사용하세요.

추론 강도를 높이면 응답 시간과 토큰 사용량이 늘지만 복잡한 작업의 품질은 향상될 수 있습니다. 자세한 내용은 모델, 설정 기초, 설정 레퍼런스를 참고하세요.

대부분의 추론 수준에서는 사용자가 직접 요청하면 ChatGPT가 에이전트를 생성합니다. Ultra 설정에서는 병렬 작업이 유용할 때 ChatGPT가 스스로 작업을 위임할 수도 있습니다.

현재 로컬 Codex 릴리스에서는 사용자가 직접 요청하거나 해당 작업에 적용되는 프로젝트 또는 스킬 지침에서 요청하면 에이전트를 생성합니다.

하위 에이전트를 열면 읽기 전용인 진행 중 목록과 완료 목록이 표시됩니다. 작업을 마친 하위 에이전트를 선택해 세부 정보와 결과를 확인하세요. 웹 사이드바에서는 하위 에이전트의 활동을 확인할 수 있지만 개별 에이전트를 중지하거나 추가 지시를 내릴 수는 없습니다.

• 기본 스레드에 표시되는 활동에서 하위 에이전트 스레드를 열어 작업 내용을 확인하세요.
• 실행 중인 하위 에이전트에 추가 지시를 내리거나 중지하려면 Codex에 직접 요청하세요. 작업을 마친 하위 에이전트의 스레드를 닫아 달라고 요청할 수도 있습니다.

Report checklistPresentation checkliststarted working

• CLI에서 /subagents를 사용해 실행 중인 에이전트 스레드 사이를 전환하고 해당 스레드의 진행 상황을 확인하세요.
• 실행 중인 하위 에이전트에 추가 지시를 내리거나 중지하려면 Codex에 직접 요청하세요. 작업을 마친 에이전트의 스레드를 닫아 달라고 요청할 수도 있습니다.

• 백그라운드 에이전트 패널을 사용할 수 있으면 패널을 펼쳐 상태를 확인하거나, 실행 중인 하위 에이전트를 중지하거나, 하위 에이전트 스레드를 여세요.
• 실행 중인 하위 에이전트에 추가 지시를 내리거나 중지하려면 Codex에 직접 요청하세요. 작업을 마친 하위 에이전트의 스레드를 닫아 달라고 요청할 수도 있습니다.

하위 에이전트는 현재 샌드박스 정책을 상속합니다.

ChatGPT Work는 자체 호스팅 환경에서 하위 에이전트를 실행하며 로컬 Codex 샌드박스나 승인 모드를 조정하는 기능은 제공하지 않습니다. 하위 에이전트는 상위 채팅에서 사용할 수 있는 도구를 사용합니다. 웹사이트와 커넥터에 대한 권한은 각 도구에 따라 다릅니다.

하위 에이전트는 Composer 아래에서 선택한 권한 모드를 상속합니다. Codex에 작업 위임을 요청하기 전에 상위 턴의 권한 모드를 선택하세요.

대화형 CLI 세션에서는 기본 스레드를 보고 있는 동안에도 비활성 에이전트 스레드에서 보낸 승인 요청이 표시될 수 있습니다. 승인 오버레이에는 요청을 보낸 스레드의 레이블이 표시됩니다. 요청을 승인하거나 거부하거나 답변하기 전에 o를 눌러 해당 스레드를 열 수 있습니다.

비대화형 플로우이거나 실행 중에 새 승인 요청을 표시할 수 없는 경우, 새 승인이 필요한 작업은 실패하고 Codex는 상위 워크플로우에 오류를 전달합니다.

하위 에이전트는 /permissions 또는 --yolo로 변경한 내용을 포함해 상위 턴의 현재 샌드박스 및 승인 설정을 상속합니다. 사용자 지정 에이전트 파일로는 이 설정을 재정의할 수 없습니다.

하위 에이전트는 Composer 아래에서 선택한 권한 모드를 상속합니다. Codex에 작업 위임을 요청하기 전에 상위 턴의 권한 모드를 선택하세요.

샌드박스 및 승인 설정은 상위 세션에서 지정하세요. 사용자 지정 에이전트 지침으로 수정을 피하도록 요청할 수는 있지만, 이 지침이 별도의 읽기 전용 샌드박스를 만들지는 않습니다.

사용자 지정 에이전트

Codex는 다음 에이전트를 기본 제공합니다.

• default: 별도로 지정된 에이전트가 없을 때 사용하는 범용 에이전트입니다.
• worker: 구현과 수정을 직접 수행하는 데 중점을 둔 에이전트입니다.
• explorer: 주로 코드를 읽으며 코드베이스를 탐색하는 에이전트입니다.

사용자 지정 에이전트를 정의하려면 개인용 에이전트는 ~/.codex/agents/에, 프로젝트 전용 에이전트는 .codex/agents/에 개별 TOML 파일을 추가하세요.

파일 하나에 사용자 지정 에이전트 하나를 정의합니다. 사용자 지정 에이전트는 모델 설정과 지침을 변경하거나 지원되는 기능을 비활성화할 수 있습니다. 권한, 공급자, MCP 서버는 상위 에이전트에서 상속하며 사용자 지정 에이전트 파일로 재정의할 수 없습니다.

각 사용자 지정 에이전트 파일에는 다음 필드가 필요합니다.

• name
• description
• developer_instructions

사용자 지정 에이전트 파일에 model 또는 model_reasoning_effort를 설정하면 해당 필드는 파일에 지정한 값이 우선합니다. 파일을 적용하기 전에 Codex는 각 설정값을 에이전트 생성 요청에 명시한 값, 해당 [agents] 기본값, 상위 에이전트의 값 순으로 결정합니다. 생성 요청이나 [agents] 기본값에서 모델을 선택했고 양쪽 모두 추론 강도를 지정하지 않았다면 Codex는 해당 모델의 기본 추론 강도를 사용합니다. 사용자 지정 에이전트 파일에 model만 설정하면 앞서 결정된 추론 강도가 유지됩니다. 선택한 모델이 그 강도를 지원하지 않거나 다른 강도를 사용하려면 파일에 model_reasoning_effort도 설정하세요. 스킬은 상위 에이전트에서 상속하며, 사용자 지정 에이전트에서 skills.config로 개별 스킬을 비활성화할 수 있습니다.

전역 설정

하위 에이전트의 전역 설정은 기존과 마찬가지로 [agents] 섹션에 지정합니다. 자세한 내용은 설정 문서를 참고하세요.

참고 사항

• agents.enabled의 기본값은 true입니다. 다중 에이전트 도구를 비활성화하려면 false로 설정하세요.
• agents.max_concurrent_threads_per_session을 설정하지 않으면 Codex가 기본값을 선택합니다. 기존 설정에서는 이전 이름인 agents.max_threads를 별칭으로 계속 사용할 수 있습니다.
• 에이전트 생성 요청에 명시한 값은 agents.default_subagent_model과 agents.default_subagent_reasoning_effort보다 우선합니다.
• agents.interrupt_message의 기본값은 true입니다. 모델이 볼 수 있는 중단 메시지를 에이전트의 컨텍스트에서 제외하려면 false로 설정하세요.
• 사용자 지정 에이전트의 이름이 explorer 같은 기본 제공 에이전트의 이름과 같으면 사용자 지정 에이전트가 우선합니다.

사용자 지정 에이전트 파일 스키마

model, model_reasoning_effort, model_reasoning_summary, model_verbosity로 모델의 동작을 조정하세요. 각 설정에 사용할 수 있는 값은 설정 레퍼런스를 참고하세요.

사용자 지정 에이전트의 기능을 제한하려면 비활성화할 기능 키의 값을 false로 설정하세요. 지원되는 키는 features.shell_tool, features.apps, features.plugins, features.memories, features.request_permissions_tool입니다. 개별 스킬은 skills.config로, 번들 스킬은 skills.bundled.enabled = false로 비활성화하세요. 자동으로 포함되는 스킬 지침 블록을 제외하려면 skills.include_instructions = false를 설정하세요. 관리 정책에서 정한 요구 사항은 계속 적용됩니다.

sandbox_mode, approval_policy, model_provider, mcp_servers를 비롯한 다른 세션 설정은 사용자 지정 에이전트 파일에 넣어도 상위 세션의 설정을 재정의하지 않습니다. 서비스 등급도 최상위 세션에서 선택한 값을 따릅니다. 에이전트가 MCP 서버를 사용할 수 있도록 상위 세션에서 서버를 설정하세요.

Codex는 name 필드로 사용자 지정 에이전트를 식별합니다. 파일 이름을 에이전트 이름과 일치시키는 것이 가장 간단하지만, 실제 식별 기준은 name 필드입니다.

사용자 지정 에이전트 예시

사용자 지정 에이전트는 담당 범위를 좁히고 작업 방식을 구체적으로 정할 때 가장 효과적입니다. 각 에이전트에 명확한 역할과 그 역할에 맞는 도구를 부여하고, 담당 범위를 벗어나지 않도록 지침을 작성하세요.

다음 예시에서는 로그인한 계정이나 워크스페이스에 액세스 권한이 있는 경우 GPT-6.1 Sol을 사용합니다. 사용할 수 없다면 액세스 가능한 모델을 선택하세요.

예시 1: PR 리뷰

이 패턴에서는 사용자 지정 에이전트 세 개가 역할을 나눠 리뷰합니다.

• pr_explorer는 코드베이스 구조를 파악하고 근거를 수집합니다.
• reviewer는 코드가 올바르게 동작하는지 확인하고 보안 및 테스트 관련 위험을 찾습니다.
• docs_researcher는 전용 MCP 서버를 사용해 프레임워크 또는 API 문서를 확인합니다.

프로젝트 설정(.codex/config.toml):

[agents]
max_concurrent_threads_per_session = 8

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

.codex/agents/pr-explorer.toml:

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Stay in exploration mode.
Do not edit files.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
Prefer fast search and targeted file reads over broad scans.
"""

.codex/agents/reviewer.toml:

1
2
3
4
5
6
7
8
9
10name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
Review code like an owner.
Do not edit files.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
"""

.codex/agents/docs-researcher.toml:

name = "docs_researcher"
description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Use the docs MCP server to confirm APIs, options, and version-specific behavior.
Return concise answers with links or exact references when available.
Do not make code changes.
"""

이 구성은 다음과 같은 프롬프트에 적합합니다.

이 브랜치를 main과 비교해 리뷰해 줘. pr_explorer에게는 변경의 영향을 받는 코드 경로를 정리하게 하고, reviewer에게는 실제 위험 요소를 찾게 하고, docs_researcher에게는 패치에서 사용하는 프레임워크 API를 검증하게 해 줘.

예시 2: 프런트엔드 통합 디버깅

이 패턴은 UI 회귀, 간헐적으로 실패하는 브라우저 플로우, 애플리케이션 코드와 실행 중인 제품 양쪽을 살펴봐야 하는 통합 버그를 조사할 때 유용합니다.

프로젝트 설정(.codex/config.toml):

[agents]
max_concurrent_threads_per_session = 6

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
startup_timeout_sec = 20

.codex/agents/code-mapper.toml:

name = "code_mapper"
description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Map the code that owns the failing UI flow.
Do not edit files.
Identify entry points, state transitions, and likely files before the worker starts editing.
"""

.codex/agents/browser-debugger.toml:

1
2
3
4
5
6
7
8
9name = "browser_debugger"
description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.
Use browser tooling for screenshots, console output, and network evidence.
Do not edit application code.
"""

.codex/agents/ui-fixer.toml:

name = "ui_fixer"
description = "Implementation-focused agent for small, targeted fixes after the issue is understood."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Own the fix once the issue is reproduced.
Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.
"""

[[skills.config]]
path = "/Users/me/.agents/skills/docs-editor/SKILL.md"
enabled = false

이 구성은 다음과 같은 프롬프트에 적합합니다.

설정 모달에서 변경 사항이 저장되지 않는 이유를 조사해 줘. browser_debugger에게는 문제를 재현하게 하고, code_mapper에게는 문제가 발생하는 코드 경로를 추적하게 해 줘. 저장이 어떻게 실패하는지 명확해지면 ui_fixer에게 최소한의 변경으로 문제를 수정하게 해 줘.