Entorno de ejecución del arnés de Codex

Contrato de runtime para los turnos del arnés de Codex. Para la configuración y el enrutamiento, consulte Arnés de Codex. Para los campos de configuración, consulte Referencia del arnés de Codex.

Descripción general

Codex controla el bucle nativo del modelo, la reanudación nativa de hilos, la continuación nativa de herramientas y la Compaction nativa. OpenClaw controla el enrutamiento de canales, los archivos de sesión, la entrega de mensajes visibles, las herramientas dinámicas de OpenClaw, las aprobaciones, la entrega de contenido multimedia y un reflejo de la transcripción en torno a ese límite.

El enrutamiento del prompt sigue el runtime seleccionado, no solo la cadena del proveedor. Un turno nativo de Codex recibe las instrucciones de desarrollador del servidor de aplicaciones de Codex; una ruta explícita de compatibilidad de OpenClaw mantiene el prompt del sistema habitual de OpenClaw incluso cuando utiliza autenticación o transporte de OpenAI con características de Codex.

OpenClaw inicia y reanuda hilos nativos de Codex con la personalidad integrada de Codex desactivada (personality: "none") para que los archivos de personalidad del espacio de trabajo y la identidad del agente de OpenClaw sigan siendo la autoridad. Por lo demás, Codex nativo mantiene las instrucciones base y del modelo controladas por Codex, así como la carga de la documentación del proyecto. Las ejecuciones ligeras de OpenClaw (por ejemplo, cron) siguen suprimiendo la carga de la documentación del proyecto.

Las instrucciones de desarrollador de OpenClaw abarcan aspectos del runtime de OpenClaw: la entrega al canal de origen, las herramientas dinámicas de OpenClaw, la delegación ACP, el contexto del adaptador y los archivos de perfil activos del espacio de trabajo del agente. Los catálogos de Skills y los punteros MEMORY.md enrutados mediante herramientas se proyectan como instrucciones de desarrollador para la colaboración limitadas al turno. Cuando las herramientas de memoria no están disponibles, el contenido activo de BOOTSTRAP.md y todo MEMORY.md se incorporan en su lugar como contexto de entrada de texto sin formato para el turno.

La mayoría de las herramientas dinámicas de OpenClaw utilizan el espacio de nombres consultable openclaw. Las herramientas marcadas con catalogMode: "direct-only" utilizan openclaw_direct, que Codex mantiene directamente visible para el modelo como DirectModelOnly, en lugar de exponerlo a la ejecución anidada del modo de código.

Vinculaciones de hilos y cambios de modelo

Cuando una sesión de OpenClaw está asociada a un hilo existente de Codex, el siguiente turno vuelve a enviar al servidor de aplicaciones el modelo seleccionado actualmente, la política de aprobación, el entorno aislado, el revisor de aprobaciones y el nivel de servicio. Al cambiar de openai/gpt-5.5 a openai/gpt-5.2, se mantiene la vinculación del hilo, pero se solicita a Codex que continúe con el modelo recién seleccionado.

Las vinculaciones supervisadas son la excepción. El selector de modelos de OpenClaw permanece bloqueado y las reanudaciones omiten las anulaciones del modelo y el proveedor para que Codex restaure el modelo y el proveedor persistentes del hilo canónico. Un control nativo independiente de Codex puede cambiar ese par persistente, y la instantánea inicial puede generar la advertencia habitual de Codex sobre la diferencia de modelo; el modelo externo de OpenClaw y la cadena de reserva nunca sustituyen a ninguno de los dos.

Supervisión y continuación segura

La supervisión de Codex es una capacidad opcional del mismo Plugin codex. Descubre hilos nativos mediante una conexión independiente y solo proyecta las sesiones no archivadas en el catálogo del Gateway. Sin una configuración de conexión explícita de appServer, esa conexión utiliza stdio administrado en el directorio principal del usuario, mientras que el arnés ordinario sigue limitado al agente. Las operaciones de listado y lectura de metadatos son pasivas: no reanudan ningún hilo, no suscriben OpenClaw a sus eventos en vivo ni responden a sus solicitudes de aprobación.

