Configuration
Associazione
L'"abbinamento" è il passaggio esplicito di approvazione dell'accesso di OpenClaw. Viene usato in due punti:
- Abbinamento DM (chi è autorizzato a parlare con il bot)
- 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 telegramopenclaw 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
- Account predefinito:
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).
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:
- In Telegram, invia un messaggio al tuo bot:
/pair - Il bot risponde con due messaggi: un messaggio di istruzioni e un messaggio separato con codice di configurazione (facile da copiare/incollare in Telegram).
- Sul telefono, apri l'app iOS OpenClaw → Impostazioni → Gateway.
- Scansiona il codice QR o incolla il codice di configurazione e connettiti.
- 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://...owss://...)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
nodeprincipale trasferito restascopes: [] - qualsiasi token
operatortrasferito 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 listopenclaw 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.
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.