Troubleshooting Shelly: relay offline e apertura fallita - Mattone Docs

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

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.

▷ Prompt Claude Code: Debug Shelly · incolla in Claude Code:

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.

Shelly Cloud

Verifica device/account

Collegamento Shelly

Registro SHELLY_DEVICES

⌘I