Entornos de ejecución de agentes

Un entorno de ejecución de agente posee un bucle de modelo preparado: recibe el prompt, controla la salida del modelo, gestiona las llamadas a herramientas nativas y devuelve el turno finalizado a OpenClaw.

Es fácil confundir los entornos de ejecución con los proveedores porque ambos aparecen cerca de la configuración del modelo. Son capas diferentes:

Un harness es la implementación que proporciona un entorno de ejecución de agente (término de código). Por ejemplo, el harness de Codex incluido implementa el entorno de ejecución codex. La configuración pública usa agentRuntime.id en las entradas de proveedor o modelo; las claves de entorno de ejecución para el agente completo son heredadas y se ignoran. openclaw doctor --fix elimina las antiguas fijaciones de entorno de ejecución para el agente completo y reescribe las referencias heredadas de modelos de entorno de ejecución como referencias canónicas de proveedor/modelo, además de añadir una política de entorno de ejecución limitada al modelo cuando sea necesario.

Dos familias de entornos de ejecución:

• Los harnesses integrados se ejecutan dentro del bucle de agente preparado de OpenClaw: el entorno de ejecución openclaw incorporado y los harnesses de Plugin registrados, como codex y copilot.
• Los backends de CLI ejecutan un proceso de CLI local y mantienen canónica la referencia del modelo. Por ejemplo, anthropic/claude-opus-4-8 con agentRuntime.id: "claude-cli" limitado al modelo significa «seleccionar el modelo de Anthropic y ejecutarlo mediante Claude CLI». claude-cli no es un identificador de harness integrado y no debe pasarse a la selección de AgentHarness.

El harness copilot es un harness de Plugin externo independiente y opcional para la CLI de GitHub Copilot; consulta Entorno de ejecución de agente de GitHub Copilot para conocer la decisión de cara al usuario entre PI, Codex y el entorno de ejecución de agente de GitHub Copilot.

Superficies de Codex

Varias superficies comparten el nombre Codex:

