Synology Chat

Status: bundled plugin direct-message channel using Synology Chat webhooks. The plugin accepts inbound messages from Synology Chat outgoing webhooks and sends replies through a Synology Chat incoming webhook.

Bundled plugin

Synology Chat ships as a bundled plugin in current OpenClaw releases, so normal packaged builds do not need a separate install.

If you are on an older build or a custom install that excludes Synology Chat, install it manually:

Install from a local checkout:

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

Details: Plugins

Quick setup

1. Ensure the Synology Chat plugin is available.
   • Current packaged OpenClaw releases already bundle it.
   • Older/custom installs can add it manually from a source checkout with the command above.
   • text

     Copy

     openclaw onboard
     now shows Synology Chat in the same channel setup list as
     text

     Copy

     openclaw channels add
     .
   • Non-interactive setup:
     text

     Copy

     openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>
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:
   • text

     Copy

     https://gateway-host/webhook/synology
     by default.
   • Or your custom
     text

     Copy

     channels.synology-chat.webhookPath
     .
4. Finish setup in OpenClaw.
   • Guided:
     text

     Copy

     openclaw onboard
   • Direct:
     text

     Copy

     openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>
5. Restart gateway and send a DM to the Synology Chat bot.

Webhook auth details:

• OpenClaw accepts the outgoing webhook token from
  text

  Copy

  body.token
  , then
  text

  Copy

  ?token=...
  , then headers.
• Accepted header forms:
  • text

    Copy

    x-synology-token
  • text

    Copy

    x-webhook-token
  • text

    Copy

    x-openclaw-token
  • text

    Copy

    Authorization: Bearer <token>
• Empty or missing tokens fail closed.

Minimal config:

json5
Copy
{
  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,
    },
  },
}

Environment variables

For the default account, you can use env vars:

• text

  Copy

  SYNOLOGY_CHAT_TOKEN
• text

  Copy

  SYNOLOGY_CHAT_INCOMING_URL
• text

  Copy

  SYNOLOGY_NAS_HOST
• text

  Copy

  SYNOLOGY_ALLOWED_USER_IDS
  (comma-separated)
• text

  Copy

  SYNOLOGY_RATE_LIMIT
• text

  Copy

  OPENCLAW_BOT_NAME

Config values override env vars.

cannot be set from a workspace ; see Workspace

text

Copy

.env

files.

DM policy and access control

• text

  Copy

  dmPolicy: "allowlist"
  is the recommended default.
• text

  Copy

  allowedUserIds
  accepts a list (or comma-separated string) of Synology user IDs.
• In
  text

  Copy

  allowlist
  mode, an empty
  text

  Copy

  allowedUserIds
  list is treated as misconfiguration and the webhook route will not start (use
  text

  Copy

  dmPolicy: "open"
  with
  text

  Copy

  allowedUserIds: ["*"]
  for allow-all).
• text

  Copy

  dmPolicy: "open"
  allows public DMs only when
  text

  Copy

  allowedUserIds
  includes
  text

  Copy

  "*"
  ; with restrictive entries, only matching users can chat.
• text

  Copy

  dmPolicy: "disabled"
  blocks DMs.
• Reply recipient binding stays on stable numeric
  text

  Copy

  user_id
  by default.
  text

  Copy

  channels.synology-chat.dangerouslyAllowNameMatching: true
  is break-glass compatibility mode that re-enables mutable username/nickname lookup for reply delivery.
• Pairing approvals work with:
  • text

    Copy

    openclaw pairing list synology-chat
  • text

    Copy

    openclaw pairing approve synology-chat <CODE>

Outbound delivery

Use numeric Synology Chat user IDs as targets.

Examples:

bash
Copy
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"

Media sends are supported by URL-based file delivery. Outbound file URLs must use

or , and private or otherwise blocked network targets are rejected before OpenClaw forwards the URL to the NAS webhook.

Multi-account

Multiple Synology Chat accounts are supported under

. Each account can override token, incoming URL, webhook path, DM policy, and limits. Direct-message sessions are isolated per account and user, so the same numeric on two different Synology accounts does not share transcript state. Give each enabled account a distinct . OpenClaw now rejects duplicate exact paths and refuses to start named accounts that only inherit a shared webhook path in multi-account setups. If you intentionally need legacy inheritance for a named account, set on that account or at , but duplicate exact paths are still rejected fail-closed. Prefer explicit per-account paths.

json5
Copy
{
  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"],
        },
      },
    },
  },
}

Security notes

• Keep
  text

  Copy

  token
  secret and rotate it if leaked.
• Keep
  text

  Copy

  allowInsecureSsl: false
  unless you explicitly trust a self-signed local NAS cert.
• Inbound webhook requests are token-verified and rate-limited per sender.
• Invalid token checks use constant-time secret comparison and fail closed.
• Prefer
  text

  Copy

  dmPolicy: "allowlist"
  for production.
• Keep
  text

  Copy

  dangerouslyAllowNameMatching
  off unless you explicitly need legacy username-based reply delivery.
• Keep
  text

  Copy

  dangerouslyAllowInheritedWebhookPath
  off unless you explicitly accept shared-path routing risk in a multi-account setup.

Troubleshooting

• text

  Copy

  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
• text

  Copy

  Invalid token
  :
  • the outgoing webhook secret does not match
    text

    Copy

    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
• text

  Copy

  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
• text

  Copy

  Allowlist is empty. Configure allowedUserIds or use dmPolicy=open with allowedUserIds=["*"].
  :
  • text

    Copy

    dmPolicy="allowlist"
    is enabled but no users are configured
• text

  Copy

  User not authorized
  :
  • the sender's numeric
    text

    Copy

    user_id
    is not in
    text

    Copy

    allowedUserIds

Related

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