Cómo migrar de Codex a OpenHands sin perder el contexto (2026)

Ambas herramientas documentan su descubrimiento con precisión, lo que hace que la diferencia sea fácil de ver una vez que las lees lado a lado.

Codex ensambla todo en una sola cadena ordenada antes de comenzar a trabajar:

"Codex construye una cadena de instrucciones cuando se inicia (una vez por ejecución; en la TUI esto generalmente significa una vez por sesión iniciada)".

El descubrimiento comienza de forma global, en el directorio de inicio de Codex, donde "lee AGENTS.override.md si existe. De lo contrario, Codex lee AGENTS.md" y "utiliza solo el primer archivo no vacío en este nivel". Luego recorre el proyecto:

"Comenzando en la raíz del proyecto (normalmente la raíz de Git), Codex desciende hasta tu directorio de trabajo actual".

En cada directorio a lo largo de esa ruta, busca AGENTS.override.md, luego AGENTS.md, luego cualquier nombre alternativo configurado en project_doc_fallback_filenames, e "incluye como máximo un archivo por directorio". La fusión es una concatenación: "Codex concatena los archivos desde la raíz hacia abajo, uniéndolos con líneas en blanco. Los archivos más cercanos a tu directorio actual anulan las pautas anteriores porque aparecen más tarde en el prompt combinado".

Y hay un límite estricto: Codex "deja de agregar archivos una vez que el tamaño combinado alcanza el límite definido por project_doc_max_bytes (32 KiB por defecto)".

OpenHands parte de la premisa opuesta. Su AGENTS.md raíz está siempre activo, pero todo lo demás se retiene deliberadamente hasta que sea relevante. La documentación detalla los mecanismos en una tabla: AGENTS.md en la raíz del repositorio significa "El contenido completo se incluye en el prompt de sistema inicial", mientras que una Agent Skill en .agents/skills/<nombre-del-skill>/SKILL.md significa "El nombre y la descripción se anuncian primero; el agente invoca el skill completo cuando es relevante".

La pauta que sigue es la frase más importante para cualquiera que llegue desde Codex:

"Usa AGENTS.md para convenciones cortas a nivel de repositorio. Usa SKILL.md para conocimientos específicos que solo se necesitan para algunas tareas".

Y la advertencia asociada a ella:

"El contenido siempre activo ocupa el contexto de la conversación desde el principio. Mantén AGENTS.md conciso y mueve las instrucciones extensas o especializadas a skills y referencias bajo demanda".

Por lo tanto: el contenido de tus reglas se transfiere textualmente. La estructura de tus reglas no. En Codex, anidar directorios es el mecanismo de condicionalidad: colocas un archivo cerca del trabajo especializado y este llega tarde en el prompt concatenado. En OpenHands, la anidación no es el mecanismo en absoluto; el mecanismo es la descripción de un skill, un disparador declarado o un patrón de ruta declarado.

Aplanar una cadena de Codex en un solo AGENTS.md de OpenHands no es un atajo. Es precisamente lo que la documentación del destino te dice que no hagas.

Paso 1: Dividir la cadena según la frecuencia con la que se aplica realmente cada parte

Recorre tu cadena de instrucciones de Codex desde la raíz hacia abajo y clasifica cada bloque en uno de tres grupos.

Siempre verdadero, en todas partes. El comando de prueba, el gestor de paquetes, la regla de "nunca editar archivos generados", la convención de nomenclatura que se mantiene en todo el repositorio. Este es tu nuevo AGENTS.md raíz, y debe ser corto. Si tu AGENTS.md raíz actual es largo porque creció hacia el límite de 32 KiB, este es el momento de descubrir cuánto de él era realmente universal.

Solo verdadero en un área. Todo lo que vivía en un AGENTS.md anidado porque se aplicaba al servicio de pagos, al frontend o a la carpeta de migraciones. Estos se convierten en skills con una declaración de paths. OpenHands documenta esto como una regla determinista en lugar de una sugerencia: paths "convierte el archivo en una regla activada por ruta. La regla no se anuncia al modelo y se inyecta una vez por conversación cuando se lee, edita o crea un archivo coincidente".

