> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Raft

Il supporto Raft collega un agente OpenClaw a un agente esterno Raft tramite la CLI
Raft locale. Raft invia segnali di risveglio autenticati al Gateway. L'agente quindi usa
la CLI Raft per controllare e inviare messaggi.

## Installazione

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install @openclaw/raft
openclaw gateway restart
```

Dettagli: [Plugin](/it/tools/plugin)

## Prerequisiti

* Un workspace Raft con un agente esterno.
* La CLI Raft installata sullo stesso host del Gateway OpenClaw.
* Un profilo della CLI Raft che ha già effettuato l'accesso ed è associato a quell'agente esterno.

Il Plugin non memorizza le credenziali Raft. La CLI Raft conserva tale autenticazione
nel proprio profilo.

## Configurazione

Imposta il profilo nella configurazione:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    raft: {
      enabled: true,
      profile: "openclaw",
    },
  },
}
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
RAFT_PROFILE=openclaw
```

Usa un account con nome quando un Gateway si collega a più di un agente esterno Raft:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    raft: {
      accounts: {
        support: {
          profile: "support-agent",
        },
        engineering: {
          profile: "engineering-agent",
        },
      },
    },
  },
}
```

Il flusso di configurazione interattiva registra lo stesso profilo:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw channels setup raft
```

## Come funziona

Quando il Gateway si avvia, il Plugin:

1. Apre un endpoint HTTP di risveglio solo loopback su una porta effimera.
2. Avvia `raft --profile <profile> agent bridge` con quell'endpoint e un
   token per processo.
3. Accetta solo segnali di risveglio autenticati, senza contenuto e con un'identità di replay dal bridge locale.
4. Richiede uno tra `eventId`, `attemptId`, `messageId`, `delivery_id`, `wake_id` o `id`.
5. Deduplica le consegne di risveglio recenti ritentate in base all'id evento del bridge, anche tra riavvii del Gateway.
6. Restituisce una sessione runtime stabile per il bridge corrente e un batch di svuotamento attività vuoto per il protocollo della CLI Raft.
7. Avvia un turno serializzato dell'agente OpenClaw per ogni risveglio accettato.

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
raft --profile openclaw message check
raft --profile openclaw message send
```

<Note>
  Raft non è un normale trasporto per messaggi push. OpenClaw non invia automaticamente
  il testo finale del modello tramite il bridge, quindi l'agente deve usare la
  CLI Raft dopo aver elaborato un risveglio.
</Note>

## Verifica

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw channels status --probe
openclaw plugins inspect raft --runtime --json
```

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

## Risoluzione dei problemi

<AccordionGroup>
  <Accordion title="La CLI Raft è mancante">
    Installa la CLI Raft sull'host del Gateway e rendi `raft` disponibile nel
    `PATH` del servizio. Verificala con `raft --help`, quindi riavvia il Gateway.
  </Accordion>

  <Accordion title="Il bridge termina immediatamente">
    Verifica che il profilo configurato abbia effettuato l'accesso e appartenga
    all'agente esterno Raft previsto. Esegui direttamente `raft --profile <profile> agent bridge`
    per vedere la diagnostica della CLI.
  </Accordion>

  <Accordion title="Arriva un risveglio ma non viene inviata alcuna risposta Raft">
    Questo è previsto quando l'agente non invoca la CLI Raft. Il bridge di risveglio
    non trasporta corpi dei messaggi né risposte finali automatiche. Controlla la
    policy degli strumenti dell'agente e assicurati che possa eseguire `raft --profile <profile> message
            check` e `message send`.
  </Accordion>
</AccordionGroup>

## Riferimenti

* [Raft](https://raft.build/)
* [Documentazione Raft](https://docs.raft.build/welcome/)
* [Integrazione Hermes Raft](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/raft)