Connecting OpenClaw AI Agents to Synology Chat - Setup and Configuration Guide

Not every organisation runs Slack or Teams. Plenty of Australian businesses - particularly those in manufacturing, logistics, and professional services - run Synology NAS devices and use Synology Chat as their internal messaging platform. It's self-hosted, it's private, and it doesn't require a per-user subscription to a cloud provider.

If you're running OpenClaw for AI agent workflows and your team communicates through Synology Chat, the good news is that there's a bundled plugin that connects the two. Your AI agents can receive direct messages from users in Synology Chat and respond through the same channel, creating a natural conversational interface without forcing anyone to switch tools.

At Team 400, we work with organisations deploying AI agents across various internal platforms, and Synology Chat is more common than you might think. Here's how the integration works and what to watch out for during setup.

How the integration works

The OpenClaw Synology Chat plugin uses a webhook-based architecture. Two webhooks connect the systems:

Outgoing webhook (Synology to OpenClaw): When a user sends a DM to the bot in Synology Chat, Synology fires an outgoing webhook to your OpenClaw gateway. This webhook includes the user's message, their user ID, and a secret token for authentication.

Incoming webhook (OpenClaw to Synology): When OpenClaw's AI agent generates a response, it sends it back to Synology Chat through an incoming webhook URL. The response appears as a message from the bot in the user's DM conversation.

It's a simple request-response loop: user sends message, webhook fires, OpenClaw processes it, response goes back through the incoming webhook. No persistent connections, no WebSocket complexity, no middleware.

Setting it up

The plugin ships bundled with current OpenClaw releases, so there's nothing extra to install. If you're on an older build, you can install it manually from a local checkout:

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

The setup process has two sides - Synology Chat configuration and OpenClaw configuration.

Synology Chat side

In your Synology Chat admin panel, create two webhook integrations:

1. Incoming webhook - this gives you a URL that OpenClaw will use to send messages. Copy this URL; you'll need it for the OpenClaw config.
2. Outgoing webhook - this fires when users send messages. Set a secret token (make it strong and random). Point the URL to your OpenClaw gateway endpoint, which defaults to https://gateway-host/webhook/synology.

OpenClaw side

You can configure through the guided setup (openclaw onboard) or directly via the CLI:

openclaw channels add --channel synology-chat --token <your-outgoing-token> --url <incoming-webhook-url>

The minimal JSON configuration looks like this:

{
  "channels": {
    "synology-chat": {
      "enabled": true,
      "token": "your-outgoing-webhook-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
    }
  }
}

Restart the gateway and test by sending a DM to the bot in Synology Chat.

Token authentication - what happens under the hood

When Synology sends an outgoing webhook, OpenClaw looks for the authentication token in several places, in this order:

1. body.token in the POST payload
2. ?token=... as a query parameter
3. Request headers: x-synology-token, x-webhook-token, x-openclaw-token, or Authorization: Bearer <token>

If the token is missing or doesn't match, the request is rejected. No fallback, no anonymous access. Token verification uses constant-time comparison to prevent timing attacks, which is a small detail but shows the integration takes security seriously.

One gotcha I've seen in practice: if you're running a reverse proxy (nginx, Traefik, Caddy) in front of your OpenClaw gateway, make sure it passes through the authentication headers. Some proxy configurations strip non-standard headers by default. If your outgoing webhook sends the token in the x-synology-token header and your proxy drops it, every request will fail with "Invalid token" and you'll spend an hour wondering why.

DM policies and access control

This is where the configuration matters most for production deployments. OpenClaw supports three DM policies:

allowlist (recommended for production): Only users whose numeric Synology user IDs are listed in allowedUserIds can interact with the bot. Everyone else is silently rejected. If you set dmPolicy: "allowlist" but leave allowedUserIds empty, OpenClaw treats this as a misconfiguration and refuses to start the webhook route entirely. This is a good safety default - it prevents accidentally deploying an open bot because someone forgot to populate the user list.

open: Any Synology Chat user can message the bot. Fine for testing, but think carefully before using this in production. Depending on what your AI agents can access and do, you probably want to control who can interact with them.

disabled: Blocks all DMs. Useful if you're temporarily taking the channel offline without removing the configuration.

For managing user access, OpenClaw has a pairing system:

openclaw pairing list synology-chat
openclaw pairing approve synology-chat <CODE>

This gives you a more controlled onboarding flow than just adding user IDs to a config file.

Multi-account setups

If your organisation runs multiple Synology NAS devices - or wants separate bot personas for different purposes - OpenClaw supports multiple Synology Chat accounts under the same plugin.

Each account gets its own token, incoming URL, webhook path, DM policy, and rate limits. Sessions are isolated per account and user, so the same user interacting with two different bot accounts maintains separate conversation histories.

The key rule: every enabled account must have a distinct webhookPath. OpenClaw rejects duplicate paths and won't start accounts that share a webhook path in multi-account configurations. This prevents the ambiguity of "which account should handle this incoming request?"

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

A practical use case: one account handles general Q&A through an AI assistant, while another account is dedicated to alerting - sending notifications about system events, build failures, or data pipeline issues to specific users.

Security considerations

A few things worth highlighting for production deployments:

Keep allowInsecureSsl: false. The only reason to enable insecure SSL is if your NAS uses a self-signed certificate and you can't or won't set up proper certificates. If that's your situation, at least restrict the webhook to your internal network.

Rate limiting is built in. Both invalid token attempts and authenticated messages are rate-limited per sender. This prevents abuse if someone discovers your webhook endpoint and tries to flood it.

Avoid dangerouslyAllowNameMatching. By default, OpenClaw binds reply delivery to stable numeric user IDs. There's a break-glass option to use username/nickname matching instead, but usernames are mutable - if someone changes their display name, messages could go to the wrong person. Keep this off unless you have a specific legacy reason to enable it.

Rotate tokens if compromised. If your outgoing webhook token leaks, anyone who knows your gateway URL can send messages as if they were a Synology Chat user. Generate a new token in Synology Chat, update the OpenClaw config, and restart.

Troubleshooting the common issues

The most frequent problems we see during setup:

• "Missing required fields" - the outgoing webhook payload is incomplete. Check that Synology is sending token, user_id, and text in the request body. If your gateway sits behind a proxy, verify the proxy isn't mangling the request body.
• "Invalid token" - the token in the request doesn't match your config. Double-check for trailing whitespace, and make sure the request is hitting the correct account's webhook path.
• "User not authorized" - the sender's numeric user ID isn't in your allowlist. Find their user ID in Synology Chat admin and add it to allowedUserIds.

Why self-hosted chat matters for AI agents

There's a broader point here worth making. Organisations that choose self-hosted platforms like Synology Chat often do so because they want to keep communications on their own infrastructure. When you add AI agents to the mix, that data sovereignty question becomes even more important. Where do the agent conversations get processed? What data is the agent accessing?

OpenClaw's architecture keeps the message routing local - it's running on your gateway, not a third-party cloud service. The AI processing itself depends on which model backend you've configured, but the messaging layer stays on your infrastructure.

For more on deploying AI agents across your organisation's existing communication platforms, the OpenClaw documentation covers the full channel setup. And if you need help designing an agent architecture that works with your existing tools - whether that's Synology Chat, Teams, Slack, or something else - our team can help you plan and build it.