English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Configuration

Associazione

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

  1. Associazione DM (chi è autorizzato a parlare con il bot)
  2. Associazione Node (quali dispositivi/nodi sono autorizzati a unirsi alla rete Gateway)

Contesto di sicurezza: Sicurezza

1) Associazione DM (accesso chat in ingresso)

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

I criteri DM predefiniti sono documentati in: Sicurezza

dmPolicy: "open" è pubblico solo quando la lista consentiti DM effettiva include "*". Configurazione e convalida richiedono quel carattere jolly per le configurazioni public-open. Se lo stato esistente contiene open con voci allowFrom concrete, il runtime ammette comunque 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

bash
openclaw pairing list telegramopenclaw pairing approve telegram <CODE>

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 le richieste di approvazione exec. Dopo che esiste un proprietario, le approvazioni di associazione 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 liste consentiti DM sia a quelle dei gruppi.

I gruppi statici usano type: "message.senders" e sono referenziati con accessGroup:<name> dalle liste consentiti dei canali:

json5
{  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 in ~/.openclaw/credentials/:

  • Richieste in sospeso: <channel>-pairing.json
  • Archivio lista consentiti approvata:
    • 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 proprio file di lista consentiti con ambito.
  • L'account predefinito usa il file di lista consentiti senza ambito a livello di canale.

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

2) Associazione 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 associazione del dispositivo che deve essere approvata.

Associare dalla Control UI (consigliato)

Usa una sessione Control UI già connessa con accesso operator.admin:

  1. Apri la Control UI e seleziona Nodi.
  2. In Dispositivi, fai clic su Associa dispositivo mobile.
  3. Sul telefono, apri l'app OpenClaw → Impostazioni → Gateway.
  4. Scansiona il codice QR o incolla il codice di configurazione, quindi connettiti.

Le app ufficiali OpenClaw per iOS e Android vengono approvate automaticamente quando i loro metadati del codice di configurazione corrispondono. Se Dispositivi mostra una richiesta in sospeso (ad esempio per un client non ufficiale o metadati non corrispondenti), controlla il ruolo e gli ambiti prima di approvarla.

Il pulsante è disabilitato quando la sessione Control UI corrente non ha accesso amministratore. In quel caso usa il flusso di approvazione CLI qui sotto dall'host Gateway.

Associare tramite Telegram

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

  1. In Telegram, invia al 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 OpenClaw per iOS → Impostazioni → Gateway.
  4. Scansiona il codice QR oppure incolla il codice di configurazione e connettiti.
  5. L'app mobile ufficiale si connette automaticamente. Se /pair pending mostra una richiesta, controlla il ruolo e gli ambiti prima di approvarla.

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 un singolo dispositivo usato per l'handshake di associazione iniziale

Quel token bootstrap contiene il profilo bootstrap di associazione integrato:

  • il profilo di configurazione integrato consente solo la baseline QR/codice di configurazione nuova: node più un passaggio operator limitato
  • il token node passato resta scopes: []
  • il token operator passato è limitato a operator.approvals, operator.read, operator.talk.secrets e operator.write
  • operator.admin non viene concesso dal bootstrap QR/codice di configurazione; richiede un flusso separato di associazione o token operatore approvato
  • la successiva rotazione/revoca dei token resta limitata sia dal contratto di ruolo approvato del dispositivo sia dagli ambiti operatore della sessione chiamante

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

Per Tailscale, pubblico o altre associazioni mobili remote, usa Tailscale Serve/Funnel o un altro URL Gateway wss://. I codici di configurazione ws:// in chiaro sono accettati solo per local 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

bash
openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>

Quando un'approvazione esplicita viene negata perché la sessione del dispositivo associato che approva è stata aperta con ambito solo di associazione, la CLI ritenta la stessa richiesta con operator.admin. Questo consente a un dispositivo associato esistente con capacità di amministratore di recuperare una nuova associazione Control UI/browser senza modificare devices/paired.json a mano. Il Gateway convalida 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 con CIDR attendibile

L'associazione dei dispositivi resta manuale per impostazione predefinita. Per reti Node strettamente controllate, puoi scegliere di abilitare l'approvazione automatica dei Node alla prima connessione con CIDR espliciti o IP esatti:

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

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

Archiviazione dello stato di associazione dei Node

Archiviato in ~/.openclaw/devices/:

  • pending.json (a 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 Node WS richiedono comunque l'associazione dei dispositivi.
  • Il record di associazione è la fonte di verità persistente per i ruoli approvati. I token dei dispositivi attivi restano limitati a quell'insieme di ruoli approvati; una voce token isolata al di fuori dei ruoli approvati non crea nuovo accesso.

Documentazione correlata

Was this useful?
On this page

On this page