1. 为什么要在 OpenClaw 里接 Synology Chat如果你手里已经有一台群晖 NAS日常通知、告警、团队沟通都跑在 Synology Chat 上那把它接进 OpenClaw 是一件很自然的事。OpenClaw 本身是一个可扩展的智能体网关支持多种消息通道而 Synology Chat 通道是以插件形式存在的并不在默认核心通道里。这意味着你需要先装插件再配 Webhook最后联调消息收发。我先把结论说清楚Synology Chat 通道能做什么它能让 OpenClaw 接收来自 Synology Chat 的私信消息也能主动向指定用户发送消息还支持基于 URL 的文件传输。适合谁适合已经在用群晖生态、希望把 AI 能力接入内部沟通工具、又不想额外搭一套消息中间件的开发者和运维同学。整个链路的核心是两条 Webhook一条是 Synology Chat 的「传入 Webhook」用来让 OpenClaw 往 Chat 里发消息另一条是「传出 Webhook」把 Synology Chat 的消息回调到 OpenClaw 网关。两条都通了最小可用链路才算跑通。这篇会按「装插件 → 生成回调地址 → 写配置 → 三步验证 → 排错」的顺序走配置片段可以直接复制参数表对照着填。你不需要先理解 OpenClaw 的全部架构跟着做就能跑起来。2. 前置准备插件安装与 Webhook 回调地址生成2.1 安装 Synology Chat 插件Synology Chat 不是 OpenClaw 默认核心通道的一部分必须通过本地代码库安装。假设你已经把 OpenClaw 仓库拉到本地进入仓库根目录后执行openclaw plugins install ./extensions/synology-chat安装完成后可以用下面的命令确认插件是否被识别openclaw plugins list输出里应该能看到synology-chat这一项。如果没看到先检查路径是否正确./extensions/synology-chat是相对仓库根目录的路径别在别的目录下执行。2.2 在 Synology Chat 里创建两条 Webhook打开 Synology Chat 的集成设置这里要做两件事第一创建一个「传入 Webhook」复制它生成的 URL。这个 URL 长这样https://nas.example.com/webapi/entry.cgi?apiSYNO.Chat.Externalmethodincomingversion2tokenxxxxx它对应配置里的incomingUrl作用是让 OpenClaw 能往 Chat 里发消息。第二创建一个「传出 Webhook」用一个密钥令牌token并把它的 URL 指向你的 OpenClaw 网关。默认回调地址是https://gateway-host/webhook/synology如果你在配置里自定义了channels.synology-chat.webhookPath那传出 Webhook 的 URL 就要跟着改成你自定义的路径。这一步很容易被忽略路径不一致会导致回调 404。2.3 关键参数对照表下面这张表把配置项和 Synology 侧、OpenClaw 侧的对应关系列清楚配的时候对着填配置项含义对应来源token传出 Webhook 的密钥令牌Synology Chat 传出 WebhookincomingUrl传入 Webhook 完整 URLSynology Chat 传入 WebhookwebhookPathOpenClaw 接收回调的路径自定义默认/webhook/synologydmPolicy私信策略allowlist/open/disabledallowedUserIds允许的用户 ID 列表Synology 用户 IDrateLimitPerMinute每分钟速率限制自定义默认建议 30allowInsecureSsl是否允许不安全 SSL生产环境保持false注意token一旦泄露要立即轮换。传入的 Webhook 请求会做令牌验证并按发送者做速率限制这两层是默认生效的。3. 可复制配置channels.synology-chat 完整片段3.1 最小可用配置先给一份能直接跑的最小配置。把它合并进你的 OpenClaw 配置文件通常是 JSON 或 TOML 结构下面以 JSON 形式展示{ channels: { synology-chat: { enabled: true, token: synology-outgoing-token, incomingUrl: https://nas.example.com/webapi/entry.cgi?apiSYNO.Chat.Externalmethodincomingversion2tokenxxxxx, webhookPath: /webhook/synology, dmPolicy: allowlist, allowedUserIds: [123456], rateLimitPerMinute: 30, allowInsecureSsl: false } } }几个点单独说一下。dmPolicy推荐用allowlist这是最稳的默认策略。在allowlist模式下如果allowedUserIds是空列表会被当成配置错误Webhook 路由根本不会启动。想放开所有人就用dmPolicy: open想彻底禁用私信就用dmPolicy: disabled。allowedUserIds接受 Synology 用户 ID 的列表也可以写成逗号分隔的字符串。用户 ID 是数字形式的别填成用户名。3.2 用环境变量简化配置如果你不想把敏感信息写进配置文件可以用环境变量。默认账户支持这几个export SYNOLOGY_CHAT_TOKENsynology-outgoing-token export SYNOLOGY_CHAT_INCOMING_URLhttps://nas.example.com/webapi/entry.cgi?... export SYNOLOGY_NAS_HOSTnas.example.com export SYNOLOGY_ALLOWED_USER_IDS123456,789012 export SYNOLOGY_RATE_LIMIT30 export OPENCLAW_BOT_NAMEOpenClaw规则是配置文件里的值会覆盖环境变量。也就是说如果你在配置里写了token环境变量里的SYNOLOGY_CHAT_TOKEN就不生效了。调试阶段建议先用环境变量跑通再固化到配置文件。3.3 多账户配置一个 OpenClaw 网关可以接多个 Synology Chat 账户挂在channels.synology-chat.accounts下面。每个账户可以单独覆盖令牌、传入 URL、Webhook 路径、私信策略和限制{ 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] } } } } }注意alerts这个账户用了独立的webhookPath那它在 Synology 侧的传出 Webhook 也要指向/webhook/synology-alerts两边必须一致。3.4 重启网关配置改完重启 OpenClaw 网关让配置生效openclaw gateway restart重启后留意日志里有没有synology-chat通道启动成功的记录。如果allowlist模式下allowedUserIds为空这里会直接报配置错误路由不会起来。4. 三步验证从发消息到确认频道响应配置写完不代表通了必须做验证。下面三步按顺序做每一步都有明确的成功标志。4.1 第一步发送测试消息用openclaw message send主动往 Synology Chat 发一条消息。目标用数字形式的 Synology 用户 IDopenclaw message send --channel synology-chat --target 123456 --text 来自 OpenClaw 的消息也支持带通道前缀的写法openclaw message send --channel synology-chat --target synology-chat:123456 --text 再次问候成功标志你的 Synology Chat 里对应会话收到这条消息。如果没收到先看网关日志里incomingUrl请求的返回码401 通常是 token 或 URL 不对。4.2 第二步查看回调日志这一步验证的是「传出 Webhook」方向也就是 Synology Chat 的消息能不能回调到 OpenClaw。在 Synology Chat 里给机器人发一条私信然后看 OpenClaw 网关日志openclaw gateway logs --follow成功标志日志里出现/webhook/synology路径的请求记录并且能看到发送者 ID 被正确解析。如果日志里完全没有这条请求说明 Synology 侧的传出 Webhook URL 没指对或者路径和webhookPath不一致。4.3 第三步确认频道响应最后确认 OpenClaw 能对收到的消息做出响应。在 Synology Chat 里发一条消息观察机器人是否回复。如果配置了dmPolicy: allowlist但发送者不在allowedUserIds里消息会被拦下这时可以用配对命令处理openclaw pairing list synology-chat openclaw pairing approve synology-chat 用户ID成功标志机器人对允许的用户做出响应且日志里没有速率限制触发的记录。三步都过了最小可用链路就算跑通了。5. 常见报错排查401、local proxy failed 与 OAuth联调阶段最容易卡在几个固定报错上下面按真实报错逐个拆。5.1 401 Unauthorized这是最常见的。原因通常是token和 Synology 侧传出 Webhook 的令牌不一致或者incomingUrl里的 token 被截断。排查顺序先核对配置文件里的token是否和 Synology 传出 Webhook 完全一致再检查incomingUrl是否完整复制尤其是token后面的部分。如果用了环境变量确认配置文件没有把它覆盖掉。5.2 local proxy failed这个报错一般出现在网关无法访问incomingUrl的时候。检查SYNOLOGY_NAS_HOST或incomingUrl里的主机名能不能从网关所在机器解析和访问。如果 NAS 用的是自签名证书而allowInsecureSsl是falseTLS 握手会失败。生产环境不建议打开allowInsecureSsl正确做法是把 NAS 证书换成受信任的或者把 CA 装到网关机器上。5.3 reading choices 相关报错这类报错通常和消息体解析有关多出现在传出 Webhook 的 payload 格式和预期不一致时。确认 Synology Chat 传出 Webhook 指向的路径和webhookPath完全一致路径不一致时请求可能落到别的处理器上导致解析失败。5.4 OAuth 相关报错如果你在 Synology 侧配置时误开了需要 OAuth 的集成方式会看到 OAuth 相关报错。Synology Chat 的 Webhook 集成走的是令牌验证不需要 OAuth。回到集成设置确认用的是传入/传出 Webhook而不是其他授权模式。5.5 配置三件套自查不管遇到哪种报错先把这三件套对齐一遍Base URLincomingUrl和webhookPath对应的网关地址、Keytoken、Model ID通道标识synology-chat。三者任一错位链路都通不了。多账户场景下每个账户的这三件套要单独核对别串了。6. 把链路用起来消息发送、媒体与安全实践链路跑通之后日常使用主要围绕消息发送和访问控制。消息发送用openclaw message send目标用数字用户 ID。媒体内容支持基于 URL 的文件传输方式也就是说你可以把文件放在一个可访问的 URL 上通过消息发送出去而不是直接上传二进制。访问控制上生产环境建议保持dmPolicy: allowlist把允许的用户 ID 明确列出来。dmPolicy: open虽然方便但任何发送者都能触发风险较高。rateLimitPerMinute按实际流量调默认 30 对大多数内部场景够用告警类账户可以适当调高。安全方面token要妥善保管泄露立即轮换allowInsecureSsl除非你明确信任自签名的本地 NAS 证书否则保持false。传入的 Webhook 请求本身会做令牌验证和按发送者限流这两层别关掉。如果你打算长期跑编码或 Agent 类任务把 Synology Chat 作为通知和交互入口配合 OpenClaw 的 Coding Plan 会更顺需要验证模型行为时可以直接在模型对话里试接入和排障过程中要生成或轮换密钥去 API Keys 页面操作具体参数对照接入文档。这几处配合起来Synology Chat 通道就不只是「能收消息」而是真正嵌进你的工作流里了。
