MemoryLake
Volver a todos los artículos
Tutorial19 de noviembre de 2026·11 min de lectura

Cómo migrar sus Codex Hooks a Claude Code sin perder el contexto (2026)

Su equipo tiene algunos hooks de Codex que realizan un trabajo real. Uno verifica cada comando de shell contra un script de política antes de ejecutarse. Otro carga notas de sesión cuando comienza un chat. Uno le recuerda al agente que ejecute pruebas antes de detenerse. Está agregando Claude Code a su flujo de trabajo, ha usado /import codex para traer sus instrucciones y skills, y la primera sesión comienza sin ninguno de esos hooks.

Eso es de esperar. La descripción de comandos de Claude Code detalla que /import trae la configuración de Codex "incluyendo archivos de instrucciones, servidores MCP, comandos, subagentes y skills". Los hooks no están en esa lista. Moverlos es un paso manual.

La buena noticia es que ambas herramientas describen los hooks con una forma muy similar, por lo que la mayor parte del trabajo es traducción en lugar de reescritura. La documentación de Claude Code describe tres niveles de anidamiento: un evento de hook, "un grupo de matchers para filtrar cuándo se activa" y uno o más handlers. La documentación de Codex describe los mismos tres niveles.

Esta guía cubre dónde residen los hooks en cada herramienta, qué se transfiere sin cambios, qué necesita traducción, qué eventos existen solo en un lado, cómo funciona la confianza en cada uno, cómo mover hooks de carga de contexto sin perder lo que cargan y una migración manual paso a paso.

Qué es un hook en cada herramienta

La documentación de Codex describe los hooks como "un marco de extensibilidad para Codex. Le permiten ejecutar scripts o herramientas MCP durante el bucle agéntico". Su lista de ejemplos incluye "Resumir chats para crear memorias persistentes automáticamente" y "Ejecutar una verificación de validación personalizada cuando finaliza un turno de chat, aplicando estándares".

La documentación de Claude Code dice que los hooks "se definen en archivos de configuración JSON" y se organizan como evento, grupo de matchers y handler. Un handler puede ser un comando de shell, un endpoint HTTP, una herramienta MCP, un prompt o un agente.

Codex admite menos tipos de handlers. Su documentación dice: "Se admiten los handlers command y mcp_tool. Los handlers prompt y agent se analizan pero se omiten". Dado que Claude Code admite ambos, cada handler que realmente se ejecuta en Codex tiene un tipo coincidente en Claude Code.

Dónde residen los hooks

En Codex, los hooks van en un archivo hooks.json o integrados en config.toml. La documentación enumera las ubicaciones de hooks.json:

  • Sistema: /etc/codex/hooks.json en macOS y Linux.
  • Usuario: $CODEX_HOME/hooks.json, que es ~/.codex/hooks.json cuando CODEX_HOME no está definido.
  • Proyecto de confianza: .codex/hooks.json.

Codex también carga hooks incluidos con plugins habilitados. Cuando una capa usa ambos archivos, la documentación dice: "Codex carga ambos y advierte al inicio. Prefiera un formato por capa".

En Claude Code, los hooks van en archivos de configuración. La tabla de la documentación enumera las ubicaciones principales:

  • ~/.claude/settings.json para todos sus proyectos.
  • .claude/settings.json para un solo proyecto, que "puede ser confirmado en el repositorio".
  • .claude/settings.local.json para un solo proyecto, mantenido localmente.
  • Configuraciones de políticas gestionadas, plugins y frontmatter de skills o subagentes.

Por lo tanto, un hooks.json de nivel de usuario de Codex se mapea más estrechamente a ~/.claude/settings.json, y el .codex/hooks.json de un proyecto se mapea a .claude/settings.json, bajo una clave de hooks de nivel superior.

Qué se transfiere sin cambios

Varias piezas no necesitan traducción.

La estructura. Nombres de eventos, grupos de matchers y una lista de handlers por grupo.

Los nombres de eventos compartidos. SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SubagentStart, SubagentStop y Stop aparecen en las referencias de ambas herramientas.

Fuentes de SessionStart. Codex enumera startup, resume, clear, compact y fork. La tabla de matchers de SessionStart de Claude Code enumera los mismos cinco valores.

Los campos de entrada comunes. Ambos envían JSON en stdin con session_id, transcript_path, cwd, hook_event_name y permission_mode.

Código de salida 2. En Codex, varios eventos le permiten "usar el código de salida 2 y escribir el motivo del bloqueo en stderr". Claude Code también trata el código de salida 2 como una señal de bloqueo en los eventos que lo admiten, y documenta su comportamiento por evento.

Tiempo de espera predeterminado. Codex usa 600 segundos para la mayoría de los hooks. Claude Code enumera 600 como el valor predeterminado para los hooks de comando.

