# Codex 워커 정의 참조 사본

> [`AGENTS.md`](../../../AGENTS.md) B.8(Codex 실행 규격)의 워커 역할 정의다. **런타임 위치는 `~/.codex/agents/*.toml`(글로벌)** 이며,
> 이 디렉터리는 다른 PC·협업자가 같은 워커 계층을 설치하도록 두는 참조 사본이다.

## 설치

```powershell
Copy-Item -LiteralPath docs\ops\codex-agents\*.toml -Destination "$env:USERPROFILE\.codex\agents\" -Force
```

`~/.codex/config.toml`에는 다음이 있어야 한다(현재 워크스테이션 값).

```toml
[agents]
enabled = true
default_subagent_model = "gpt-5.6-terra"
default_subagent_reasoning_effort = "medium"
max_concurrent_threads_per_session = 8
```

## 왜 `.codex/agents/`(프로젝트 스코프)에 두지 않는가

- Codex는 신뢰된 프로젝트의 `.codex/agents/`를 글로벌보다 우선해 읽는다고 안내하지만, 프로젝트 스코프 커스텀 서브에이전트가
  스폰되지 않는 이슈 [openai/codex#26408](https://github.com/openai/codex/issues/26408)이 2026-09-06 기준 열려 있다(0.137.0에서 보고, 수정 버전 없음).
- 같은 이름을 `.codex/agents/`에 두면 글로벌 정의를 가려 워커가 아예 안 뜰 수 있다. 이슈가 닫히고 실제 스폰이 확인되면 이 사본을 `.codex/agents/`로 옮긴다.

## 파일

| 파일 | 역할 | 모델 | 샌드박스 |
|---|---|---|---|
| `explorer.toml` | 코드베이스 탐색·근거 수집 | `gpt-5.6-luna` | read-only |
| `researcher.toml` | 웹·문서·논문 스위핑 | `gpt-5.6-luna` | read-only |
| `worker.toml` | 작업 패킷 기반 구현 | `gpt-5.6-terra` | 상위 상속 |
| `verifier.toml` | 검증 명령 실행·원문 보고 | `gpt-5.6-luna` | 상위 상속 |

글로벌 파일을 고치면 이 사본도 같은 내용으로 맞춘다(B절 동기화 규칙).