Crea plugins de Agent Harness con OpenClaw

¿Alguna vez has sentido que las abstracciones estándar de una API se quedan cortas cuando necesitas un control total sobre la ejecución de tu agente? A veces, gestionar sesiones nativas o flujos de eventos complejos requiere una integración más profunda que un simple plugin de provider.

Un agent harness es el ejecutor de bajo nivel para un turno de agente preparado en OpenClaw. No es un model provider, ni un canal, ni un registro de herramientas.

Usa esta interfaz solo para plugins nativos integrados o de confianza. El contrato es todavía experimental porque los tipos de parámetros reflejan intencionadamente el runner embebido actual.

Cuándo usar un harness

Registra un agent harness cuando una familia de modelos tiene su propio runtime de sesión nativo y el transporte normal del provider de OpenClaw no es la abstracción adecuada.

Ejemplos:

• Un servidor de coding-agent nativo que gestiona hilos y compactación.
• Una CLI local o un demonio que debe transmitir eventos nativos de plan, razonamiento y herramientas.
• Un runtime de modelo que necesita su propio ID de reanudación.
• Un transcript de sesión de OpenClaw sincronizado para mantener el historial.

No registres un harness solo para añadir una nueva API de LLM. Para APIs de modelos normales por HTTP o WebSocket, construye un provider plugin.

Lo que el core sigue controlando

Antes de elegir un harness, OpenClaw ya ha resuelto:

• El provider y el model.
• El estado de autenticación del runtime.
• El nivel de pensamiento (thinking level) y el presupuesto de contexto.
• El archivo de sesión y transcript de OpenClaw.
• El workspace, el sandbox, las políticas de herramientas y el entorno de ejecución.
• Los callbacks de respuesta del canal y los callbacks de streaming.
• La política de fallback del modelo y el cambio de modelo en vivo.

Esa división es intencionada. Un harness ejecuta un intento preparado; no elige providers, ni reemplaza la entrega del canal, ni cambia modelos de forma silenciosa.

Registrar un harness

Importar: openclaw/plugin-sdk/agent-harness

import type { AgentHarness } from "openclaw/plugin-sdk/agent-harness";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

const myHarness: AgentHarness = {
  id: "my-harness",
  label: "My native agent harness",

  supports(ctx) {
    return ctx.provider === "my-provider"
      ? { supported: true, priority: 100 }
      : { supported: false };
  },

  async runAttempt(params) {
    // Start or resume your native thread.
    // Use params.prompt, params.tools, params.images, params.onPartialReply,
    // params.onAgentEvent, and the other prepared attempt fields.
    return await runMyNativeTurn(params);
  },
};

export default definePluginEntry({
  id: "my-native-agent",
  name: "My Native Agent",
  description: "Runs selected models through a native agent daemon.",
  register(api) {
    api.registerAgentHarness(myHarness);
  },
});

Política de selección

OpenClaw elige un harness después de la resolución del provider/model:

1. OPENCLAW_AGENT_RUNTIME=<id> fuerza un harness registrado con ese ID.
2. OPENCLAW_AGENT_RUNTIME=pi fuerza el harness PI integrado.
3. OPENCLAW_AGENT_RUNTIME=auto pregunta a los harnesses registrados si soportan el provider/model resuelto.
4. Si ningún harness registrado coincide, OpenClaw usa PI a menos que el fallback a PI esté desactivado.

Los fallos de un harness de plugin forzado aparecen como fallos de ejecución. En modo auto, OpenClaw puede volver a PI cuando el harness del plugin seleccionado falla antes de que un turno haya producido efectos secundarios. Configura OPENCLAW_AGENT_HARNESS_FALLBACK=none o embeddedHarness.fallback: "none" para que ese fallback sea un fallo crítico en su lugar.

El plugin Codex integrado registra codex como su ID de harness. El core lo trata como un ID de harness de plugin ordinario; los alias específicos de Codex pertenecen al plugin o a la configuración del operador, no al selector de runtime compartido.

Emparejamiento de Provider y harness

La mayoría de los harnesses también deberían registrar un provider. El provider hace que las referencias de modelos, el estado de autenticación, los metadatos del modelo y la selección de /model sean visibles para el resto de OpenClaw. El harness luego reclama ese provider en supports(...).

El plugin Codex integrado sigue este patrón:

• ID del provider: codex
• Referencias de modelo del usuario: codex/gpt-5.4, codex/gpt-5.2, u otro modelo devuelto por el servidor de la aplicación Codex.
• ID del harness: codex
• Autenticación: disponibilidad de provider sintético, porque el harness de Codex gestiona el login y la sesión nativa de Codex.
• Petición al servidor de la aplicación: OpenClaw envía el ID de modelo básico a Codex y deja que el harness hable con el protocolo nativo del servidor de la aplicación.

El plugin de Codex es aditivo. Las referencias simples a openai/gpt-* siguen siendo referencias del provider OpenAI y continúan usando la ruta normal del provider de OpenClaw. Selecciona codex/gpt-* cuando quieras autenticación gestionada por Codex, descubrimiento de modelos de Codex, hilos nativos y ejecución en el servidor de la aplicación Codex. /model puede cambiar entre los modelos de Codex devueltos por su servidor sin requerir credenciales del provider OpenAI.