Qué necesita traducción

Matchers. Ambos usan el matcher para filtrar por nombre de herramienta o fuente de inicio, pero lo evalúan de manera diferente. Codex dice que su matcher "es una cadena regex". Claude Code trata un matcher compuesto solo por letras, dígitos y algunos separadores como nombres exactos, y cualquier otra cosa como una expresión regular de JavaScript no anclada. Un matcher de Codex como ^apply_patch$ sigue siendo una regex en Claude Code, pero el nombre de la herramienta dentro de él necesita cambiar.

Nombres de herramientas. La herramienta de shell de Codex coincide como Bash, que también es el nombre en Claude Code. Las ediciones de archivos difieren. En Codex, apply_patch puede coincidir "como apply_patch, Edit o Write". En Claude Code, las herramientas de edición coinciden por nombres como Edit y Write. Si sus hooks de Codex ya usan Edit|Write, ese matcher se transfiere. Si usan apply_patch, cámbielo.

Nombres de herramientas MCP. Ambos usan el patrón mcp__server__tool en sus ejemplos, por lo que los matchers de MCP pueden transferirse. Verifique que el servidor tenga el mismo nombre en ambas herramientas.

Rutas de scripts. Los ejemplos de Codex hacen referencia a scripts de proyecto a través de Git, con rutas bajo .codex/hooks/. Claude Code ofrece un marcador de posición para esto: ${CLAUDE_PROJECT_DIR}, "la raíz del proyecto donde comenzó la sesión". Si mueve los scripts a .claude/hooks/, actualice también las rutas.

El campo model. Codex enumera model como un campo de entrada común, una "extensión específica de Codex". Claude Code dice: "Solo los hooks de SessionStart pueden recibir un campo model, y Claude Code no siempre lo incluye". Un script de Codex que lee el modelo en cada evento necesita una alternativa.

IDs de turno. Codex agrega turn_id a los hooks con alcance de turno. Los campos comunes de Claude Code incluyen prompt_id, que identifica el prompt del usuario que se está procesando. Los scripts de registro que se basan en IDs de turno necesitan ajustes.

Límites de contexto. El campo additionalContextLimit de Codex controla cuánto contexto puede enviar un hook antes de que Codex guarde el texto completo en el disco. La tabla de campos de handler de Claude Code no enumera ese campo, así que elimínelo cuando copie un handler.

Eventos en un solo lado

Codex enumera tres eventos que la referencia de hooks de Claude Code no incluye bajo los mismos nombres: PreModelRequest, PostModelRequest e Interrupt. Codex ejecuta los dos primeros "para cada intento de solicitud al modelo", e Interrupt cuando se interrumpe un turno activo.

Si depende de ellos, busque el evento de Claude Code más cercano o acepte que el comportamiento no se transferirá. Claude Code, a su vez, tiene muchos eventos que Codex no tiene, como PostToolUseFailure, Notification, FileChanged y PreModelSwitch. Una migración es un buen momento para verificar si alguno de ellos hace mejor el trabajo.

Cómo funciona la confianza en cada lado

Codex confía en los hooks individualmente. Su documentación dice: "Antes de que un hook no gestionado pueda ejecutarse, Codex requiere que revise y confíe en la definición exacta del hook. Codex registra la confianza contra el hash actual del hook, por lo que los hooks nuevos o modificados se marcan para revisión y se omiten hasta que se confíe en ellos".

Claude Code verifica la confianza del espacio de trabajo en su lugar. En una sesión interactiva, "retiene los hooks de cada archivo de configuración, incluido su propio ~/.claude/settings.json, hasta que acepte el diálogo de confianza del espacio de trabajo para la carpeta". En una sesión de SDK o -p, "trata la carpeta como de confianza".

El menú /hooks de Claude Code es un navegador de solo lectura que muestra cada hook y de dónde proviene. Úselo después de migrar para confirmar que cada hook aterrizó donde esperaba.

Hooks de plugins, gestionados y desactivados

No todos los hooks son suyos para mover.

Hooks de plugins viajan con su plugin. Codex dice que los plugins habilitados pueden proporcionar hooks "a través de su manifiesto o, por defecto, hooks/hooks.json en la raíz del plugin". Claude Code usa el mismo nombre de archivo dentro de un plugin, y su documentación dice que "Cuando un plugin está habilitado, sus hooks se fusionan con sus hooks de usuario y de proyecto". Si un hook provino de un plugin, instale la versión de Claude Code de ese plugin en lugar de copiar el hook.

Hooks gestionados pertenecen a su administrador. Codex marca los hooks de fuentes de sistema, MDM, nube o requirements.toml como gestionados y de confianza por política. Claude Code tiene configuraciones de políticas gestionadas y una configuración allowManagedHooksOnly que bloquea los hooks de usuario, proyecto, locales y de plugins. Consulte con su administrador antes de recrear un hook gestionado usted mismo.

