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 connette un agente OpenClaw a un agente esterno Raft tramite la CLI Raft locale. Raft invia al Gateway notifiche di riattivazione autenticate; l'agente usa quindi la CLI Raft per controllare e inviare messaggi. Solo chat dirette (nessun gruppo).

Installazione

Raft è un plugin esterno ufficiale. Installalo sull'host del Gateway:

bash
openclaw plugins install @openclaw/raftopenclaw gateway restart

Dettagli: Plugin

Prerequisiti

  • Uno spazio di lavoro Raft con un agente esterno.
  • La CLI Raft installata sullo stesso host del Gateway OpenClaw e disponibile nel PATH del servizio.
  • Un profilo della CLI Raft con accesso già effettuato e associato a tale agente esterno.

Il plugin non memorizza le credenziali Raft; la CLI Raft conserva l'autenticazione nel proprio profilo.

Configurazione

Imposta il profilo nella configurazione:

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

Per l'account predefinito, puoi invece impostare RAFT_PROFILE nell'ambiente del Gateway:

bash
RAFT_PROFILE=openclaw

Usa un account denominato quando un Gateway si connette a più di un agente esterno Raft:

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

La configurazione interattiva registra lo stesso profilo:

bash
openclaw channels add --channel raft

Funzionamento

All'avvio del Gateway, il plugin:

  1. Apre un endpoint HTTP di riattivazione accessibile solo tramite local loopback su una porta temporanea.
  2. Avvia raft --profile <profile> agent bridge con tale endpoint e un token specifico per il processo.
  3. Accetta dal bridge locale esclusivamente notifiche di riattivazione autenticate, prive di contenuto e dotate di un'identità anti-replay.
  4. Richiede uno tra eventId, attemptId, messageId, delivery_id, wake_id o id in ogni payload di riattivazione.
  5. Deduplica per 24 ore i tentativi ripetuti di consegna delle notifiche di riattivazione in base all'ID evento del bridge, anche tra riavvii del Gateway.
  6. Restituisce una sessione di runtime stabile per il bridge corrente e un batch vuoto per lo scaricamento delle attività del protocollo CLI Raft.
  7. Avvia un turno serializzato dell'agente OpenClaw per ogni riattivazione accettata.

Il bridge gestisce i nuovi tentativi di consegna e le riconnessioni di Raft. Il turno di OpenClaw riceve solo una notifica di riattivazione, non una copia del corpo del messaggio Raft. Usa la CLI per leggere i messaggi in sospeso e inviare la risposta:

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

Verifica

Controlla che OpenClaw riesca a trovare la CLI e disponga di un profilo configurato:

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

Invia quindi un messaggio all'agente esterno Raft. Il log del Gateway dovrebbe mostrare l'avvio del bridge Raft, seguito da una riattivazione in ingresso. L'agente dovrebbe usare il profilo Raft configurato per controllare i messaggi in sospeso.

Risoluzione dei problemi

La CLI Raft non è disponibile

Installa la CLI Raft sull'host del Gateway e rendi raft disponibile nel PATH del servizio. Verificala con raft --help, quindi riavvia il Gateway.

Il bridge termina immediatamente

Verifica che nel profilo configurato sia stato effettuato l'accesso e che appartenga all'agente esterno Raft previsto. Esegui direttamente raft --profile <profile> agent bridge per visualizzare la diagnostica della CLI.

Arriva una riattivazione, ma non viene inviata alcuna risposta Raft

Questo comportamento è previsto quando l'agente non richiama la CLI Raft. Il bridge di riattivazione non trasporta i corpi dei messaggi né le risposte finali automatiche. Controlla i criteri di utilizzo degli strumenti dell'agente e assicurati che possa eseguire raft --profile <profile> message check e message send.

Riferimenti

Was this useful?
On this page

On this page