Para una sesión almacenada o inactiva en el equipo del Gateway, Continuar como rama crea un Chat normal con el modelo bloqueado y refleja un historial limitado de mensajes del usuario y del asistente hasta el último turno terminal persistente del origen. El primer turno normal de Chat instala los controladores de aprobación reales y utiliza una bifurcación nativa temporal para fijar la instantánea sin anular el modelo ni el proveedor. Codex App Server utiliza su configuración nativa actual y devuelve el par seleccionado; emite su advertencia habitual si ese modelo difiere del último modelo registrado del origen. En la misma conexión de supervisión, OpenClaw inicia el hilo canónico del arnés de Codex de origen appServer conforme a su directorio de trabajo y su política de runtime, con exactamente el modelo y el proveedor devueltos para ese inicio inicial, inyecta el historial visible limitado y archiva la bifurcación temporal. El origen nunca se reanuda. El hilo canónico dispone de toda la superficie de herramientas del arnés de OpenClaw; el razonamiento, las llamadas a herramientas y los resultados de herramientas del origen no se clonan en él. El ámbito de la conexión privada se conserva durante los estados de vinculación pendiente y confirmada, por lo que cada turno posterior permanece en esa conexión con la autenticación nativa y la configuración del proveedor. Si la supervisión está desactivada o se produce una divergencia en la vinculación o la conexión, se aplica un cierre seguro en lugar de cambiar al arnés ordinario del directorio principal del agente.

El origen original de la CLI, VS Code, Atlas o ChatGPT sigue siendo apto para ambos catálogos. La rama canónica es un hilo nativo de Codex, pero su tipo de origen es appServer; los clientes nativos pueden filtrar ese tipo de origen, por lo que no se garantiza que aparezca en Codex Desktop.

Los orígenes activos no pueden iniciar una rama nueva ni archivarse; sí se puede abrir un Chat supervisado existente. notLoaded significa que la actividad es desconocida, no que esté inactivo; OpenClaw solo permite archivar una fila local idle o notLoaded tras una confirmación explícita de que no hay otro ejecutor y una lectura reciente del estado local del proceso. Codex serializa las mutaciones de hilos dentro de un proceso de App Server, pero no proporciona un arrendamiento exclusivo entre procesos para el ejecutor ni para el responsable de las aprobaciones, por lo que esa lectura no puede demostrar que otro proceso no esté usando el hilo. OpenClaw bloquea a un propietario de vinculación que se sabe activo para el destino exacto o para cualquier descendiente generado y no archivado que devuelva la consulta paginada de descendientes de Codex. Los errores de enumeración, los ciclos y el agotamiento del límite de seguridad provocan un cierre seguro. El archivado nativo todavía puede entrar en conflicto con un turno nuevo de otro proceso, por lo que la confirmación abarca los clientes desconocidos y el intervalo entre la lectura del estado y el archivado. Un Chat supervisado con el modelo bloqueado no puede eliminarse mientras proteja la vinculación nativa.

Los catálogos de nodos emparejados se limitan a metadatos en la versión inicial. El límite actual de invocación del Node es de solicitud/respuesta y no puede transportar los eventos de turno de larga duración, las solicitudes de aprobación ni la salida en streaming que requiere una vinculación real del arnés de Codex. Por tanto, las acciones remotas Continuar y Archivar siguen sin estar disponibles incluso cuando la fila está inactiva.

Consulte Supervisión de Codex para conocer la configuración del operador y el comportamiento visible de la interfaz de control.

Respuestas visibles y Heartbeat

Los turnos de chat directo o de origen mediante el arnés de Codex utilizan de forma predeterminada la entrega final automática del asistente para las superficies internas de WebChat, de acuerdo con el contrato del arnés de Pi: el agente responde con normalidad y OpenClaw publica el texto final en la conversación de origen. Establezca messages.visibleReplies: "message_tool" para mantener privado el texto final del asistente, salvo que el agente llame a message(action="send").

