Skip to main content
O Raft conecta um agente do OpenClaw a um Agente Externo do Raft por meio da CLI do Raft local. O Raft envia avisos de ativação autenticados ao Gateway; em seguida, o agente usa a CLI do Raft para verificar e enviar mensagens. Somente conversas diretas (sem grupos).

​
Instalação

O Raft é um plugin externo oficial. Instale-o no host do Gateway:
Detalhes: Plugins

​
Pré-requisitos

  • Um espaço de trabalho do Raft com um Agente Externo.
  • A CLI do Raft instalada no mesmo host que o Gateway do OpenClaw e disponível no PATH do serviço.
  • Um perfil da CLI do Raft que já tenha uma sessão iniciada e esteja associado a esse Agente Externo.
O plugin não armazena credenciais do Raft; a CLI do Raft mantém essa autenticação no próprio perfil.

​
Configuração

Defina o perfil na configuração:
Para a conta padrão, você também pode definir RAFT_PROFILE no ambiente do Gateway:
Use uma conta nomeada quando um Gateway se conectar a mais de um Agente Externo do Raft:
A configuração interativa registra o mesmo perfil:

​
Como funciona

Quando o Gateway é iniciado, o plugin:
  1. Abre um endpoint HTTP de ativação acessível somente por local loopback em uma porta efêmera.
  2. Inicia raft --profile <profile> agent bridge com esse endpoint e um token específico do processo.
  3. Aceita somente avisos de ativação autenticados, sem conteúdo e com uma identidade de repetição, provenientes da ponte local.
  4. Exige eventId, attemptId, messageId, delivery_id, wake_id ou id em cada carga útil de ativação.
  5. Elimina duplicatas de entregas de ativação repetidas pelo ID de evento da ponte durante 24 horas, inclusive após reinicializações do Gateway.
  6. Retorna uma sessão de execução estável para a ponte atual e um lote vazio de escoamento de atividades para o protocolo da CLI do Raft.
  7. Inicia um turno serializado do agente do OpenClaw para cada ativação aceita.
A ponte gerencia as novas tentativas de entrega e as reconexões do Raft. O turno do OpenClaw recebe apenas um aviso de ativação, e não uma cópia do corpo da mensagem do Raft. Ele usa a CLI para ler mensagens pendentes e enviar sua resposta:
O Raft não é um transporte de mensagens por push. O OpenClaw não envia automaticamente o texto final do modelo de volta pela ponte; portanto, o agente deve usar a CLI do Raft após processar uma ativação.

​
Verificação

Verifique se o OpenClaw consegue encontrar a CLI e tem um perfil configurado:
Em seguida, envie uma mensagem ao Agente Externo do Raft. O log do Gateway deve mostrar a inicialização da ponte do Raft, seguida por uma ativação recebida. O agente deve usar o perfil configurado do Raft para verificar suas mensagens pendentes.

​
Solução de problemas

Instale a CLI do Raft no host do Gateway e disponibilize raft no PATH do serviço. Verifique-a com raft --help e reinicie o Gateway.
Verifique se o perfil configurado tem uma sessão iniciada e pertence ao Agente Externo do Raft pretendido. Execute raft --profile <profile> agent bridge diretamente para ver o diagnóstico da CLI.
Isso é esperado quando o agente não invoca a CLI do Raft. A ponte de ativação não transporta corpos de mensagens nem respostas finais automáticas. Verifique a política de ferramentas do agente e garanta que ele possa executar raft --profile <profile> message check e message send.

​
Referências