Synology Chat

状态：内置插件，通过 Synology Chat webhook 实现私信渠道。插件接收来自 Synology Chat 出站 webhook 的消息，并通过入站 webhook 发送回复。

内置插件

当前 OpenClaw 版本已内置 Synology Chat 插件，正常打包版本无需额外安装。

如果你用的是旧版或自定义安装，可以手动从源码 checkout 安装：

bash

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

详情：插件系统

快速配置

想把龙虾接进你的群晖 NAS？按以下步骤操作：

确认 Synology Chat 插件已可用。
- 当前打包版已内置，无需额外安装。
- 旧版/自定义安装可从源码 checkout 手动添加。
- openclaw onboard 现在会在与 openclaw channels add 相同的渠道列表中显示 Synology Chat。
- 非交互式配置：openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>
在 Synology Chat 集成设置中：
- 创建一个入站 webhook 并复制其 URL。
- 创建一个出站 webhook 并设置 secret token。
将出站 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 按以下顺序接受出站 webhook 中的 token：

body.token（请求体字段）
?token=...（URL 参数）
Headers：x-synology-token、x-webhook-token、x-openclaw-token、Authorization: Bearer <token>

Token 为空或缺失会直接拒绝请求（故障关闭模式）。

最小配置示例：

json5

{
  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

私信策略与访问控制

dmPolicy: "allowlist" 是推荐的默认值。
allowedUserIds 接受 Synology 用户 ID 列表（或逗号分隔字符串）。
allowlist 模式下，空的 allowedUserIds 列表被视为配置错误，webhook 路由不会启动（如需允许所有人，使用 dmPolicy: "open"）。
dmPolicy: "open" 允许任何发送方。
dmPolicy: "disabled" 屏蔽所有私信。
回复接收方绑定默认使用稳定的数字 user_id。channels.synology-chat.dangerouslyAllowNameMatching: true 是应急兼容模式，可重新启用基于可变用户名/昵称的回复投递。
配对操作：
- openclaw pairing list synology-chat
- openclaw pairing approve synology-chat <CODE>

出站投递

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

bash

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"

支持基于 URL 的文件投递（媒体发送）。

多账号

channels.synology-chat.accounts 下支持多个 Synology Chat 账号。每个账号可以独立覆盖 token、incoming URL、webhook 路径、私信策略和频率限制。私信会话按账号和用户隔离，同一数字 user_id 在两个不同 Synology 账号上不共享对话记录。

每个已启用的账号必须有独立的 webhookPath。OpenClaw 会拒绝完全重复的路径并拒绝启动仅继承共享路径的命名账号。如确实需要传统继承模式，可设置 dangerouslyAllowInheritedWebhookPath: true，但重复路径仍会被拒绝。

json5

{
  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 检查使用恒定时间比较。
生产环境推荐使用 dmPolicy: "allowlist"。
除非明确需要传统用户名回复投递，否则保持 dangerouslyAllowNameMatching 关闭。
除非在多账号场景中明确接受共享路径路由风险，否则保持 dangerouslyAllowInheritedWebhookPath 关闭。

故障排查

Missing required fields (token, user_id, text)：出站 webhook 请求体缺少必填字段；若 Synology 通过 headers 发送 token，检查 Gateway/代理是否保留了这些 headers。
Invalid token：出站 webhook secret 与 channels.synology-chat.token 不匹配；或请求打到了错误的账号/路径；或反向代理在请求到达 OpenClaw 前剥离了 token header。
Rate limit exceeded：来自同一来源的过多无效 token 尝试会导致该来源被临时锁定；已认证的发送方也有独立的每用户消息频率限制。
Allowlist is empty. Configure allowedUserIds or use dmPolicy=open.：启用了 dmPolicy="allowlist" 但未配置任何用户。
User not authorized：发送方的数字 user_id 不在 allowedUserIds 中。

常见问题

Q: 机器人一直回复 Missing required fields (token, user_id, text) 是怎么回事？

A: 说明出站 Webhook 请求体丢失了关键字段，或者 Synology 用 Header 传了 token 但被你的反向代理吞掉了。检查 Nginx 等代理配置是否保留了 Header。

Q: 私聊提示 User not authorized 怎么解？

A: 你的 dmPolicy 设为了 allowlist（默认建议），但配置的 allowedUserIds 里没有包含你的群晖用户 ID（一串数字）。可以执行 openclaw pairing list synology-chat 然后从群晖 Chat 输入配对码，或者直接在配置中添加自己的数字 ID。

Q: 能让两个不同的 Synology 账号共用同一个 webhook 路径吗？

A: 不可以。每个命名账号必须有独立的 webhookPath。如果一定要用旧版的继承共享路径，必须显式开启 dangerouslyAllowInheritedWebhookPath: true，但风险自负。

Synology Chat ​

内置插件 ​

快速配置 ​

Webhook 认证说明 ​

环境变量 ​

私信策略与访问控制 ​

出站投递 ​

多账号 ​

安全注意事项 ​

故障排查 ​

常见问题 ​

相关文档 ​