Codex Agent Configuration

Alcance: configurar un rol utilizable

Esta guía documenta configuración de custom agents y subagentes de Codex según fuentes oficiales consultadas el 2026-11-09. Complementa agent-profiles, subagents-and-delegation y orchestrator-agent con ejemplos de producto. Todos los archivos mostrados son ejemplos dentro del artículo; no se crearon configuraciones reales para el Atlas.

La guía de subagents describe archivos TOML independientes en .codex/agents/ para un proyecto y ~/.codex/agents/ para agentes personales. Cada uno requiere name, description y developer_instructions. El nombre identifica al agente; hacer coincidir archivo y nombre simplifica mantenimiento.

Ejemplo de perfil de revisión

Un archivo ilustrativo .codex/agents/document_reader.toml podría contener:

name = "document_reader"
description = "Revisa documentos asignados y devuelve hallazgos con evidencia."
developer_instructions = """
Revisa únicamente el alcance recibido y amplíalo cuando una duda concreta lo justifique.
No edites archivos. Devuelve hallazgos con ubicación, motivo e incertidumbres.
No publiques ni delegues trabajo adicional.
"""
 
[features]
apps = false
plugins = false

Las instrucciones delimitan el trabajo deseado. Los flags recortan esas capacidades soportadas; la frase «no edites» no crea un sandbox de solo lectura. Para esa restricción técnica, configurar la sesión según codex-permissions-and-approvals-configuration. Deshabilitar apps o plugins tampoco implica deshabilitar todo acceso por herramientas de archivos o shell.

La documentación permite reducir otras capacidades soportadas, como features.shell_tool. Debe examinarse qué herramientas efectivas quedan disponibles: retirar shell elimina una vía de ejecución, no demuestra por sí solo aislamiento frente a todas las vías de escritura.

Modelo, esfuerzo y configuración de sesión

El perfil puede personalizar modelo, esfuerzo e instrucciones dentro de las opciones admitidas. El ejemplo omite modelo y esfuerzo para no fijar un modelo o nivel incompatible con otra cuenta. La referencia de configuración documenta model_reasoning_effort y advierte que los valores disponibles dependen del modelo y cliente.

Antes de añadir opciones, identificar su scope:

Decisión	Dónde comprobarla
Nombre, propósito e instrucciones del especialista	Archivo del custom agent.
Modelo y esfuerzo disponibles	Perfil, sesión y catálogo accesible a la cuenta.
Sandbox y aprobación	Sesión padre; no se reemplazan desde el custom agent.
MCP y proveedor	Configuración heredada del padre y sus controles.
Procedimiento reutilizable	codex-skill-configuration.

Un perfil de Copilot con tools: [read, search] utiliza otro contrato. No debe copiarse como si fuera el schema TOML de Codex. coding-agent-development-format-reference permite comparar esos formatos.

Usarlo como subagente u orquestador

Según la guía oficial, los subagentes heredan permisos de la sesión padre; un custom agent no establece su propio sandbox independiente. Un reviewer lanzado desde una sesión con escritura no se vuelve técnicamente read-only solo por su nombre o instrucciones.

El rol orquestador puede describirse mediante instrucciones de descomposición, integración y parada, pero ese nombre no otorga privilegios especiales. Un encargo ilustrativo sería:

Delegá en document_reader la revisión de los dos documentos indicados.
Debe devolver hallazgos y fuentes; conservá la integración y aceptación global.
No habilites nuevas capacidades ni amplíes el encargo a otros archivos sin motivo.

La aparición de un perfil y la creación de una ejecución son evidencias distintas. El ejemplo de prompt es documental: no se delegó trabajo para escribir esta guía.

Comprobación antes de adoptar

Confirmar versión del cliente, descubrimiento del perfil y nombre utilizado. En un laboratorio, asignar una revisión pequeña y observar si el participante recibe el encargo, qué herramientas tiene y qué resultado devuelve. Verificar por separado las restricciones del runtime, incluso si el texto final afirma haberlas respetado.

Para repartir lectura y escritura con fronteras distintas, evaluar sesiones o entornos separados que apliquen cada política, en lugar de asumir permisos independientes entre subagentes hermanos. generated-code-verification conserva la aceptación del trabajo y agent-evaluation la evaluación entre tareas. Esta guía no certifica comportamiento de una instalación concreta.