​

Synology Chat

​

内置插件

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

​

快速开始

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

• OpenClaw 按以下顺序接受出站 webhook 令牌：body.token，然后是 ?token=...，再然后是请求头。
• 接受的请求头形式：
  • x-synology-token
  • x-webhook-token
  • x-openclaw-token
  • Authorization: Bearer <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

​

私信策略和访问控制

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

​

出站投递

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"

​

多账户

{
  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，如果泄露请轮换。
• 保持 allowInsecureSsl: false，除非你明确信任自签名的本地 NAS 证书。
• 入站 webhook 请求会按发送者进行令牌验证和速率限制。
• 无效令牌检查使用恒定时间密钥比较，并以失败关闭的方式处理。
• 生产环境推荐使用 dmPolicy: "allowlist"。
• 除非你明确需要基于旧版用户名的回复投递，否则请保持 dangerouslyAllowNameMatching 关闭。
• 除非你明确接受多账户设置中共享路径路由的风险，否则请保持 dangerouslyAllowInheritedWebhookPath 关闭。

​

故障排除

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

​

相关内容

• Channels Overview — 所有受支持的渠道
• Pairing — 私信认证和配对流程
• Groups — 群聊行为和提及门控
• Channel Routing — 消息的会话路由
• Security — 访问模型和加固