快速开始

Synology Chat

Status：使用 Synology Chat webhook 的内置插件私信渠道。该插件接收来自 Synology Chat 外发 webhook 的入站消息，并通过 Synology Chat 传入 webhook 发送回复。

内置插件

Synology Chat 在当前 OpenClaw 版本中作为内置插件随附，因此常规打包版本不需要单独安装。

如果你使用的是较旧版本，或排除了 Synology Chat 的自定义安装，请手动安装：

从本地 checkout 安装：

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

详情：插件

快速设置

确保 Synology Chat 插件可用。
- 当前打包的 OpenClaw 版本已经内置它。
- 较旧/自定义安装可以使用上面的命令从源码 checkout 手动添加它。
- openclaw onboard 现在会在与 openclaw channels add 相同的渠道设置列表中显示 Synology Chat。
- 非交互式设置：openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>
在 Synology Chat 集成中：
- 创建一个传入 webhook，并复制其 URL。
- 使用你的 secret token 创建一个外发 webhook。
将外发 webhook URL 指向你的 OpenClaw Gateway 网关：
- 默认是 https://gateway-host/webhook/synology。
- 或使用你的自定义 channels.synology-chat.webhookPath。
在 OpenClaw 中完成设置。
- 引导式：openclaw onboard
- 直接：openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>
重启 Gateway 网关，并向 Synology Chat 机器人发送一条私信。

Webhook 认证详情：

OpenClaw 先从 body.token 接受外发 webhook token，然后是 ?token=...，最后是 headers。
接受的 header 形式：
- x-synology-token
- x-webhook-token
- x-openclaw-token
- Authorization: Bearer <token>
空 token 或缺失 token 会失败并关闭访问。

最小配置：

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

环境变量

对于默认账号，你可以使用环境变量：

SYNOLOGY_CHAT_TOKEN
SYNOLOGY_CHAT_INCOMING_URL
SYNOLOGY_NAS_HOST
SYNOLOGY_ALLOWED_USER_IDS（逗号分隔）
SYNOLOGY_RATE_LIMIT
OPENCLAW_BOT_NAME

配置值会覆盖环境变量。

SYNOLOGY_CHAT_INCOMING_URL 不能从工作区 .env 设置；请参阅工作区 .env 文件。

私信策略和访问控制

dmPolicy: "allowlist" 是推荐默认值。
allowedUserIds 接受 Synology 用户 ID 列表（或逗号分隔字符串）。
在 allowlist 模式下，空的 allowedUserIds 列表会被视为配置错误，并且 webhook 路由不会启动（若要允许所有人，请使用 dmPolicy: "open" 搭配 allowedUserIds: ["*"]）。
dmPolicy: "open" 只有在 allowedUserIds 包含 "*" 时才允许公开私信；如果有受限条目，只有匹配用户可以聊天。
dmPolicy: "disabled" 会阻止私信。
回复收件人绑定默认保持在稳定的数字 user_id 上。channels.synology-chat.dangerouslyAllowNameMatching: true 是破窗兼容模式，会重新启用可变用户名/昵称查找来投递回复。
配对批准可使用：
- openclaw pairing list synology-chat
- openclaw pairing approve synology-chat <CODE>

出站投递

使用数字 Synology Chat 用户 ID 作为目标。

示例：

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"

支持通过基于 URL 的文件投递发送媒体。出站文件 URL 必须使用 http 或 https，并且私有或其他被阻止的网络目标会在 OpenClaw 将 URL 转发到 NAS webhook 之前被拒绝。

多账号

channels.synology-chat.accounts 下支持多个 Synology Chat 账号。每个账号都可以覆盖 token、传入 URL、webhook 路径、私信策略和限制。私信会话按账号和用户隔离，因此两个不同 Synology 账号上的相同数字 user_id 不会共享对话记录状态。为每个启用的账号提供不同的 webhookPath。OpenClaw 现在会拒绝重复的精确路径，并且在多账号设置中，会拒绝启动仅继承共享 webhook 路径的命名账号。如果你确实需要为某个命名账号使用旧版继承，请在该账号或 channels.synology-chat 上设置 dangerouslyAllowInheritedWebhookPath: true，但重复的精确路径仍会失败并关闭访问。优先使用显式的逐账号路径。

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

安全说明

保持 token 机密；如果泄露，请轮换它。
除非你明确信任自签名本地 NAS 证书，否则保持 allowInsecureSsl: false。
入站 webhook 请求会经过 token 验证，并按发送者限速。
无效 token 检查使用常量时间 secret 比较，并会失败并关闭访问。
生产环境优先使用 dmPolicy: "allowlist"。
除非你明确需要旧版基于用户名的回复投递，否则保持 dangerouslyAllowNameMatching 关闭。
除非你明确接受多账号设置中的共享路径路由风险，否则保持 dangerouslyAllowInheritedWebhookPath 关闭。

故障排除

Missing required fields (token, user_id, text)：
- 外发 webhook payload 缺少某个必需字段
- 如果 Synology 在 headers 中发送 token，请确保 Gateway 网关/代理保留这些 headers
Invalid token：
- 外发 webhook secret 与 channels.synology-chat.token 不匹配
- 请求命中了错误的账号/webhook 路径
- 反向代理在请求到达 OpenClaw 之前剥离了 token header
Rate limit exceeded：
- 来自同一来源的过多无效 token 尝试可能会暂时锁定该来源
- 已认证发送者也有单独的按用户消息限速
Allowlist is empty. Configure allowedUserIds or use dmPolicy=open with allowedUserIds=["*"].：
- dmPolicy="allowlist" 已启用，但未配置任何用户
User not authorized：
- 发送者的数字 user_id 不在 allowedUserIds 中

Synology Chat

内置插件

快速设置

环境变量

私信策略和访问控制

出站投递

多账号

安全说明

故障排除

相关内容

Ask OpenClaw

# 内置插件

# 快速设置

# 环境变量

# 私信策略和访问控制

# 出站投递

# 多账号

# 安全说明

# 故障排除

# 相关内容

内置插件

快速设置

环境变量

私信策略和访问控制

出站投递

多账号

安全说明

故障排除

相关内容