> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattone.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Shelly: relay offline e apertura fallita

> Diagnosi e risoluzione dei problemi più comuni nell'integrazione Shelly: device offline, token scaduto, canale relay errato e apertura mancata.

Usa questa guida per diagnosticare i problemi dell'integrazione Shelly, la maggior parte dei casi riguarda un device offline o un token Shelly Cloud scaduto o non valido. Prima di qualsiasi modifica alla configurazione, controlla sempre i log della piattaforma per identificare il codice di errore esatto.

## Tabella sintomi, cause e soluzioni

| Sintomo                                  | Causa probabile                                            | Soluzione                                                                                                          |
| ---------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Device offline nel pannello Mattone      | WiFi intermittente o device senza corrente                 | Verifica la connessione WiFi dell'immobile; controlla che il device Shelly sia alimentato correttamente            |
| Token non valido (errore 401)            | Token scaduto o rigenerato in Shelly Cloud                 | Chiedi allo studente di rigenerare il token in Shelly Cloud; aggiorna il token nel Vault                           |
| Apertura non funziona ma device è online | Relay configurato sul canale sbagliato                     | Verifica quale canale (CH1 o CH2) controlla fisicamente la porta; aggiorna la configurazione in piattaforma        |
| Link di apertura non arriva all'ospite   | Tool `get-access-link` mancante o skill assente in Conduit | Verifica che il tool `get-access-link` sia attivo e che la skill di check-in sia configurata nel workspace Conduit |
| Apertura ritardata (oltre 3 secondi)     | Cloud Shelly lento o rete locale congestionata             | Verifica la latenza del cloud Shelly; testa l'apertura in orari diversi per escludere picchi di traffico           |

<Tip>
  Per verificare lo stato del device senza aprire l'app Shelly Cloud, usa il tool `check-device-status` da Conduit, restituisce lo stato del device in tempo reale con il codice risposta esatto, permettendoti di distinguere subito tra device offline e token non valido.
</Tip>

<Tip>
  **▷ Prompt Claude Code: Debug Shelly**  ·  incolla in Claude Code:
</Tip>

```text theme={null}
Contesto: in questa sessione di Claude Code NON hai il repo/codice caricato.
Per prima cosa apri il repo di check-in giusto, `~/Projects/cosmica-booking`
(baseline: `src/lib/shelly.ts`, SHELLY_DEVICES) o il repo di check-in dello
studente, e LEGGI le pagine mattone-docs /troubleshooting/metodo e
/integrazioni/shelly/troubleshooting. Poi procedi:

Applica il metodo di mattone-docs /troubleshooting/metodo a questo problema
Shelly: [DESCRIVI IL SINTOMO, es. "device offline" / "online ma non apre" per
lo slug [SLUG]]. Leggi lo stato reale (POST /device/status) prima di concludere.
Isola: alimentazione/WiFi 2.4GHz caduto, oppure account/deviceId errato in
SHELLY_DEVICES rispetto a Shelly Cloud, oppure account sbagliato (cosmica vs
verdi). Fammi provare un'apertura reale e leggi l'esito; poi proponi il fix.
```

<CardGroup cols={2}>
  <Card title="Shelly Cloud" icon="arrow-up-right-from-square" href="https://control.shelly.cloud">Verifica device/account</Card>
  <Card title="Collegamento Shelly" icon="arrow-up-right-from-square" href="/integrazioni/shelly/collegamento">Registro SHELLY\_DEVICES</Card>
</CardGroup>