Desactivar hooks funciona de manera diferente. En Codex, los hooks están habilitados por defecto y se desactivan con un feature flag en config.toml. En Claude Code, el interruptor documentado es disableAllHooks en un archivo de configuración, y no puede desactivar hooks gestionados desde fuera de las configuraciones gestionadas.

Mover hooks de carga de contexto

Los hooks de SessionStart que cargan contexto son los que más vale la pena hacer bien, porque dan forma a lo que el agente sabe desde el primer turno.

En Codex, "El texto plano en stdout se agrega como contexto de desarrollador adicional", y un campo JSON additionalContext funciona de la misma manera. Codex también ejecuta hooks de SessionStart que coinciden con compact después de compactar una sesión, para que el contexto regrese después de un resumen.

Claude Code funciona de manera similar. Su documentación dice que para SessionStart, "Claude Code agrega stdout de texto plano como contexto que Claude puede ver y sobre el cual puede actuar". Su fuente compact se activa después de una "compactación automática o manual".

Claude Code agrega consejos sobre qué pertenece a un hook en absoluto. Su sección SessionStart dice que el evento es "Útil para cargar contexto de desarrollo como problemas existentes o cambios recientes en su código base", y luego: "Para contexto estático que no requiere un script, use CLAUDE.md".

Por lo tanto, si un hook de Codex no hace más que imprimir las mismas convenciones cada vez, la migración es una oportunidad para mover ese texto a CLAUDE.md y mantener el hook para el contexto que cambia. Cubrimos qué hooks de Claude Code pueden agregar contexto, y cuándo CLAUDE.md es el mejor lugar, en nuestra guía sobre Claude Code hooks.

Lo que la gente intenta primero

Esperar que /import codex traiga los hooks. Su lista documentada cubre archivos de instrucciones, servidores MCP, comandos, subagentes y skills.

Copiar hooks.json en .claude/. Las ubicaciones documentadas de Claude Code son archivos de configuración, plugins y frontmatter de skills o subagentes.

Mantener apply_patch en los matchers. Las herramientas de edición de Claude Code usan nombres diferentes.

Leer model en cada evento. En Claude Code, solo SessionStart puede recibirlo.

Mantener convenciones estáticas en un hook. Claude Code recomienda CLAUDE.md para contexto estático.

La migración manual

Paso 1: Liste sus hooks de Codex

Abra /hooks en la CLI de Codex y anote la fuente, el evento, el matcher y el comando de cada hook.

Paso 2: Elija el archivo de configuración de Claude Code

Use ~/.claude/settings.json para hooks personales y .claude/settings.json para hooks de proyecto compartidos.

Paso 3: Copie la estructura

Recree cada evento y grupo de matchers bajo la clave hooks, convirtiendo cualquier hook de TOML a JSON.

Paso 4: Traduzca matchers y rutas

Reemplace apply_patch, verifique los matchers de regex y apunte las rutas de los scripts a ${CLAUDE_PROJECT_DIR}.

Paso 5: Ajuste los scripts que leen campos exclusivos de Codex

Agregue alternativas para model y turn_id, y elimine additionalContextLimit.

Paso 6: Mueva el contexto estático a CLAUDE.md

Mantenga los hooks para el contexto que cambia. Ponga las convenciones fijas en CLAUDE.md.

Paso 7: Confíe en la carpeta y verifique

Acepte el diálogo de confianza del espacio de trabajo, luego verifique /hooks y active cada evento una vez.

La mejor manera: Mantenga lo que sus hooks aplican en un solo lugar

Los hooks aplican reglas y cargan contexto. Las razones detrás de ellos, como por qué se bloquea un comando, qué política implementa una verificación o qué se supone que deben contener las notas de la sesión, son contexto del proyecto. Cuando los hooks se mueven entre herramientas, los scripts vienen con ellos, pero el razonamiento detrás de ellos puede vivir solo en la memoria de alguien.

MemoryLake es una capa de memoria para ese tipo de contexto de proyecto, como políticas, convenciones y las razones detrás de sus verificaciones, mantenida en un solo lugar y disponible para los asistentes que conecte, como ChatGPT, Claude Code y Codex.

Usted escribe las entradas usted mismo, con sus propias palabras. No se lee nada de, ni se escribe en, ni se elimina de sus archivos hooks.json, sus archivos de configuración, sus scripts de hooks, sus sesiones de Codex o Claude Code, ni el almacenamiento de ningún proveedor. Los hooks funcionan de la manera que OpenAI y Anthropic describen.

Paso 1: Cree una clave de API

