OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Developer and self-hosted

Raft

Raft connecte un agent OpenClaw à un agent externe Raft via la CLI Raft locale. Raft envoie des signaux de réveil authentifiés au Gateway ; l’agent utilise ensuite la CLI Raft pour consulter et envoyer des messages. Discussions directes uniquement (aucun groupe).

Installation

Raft est un plugin externe officiel. Installez-le sur l’hôte du Gateway :

bash
openclaw plugins install @openclaw/raftopenclaw gateway restart

Détails : Plugins

Prérequis

  • Un espace de travail Raft avec un agent externe.
  • La CLI Raft installée sur le même hôte que le Gateway OpenClaw et accessible dans le PATH du service.
  • Un profil de CLI Raft déjà connecté et associé à cet agent externe.

Le plugin ne stocke pas les identifiants Raft ; la CLI Raft conserve cette authentification dans son propre profil.

Configuration

Définissez le profil dans la configuration :

json5
{  channels: {    raft: {      enabled: true,      profile: "openclaw",    },  },}

Pour le compte par défaut, vous pouvez à la place définir RAFT_PROFILE dans l’environnement du Gateway :

bash
RAFT_PROFILE=openclaw

Utilisez un compte nommé lorsqu’un même Gateway se connecte à plusieurs agents externes Raft :

json5
{  channels: {    raft: {      accounts: {        support: {          profile: "support-agent",        },        engineering: {          profile: "engineering-agent",        },      },    },  },}

La configuration interactive enregistre le même profil :

bash
openclaw channels add --channel raft

Fonctionnement

Au démarrage du Gateway, le plugin :

  1. Ouvre un point de terminaison HTTP de réveil accessible uniquement en local loopback sur un port éphémère.
  2. Lance raft --profile <profile> agent bridge avec ce point de terminaison et un jeton propre au processus.
  3. Accepte uniquement les signaux de réveil authentifiés, sans contenu et dotés d’un identifiant anti-rejeu, provenant du pont local.
  4. Exige la présence de eventId, attemptId, messageId, delivery_id, wake_id ou id dans chaque charge utile de réveil.
  5. Déduplique pendant 24 heures les tentatives répétées de livraison des réveils selon l’identifiant d’événement du pont, y compris après les redémarrages du Gateway.
  6. Renvoie une session d’exécution stable pour le pont actuel et un lot vide de vidage d’activité pour le protocole de la CLI Raft.
  7. Lance un tour sérialisé de l’agent OpenClaw pour chaque réveil accepté.

Le pont gère les nouvelles tentatives de livraison et les reconnexions de Raft. Le tour OpenClaw reçoit uniquement une notification de réveil, et non une copie du corps du message Raft. Il utilise la CLI pour lire les messages en attente et envoyer sa réponse :

bash
raft --profile openclaw message checkraft --profile openclaw message send

Vérification

Vérifiez qu’OpenClaw peut trouver la CLI et qu’un profil est configuré :

bash
openclaw channels status --probeopenclaw plugins inspect raft --runtime --json

Envoyez ensuite un message à l’agent externe Raft. Le journal du Gateway doit indiquer le démarrage du pont Raft, suivi de la réception d’un réveil. L’agent doit utiliser le profil Raft configuré pour consulter ses messages en attente.

Résolution des problèmes

La CLI Raft est introuvable

Installez la CLI Raft sur l’hôte du Gateway et rendez raft accessible dans le PATH du service. Vérifiez-la avec raft --help, puis redémarrez le Gateway.

Le pont s’arrête immédiatement

Vérifiez que le profil configuré est connecté et appartient à l’agent externe Raft prévu. Exécutez directement raft --profile <profile> agent bridge pour afficher le diagnostic de la CLI.

Un réveil arrive, mais aucune réponse Raft n’est envoyée

Ce comportement est attendu lorsque l’agent n’appelle pas la CLI Raft. Le pont de réveil ne transporte ni le corps des messages ni les réponses finales automatiques. Vérifiez la politique d’utilisation des outils de l’agent et assurez-vous qu’il peut exécuter raft --profile <profile> message check et message send.

Références

Was this useful?
On this page

On this page