Este grupo es donde la migración gana algo. En Codex, un archivo anidado se aplica porque iniciaste la sesión en ese directorio o debajo de él; el alcance es un efecto secundario de dónde te encuentras. Un patrón de paths se aplica cuando el agente realmente toca un archivo coincidente, independientemente de dónde comenzó la sesión. Esa es una versión más precisa de lo que intentabas expresar.

Solo verdadero para ciertas tareas. Listas de verificación de lanzamientos, runbooks de incidentes, la larga explicación de cómo está conectado el flujo de datos. Estos se convierten en skills ordinarios con un nombre y una descripción. No cuestan casi nada hasta que se invocan, por lo que pueden ser tan largos como sea necesario, lo opuesto a la restricción bajo la que trabajabas con una cadena concatenada y un límite de bytes. Una advertencia que vale la pena tener en cuenta al mover cosas a los skills: agent skills are not memory. Un skill es un procedimiento que el agente puede invocar, no un registro de lo que decidió tu equipo.

Hay un cuarto grupo que vale la pena mencionar: pautas que se activan por una frase en lugar de un archivo. OpenHands también admite eso: triggers "inyecta el skill cuando aparece una palabra clave o comando en un mensaje del usuario" y el skill sigue estando disponible para la invocación del modelo también. Si un archivo declara ambos, la documentación es explícita en que "paths tiene prioridad".

Paso 2: Corregir las suposiciones de nombres de archivos que cambian de dirección

Dos detalles te darán problemas, y apuntan en direcciones opuestas.

Codex requiere que registres cualquier nombre de archivo de instrucciones no estándar. Su documentación establece que los nombres de archivos que no están en la lista project_doc_fallback_filenames "se ignoran para el descubrimiento de instrucciones". Si tu repositorio terminó con un CLAUDE.md que Codex lee, lo lee porque alguien lo puso en esa lista.

OpenHands hace lo contrario por defecto: "OpenHands también reconoce CLAUDE.md y GEMINI.md como contexto de repositorio específico del modelo". No hay nada que registrar. Lo que significa que un CLAUDE.md que habías estado ignorando, o que habías dejado deliberadamente fuera de la lista de alternativas de Codex, se activa al llegar. Verifica si tienes uno antes de tu primera ejecución.

El otro detalle es AGENTS.override.md. Codex lo usa en dos lugares: globalmente, donde se impone sobre AGENTS.md por completo, y por directorio, donde se verifica primero. Es una vía de escape útil para comportamientos locales temporales. La documentación de skills de OpenHands no describe un nombre de archivo de anulación de ese tipo, por lo que cualquier AGENTS.override.md en tu árbol es un archivo sin lector documentado en el otro lado. Decide por cada archivo si su contenido pertenece al AGENTS.md raíz, a un skill acotado o a ninguna parte.

Una nota más sobre archivos heredados: OpenHands documenta que "un skill .md heredado sin un disparador siempre se carga por completo" y recomienda preferir AGENTS.md para ese caso para que la intención quede clara. Si estás portando un montón de Markdown suelto, esa es la frase sobre la cual planificar: un skill .md simple se comportará como contenido siempre activo, lo que te devuelve exactamente a la posición de la que estás migrando. Si tus archivos de instrucciones comenzaron su vida como un CLAUDE.md, converting a CLAUDE.md into an AGENTS.md cubre las diferencias de nomenclatura y contenido con más detalle.

Todo lo anterior es un trabajo de reestructuración, y harás una versión de ello cada vez que el modelo de carga cambie debajo de ti. Codex utiliza una concatenación limitada por bytes. OpenHands utiliza la divulgación progresiva. La próxima herramienta utilizará otra cosa.

Lo que sobrevive a todo esto es el razonamiento: por qué existe la convención, qué rechazaste y qué incidente hizo que se creara la regla en primer lugar. Eso nunca encaja cómodamente en un archivo de instrucciones, porque un archivo de instrucciones es una lista de comandos y debe mantenerse corto en ambas plataformas.

MemoryLake mantiene esa capa fuera de ambos entornos de ejecución y la sirve al agente que la solicite, a través de MCP o la API. Codex conserva sus propias memorias locales y OpenHands mantiene su catálogo de skills exactamente como están.

Paso 1: Crear una clave de API

Genera una clave y realiza tu primera solicitud en unos treinta segundos, antes de comenzar a dividir archivos.

Paso 2: Subir tus primeras memorias

