No te limites a usar Codex: los Hooks son el modo avanzado

Muchas personas usan Codex sobre todo para escribir código, editar archivos y ejecutar comandos. Esa es la parte más visible de Codex, pero quedarse ahí hace fácil pasar por alto una función más adecuada para un uso avanzado: Hook.

El valor de un Hook no está en hacer que Codex escriba mejor código, sino en hacer que trabaje siguiendo reglas. Los Hooks pueden ejecutar scripts personalizados en eventos clave del ciclo de vida, por ejemplo antes de enviar un prompt de usuario, antes o después de una llamada a herramientas, cuando se solicita permiso o cuando termina un turno. Así puedes integrar reglas de equipo, controles de seguridad, protección de privacidad y registro automático dentro del flujo de trabajo de Codex, en lugar de depender siempre de recordatorios manuales.

Un ejemplo típico es una revisión de privacidad. Antes de enviar un prompt a Codex, un Hook puede escanearlo para detectar API keys, tokens, claves privadas, teléfonos, direcciones internas u otra información sensible. Si una regla coincide, puede bloquear el envío o mostrar una advertencia clara para que el usuario limpie el contenido primero.

Qué es un Hook

Un Codex Hook puede entenderse como un manejador de ciclo de vida dentro del flujo de trabajo de Codex. Se activa cuando ocurre un evento configurado y recibe el contexto actual como JSON por la entrada estándar. El script puede devolver avisos, añadir contexto o bloquear acciones posteriores en algunos eventos.

La documentación oficial menciona usos como:

enviar la conversación a un sistema personalizado de logs o analítica;
escanear prompts del equipo para evitar pegar API keys por error;
resumir conversaciones automáticamente para crear memoria persistente;
ejecutar una validación personalizada cuando termina un turno;
añadir contexto o reglas específicas según el directorio actual.

Por eso un Hook se parece más a una capa de control de flujo de trabajo y guardarraíl de seguridad que a una técnica de prompt. El prompt le dice a Codex qué debería hacer; el Hook inserta revisiones, registros y restricciones antes o después de que Codex actúe.

Dónde se colocan los Hooks

Codex puede cargar Hooks desde hooks.json o desde tablas [hooks] dentro de config.toml. Las cuatro ubicaciones más comunes son:

~/.codex/hooks.json
~/.codex/config.toml
<repo>/.codex/hooks.json
<repo>/.codex/config.toml

Los Hooks de usuario sirven para reglas personales comunes, como “no enviar posibles secretos” o “resumir al terminar cada sesión”. Los Hooks de proyecto sirven para normas del repositorio, como “no editar directorios generados”, “comprobar front matter antes de confirmar” o “bloquear comandos peligrosos antes de ejecutarlos”.

La configuración local de proyecto en .codex/ solo se carga cuando esa capa del proyecto está marcada como confiable. Los Hooks de usuario no dependen de la confianza del proyecto. Esto es importante porque los Hooks de proyecto ejecutan scripts locales; un repositorio desconocido no debería recibir confianza automática.

Eventos frecuentes

Los Hooks no tienen un único punto de activación. Cada evento encaja con un uso distinto.

UserPromptSubmit ocurre justo antes de enviar un prompt de usuario. Sirve para revisiones de privacidad, detección de términos sensibles y validación de políticas de prompt. Por ejemplo, si el prompt parece incluir una clave que empieza por sk-, el Hook puede bloquear el envío.

PreToolUse ocurre antes de que Codex llame a una herramienta. Sirve para bloquear comandos, escrituras de archivos o llamadas a herramientas MCP. Por ejemplo, puede detectar rm -rf, escrituras en directorios del sistema o lecturas de rutas sensibles, y devolver una razón de rechazo.

PermissionRequest ocurre cuando Codex va a pedir permiso. Sirve para aprobar o rechazar automáticamente solicitudes bien definidas. Un equipo puede permitir comandos fijos de prueba y rechazar el acceso a ciertos directorios.

PostToolUse ocurre después de ejecutar una herramienta. Sirve para revisar salida de comandos, escanear archivos generados o recordar pasos siguientes. No puede deshacer efectos secundarios ya realizados, pero puede dar feedback antes de que Codex continúe.

SessionStart ocurre cuando una sesión empieza o se reanuda. Sirve para cargar convenciones del proyecto, normas de equipo, contexto común o notas locales.

Stop ocurre cuando un turno está a punto de detenerse. Sirve para revisiones finales, como comprobar si se ejecutaron pruebas, si quedan TODOs o si conviene hacer una pasada adicional de verificación.

Cómo diseñar un Hook de privacidad

La revisión de privacidad encaja especialmente bien en UserPromptSubmit, porque ocurre antes de que el contenido del usuario entre realmente en el flujo de Codex. No intentes cubrirlo todo desde el principio. Empieza por lo que la gente pega por error con más frecuencia.

Conviene revisar primero estos patrones:

API keys de OpenAI, GitHub y proveedores cloud;
bloques de clave privada como -----BEGIN PRIVATE KEY-----;
fragmentos de archivos .env;
tokens de acceso, Bearer tokens y JWT;
dominios internos y cadenas de conexión a bases de datos;
datos personales como documentos, teléfonos y correos.

El script del Hook recibe JSON, lee el campo prompt y lo escanea con expresiones regulares o una tabla de reglas. Si encuentra un problema, puede bloquear el envío:

1
2
3
4