Estas superficies son independientes de forma intencionada. Habilitar el Plugin codex hace que estén disponibles las funciones nativas del servidor de aplicaciones; openclaw doctor --fix se encarga de reparar las rutas heredadas de Codex y de limpiar las fijaciones obsoletas de sesión. Seleccionar openai/* para un modelo de agente ahora significa «ejecutar esto mediante Codex», salvo que se esté usando una superficie de API de OpenAI ajena al agente.

La configuración habitual de una suscripción a ChatGPT/Codex usa OAuth de Codex para la autenticación, pero mantiene la referencia del modelo como openai/* y selecciona el entorno de ejecución codex:

{  agents: {    defaults: {      model: "openai/gpt-5.6-sol",    },  },}

Esto significa que OpenClaw selecciona una referencia de modelo de OpenAI y después solicita al entorno de ejecución del servidor de aplicaciones de Codex que ejecute el turno de agente integrado. No significa «usar facturación de API», ni que el canal, el catálogo de proveedores de modelos o el almacén de sesiones de OpenClaw se conviertan en Codex.

Cuando el Plugin codex incluido está habilitado, usa la superficie nativa de comandos /codex (/codex bind, /codex threads, /codex resume, /codex steer, /codex stop) para controlar Codex con lenguaje natural en lugar de ACP. Usa ACP para Codex solo cuando el usuario solicite explícitamente ACP/acpx o esté probando la ruta del adaptador ACP. Claude Code, Gemini CLI, OpenCode, Cursor y otros harnesses externos similares siguen usando ACP.

Árbol de decisión:

1. Vincular/controlar/hilo/reanudar/dirigir/detener Codex -> superficie nativa de comandos /codex cuando el Plugin codex incluido está habilitado.
2. Codex como entorno de ejecución integrado o la experiencia normal del agente Codex respaldada por una suscripción -> openai/<model>.
3. OpenClaw elegido explícitamente para un modelo de OpenAI -> mantén la referencia del modelo como openai/<model> y establece la política de entorno de ejecución del proveedor/modelo como agentRuntime.id: "openclaw". Un perfil OAuth de openai seleccionado se enruta internamente mediante el transporte de autenticación de Codex de OpenClaw.
4. Referencias heredadas de modelos Codex en la configuración -> repáralas con openclaw doctor --fix para convertirlas en openai/<model>; doctor conserva la ruta de autenticación de Codex añadiendo agentRuntime.id: "codex" limitado al proveedor/modelo cuando la referencia antigua del modelo lo implicaba. Las referencias heredadas de modelos codex-cli/* se reparan para usar la misma ruta openai/<model> del servidor de aplicaciones de Codex; OpenClaw ya no mantiene un backend de CLI de Codex incluido.
5. Se solicita explícitamente ACP, acpx o el adaptador ACP de Codex -> runtime: "acp" y agentId: "codex".
6. Claude Code, Gemini CLI, OpenCode, Cursor, Droid u otro harness externo -> ACP/acpx, no el entorno de ejecución nativo de subagentes.

Para conocer la división de prefijos de la familia OpenAI, consulta OpenAI y Proveedores de modelos. Para conocer el contrato de compatibilidad del entorno de ejecución de Codex, consulta Entorno de ejecución del harness de Codex.

Propiedad del entorno de ejecución

Los distintos entornos de ejecución controlan diferentes partes del bucle:

Regla de diseño: si OpenClaw controla la superficie, puede proporcionar el comportamiento normal de los hooks de Plugin. Si el entorno de ejecución nativo controla la superficie, OpenClaw necesita eventos del entorno de ejecución o hooks nativos. Si el entorno de ejecución nativo controla el estado canónico del hilo, OpenClaw refleja y proyecta el contexto en lugar de reescribir elementos internos no compatibles.

Selección del entorno de ejecución

OpenClaw resuelve un entorno de ejecución integrado después de resolver el proveedor y el modelo, en este orden:

1. Prevalece la política de entorno de ejecución limitada al modelo. Se encuentra en una entrada de modelo de proveedor configurada, o en agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime. Un comodín de proveedor como agents.defaults.models["vllm/*"].agentRuntime se aplica después de la política de modelo exacta, de modo que los modelos del proveedor detectados dinámicamente puedan compartir un entorno de ejecución sin sobrescribir las excepciones exactas de cada modelo.
2. Política de entorno de ejecución limitada al proveedor: models.providers.<provider>.agentRuntime.
3. Modo auto: los entornos de ejecución de Plugin registrados pueden reclamar pares de proveedor/modelo compatibles.
4. Si nada reclama el turno en modo auto, OpenClaw recurre a openclaw como entorno de ejecución de compatibilidad. Usa un identificador explícito de entorno de ejecución cuando la ejecución deba ser estricta.

Se ignoran las fijaciones de entorno de ejecución para toda la sesión y para todo el agente: OPENCLAW_AGENT_RUNTIME, el estado de sesión agentHarnessId/agentRuntimeOverride, agents.defaults.agentRuntime y agents.list[].agentRuntime. Ejecuta openclaw doctor --fix para eliminar la configuración obsoleta del entorno de ejecución de todo el agente y convertir las referencias heredadas de modelos de entorno de ejecución cuando pueda conservarse la intención.

Los entornos de ejecución explícitos de Plugin para proveedor/modelo fallan de forma cerrada: agentRuntime.id: "codex" en un proveedor o modelo significa Codex, o un error claro de selección/entorno de ejecución; nunca se redirige silenciosamente a OpenClaw. Solo auto puede redirigir a OpenClaw un turno sin coincidencia.

Los alias de backend de CLI difieren de los identificadores de harness integrado. Forma preferida para Claude CLI:

{  agents: {    defaults: {      model: "anthropic/claude-opus-4-8",      models: {        "anthropic/claude-opus-4-8": {          agentRuntime: { id: "claude-cli" },        },      },    },  },}

Las referencias heredadas como claude-cli/claude-opus-4-7 siguen siendo compatibles, pero la configuración nueva debe mantener canónicos el proveedor/modelo y colocar el backend de ejecución en la política de entorno de ejecución del proveedor/modelo.

Las referencias heredadas codex-cli/* son diferentes: doctor las migra a openai/* para que se ejecuten mediante el harness del servidor de aplicaciones de Codex, en lugar de conservar un backend de CLI de Codex.

El modo auto es intencionadamente conservador para la mayoría de los proveedores. Los modelos de agente de OpenAI son la excepción: tanto un entorno de ejecución sin configurar como auto se resuelven al harness de Codex. La configuración explícita del entorno de ejecución de OpenClaw sigue siendo una ruta de compatibilidad opcional para los turnos de agente openai/*; cuando se combina con un perfil OAuth de openai seleccionado, OpenClaw enruta internamente esa ruta mediante el transporte de autenticación de Codex, a la vez que mantiene la referencia pública del modelo como openai/*. La selección del entorno de ejecución ignora las fijaciones obsoletas de sesión del entorno de ejecución de OpenAI, que pueden limpiarse con openclaw doctor --fix.

Si openclaw doctor advierte que el Plugin codex está habilitado mientras todavía quedan referencias heredadas de modelos Codex en la configuración, trátalo como estado de ruta heredada y ejecuta openclaw doctor --fix para reescribirlo como openai/* con el entorno de ejecución de Codex.

Entorno de ejecución de agente de GitHub Copilot

El Plugin externo @openclaw/copilot registra un runtime copilot opcional respaldado por la CLI de GitHub Copilot (@github/copilot-sdk). Reclama el proveedor de suscripción canónico github-copilot y nunca lo selecciona auto. Actívelo por modelo o por proveedor mediante agentRuntime.id:

{  agents: {    defaults: {      model: "github-copilot/gpt-5.5",      models: {        "github-copilot/gpt-5.5": {          agentRuntime: { id: "copilot" },        },      },    },  },}

El harness reclama su proveedor, runtime, clave de sesión de la CLI y prefijo del perfil de autenticación en extensions/copilot/doctor-contract-api.ts, que openclaw doctor carga automáticamente. Para obtener información sobre la configuración, la autenticación, la replicación de transcripciones, la Compaction, el contrato declarativo de doctor y la decisión más amplia entre los SDK de Pi, Codex y Copilot, consulte runtime de agente de GitHub Copilot.

Contrato de compatibilidad

Cuando un runtime no es OpenClaw, su documentación debe indicar qué superficies de OpenClaw admite:

El contrato de compatibilidad del runtime de Codex se documenta en runtime del harness de Codex.

Etiquetas de estado

La salida de estado puede mostrar las etiquetas Execution y Runtime. Deben interpretarse como información de diagnóstico, no como nombres de proveedores:

• Una referencia de modelo como openai/gpt-5.6-sol corresponde al proveedor/modelo seleccionado.
• Un identificador de runtime como codex corresponde al bucle que ejecuta el turno.
• Una etiqueta de canal como Telegram o Discord indica dónde tiene lugar la conversación.

Si una ejecución muestra un runtime inesperado, inspeccione primero la política de runtime del proveedor/modelo seleccionado. Las fijaciones de runtime de sesiones heredadas ya no determinan el enrutamiento.

Relacionado

• Harness de Codex
• Runtime del harness de Codex
• Runtime de agente de GitHub Copilot
• OpenAI
• Plugins de harness de agentes
• Bucle del agente
• Modelos
• Estado