vignette/docs/ops/codex-agents

Codex 워커 정의 참조 사본

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

설치

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

~/.codex/config.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이 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절 동기화 규칙).