Configuration

Associazione

"Associazione" è il passaggio esplicito di approvazione dell'accesso di OpenClaw. Viene usata in due punti:

Associazione DM (chi può parlare con il bot)
Associazione dei nodi (quali dispositivi/nodi possono entrare nella rete del Gateway)

Contesto di sicurezza: Sicurezza

1) Associazione DM (accesso chat in ingresso)

Quando un canale è configurato con la policy DM pairing, i mittenti sconosciuti ricevono un codice breve e il loro messaggio non viene elaborato finché non lo approvi.

Le policy DM predefinite sono documentate in: Sicurezza

dmPolicy: "open" è pubblica solo quando l'elenco di consentiti DM effettivo include "*". La configurazione e la validazione richiedono quel carattere jolly per le configurazioni aperte pubblicamente. Se lo stato esistente contiene open con voci allowFrom concrete, a runtime vengono comunque ammessi solo quei mittenti, e le approvazioni dell'archivio di associazione non ampliano l'accesso open.

Codici di associazione:

8 caratteri, maiuscoli, senza caratteri ambigui (0O1I).
Scadono dopo 1 ora. Il bot invia il messaggio di associazione solo quando viene creata una nuova richiesta (circa una volta all'ora per mittente).
Le richieste di associazione DM in sospeso sono limitate a 3 per canale per impostazione predefinita; le richieste aggiuntive vengono ignorate finché una non scade o viene approvata.

Approvare un mittente

openclaw pairing list telegram
openclaw pairing approve telegram &lt;CODE&gt;

Se non è ancora configurato alcun proprietario dei comandi, l'approvazione di un codice di associazione DM inizializza anche commands.ownerAllowFrom con il mittente approvato, ad esempio telegram:123456789. Questo assegna alle configurazioni iniziali un proprietario esplicito per i comandi privilegiati e per le richieste di approvazione dell'esecuzione. Dopo che un proprietario esiste, le approvazioni di associazione successive concedono solo l'accesso DM; non aggiungono altri proprietari.

Canali supportati: bluebubbles, discord, feishu, googlechat, imessage, irc, line, matrix, mattermost, msteams, nextcloud-talk, nostr, openclaw-weixin, signal, slack, synology-chat, telegram, twitch, whatsapp, zalo, zalouser.

Gruppi di mittenti riutilizzabili

Usa accessGroups di primo livello quando lo stesso insieme di mittenti attendibili deve applicarsi a più canali di messaggistica o sia agli elenchi di consentiti DM sia a quelli di gruppo.

I gruppi statici usano type: "message.senders" e vengono referenziati con accessGroup:<name> dagli elenchi di consentiti dei canali:

{
  accessGroups: {
    operators: {
      type: "message.senders",
      members: {
        discord: ["discord:123456789012345678"],
        telegram: ["987654321"],
        whatsapp: ["+15551234567"],
      },
    },
  },
  channels: {
    telegram: { dmPolicy: "allowlist", allowFrom: ["accessGroup:operators"] },
    whatsapp: { groupPolicy: "allowlist", groupAllowFrom: ["accessGroup:operators"] },
  },
}

I gruppi di accesso sono documentati in dettaglio qui: Gruppi di accesso

Dove si trova lo stato

Archiviato sotto ~/.openclaw/credentials/:

Richieste in sospeso: <channel>-pairing.json
Archivio dell'elenco di consentiti approvato:
- Account predefinito: <channel>-allowFrom.json
- Account non predefinito: <channel>-<accountId>-allowFrom.json

Comportamento dell'ambito account:

Gli account non predefiniti leggono/scrivono solo il proprio file di elenco consentiti con ambito.
L'account predefinito usa il file di elenco consentiti senza ambito del canale.

Trattali come dati sensibili (regolano l'accesso al tuo assistente).

2) Associazione di dispositivi Node (nodi iOS/Android/macOS/headless)

I nodi si connettono al Gateway come dispositivi con role: node. Il Gateway crea una richiesta di associazione del dispositivo che deve essere approvata.

Associare tramite Telegram (consigliato per iOS)

Se usi il Plugin device-pair, puoi completare la prima associazione del dispositivo interamente da Telegram:

In Telegram, invia un messaggio al tuo bot: /pair
Il bot risponde con due messaggi: un messaggio di istruzioni e un messaggio separato con il codice di configurazione (facile da copiare/incollare in Telegram).
Sul telefono, apri l'app iOS di OpenClaw → Settings → Gateway.
Scansiona il codice QR o incolla il codice di configurazione e connettiti.
Di nuovo in Telegram: /pair pending (rivedi ID richiesta, ruolo e ambiti), quindi approva.

Il codice di configurazione è un payload JSON codificato in base64 che contiene:

url: l'URL WebSocket del Gateway (ws://... o wss://...)
bootstrapToken: un token di bootstrap di breve durata per singolo dispositivo usato per l'handshake di associazione iniziale

Quel token di bootstrap include il profilo di bootstrap di associazione integrato:

il token node principale consegnato rimane scopes: []
qualsiasi token operator consegnato rimane limitato all'elenco di consentiti di bootstrap: operator.approvals, operator.read, operator.talk.secrets, operator.write
i controlli degli ambiti di bootstrap hanno un prefisso di ruolo, non un unico pool piatto di ambiti: le voci di ambito operator soddisfano solo le richieste operator, e i ruoli non operator devono comunque richiedere gli ambiti sotto il proprio prefisso di ruolo
la rotazione/revoca successiva dei token rimane limitata sia dal contratto di ruolo approvato del dispositivo sia dagli ambiti operator della sessione chiamante

Tratta il codice di configurazione come una password finché è valido.

Per Tailscale, per l'associazione mobile pubblica o remota di altro tipo, usa Tailscale Serve/Funnel o un altro URL Gateway wss://. I codici di configurazione in chiaro ws:// sono accettati solo per loopback, indirizzi LAN privati, host Bonjour .local e l'host dell'emulatore Android. Gli indirizzi CGNAT Tailnet, i nomi .ts.net e gli host pubblici continuano a fallire in modo chiuso prima dell'emissione del QR/codice di configurazione.

Approvare un dispositivo Node

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

Quando un'approvazione esplicita viene negata perché la sessione del dispositivo associato che approva è stata aperta con un ambito solo per l'associazione, la CLI riprova la stessa richiesta con operator.admin. Questo consente a un dispositivo associato esistente con capacità di amministrazione di recuperare una nuova associazione di Control UI/browser senza modificare manualmente devices/paired.json. Il Gateway valida comunque la connessione riprovata; i token che non possono autenticarsi con operator.admin restano bloccati.

Se lo stesso dispositivo riprova con dettagli di autenticazione diversi (ad esempio ruolo/ambiti/chiave pubblica diversi), la precedente richiesta in sospeso viene sostituita e viene creato un nuovo requestId.

Approvazione automatica facoltativa dei nodi tramite CIDR attendibile

L'associazione dei dispositivi rimane manuale per impostazione predefinita. Per reti di nodi strettamente controllate, puoi abilitare l'approvazione automatica della prima associazione dei nodi con CIDR espliciti o IP esatti:

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

Questo si applica solo alle nuove richieste di associazione role: node senza ambiti richiesti. I client operator, browser, Control UI e WebChat richiedono comunque l'approvazione manuale. Anche le modifiche a ruolo, ambito, metadati e chiave pubblica richiedono l'approvazione manuale.

Archiviazione dello stato di associazione Node

Archiviato sotto ~/.openclaw/devices/:

pending.json (di breve durata; le richieste in sospeso scadono)
paired.json (dispositivi associati + token)

Note

L'API legacy node.pair.* (CLI: openclaw nodes pending|approve|reject|remove|rename) è un archivio di associazione separato di proprietà del Gateway. I nodi WS richiedono comunque l'associazione dispositivo.
Il record di associazione è la fonte di verità duratura per i ruoli approvati. I token dei dispositivi attivi restano limitati a quell'insieme di ruoli approvati; una voce di token estranea al di fuori dei ruoli approvati non crea nuovo accesso.

Documentazione correlata

Modello di sicurezza + prompt injection: Sicurezza
Aggiornamento sicuro (eseguire doctor): Aggiornamento
Configurazioni dei canali:
- Telegram: Telegram
- WhatsApp: WhatsApp
- Signal: Signal
- iMessage: iMessage
- BlueBubbles (bridge iMessage legacy): BlueBubbles
- Discord: Discord
- Slack: Slack

# 1) Associazione DM (accesso chat in ingresso)

# Approvare un mittente

# Gruppi di mittenti riutilizzabili

# Dove si trova lo stato

# 2) Associazione di dispositivi Node (nodi iOS/Android/macOS/headless)

# Associare tramite Telegram (consigliato per iOS)

# Approvare un dispositivo Node

# Approvazione automatica facoltativa dei nodi tramite CIDR attendibile

# Archiviazione dello stato di associazione Node

# Note

# Documentazione correlata