Configuración práctica de subagentes en Codex: explorar, verificar y entregar con seguridad

Guía práctica para configurar subagentes de Codex por rol y combinar exploración paralela, verificación e implementación segura.

Subagentes de Codex en la práctica

Las tareas grandes pierden fiabilidad cuando requisitos, búsquedas y registros de pruebas comparten un solo hilo. Los subagentes permiten que el hilo principal conserve decisiones y síntesis, mientras exploración, verificación e implementación acotadas se delegan. Las versiones actuales los habilitan por defecto y `/agent` permite inspeccionar los hilos.

> Estos ejemplos se comprobaron el 08-09-2026 con Codex CLI 0.153.4 y documentación oficial. Claves y modelos dependen de versión y cuenta; valida siempre con `--strict-config`.

1. Dividir por independencia

Conviene paralelizar trabajo independiente y de lectura: seguridad, huecos de pruebas y documentación de API. Editar los mismos archivos en paralelo genera conflictos.

• **Explorer:** descubrimiento de archivos y trazado de llamadas, solo lectura.

• **Verifier:** ejecuta pruebas, lint y build; devuelve evidencia exacta.

• **Worker:** implementa el cambio mínimo con propiedad explícita de archivos.

• **Main:** conserva requisitos, prioridad, diff final y conclusiones.

Cada subagente usa su propio modelo y herramientas, por lo que consume más tokens. Úsalo cuando las tareas sean independientes y puedan resumirse brevemente.

2. Configuración global y roles con nombre

```toml

[agents]

default_subagent_model = "gpt-5.4-mini"

default_subagent_reasoning_effort = "low"

max_concurrent_threads_per_session = 4

[agents.explorer]

description = "Read-only codebase mapping and evidence gathering."

config_file = "agents/explorer.toml"

[agents.verifier]

description = "Run tests, lint, build, and report exact failures."

config_file = "agents/verifier.toml"

```

La configuración de usuario vive en `~/.codex/config.toml`; un proyecto de confianza puede añadir `.codex/config.toml`. `config_file` relativo se resuelve desde el archivo que declara el rol. La documentación también admite roles independientes en `~/.codex/agents/` y `.codex/agents/`; el esquema actual exige `name`, `description` y `developer_instructions`. Valida antes de mezclar patrones.

Explorer — read-only

```toml

name = "explorer"

description = "Read-only explorer for locating code and tracing behavior."

developer_instructions = """

Inspect only. Cite files and symbols. Do not edit or propose broad refactors.

Return a concise evidence map to the parent.

"""

model = "gpt-5.4-mini"

model_reasoning_effort = "low"

sandbox_mode = "read-only"

```

Verifier — workspace-write

```toml

name = "verifier"

description = "Runs checks and reports exact failures."

developer_instructions = """

Run the requested checks. Do not fix application code.

Report the command, exit status, failing assertion, and likely root cause.

"""

model = "gpt-5.4"

model_reasoning_effort = "medium"

sandbox_mode = "workspace-write"

```

Los hijos heredan el sandbox y la política de aprobación activos del turno padre. Los cambios de permisos en tiempo de ejecución pueden prevalecer sobre el archivo de rol. Reduce primero los permisos del padre.

3. Validar antes de usar

```bash

codex --version

codex features list

codex exec --strict-config -s read-only \

"Inspect the repository configuration and return a short summary. Do not edit files."

```

`--strict-config` rechaza campos desconocidos. Fallos comunes: `reasoning_effort` en vez de `model_reasoning_effort`, ruta `config_file` inexistente o modelo no disponible. Comprueba `/model`, catálogo local y una ejecución real; inicia una sesión nueva tras cambiar la configuración.

4. Patrones de invocación

```text

Review this branch against main. Run explorer read-only to map changed paths,

and verifier to execute relevant tests and the build. Run them in parallel,

wait for both, then return one summary with file paths, commands, and evidence.

Do not edit code.

```

```text

Run explorer and verifier in parallel first. Only after the main agent confirms

the root cause, start one worker. The worker owns only src/parser.ts and makes

the smallest fix. Finally, verifier reruns the same commands.

```

Indica en el prompt la división, la espera y las condiciones de cierre. Usa `/agent` para inspeccionar, redirigir o detener hilos.

5. Reproducir la separación de roles en Claude Code

Claude Code también admite subagentes personalizados, pero no reutiliza la configuración TOML de Codex. Los roles del proyecto suelen definirse como archivos Markdown, por ejemplo `.claude/agents/explorer.md` y `.claude/agents/verifier.md`. No significa que Claude carezca de agentes: **la estructura TOML de Codex no se aplica allí, y la separación equivalente se describe mediante archivos Markdown de roles**.

```markdown

name: explorer

description: Localiza código y rutas de llamada sin editar.

tools: Read, Grep, Glob

model: haiku

No modifiques archivos. Devuelve al agente principal un mapa breve de evidencias.

```

```markdown

name: verifier

description: Ejecuta pruebas y builds e informa fallos exactos.

tools: Read, Grep, Glob, Bash

No corrijas el código. Informa comandos, códigos de salida y puntos de fallo.

```

Los roles personales van en `~/.claude/agents/`; los del proyecto, en `.claude/agents/`. Comprueba la documentación oficial y la versión instalada porque el frontmatter puede cambiar.

6. Lista de seguridad

• Paraleliza lecturas; serializa escrituras compartidas.

• Da a cada agente una pregunta, un entregable y una condición de parada.

• Verifica comandos, códigos de salida y diffs, no solo el éxito declarado.

• En modo no interactivo, una acción que requiere aprobación puede fallar.

• Evita `danger-full-access` y saltos de aprobación sin un sandbox externo.

• No copies secretos, archivos de autenticación ni rutas personales.

• Empieza con pocos hilos y aumenta solo tras medir el cuello de botella.

7. Receta repetible

Usa **Map → Decide → Change → Verify**: exploradores en áreas independientes; el principal fija alcance; un worker edita; verifier repite comprobaciones limpias; el principal decide con evidencia.

La ventaja no es la cantidad de agentes, sino límites claros: exploración de solo lectura, verificación basada en evidencia y propiedad explícita de archivos.

Referencias

• https://developers.openai.com/codex/subagents

• https://developers.openai.com/codex/config-reference

• https://developers.openai.com/codex/config-file/config-advanced

• https://developers.openai.com/codex/cli