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
Al collegamento: «Config non letta dal gateway»	Collegamento incompleto o fatto prima del 10/09/2026	Ricollega dalla card Shelly in piattaforma: il salvataggio riscrive la configurazione nella forma giusta
Al collegamento: «Slack non ha accettato il messaggio di prova»	Link Slack sbagliato, o app rimossa dal canale	Fai ricreare l’Incoming Webhook allo studente (Avvisi offline) e ricollega
Lo studente non riceve gli avvisi offline	Dispositivo «non verificato» (chiave scaduta), non offline	Gli avvisi partono solo per gli offline veri: controlla la chiave Shelly dello studente e ricollega
Token non valido (errore 401)	Token scaduto o rigenerato in Shelly Cloud	Chiedi allo studente la nuova Auth Key da Shelly Cloud e ricollega dalla card Shelly in piattaforma
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 (ce n'è
più di uno). Fammi provare un'apertura reale e leggi l'esito; poi proponi il fix.

Shelly Cloud

Verifica device/account

Collegamento Shelly

Registro SHELLY_DEVICES