Vai al contenuto principale

​
Pairing

Il “pairing” è il passaggio esplicito di approvazione del proprietario di OpenClaw. Viene usato in due punti:
  1. DM pairing (chi è autorizzato a parlare con il bot)
  2. Node pairing (quali dispositivi/nodi sono autorizzati a unirsi alla rete del gateway)
Contesto di sicurezza: Security

​
1) DM pairing (accesso alla 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 approvi. Le policy DM predefinite sono documentate in: Security Codici di pairing:
  • 8 caratteri, maiuscoli, senza caratteri ambigui (0O1I).
  • Scadono dopo 1 ora. Il bot invia il messaggio di pairing solo quando viene creata una nuova richiesta (all’incirca una volta all’ora per mittente).
  • Le richieste di DM pairing in sospeso sono limitate per impostazione predefinita a 3 per canale; le richieste aggiuntive vengono ignorate finché una non scade o non viene approvata.

​
Approvare un mittente

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
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.

​
Dove si trova lo stato

Memorizzato in ~/.openclaw/credentials/:
  • Richieste in sospeso: <channel>-pairing.json
  • Archivio allowlist approvata:
    • 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 allowlist con ambito.
  • L’account predefinito usa il file allowlist senza ambito, con ambito del canale.
Tratta questi file come sensibili (controllano l’accesso al tuo assistente). Importante: questo archivio serve per l’accesso DM. L’autorizzazione dei gruppi è separata. Approvare un codice di DM pairing non consente automaticamente a quel mittente di eseguire comandi di gruppo o controllare il bot nei gruppi. Per l’accesso ai gruppi, configura le allowlist esplicite del canale per i gruppi (ad esempio groupAllowFrom, groups o override per gruppo/per argomento a seconda del canale).

​
2) Pairing del dispositivo nodo (nodi iOS/Android/macOS/headless)

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

​
Pairing tramite Telegram (consigliato per iOS)

Se usi il plugin device-pair, puoi eseguire il primo pairing del dispositivo interamente da Telegram:
  1. In Telegram, invia al tuo bot: /pair
  2. 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).
  3. Sul telefono, apri l’app iOS di OpenClaw → Impostazioni → Gateway.
  4. Incolla il codice di configurazione e connettiti.
  5. Tornato in Telegram: /pair pending (rivedi ID richiesta, ruolo e scope), quindi approva.
Il codice di configurazione è un payload JSON codificato in base64 che contiene:
  • url: l’URL WebSocket del Gateway (ws://... oppure wss://...)
  • bootstrapToken: un bootstrap token a breve durata, per un solo dispositivo, usato per l’handshake iniziale di pairing
Quel bootstrap token contiene il profilo bootstrap di pairing integrato:
  • il token node primario trasferito resta scopes: []
  • qualsiasi token operator trasferito resta vincolato all’allowlist bootstrap: operator.approvals, operator.read, operator.talk.secrets, operator.write
  • i controlli degli scope bootstrap usano prefissi di ruolo, non un unico pool di scope: le voci di scope operator soddisfano solo richieste operator, e i ruoli non operator devono comunque richiedere scope sotto il proprio prefisso di ruolo
Tratta il codice di configurazione come una password finché è valido.

​
Approvare un dispositivo nodo

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
Se lo stesso dispositivo ritenta con dettagli di autenticazione diversi (ad esempio ruolo/scope/chiave pubblica diversi), la precedente richiesta in sospeso viene sostituita e viene creato un nuovo requestId.

​
Archiviazione dello stato di pairing del nodo

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

​
Note

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

​
Documenti correlati