Para la configuración del operador, ejemplos de prefijos de modelos y configuraciones exclusivas de Codex, consulta Codex Harness.

OpenClaw requiere la versión 0.118.0 o superior del servidor de la aplicación Codex. El plugin de Codex verifica el handshake de inicialización del servidor y bloquea servidores antiguos o sin versión para que OpenClaw solo se ejecute contra la superficie del protocolo con la que ha sido probado.

Desactivar el fallback de PI

Por defecto, OpenClaw ejecuta agentes embebidos con agents.defaults.embeddedHarness configurado como { runtime: "auto", fallback: "pi" }. En modo auto, los harnesses de plugins registrados pueden reclamar un par provider/model. Si ninguno coincide, o si un harness de plugin seleccionado automáticamente falla antes de producir una salida, OpenClaw vuelve a PI.

Configura fallback: "none" cuando necesites demostrar que un harness de plugin es el único runtime que se está utilizando. Esto desactiva el fallback automático a PI; no bloquea un runtime: "pi" explícito o OPENCLAW_AGENT_RUNTIME=pi.

Para ejecuciones embebidas exclusivas de Codex:

{
  "agents": {
    "defaults": {
      "model": "codex/gpt-5.4",
      "embeddedHarness": {
        "runtime": "codex",
        "fallback": "none"
      }
    }
  }
}

Si quieres que cualquier harness de plugin registrado reclame modelos coincidentes pero no quieres que OpenClaw vuelva silenciosamente a PI, mantén runtime: "auto" y desactiva el fallback:

{
  "agents": {
    "defaults": {
      "embeddedHarness": {
        "runtime": "auto",
        "fallback": "none"
      }
    }
  }
}

Las anulaciones por agente usan la misma estructura:

{
  "agents": {
    "defaults": {
      "embeddedHarness": {
        "runtime": "auto",
        "fallback": "pi"
      }
    },
    "list": [
      {
        "id": "codex-only",
        "model": "codex/gpt-5.4",
        "embeddedHarness": {
          "runtime": "codex",
          "fallback": "none"
        }
      }
    ]
  }
}

OPENCLAW_AGENT_RUNTIME sigue anulando el runtime configurado. Usa OPENCLAW_AGENT_HARNESS_FALLBACK=none para desactivar el fallback a PI desde el entorno.

OPENCLAW_AGENT_RUNTIME=codex \
OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run

Con el fallback desactivado, una sesión falla pronto cuando el harness solicitado no está registrado, no soporta el provider/model resuelto, o falla antes de producir efectos secundarios en el turno. Esto es intencionado para despliegues exclusivos de Codex y para pruebas en vivo que deben confirmar que la ruta del servidor de la aplicación Codex está realmente en uso.

Este ajuste solo controla el agent harness embebido. No desactiva el enrutamiento de modelos específicos de provider para imagen, video, música, TTS, PDF u otros tipos.

Sesiones nativas y espejo del transcript

Un harness puede mantener un ID de sesión nativa, un ID de hilo o un token de reanudación en el lado del demonio. Mantén ese vínculo asociado explícitamente con la sesión de OpenClaw y sigue reflejando la salida del asistente y de las herramientas visible para el usuario en el transcript de OpenClaw.

El transcript de OpenClaw sigue siendo la capa de compatibilidad para:

• El historial de sesión visible en el canal.
• La búsqueda e indexación del transcript.
• Volver al harness PI integrado en un turno posterior.
• El comportamiento genérico de /new, /reset y la eliminación de sesiones.

Si tu harness almacena un vínculo secundario (sidecar), implementa reset(...) para que OpenClaw pueda limpiarlo cuando se reinicie la sesión de OpenClaw propietaria.

Resultados de herramientas y multimedia

El core construye la lista de herramientas de OpenClaw y la pasa al intento preparado. Cuando un harness ejecuta una llamada a una herramienta dinámica, devuelve el resultado de la herramienta a través de la estructura de resultados del harness en lugar de enviar tú mismo el contenido multimedia al canal.

Esto mantiene las salidas de texto, imagen, video, música, TTS, aprobaciones y herramientas de mensajería en la misma ruta de entrega que las ejecuciones respaldadas por PI.

Limitaciones actuales

• La ruta de importación pública es genérica, pero algunos alias de tipos de intentos/resultados aún llevan nombres de Pi por compatibilidad.
• La instalación de harnesses de terceros es experimental. Prefiere plugins de provider hasta que necesites un runtime de sesión nativo.
• Se admite el cambio de harness entre turnos.
• No cambies de harness en medio de un turno después de que hayan comenzado las herramientas nativas, las aprobaciones, el texto del asistente o los envíos de mensajes.

Relacionado

• SDK Overview
• Runtime Helpers
• Provider Plugins
• Codex Harness
• Model Providers

Pasos siguientes

• Explora cómo crear tu propio Provider Plugin si no necesitas ejecución nativa.
• Revisa la configuración de Codex Harness para ver un ejemplo real en funcionamiento.

AI Setup Assistant