钉钉机器人加签模式与关键词模式区别及选择

文章导读
钉钉机器人的安全设置里,加签和关键词是两种独立的校验方式。我处理过的机器人接入问题里,最常出现的情况不是配置出错,而是一开始没想清楚消息会发给谁、被谁看到。所以先不要急着复制代码,先回答两个问题:消息内容泄露了会怎样?群成员里有没有不可控的人?
📋 目录
  1. A 先看消息敏感度和接收方可控性
  2. B 配置动作与校验逻辑的差别
  3. C 加签模式的安全边界比关键词严格
  4. D 容易踩的坑:拼接、时间戳、关键词命中
  5. E 怎么验证配置是否真的生效
A A

钉钉机器人的安全设置里,加签和关键词是两种独立的校验方式。我处理过的机器人接入问题里,最常出现的情况不是配置出错,而是一开始没想清楚消息会发给谁、被谁看到。所以先不要急着复制代码,先回答两个问题:消息内容泄露了会怎样?群成员里有没有不可控的人?

先看消息敏感度和接收方可控性

在决定使用加签模式还是关键词模式时,核心判断依据是消息的敏感度和接收方的可控性。如果机器人被用于发送内部系统告警、运维通知或包含业务数据的信息,这类内容一旦被无关人员触发并获取,可能造成信息泄露,此时应优先选择加签模式。反之,如果只是发送天气提醒、每日一句等公开非敏感内容,或者接收方完全可信且需要对所有人开放交互,关键词模式足以满足需求。判断时还需考虑机器人是否会被拉入多个群聊,群成员是否包含外部人员,以及是否存在被恶意刷屏或伪造消息的风险。总体上,加签模式适合对消息来源有强认证需求的场景,关键词模式适合低风险、需要快速接入的场景。

这段判断基本把边界说清楚了。我自己的习惯是:只要消息里带着 IP、订单号、报错堆栈或者内网链接,一律用加签;只有像“下午三点会议室”这种公开提醒,才考虑用关键词。还有一个容易忽略的场景:机器人被拉进多个群,或者管理员不固定。这时候即使消息本身不敏感,也需要加签,避免群内成员拿 Webhook 地址去别的群乱发。

配置动作与校验逻辑的差别

两种模式在配置界面上都能看到,但处理逻辑完全不同。关键词模式是内容匹配,加签模式是身份认证。实际操作中,选择加签模式建议使用钉钉开放平台提供的加签生成规则,即把时间戳换行拼接加签密钥后计算HmacSHA256签名,再将得到的签名与timestamp一起放入请求头。配置时需确保机器人自定义关键词与加签的密钥都正确填写,且服务器时间与标准时间偏差不要过大,否则可能导致验签失败。对于关键词模式,只需在机器人设置中填入一个或多个自定义关键词,要求发送的消息必须包含至少一个关键词才能成功推送。比较容易忽略的是,关键词模式下的关键词是区分大小写的,且不支持正则表达式,因此需要精确设置。如果同时开启加签和关键词,则两种校验都必须通过,任何一项不满足都无法发送。

生成签名时,可以直接用下面的 Python 函数:

钉钉机器人加签模式与关键词模式区别及选择
import time
import hmac
import hashlib
import base64

def sign(secret):
    timestamp = str(round(time.time() * 1000))
    string_to_sign = f'{timestamp}\n{secret}'
    hmac_code = hmac.new(secret.encode('utf-8'), string_to_sign.encode('utf-8'), digestmod=hashlib.sha256).digest()
    sign = base64.b64encode(hmac_code).decode('utf-8')
    return timestamp, sign

把返回值里的 timestamp 和 sign 放到 POST 请求的 query 参数里,和 Webhook 地址拼接后发送。注意这里的 secret 是机器人安全设置里的加签密钥,不是 Webhook 地址里的 access_token,这两个值很容易被搞混。另外,timestamp 每次请求都要重新生成,不能复用,否则也会被拒绝。

加签模式的安全边界比关键词严格

两种模式的安全边界有明显差异。关键词模式本质上只对消息内容做字符串匹配,并不验证发送者的合法身份,任何知道机器人Webhook地址的人都可以在消息中携带关键词来触发推送,存在被伪造消息的风险。加签模式则通过HmacSHA256签名验证请求是否来自持有密钥的调用方,只要密钥不泄露,第三方即使拿到Webhook地址也无法构造合法请求,从而有效阻止伪造和篡改。但加签模式的安全边界并非绝对,如果密钥被保存在客户端代码或弱权限的服务配置中,或者日志中记录了完整的签名参数,攻击者仍有机会窃取。因此,加签模式需要配合安全的密钥管理机制,例如将密钥放在服务端环境变量中,并定期轮换。

这就像门禁卡和密码锁的区别。关键词等于贴了一张“内部使用”的纸条,知道地址就能进;加签等于刷卡,有卡才能进。但卡如果乱放,别人捡到一样能进。所以密钥要放在服务端,不要写进前端代码,也不要在请求日志里打印签名参数。轮换密钥时,要提前通知所有调用方,避免正在运行的任务因密钥更新而突然报错。

钉钉机器人加签模式与关键词模式区别及选择

容易踩的坑:拼接、时间戳、关键词命中

加签模式最常见的坑是拼接顺序。钉钉要求 timestamp、换行符、密钥挨在一起,用 HmacSHA256 计算。有人图省事用加号或空格连接,结果验签一直失败。建议把待签名字符串打出来检查,确认中间是不是一个真正的换行符。

另一个和时间有关。钉钉会校验请求时间与当前时间的偏差,服务器时间不准或网络延迟过大,即使签名正确也会被拒。所以跑机器人之前先同步一下服务器时间,可以用 ntpdate 或 chronyc 做校准。

关键词模式的坑更多在内容本身。关键词区分大小写,不支持正则,也不做模糊匹配。中英文标点、全半角空格都可能影响命中。比如关键词填“报警”,消息里写“alarm”就不会触发。另外自定义关键词有长度限制,设置太长或太特殊可能保存不了;太宽泛又容易被无关消息带出来,导致机器人被垃圾消息刷屏。

我见过不少事故是群里有人发了一条恰好包含关键词的普通消息,触发机器人告警,造成虚假通知。所以选择关键词时要尽量避免“测试”“成功”“失败”这类通用词,最好结合业务特征设置一个足够独特的词。

钉钉机器人加签模式与关键词模式区别及选择

怎么验证配置是否真的生效

验证加签模式,最简单的方法是构造一条带正确签名的 POST 请求发送到 Webhook 地址,看返回的 errcode 是否为 0。如果返回签名错误或时间戳过期,按前面说的三个方向排查:拼接、密钥、服务器时间。也可以用钉钉后台提供的调试工具,但我觉得用 curl 更能控制变量。

关键词模式更直接:先发一条包含关键词的消息,确认能收到;再发一条不含关键词的消息,确认被拒绝。这里要注意,从钉钉客户端发和从外部请求发可能走不同路径,建议两条路径都测一遍。如果同时启用了两种模式,就分别测试只满足关键词、只满足加签、两者都满足这三种情况,确保规则没有冲突。

测试时不要在生产群直接试,找一个测试群,确认正常后再把机器人拉进正式群。一旦发现异常,优先关闭机器人或临时移除 Webhook,再逐步排查。这么做虽然保守,但能避免告警通道不可用造成更大的麻烦。