Los turnos de Heartbeat de Codex incluyen heartbeat_respond de forma predeterminada en el catálogo consultable de herramientas de OpenClaw para que el agente pueda registrar si la activación debe permanecer silenciosa o generar una notificación. Las directrices sobre la iniciativa de Heartbeat se envían como una instrucción de desarrollador del modo de colaboración de Codex limitada al turno de Heartbeat; los turnos de chat ordinarios permanecen en el modo predeterminado de Codex. Cuando HEARTBEAT.md no está vacío, las instrucciones de Heartbeat remiten a Codex al archivo en lugar de incluir su contenido directamente.

Límites de los hooks

OpenClaw no utiliza archivos hooks.json globales ni del proyecto de Codex para enrutar el comportamiento de los plugins. Para el puente de herramientas y permisos nativos, OpenClaw inyecta la configuración de Codex por hilo para PreToolUse, PostToolUse, PermissionRequest y Stop.

Cuando las aprobaciones de Codex App Server están habilitadas (approvalPolicy no es "never"), la configuración predeterminada inyectada de hooks nativos omite PermissionRequest para que el revisor de App Server de Codex y el puente de aprobación de OpenClaw gestionen las escaladas reales después de la revisión. Añada permission_request a nativeHookRelay.events para forzar de todos modos el relé de compatibilidad. Otros hooks de Codex, como SessionStart y UserPromptSubmit, siguen siendo controles del nivel de Codex; no se exponen como hooks de plugins de OpenClaw en el contrato v1.

En el caso de las herramientas dinámicas de OpenClaw, OpenClaw ejecuta la herramienta después de que Codex solicita la llamada, por lo que el comportamiento del plugin y del middleware se ejecuta en el adaptador del arnés. El modo de código de Codex recibe los resultados dinámicos genéricos como texto y serializa las llamadas dinámicas anidadas; los llamadores deben analizar los resultados que parezcan JSON y no pueden depender de Promise.all para el envío simultáneo. En el caso de las herramientas nativas de Codex, Codex controla el registro canónico de la herramienta; OpenClaw puede reflejar eventos seleccionados, pero no puede reescribir el hilo nativo salvo que Codex lo exponga mediante App Server o devoluciones de llamada de hooks nativos.

Los eventos PreToolUse del modo de informe de Codex App Server aplazan la aprobación del plugin hasta la aprobación correspondiente de App Server. Si un hook before_tool_call de OpenClaw devuelve requireApproval mientras que la carga nativa establece openclaw_approval_mode: "report", el relé del hook nativo registra el requisito de aprobación del plugin y no devuelve ninguna decisión nativa. Cuando Codex envía posteriormente la solicitud de aprobación de App Server para el mismo uso de la herramienta, OpenClaw abre la solicitud de aprobación del plugin y asigna la decisión de vuelta a Codex. Los eventos PermissionRequest de Codex constituyen una ruta de aprobación independiente y aún pueden enrutarse mediante las aprobaciones de OpenClaw cuando se configuran para ese puente.

Las notificaciones de elementos de Codex App Server también proporcionan observaciones asíncronas de after_tool_call para las finalizaciones de herramientas nativas que aún no estén cubiertas por el relé nativo PostToolUse. Estas observaciones solo sirven para telemetría y compatibilidad; no pueden bloquear, retrasar ni modificar la llamada a la herramienta nativa.

Las proyecciones de Compaction y del ciclo de vida del LLM proceden de las notificaciones de Codex App Server y del estado del adaptador de OpenClaw, no de los comandos de hooks nativos de Codex. before_compaction, after_compaction, llm_input y llm_output son observaciones del nivel del adaptador, no capturas byte por byte de las cargas internas de solicitud o Compaction de Codex.

Las notificaciones nativas hook/started y hook/completed de Codex App Server se proyectan como eventos de agente codex_app_server.hook para el análisis de trayectorias y la depuración. No invocan hooks de plugins de OpenClaw.

Contrato de compatibilidad de V1

Compatible con el runtime v1 de Codex:

No compatible con el entorno de ejecución Codex v1:

