Synology Chat

​

Install

openclaw plugins install @openclaw/synology-chat

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

​

Quick setup

1. Install the plugin (above).
2. In Synology Chat integrations:
   • Create an incoming webhook and copy its URL.
   • Create an outgoing webhook with your secret token.
3. Point the outgoing webhook URL to your OpenClaw Gateway:
   • https://gateway-host/webhook/synology by default.
   • Or your custom channels.synology-chat.webhookPath.
   • Record that exact externally reachable HTTPS URL as channels.synology-chat.webhookUrl so the NAS can retrieve hosted attachments.
4. Finish setup in OpenClaw. Synology Chat appears in the same channel setup list in both flows:
   • Guided: openclaw onboard or openclaw channels add
   • Direct: openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url> --webhook-url <public-outgoing-webhook-url>
5. Restart the Gateway and send a DM to the Synology Chat bot.

• OpenClaw accepts the outgoing webhook token from body.token, then ?token=..., then headers.
• Accepted header forms:
  • x-synology-token
  • x-webhook-token
  • x-openclaw-token
  • Authorization: Bearer <token>
• Empty or missing tokens fail closed.
• Payloads may be application/x-www-form-urlencoded or application/json; token, user_id, and text are required.

​

Inbound durability

{
  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=...",
      webhookUrl: "https://gateway.example.com/webhook/synology",
      webhookPath: "/webhook/synology",
      dmPolicy: "allowlist",
      allowedUserIds: ["123456"],
      rateLimitPerMinute: 30,
      allowInsecureSsl: false,
    },
  },
}

​

Environment variables

• SYNOLOGY_CHAT_TOKEN
• SYNOLOGY_CHAT_INCOMING_URL
• SYNOLOGY_NAS_HOST
• SYNOLOGY_ALLOWED_USER_IDS (comma-separated)
• SYNOLOGY_RATE_LIMIT
• OPENCLAW_BOT_NAME

​

DM policy and access control

• Supported dmPolicy values: allowlist (default), open, and disabled. Synology Chat has no pairing flow; approve senders by adding their numeric Synology user IDs to allowedUserIds.
• allowedUserIds accepts a list (or comma-separated string) of Synology user IDs.
• In allowlist mode, an empty allowedUserIds list is treated as misconfiguration and the webhook route will not start.
• dmPolicy: "open" allows public DMs only when allowedUserIds includes "*"; with restrictive entries, only matching users can chat. open with an empty allowedUserIds list also refuses to start the route.
• dmPolicy: "disabled" blocks DMs.
• Reply recipient binding stays on stable numeric user_id by default. channels.synology-chat.dangerouslyAllowNameMatching: true is break-glass compatibility mode that re-enables mutable username/nickname lookup for reply delivery.

​

Outbound delivery

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

• webhookUrl is the exact externally reachable HTTPS callback configured in Synology Chat. OpenClaw uses its public origin, path, and existing query string when creating attachment capabilities.
• webhookPath is the internal Gateway route. A reverse proxy may map the public URL to this route, but should expose only this plugin path, not the general Gateway HTTP surface.
• incomingUrl points in the opposite direction: OpenClaw uses it to post replies to the NAS.

​

Multi-account

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

​

Security notes

• Keep token secret and rotate it if leaked.
• Keep allowInsecureSsl: false unless you explicitly trust a self-signed local NAS cert.
• Inbound webhook requests are token-verified and rate-limited per sender (rateLimitPerMinute, default 30).
• Invalid token checks use constant-time secret comparison and fail closed; repeated invalid-token attempts temporarily lock out the source IP.
• Inbound message text is sanitized against known prompt-injection patterns and truncated at 4000 characters.
• Prefer dmPolicy: "allowlist" for production.
• Keep dangerouslyAllowNameMatching off unless you explicitly need legacy username-based reply delivery.
• Keep dangerouslyAllowInheritedWebhookPath off unless you explicitly accept shared-path routing risk in a multi-account setup.
• Reverse-proxy access logs can capture attachment capability tokens. Disable query-string logging or redact __openclaw_synology_media_token_* parameters, and keep application logs free of full capability URLs.
• Hosted attachments use Content-Disposition: attachment, X-Content-Type-Options: nosniff, and Cache-Control: no-store. Files declared or named as HTML, SVG, or XML are rejected. Frozen bytes that begin as a UTF-8, UTF-16, or UTF-32 markup document after an optional encoding marker, whitespace, and comments are also rejected; literal tags later in passive text or source files do not make those files active documents.

​

Troubleshooting

• Missing required fields (token, user_id, text):
  • the outgoing webhook payload is missing one of the required fields
  • if Synology sends the token in headers, make sure the gateway/proxy preserves those headers
• Invalid token:
  • the outgoing webhook secret does not match channels.synology-chat.token
  • the request is hitting the wrong account/webhook path
  • a reverse proxy stripped the token header before the request reached OpenClaw
• Rate limit exceeded:
  • too many invalid token attempts from the same source can temporarily lock that source out
  • authenticated senders also have a separate per-user message rate limit
• Allowlist is empty. Configure allowedUserIds or use dmPolicy=open with allowedUserIds=["*"].:
  • dmPolicy="allowlist" is enabled but no users are configured
• User not authorized:
  • the sender’s numeric user_id is not in allowedUserIds
• Synology Chat attachments require webhookUrl:
  • set the account’s exact externally reachable HTTPS outgoing-webhook callback URL
  • confirm the reverse proxy maps only that public route to webhookPath
  • text and inbound messaging remain available while attachment setup is incomplete

​

Related

• Channels Overview — all supported channels
• Groups — group chat behavior and mention gating
• Channel Routing — session routing for messages
• Security — access model and hardening