Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

L‘“abbinamento” è il passaggio esplicito di approvazione dell’accesso di OpenClaw. Viene usato in due punti:
  1. Abbinamento DM (chi è autorizzato a parlare con il bot)
  2. Abbinamento dei Node (quali dispositivi/nodi sono autorizzati a unirsi alla rete Gateway)
Contesto di sicurezza: Sicurezza

​
1) Abbinamento 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’allowlist DM effettiva include "*". Configurazione e validazione richiedono quel carattere jolly per le configurazioni pubbliche aperte. Se lo stato esistente contiene open con voci allowFrom concrete, il runtime ammette comunque solo quei mittenti, e le approvazioni dello store di abbinamento non ampliano l’accesso open. Codici di abbinamento:
  • 8 caratteri, maiuscoli, senza caratteri ambigui (0O1I).
  • Scadono dopo 1 ora. Il bot invia il messaggio di abbinamento solo quando viene creata una nuova richiesta (circa una volta all’ora per mittente).
  • Le richieste di abbinamento DM in sospeso sono limitate a 3 per canale per impostazione predefinita; le richieste aggiuntive vengono ignorate finché una non scade o non viene approvata.

​
Approva un mittente

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
Se non è ancora configurato alcun proprietario dei comandi, l’approvazione di un codice di abbinamento DM inizializza anche commands.ownerAllowFrom con il mittente approvato, ad esempio telegram:123456789. Questo fornisce alle prime configurazioni un proprietario esplicito per i comandi privilegiati e le richieste di approvazione exec. Dopo che esiste un proprietario, le approvazioni di abbinamento successive concedono solo l’accesso DM; non aggiungono altri proprietari. Canali supportati: 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 alle allowlist DM sia a quelle dei gruppi. I gruppi statici usano type: "message.senders" e vengono referenziati con accessGroup:<name> dalle allowlist 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 risiede lo stato

Archiviato in ~/.openclaw/credentials/:
  • Richieste in sospeso: <channel>-pairing.json
  • Store allowlist approvate:
    • Account predefinito: <channel>-allowFrom.json
    • Account non predefinito: <channel>-<accountId>-allowFrom.json
Comportamento dell’ambito dell’account:
  • Gli account non predefiniti leggono/scrivono solo il rispettivo file allowlist con ambito.
  • L’account predefinito usa il file allowlist senza ambito specifico del canale.
Trattali come dati sensibili (controllano l’accesso al tuo assistente).
Lo store allowlist di abbinamento serve per l’accesso DM. L’autorizzazione dei gruppi è separata. L’approvazione di un codice di abbinamento DM non consente automaticamente a quel mittente di eseguire comandi di gruppo o controllare il bot nei gruppi. L’inizializzazione del primo proprietario è uno stato di configurazione separato in commands.ownerAllowFrom, e la consegna nelle chat di gruppo segue comunque le allowlist di gruppo del canale (ad esempio groupAllowFrom, groups, o override per gruppo o per argomento a seconda del canale).

​
2) Abbinamento dei dispositivi Node (nodi iOS/Android/macOS/headless)

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

​
Abbina tramite Telegram (consigliato per iOS)

Se usi il Plugin device-pair, puoi eseguire il primo abbinamento del dispositivo interamente da Telegram:
  1. In Telegram, invia un messaggio al tuo bot: /pair
  2. Il bot risponde con due messaggi: un messaggio di istruzioni e un messaggio separato con codice di configurazione (facile da copiare/incollare in Telegram).
  3. Sul telefono, apri l’app iOS OpenClaw → Impostazioni → Gateway.
  4. Scansiona il codice QR o incolla il codice di configurazione e connettiti.
  5. Di nuovo in Telegram: /pair pending (controlla 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 bootstrap a breve durata per singolo dispositivo usato per l’handshake di abbinamento iniziale
Quel token bootstrap include il profilo bootstrap di abbinamento integrato:
  • il token node principale trasferito resta scopes: []
  • qualsiasi token operator trasferito resta limitato alla allowlist bootstrap: operator.approvals, operator.read, operator.talk.secrets, operator.write
  • i controlli degli ambiti bootstrap sono prefissati dal ruolo, non un unico insieme piatto di ambiti: le voci di ambito operator soddisfano solo richieste operator, e i ruoli non operator devono comunque richiedere ambiti con il proprio prefisso di ruolo
  • la rotazione/revoca successiva dei token resta 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, abbinamento mobile pubblico o altro abbinamento mobile remoto, 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.

​
Approva 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 abbinato che approva è stata aperta con ambito solo di abbinamento, la CLI ritenta la stessa richiesta con operator.admin. Questo consente a un dispositivo abbinato esistente con capacità di amministrazione di recuperare un nuovo abbinamento Control UI/browser senza modificare devices/paired.json a mano. Il Gateway valida comunque la connessione ritentata; i token che non possono autenticarsi con operator.admin restano bloccati. Se lo stesso dispositivo ritenta con dettagli di autenticazione diversi (ad esempio ruolo/ambiti/chiave pubblica diversi), la richiesta in sospeso precedente viene sostituita e viene creato un nuovo requestId.
Un dispositivo già abbinato non ottiene silenziosamente un accesso più ampio. Se si riconnette chiedendo più ambiti o un ruolo più ampio, OpenClaw mantiene l’approvazione esistente così com’è e crea una nuova richiesta di upgrade in sospeso. Usa openclaw devices list per confrontare l’accesso attualmente approvato con il nuovo accesso richiesto prima di approvare.

​
Approvazione automatica opzionale dei Node tramite CIDR attendibili

L’abbinamento dei dispositivi resta manuale per impostazione predefinita. Per reti Node rigidamente controllate, puoi abilitare l’approvazione automatica al primo accesso dei Node con CIDR espliciti o IP esatti: 
{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}
Questo si applica solo alle nuove richieste di abbinamento role: node senza ambiti richiesti. Client operator, browser, Control UI e WebChat richiedono comunque l’approvazione manuale. Le modifiche a ruolo, ambito, metadati e chiave pubblica richiedono comunque l’approvazione manuale.

​
Archiviazione dello stato di abbinamento dei Node

Archiviato in ~/.openclaw/devices/:
  • pending.json (breve durata; le richieste in sospeso scadono)
  • paired.json (dispositivi abbinati + token)

​
Note

  • L’API legacy node.pair.* (CLI: openclaw nodes pending|approve|reject|remove|rename) è uno store di abbinamento separato di proprietà del gateway. I Node WS richiedono comunque l’abbinamento del dispositivo.
  • Il record di abbinamento è la fonte di verità durevole per i ruoli approvati. I token dispositivo attivi restano limitati a quell’insieme di ruoli approvati; una voce token isolata al di fuori dei ruoli approvati non crea nuovo accesso.

​
Documenti correlati