Permisos nativos y solicitudes de información de MCP

Para PermissionRequest, OpenClaw solo devuelve decisiones explícitas de permitir o denegar cuando la política toma una decisión. Un resultado sin decisión no equivale a permitir: Codex lo trata como si el hook no hubiera tomado una decisión y recurre a su propio guardián o a la ruta de aprobación del usuario.

Los modos de aprobación del app-server de Codex omiten este hook nativo de forma predeterminada. Esto se aplica salvo que permission_request se incluya explícitamente en nativeHookRelay.events o que un entorno de ejecución de compatibilidad lo instale.

Cuando un operador elige allow-always para una solicitud de permiso nativo de Codex, OpenClaw recuerda esa huella digital exacta de proveedor/sesión/entrada de herramienta/cwd durante un intervalo de sesión limitado. La decisión recordada solo se aplica intencionadamente a coincidencias exactas: un cambio en el comando, los argumentos, la carga útil de la herramienta o el cwd genera una nueva aprobación.

Las solicitudes de aprobación de herramientas MCP de Codex se enrutan a través del flujo de aprobación de plugins de OpenClaw cuando Codex marca _meta.codex_approval_kind como "mcp_tool_call". El request_user_input de Codex registra una pregunta del Gateway independiente del proveedor para la sesión de origen. La interfaz de control muestra la tarjeta de pregunta del Gateway, y una única opción no secreta utiliza botones de canal tipados cuando el canal es compatible. Las pulsaciones de botones, las respuestas de la interfaz de control y la siguiente respuesta de texto sin formato en cola resuelven el mismo registro del Gateway antes de que OpenClaw devuelva la respuesta del app-server. La resolución automática de Codex y las cancelaciones de intentos limitan la espera y cancelan el registro. Las preguntas secretas permanecen íntegramente en la ruta advertida de respuesta por texto. Las demás solicitudes de información de MCP se rechazan de forma segura.

Para consultar el flujo general de aprobación de plugins que transporta estas solicitudes, véase Solicitudes de permisos de plugins.

Dirección de la cola

La dirección de la cola de ejecuciones activas se asigna a turn/steer del servidor de aplicaciones de Codex. Con el valor predeterminado messages.queue.mode: "steer", OpenClaw agrupa los mensajes de chat en modo de dirección durante el intervalo de inactividad configurado y los envía como una sola solicitud turn/steer en orden de llegada.

Los turnos de revisión y Compaction manual de Codex pueden rechazar la dirección en el mismo turno. En ese caso, OpenClaw espera a que termine la ejecución activa antes de iniciar el prompt. Use /queue followup o /queue collect cuando los mensajes deban ponerse en cola de forma predeterminada en lugar de dirigir la ejecución. Consulte Cola de dirección.

Carga de comentarios de Codex

Cuando se aprueba /diagnostics [note] para una sesión en el entorno de ejecución nativo de Codex, OpenClaw también llama a feedback/upload del servidor de aplicaciones de Codex para los hilos de Codex pertinentes, incluidos los registros de cada hilo enumerado y los subhilos de Codex generados cuando están disponibles.

La carga pasa por la ruta normal de comentarios de Codex hacia los servidores de OpenAI. Si los comentarios de Codex están deshabilitados en ese servidor de aplicaciones, el comando devuelve el error del servidor de aplicaciones. La respuesta de diagnóstico completada enumera los canales, los identificadores de sesión de OpenClaw, los identificadores de hilo de Codex y los comandos locales codex resume <thread-id> de los hilos enviados.

Si se deniega o ignora la aprobación, OpenClaw no muestra esos identificadores de Codex ni envía comentarios de Codex. La carga no sustituye la exportación local de diagnósticos del Gateway. Consulte Exportación de diagnósticos para conocer el comportamiento de la aprobación, la privacidad, el paquete local y el chat grupal.

Use /codex diagnostics [note] solo cuando desee cargar los comentarios de Codex del hilo conectado actualmente sin el paquete completo de diagnósticos del Gateway.