Inicie sesión y genere una clave desde el panel de control. Guárdela fuera de sus repositorios, como cualquier otra credencial.

La consola de MemoryLake mostrando la pantalla de claves de API, donde se crea y copia una nueva clave para usar en un agente
La consola de MemoryLake mostrando la pantalla de claves de API, donde se crea y copia una nueva clave para usar en un agente

Paso 2: Suba sus primeras memorias

Comience con los hooks que enumeró en el Paso 1 de la migración manual. Para cada uno, escriba qué aplica y por qué. Un hook por entrada.

El espacio de trabajo de MemoryLake con los primeros documentos subidos, enumerando cada archivo a medida que se convierte en memoria buscable
El espacio de trabajo de MemoryLake con los primeros documentos subidos, enumerando cada archivo a medida que se convierte en memoria buscable

Paso 3: Conecte su IA y agentes

Conecte Claude Code, Codex y los otros asistentes que utilice. Cada uno puede recurrir a las mismas razones, independientemente de qué herramienta ejecute el hook.

La pantalla de integraciones de MemoryLake que enumera los clientes de IA y los marcos de agentes que se pueden conectar a la capa de memoria
La pantalla de integraciones de MemoryLake que enumera los clientes de IA y los marcos de agentes que se pueden conectar a la capa de memoria

Qué cambia esto en la práctica

La primera diferencia es una traducción más fácil. Cuando el propósito de un hook está escrito, puede elegir el evento de Claude Code correcto incluso cuando los nombres difieren.

La segunda es menos duplicación. El contexto que no cambia va a CLAUDE.md una vez, no a un script que lo imprime en cada sesión.

La tercera es la consistencia entre herramientas. Las mismas políticas y razones están disponibles en Claude Code y en Codex.

Mejores prácticas para mover Codex hooks a Claude Code

Inventario primero. Use /hooks en Codex para ver cada fuente.

Mapee archivos deliberadamente. Hooks de usuario a ~/.claude/settings.json, hooks de proyecto a .claude/settings.json.

Traduzca nombres de herramientas. apply_patch se convierte en Edit o Write.

Use ${CLAUDE_PROJECT_DIR} para scripts. Apunta a la raíz del proyecto donde comenzó la sesión.

Verifique eventos exclusivos de Codex. PreModelRequest, PostModelRequest e Interrupt necesitan un plan.

Mueva el texto estático a CLAUDE.md. Mantenga los hooks para el contexto cambiante.

Revise .claude/ antes de ejecuciones programadas. Las sesiones -p tratan la carpeta como de confianza.

Conclusión

El comando /import codex de Claude Code trae archivos de instrucciones, servidores MCP, comandos, subagentes y skills, y los hooks no están en esa lista documentada. Moverlos a mano es principalmente traducción, porque ambas herramientas usan los mismos tres niveles: evento, grupo de matchers y handlers. La mayoría de los nombres de eventos, las fuentes de SessionStart, los campos de entrada comunes, el código de salida 2 y el tiempo de espera predeterminado se transfieren.

Los cambios están en los detalles: los matchers se evalúan de manera diferente, apply_patch necesita un nombre de herramienta de Claude Code, las rutas de los scripts deben usar ${CLAUDE_PROJECT_DIR} y los scripts que leen model, turn_id o additionalContextLimit necesitan ajustes. Codex confía en cada hook por hash, mientras que Claude Code verifica la confianza del espacio de trabajo. Aproveche el movimiento para poner el contexto estático en CLAUDE.md y mantener los hooks para lo que cambia.

Preguntas frecuentes

¿Trae /import codex los hooks de Codex?

La referencia de Claude Code enumera archivos de instrucciones, servidores MCP, comandos, subagentes y skills. Los hooks no están en esa lista.

¿Dónde van los hooks en Claude Code?

En archivos de configuración como ~/.claude/settings.json o .claude/settings.json, bajo la clave hooks.

¿Puedo reutilizar mi estructura de hooks.json de Codex?

En su mayoría. Ambos usan eventos, grupos de matchers y handlers. Traduzca los nombres de las herramientas y las rutas.

¿Qué reemplaza a apply_patch en un matcher de Claude Code?

Las herramientas de edición de Claude Code, como Edit y Write.

¿Funcionan los hooks de SessionStart de Codex de la misma manera en Claude Code?

Ambos agregan stdout de texto plano como contexto y admiten las mismas fuentes de inicio.

¿Qué eventos de hook de Codex no tienen un evento de Claude Code con el mismo nombre?

PreModelRequest, PostModelRequest e Interrupt.

¿Necesito volver a confiar en los hooks en Claude Code?

Claude Code retiene los hooks de los archivos de configuración hasta que acepte el diálogo de confianza del espacio de trabajo en una sesión interactiva.