{
  "decision": "block",
  "reason": "Se detectó una posible API key. Elimina la información sensible antes de enviar."
}

También puede devolver contexto adicional sin bloquear, pero para secretos, claves privadas y tokens de alto riesgo, bloquear suele ser la opción más segura.

Ejemplo de `hooks.json`

Para una configuración a nivel de repositorio, crea .codex/hooks.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python .codex/hooks/privacy_check.py",
            "timeout": 10,
            "statusMessage": "Checking prompt privacy"
          }
        ]
      }
    ]
  }
}

El script correspondiente puede leer JSON desde la entrada estándar:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


import json
import re
import sys

payload = json.load(sys.stdin)
prompt = payload.get("prompt", "")

patterns = [
    r"sk-[A-Za-z0-9_-]{20,}",
    r"ghp_[A-Za-z0-9_]{20,}",
    r"-----BEGIN [A-Z ]*PRIVATE KEY-----",
    r"Bearer\s+[A-Za-z0-9._-]{20,}",
]

for pattern in patterns:
    if re.search(pattern, prompt):
        print(json.dumps({
            "decision": "block",
            "reason": "Se detectó un posible secreto, token o clave privada. Elimina la información sensible primero."
        }, ensure_ascii=False))
        raise SystemExit(0)

Este ejemplo solo muestra la idea. En uso real, conviene separar las reglas en una lista mantenible y controlar los falsos positivos. Un ejemplo de documentación que contiene Bearer no siempre es una fuga, y un proyecto puede tener claves falsas para pruebas. Cuanto más estrictas sean las reglas, más falsos positivos habrá; cuanto más flexibles, más fácil será pasar por alto riesgos reales.

Formato inline en `config.toml`

Si no quieres mantener un hooks.json separado, también puedes escribir la configuración en config.toml. Los Hooks inline en TOML usan la misma estructura de eventos que hooks.json:

1
2
3
4
5
6
7
8


[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = 'python ".codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

Si una misma capa de configuración contiene hooks.json y [hooks] inline, Codex carga ambos y muestra una advertencia. En la práctica, es mejor elegir un formato por capa para que las reglas sean fáciles de auditar.

Qué tener en cuenta al usar Hooks

Primero, los Hooks ejecutan comandos locales, así que hay que revisar su origen. Los Hooks no gestionados necesitan review y trust antes de ejecutarse. Si cambia la definición del Hook, debe confiarse de nuevo. No conviene permitir sin más un .codex/hooks.json de un repositorio desconocido.

Segundo, pueden ejecutarse varios Hooks coincidentes. No asumas que un solo Hook bloqueará todo, y evita reglas contradictorias. En entornos de equipo, deja claro qué reglas son de usuario, de proyecto o gestionadas por administradores.

Tercero, los Hooks son guardarraíles, no un límite de seguridad completo. Por ejemplo, PreToolUse puede bloquear muchas llamadas a herramientas, pero la documentación oficial aclara que no intercepta todas las rutas de shell ni todas las herramientas que no sean shell o MCP. Los flujos de alto riesgo siguen necesitando permisos, sandboxing, revisión de código y mínimo privilegio.

Cuarto, los scripts de Hook deben ser rápidos. Las revisiones de privacidad y de comandos están en el bucle interactivo. Si un script tarda decenas de segundos cada vez, la experiencia se vuelve lenta. Usa reglas simples cuando basten, y evita llamar a servicios externos pesados en cada evento.

Quinto, el formato de salida debe ser estricto. Cada evento admite campos de retorno distintos. UserPromptSubmit puede usar decision: "block" para bloquear un prompt, mientras que PreToolUse tiene su propia estructura hookSpecificOutput. Revisa el contrato de entrada y salida del evento antes de escribir el Hook.

Buenos primeros escenarios

Si estás empezando con Hooks, no hace falta construir de golpe un sistema complejo de políticas empresariales. Puedes empezar por tres casos pequeños.

El primero es la revisión de privacidad. Aporta valor real rápidamente y sirve tanto para individuos como para equipos. Pegar por error secretos, tokens o fragmentos de .env es un problema real en flujos de programación con IA.

El segundo es bloquear comandos peligrosos. Un Hook PreToolUse para Bash puede impedir borrados recursivos, cambios en directorios del sistema o subidas a remotos desconocidos.

El tercero es la revisión final. Un Hook Stop o PostToolUse puede recordar a Codex comprobar pruebas, builds, formato, documentación y cambios sin confirmar antes de terminar. No siempre necesita bloquear; un recordatorio ya puede reducir trabajos incompletos.

Conclusión

Lo avanzado de Codex Hooks no es añadir una función vistosa más, sino conectar reglas al bucle de ejecución de Codex.

En el uso básico, le dices a Codex qué hacer mediante un prompt. En el uso avanzado, usas Hooks para comprobar en puntos clave si Codex está siguiendo las reglas. Revisiones de privacidad, control de comandos, políticas de permisos, resúmenes de sesión y validación final pueden pasar de recordatorios manuales a flujo ejecutable.

Si ya usas Codex en proyectos reales, merece la pena configurar Hooks pronto. No sustituyen el juicio humano, el sandboxing ni el control de permisos, pero pueden convertir requisitos de seguridad y proceso fáciles de olvidar en acciones predeterminadas que se ejecutan cada vez.

Referencias: OpenAI Codex Advanced Configuration - Hooks, OpenAI Codex Hooks