Saltar al contenido principal
La compatibilidad con Raft conecta un agente de OpenClaw a un External Agent de Raft mediante la CLI local de Raft. Raft envía indicios de activación autenticados al Gateway. Después, el agente usa la CLI de Raft para comprobar y enviar mensajes.

​
Instalación

Raft es un Plugin externo oficial. Instálalo en el host del Gateway: 
openclaw plugins install @openclaw/raft
openclaw gateway restart
Detalles: Plugins

​
Requisitos previos

  • Un espacio de trabajo de Raft con un External Agent.
  • La CLI de Raft instalada en el mismo host que el Gateway de OpenClaw.
  • Un perfil de la CLI de Raft que ya haya iniciado sesión y esté asociado con ese External Agent.
El Plugin no almacena credenciales de Raft. La CLI de Raft conserva esa autenticación en su propio perfil.

​
Configuración

Define el perfil en la configuración: 
{
  channels: {
    raft: {
      enabled: true,
      profile: "openclaw",
    },
  },
}
Para la cuenta predeterminada, también puedes definir RAFT_PROFILE en el entorno del Gateway: 
RAFT_PROFILE=openclaw
Usa una cuenta con nombre cuando un Gateway se conecta a más de un External Agent de Raft: 
{
  channels: {
    raft: {
      accounts: {
        support: {
          profile: "support-agent",
        },
        engineering: {
          profile: "engineering-agent",
        },
      },
    },
  },
}
El flujo de configuración interactivo registra el mismo perfil: 
openclaw channels setup raft

​
Cómo funciona

Cuando el Gateway se inicia, el Plugin:
  1. Abre un endpoint HTTP de activación solo de loopback en un puerto efímero.
  2. Inicia raft --profile <profile> agent bridge con ese endpoint y un token por proceso.
  3. Acepta solo indicios de activación autenticados y sin contenido con una identidad de repetición desde el bridge local.
  4. Requiere uno de eventId, attemptId, messageId, delivery_id, wake_id o id.
  5. Deduplica las entregas de activación reintentadas recientes por identificador de evento del bridge, incluso entre reinicios del Gateway.
  6. Devuelve una sesión de tiempo de ejecución estable para el bridge actual y un lote vacío de drenaje de actividad para el protocolo de la CLI de Raft.
  7. Inicia un turno serializado de agente de OpenClaw por cada activación aceptada.
El bridge es responsable de los reintentos de entrega y las reconexiones de Raft. El turno de OpenClaw recibe solo un aviso de activación, no una copia del cuerpo del mensaje de Raft. Usa la CLI para leer los mensajes pendientes y enviar su respuesta: 
raft --profile openclaw message check
raft --profile openclaw message send
Raft no es un transporte normal de mensajes push. OpenClaw no envía automáticamente el texto final del modelo de vuelta a través del bridge, por lo que el agente debe usar la CLI de Raft después de procesar una activación.

​
Verificación

Comprueba que OpenClaw pueda encontrar la CLI y tenga un perfil configurado: 
openclaw channels status --probe
openclaw plugins inspect raft --runtime --json
Después, envía un mensaje al External Agent de Raft. El registro del Gateway debería mostrar el inicio del bridge de Raft, seguido de una activación entrante. El agente debería usar el perfil de Raft configurado para comprobar sus mensajes pendientes.

​
Solución de problemas

Instala la CLI de Raft en el host del Gateway y haz que raft esté disponible en el PATH del servicio. Verifícalo con raft --help y después reinicia el Gateway.
Verifica que el perfil configurado haya iniciado sesión y pertenezca al External Agent de Raft previsto. Ejecuta raft --profile <profile> agent bridge directamente para ver el diagnóstico de la CLI.
Esto es esperado cuando el agente no invoca la CLI de Raft. El bridge de activación no transporta cuerpos de mensaje ni respuestas finales automáticas. Comprueba la política de herramientas del agente y asegúrate de que pueda ejecutar raft --profile <profile> message check y message send.

​
Referencias