Compaction y réplica de la transcripción

Cuando el modelo seleccionado utiliza el entorno de ejecución de Codex, la Compaction nativa del hilo corresponde al servidor de aplicaciones de Codex. OpenClaw no ejecuta una Compaction preliminar en los turnos de Codex, no sustituye la Compaction de Codex por la del motor de contexto ni recurre a la generación de resúmenes de OpenClaw o de la API pública de OpenAI cuando no se puede iniciar la Compaction nativa. OpenClaw mantiene una réplica de la transcripción para el historial del canal, la búsqueda, /new, /reset y futuros cambios de modelo o entorno de ejecución.

Las solicitudes explícitas de Compaction, como /compact o una operación compact manual solicitada por un Plugin, inician la Compaction nativa de Codex con thread/compact/start. OpenClaw mantiene abiertos la solicitud y el arrendamiento del cliente compartido hasta que Codex emite el elemento de finalización contextCompaction correspondiente y, a continuación, informa que el turno de Compaction se ha completado. Si ese turno terminal supera el tiempo de espera de Compaction configurado, OpenClaw solicita una interrupción nativa del turno. El arrendamiento y el bloqueo de Compaction por hilo se mantienen hasta que Codex informa del estado terminal o confirma la RPC de interrupción. Si Codex no la confirma durante el período de gracia de la interrupción, OpenClaw retira la conexión antes de liberar el bloqueo. Las conexiones remotas también desconectan la vinculación del hilo correspondiente para que el trabajo posterior no pueda solaparse con un turno remoto sin confirmar. Los demás turnos de una conexión retirada fallan y pueden volver a intentarse con un cliente nuevo. El cierre del cliente, la cancelación de la solicitud o un turno de Compaction fallido devuelven una operación fallida. La Compaction automática por presión del contexto es responsabilidad de Codex; OpenClaw solo inicia la Compaction nativa para los desencadenadores solicitados manualmente.

Cuando un motor de contexto solicita la proyección de inicialización de un hilo de Codex, OpenClaw proyecta los nombres e identificadores de las llamadas a herramientas, las estructuras de entrada y el contenido censurado de los resultados de las herramientas en el nuevo hilo de Codex. No copia los valores sin procesar de los argumentos de las llamadas a herramientas en esa proyección.

La réplica incluye el prompt del usuario, el texto final del asistente y registros ligeros del razonamiento o del plan de Codex cuando el servidor de aplicaciones los emite. OpenClaw registra el inicio y el estado terminal de la Compaction nativa, pero no expone un resumen de la Compaction legible para personas ni una lista auditable de las entradas que Codex conservó después de la Compaction.

Como Codex controla el hilo nativo canónico, tool_result_persist no reescribe los registros de resultados de herramientas nativos de Codex. Solo se aplica cuando OpenClaw escribe el resultado de una herramienta en una transcripción de sesión controlada por OpenClaw.

Contenido multimedia y entrega

OpenClaw sigue controlando la entrega de contenido multimedia y la selección del proveedor multimedia. Las imágenes, los vídeos, la música, los PDF, la TTS y la comprensión de contenido multimedia utilizan los ajustes correspondientes del proveedor o modelo, como agents.defaults.mediaModels.image, agents.defaults.mediaModels.video, pdfModel y tts.

El texto, las imágenes, el vídeo, la música, la TTS, las aprobaciones y la salida de las herramientas de mensajería continúan por la ruta normal de entrega de OpenClaw; la generación de contenido multimedia no requiere el entorno de ejecución heredado. Cuando Codex emite un elemento nativo de generación de imágenes con un savedPath, OpenClaw reenvía ese archivo exacto mediante la ruta normal de contenido multimedia de respuesta aunque el turno de Codex no contenga texto del asistente.

Temas relacionados

• Entorno de ejecución de Codex
• Referencia del entorno de ejecución de Codex
• Supervisión de Codex
• Plugins nativos de Codex
• Hooks de Plugins
• Plugins de entornos de ejecución de agentes
• Exportación de diagnósticos
• Exportación de trayectorias