A medida que clasificas cada bloque en el Paso 1, te seguirás preguntando "por qué está esto aquí". Escribe la respuesta a medida que avanzas: la decisión, la alternativa que rechazaste, la restricción detrás de ella. Los documentos y otros archivos van al mismo lugar.

Paso 3: Conectar tu IA y agentes

Dale acceso a Claude, Codex, OpenClaw y OpenHands a través de MCP o la API. Un agente que puede consultar la capa de decisión ya no necesita el razonamiento integrado en el archivo siempre activo, lo que permite que el AGENTS.md raíz se mantenga tan corto como recomiendan ambos proveedores.

El primer cambio es que se termina la conversación sobre los 32 KiB. Los equipos que alcanzan el límite de Codex tienen dos opciones documentadas (aumentar el límite o dividir en directorios anidados) y ambas son formas de gestionar un presupuesto. En el lado de OpenHands, la cuestión del presupuesto cambia: el archivo raíz debe ser corto no por un límite de bytes, sino porque el contenido siempre activo compite por el contexto desde el primer mensaje. Una capa de decisión que se consulta bajo demanda es la forma en que el archivo corto se mantiene corto sin perder el razonamiento.

El segundo cambio es que el alcance se vuelve más preciso. Un patrón de paths es una declaración más fuerte que "este archivo se encuentra en el directorio de pagos", y se activa en el archivo que el agente realmente toca en lugar de donde comenzó la sesión.

El tercer cambio se manifiesta durante el período de transición. La mayoría de los equipos ejecutan ambos durante unas semanas. Dos árboles de instrucciones con dos modelos de carga diferirán de formas que nadie nota hasta que un agente hace algo que el otro no habría hecho. Una capa de decisión compartida significa que los motivos siguen siendo idénticos incluso cuando las distribuciones de archivos difieren.

Mide tu archivo raíz antes de copiarlo. Si tu cadena de Codex estaba al límite de bytes, la pregunta honesta es cuánto de ella fue alguna vez universal. La mayor parte de la respuesta es "menos de lo que crees".

Convierte la anidación de directorios en patrones declarados. No reproduzcas tu estructura de directorios de Codex en OpenHands esperando el mismo comportamiento. La anidación era el mecanismo de alcance en un lado; una declaración de paths es el mecanismo de alcance en el otro.

Audita CLAUDE.md y GEMINI.md antes de la primera ejecución. Pasan de necesitar registro a ser reconocidos automáticamente. Eso suele ser bienvenido y, ocasionalmente, una sorpresa.

Dale a cada skill una descripción que indique cuándo se aplica. El descubrimiento anuncia solo el nombre y la descripción. Una descripción que dice qué hace el skill pero no cuándo usarlo no se invocará en el momento adecuado.

No pongas el razonamiento en el archivo siempre activo. Ambos proveedores te recomiendan mantenerlo conciso. El razonamiento pertenece a un almacén que el agente consulta, no al bloque que se carga en cada mensaje.

Espera resúmenes en sesiones largas. OpenHands documenta un condensador de contexto que mantiene intactos los mensajes recientes y resume el contenido más antiguo una vez que el historial supera un tamaño configurado. Esa es una forma sensata de gestionar una conversación larga, y es una buena razón para no tratar la conversación como tu registro de nada.

Codex y OpenHands leen un archivo con el mismo nombre y lo tratan de formas casi opuestas. Codex concatena una cadena ordenada desde la raíz del proyecto hasta tu directorio de trabajo, un archivo por directorio, hasta que alcanza un límite de bytes. OpenHands carga el archivo raíz por completo y retiene todo lo demás detrás de una descripción, un disparador de palabra clave o un patrón de ruta.

Esa diferencia es la migración. El contenido se porta textualmente; la estructura tiene que reconstruirse en torno a un modelo de carga que premia un archivo siempre activo corto y detalles ilimitados bajo demanda. En el camino, te encuentras con dos sorpresas en los nombres de archivos que apuntan en direcciones opuestas, y una vía de escape (AGENTS.override.md) sin equivalente documentado.

Divide la cadena según la frecuencia con la que se aplica cada parte, convierte la anidación en patrones declarados y mantén el razonamiento en un lugar que no pertenezca a ningún entorno de ejecución. Así, el próximo modelo de carga será un trabajo de reestructuración y no un proyecto de arqueología.