Synology Chat

​

Plugin in bundle

openclaw plugins install ./path/to/local/synology-chat-plugin

​

Configurazione rapida

1. Assicurati che il Plugin Synology Chat sia disponibile.
   • Le versioni pacchettizzate correnti di OpenClaw lo includono già.
   • Le installazioni precedenti/personalizzate possono aggiungerlo manualmente da un checkout del sorgente con il comando sopra.
   • openclaw onboard ora mostra Synology Chat nello stesso elenco di configurazione dei canali di openclaw channels add.
   • Configurazione non interattiva: openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>
2. Nelle integrazioni di Synology Chat:
   • Crea un Webhook in ingresso e copiane l’URL.
   • Crea un Webhook in uscita con il tuo token segreto.
3. Punta l’URL del Webhook in uscita al tuo Gateway OpenClaw:
   • https://gateway-host/webhook/synology per impostazione predefinita.
   • Oppure il tuo channels.synology-chat.webhookPath personalizzato.
4. Completa la configurazione in OpenClaw.
   • Guidata: openclaw onboard
   • Diretta: openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>
5. Riavvia il Gateway e invia un messaggio diretto al bot Synology Chat.

• OpenClaw accetta il token del Webhook in uscita da body.token, poi da ?token=..., poi dagli header.
• Forme di header accettate:
  • x-synology-token
  • x-webhook-token
  • x-openclaw-token
  • Authorization: Bearer <token>
• I token vuoti o mancanti falliscono in modo chiuso.

{
  channels: {
    "synology-chat": {
      enabled: true,
      token: "synology-outgoing-token",
      incomingUrl: "https://nas.example.com/webapi/entry.cgi?api=SYNO.Chat.External&method=incoming&version=2&token=...",
      webhookPath: "/webhook/synology",
      dmPolicy: "allowlist",
      allowedUserIds: ["123456"],
      rateLimitPerMinute: 30,
      allowInsecureSsl: false,
    },
  },
}

​

Variabili d’ambiente

• SYNOLOGY_CHAT_TOKEN
• SYNOLOGY_CHAT_INCOMING_URL
• SYNOLOGY_NAS_HOST
• SYNOLOGY_ALLOWED_USER_IDS (separati da virgole)
• SYNOLOGY_RATE_LIMIT
• OPENCLAW_BOT_NAME

​

Criterio DM e controllo degli accessi

• dmPolicy: "allowlist" è l’impostazione predefinita consigliata.
• allowedUserIds accetta un elenco (o una stringa separata da virgole) di ID utente Synology.
• In modalità allowlist, un elenco allowedUserIds vuoto viene trattato come configurazione errata e la rotta del Webhook non si avvierà (usa dmPolicy: "open" con allowedUserIds: ["*"] per consentire tutto).
• dmPolicy: "open" consente messaggi diretti pubblici solo quando allowedUserIds include "*"; con voci restrittive, solo gli utenti corrispondenti possono chattare.
• dmPolicy: "disabled" blocca i messaggi diretti.
• Il binding del destinatario della risposta resta basato per impostazione predefinita sul valore numerico stabile user_id. channels.synology-chat.dangerouslyAllowNameMatching: true è una modalità di compatibilità di emergenza che riabilita la ricerca tramite nome utente/nickname mutabili per la consegna delle risposte.
• Le approvazioni di associazione funzionano con:
  • openclaw pairing list synology-chat
  • openclaw pairing approve synology-chat <CODE>

​

Consegna in uscita

openclaw message send --channel synology-chat --target 123456 --text "Hello from OpenClaw"
openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again"
openclaw message send --channel synology-chat --target synology:123456 --text "Short prefix"

​

Account multipli

{
  channels: {
    "synology-chat": {
      enabled: true,
      accounts: {
        default: {
          token: "token-a",
          incomingUrl: "https://nas-a.example.com/...token=...",
        },
        alerts: {
          token: "token-b",
          incomingUrl: "https://nas-b.example.com/...token=...",
          webhookPath: "/webhook/synology-alerts",
          dmPolicy: "allowlist",
          allowedUserIds: ["987654"],
        },
      },
    },
  },
}

​

Note di sicurezza

• Mantieni segreto token e ruotalo se viene divulgato.
• Mantieni allowInsecureSsl: false salvo che tu consideri esplicitamente attendibile un certificato NAS locale autofirmato.
• Le richieste Webhook in ingresso sono verificate tramite token e soggette a limite di frequenza per mittente.
• I controlli dei token non validi usano un confronto dei segreti a tempo costante e falliscono in modo chiuso.
• Preferisci dmPolicy: "allowlist" per la produzione.
• Mantieni dangerouslyAllowNameMatching disattivato salvo che tu abbia esplicitamente bisogno della consegna delle risposte legacy basata su nome utente.
• Mantieni dangerouslyAllowInheritedWebhookPath disattivato salvo che tu accetti esplicitamente il rischio di routing con percorso condiviso in una configurazione multi-account.

​

Risoluzione dei problemi

• Missing required fields (token, user_id, text):
  • nel payload del Webhook in uscita manca uno dei campi obbligatori
  • se Synology invia il token negli header, assicurati che il Gateway/proxy conservi quegli header
• Invalid token:
  • il segreto del Webhook in uscita non corrisponde a channels.synology-chat.token
  • la richiesta sta raggiungendo l’account/percorso Webhook sbagliato
  • un reverse proxy ha rimosso l’header del token prima che la richiesta raggiungesse OpenClaw
• Rate limit exceeded:
  • troppi tentativi con token non valido dalla stessa origine possono bloccare temporaneamente quell’origine
  • i mittenti autenticati hanno anche un limite di frequenza dei messaggi separato per utente
• Allowlist is empty. Configure allowedUserIds or use dmPolicy=open with allowedUserIds=["*"].:
  • dmPolicy="allowlist" è abilitato ma non sono configurati utenti
• User not authorized:
  • il valore numerico user_id del mittente non è in allowedUserIds

​

Correlati

• Panoramica dei canali — tutti i canali supportati
• Associazione — autenticazione DM e flusso di associazione
• Gruppi — comportamento delle chat di gruppo e gating delle menzioni
• Routing dei canali — routing delle sessioni per i messaggi
• Sicurezza — modello di accesso e hardening