如何把任务结果接入钉钉机器人通知（操作手册）

通用工程思想 · 编程博客 · 第 7 篇主题：给你的脚本/项目，加一个"跑完自动往钉钉群发一条结果"的能力。本篇教你怎么从零建机器人、怎么配置、以及它到底会发什么。全程操作向，可直接照着做。

这篇适合谁 / 前提

你想让你的项目"跑完自动通知你"；
你有一个钉钉（或用得起的钉钉群）；
目标：任务结束,往钉钉群自动推一条带成功/失败情况的消息。

大纲：接入钉钉分两大块

第一部分：去钉钉建一个"群机器人"，拿到两条钥匙
     ↓
第二部分：把钥匙配进项目，让它接管发
     ↓
（之后：每次跑完自动发，结束了）

先自己有"群 + 机器人 + 两把钥匙"，再让项目"接管发"。下面逐步讲。

第一部分：去钉钉建一个"群机器人"

钉钉消息不是往"某个人"发，而是发到某个群里的一个机器人。所以第一步是有个群、群里加个机器人。

第 1 步：建一个群（或用已有的群）

机器人消息会发到这个群里。
哪怕只有你自己的群（给自己发通知）也行。

第 2 步：进群设置 → 加"群机器人"

群设置里找 "智能群助手 / 群机器人 / 添加机器人"。

第 3 步：选"自定义（通过 Webhook 接入）"机器人

建好后，它会给你一个网址（Webhook），长这样：
```
https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxx
```

第 4 步：选"安全方式"（关键）

钉钉要求你选一种"防止别人冒充往你群里发"的校验。常见两种：

安全方式给什么用在哪种

加签（Secret） 给你一串 SECxxxx 密钥本篇对应的就是这种

自定义关键词规定消息必须含某个词另一种
✅ 项目用的加签（代码里有基于 SEC 的签名）。所以选"加签"，抄下那串 SEC 开头的密钥。

安全方式	给什么	用在哪种
加签（Secret）	给你一串 `SECxxxx` 密钥	本篇对应的就是这种
自定义关键词	规定消息必须含某个词	另一种

第 5 步：记下两样东西（这就是"两把钥匙"）

钥匙	是什么	样子
Webhook	机器人地址	`https://oapi.dingtalk.com/robot/send?access_token=...`
Secret	加签密钥	`SEC...` 开头的一串

至此，你手里有了"一个能往群发消息的机器人的两把钥匙"。

第二部分：把钥匙配进项目

项目通过环境变量读这两把钥匙。按你的运行方式选一条路：

路 A：本地运行（自己机器上跑）

在项目根目录的 .env 文件里加两行：

DINGTALK_WEBHOOK=你抄的Webhook地址
DINGTALK_SECRET=你抄的SEC那串

⚠️ 必须两个一起填（否则项目会报"必须同时配置"）。只填一个不行。

路 B：GitHub Actions（CI 自动跑）

在 GitHub 仓库 Settings → Secrets and variables → Actions 加两个密文变量：

DINGTALK_WEBHOOK
DINGTALK_SECRET

运行时它会自动读，不需要写进代码。

配好之后，下次任务跑完，它就会自动往群里发那条"战报"。

它发出来会是什么样

配好之后,每次任务结束,群里会收到这样一条 markdown：

### 抖音自动发送：全部成功        （或：存在失败）
> 任务：daily-streak
> 模式：正式发送                （干跑时显示"检查模式"）
> 完成时间：2026-08-09 16:00:00 +0800
> 结果：成功 2 人，失败 0 人

#### 成功名单（2）
1. 好友A - 已发送 2 条

#### 失败名单（0）
无

失败时还会有：失败名单（每人 + 原因）、失败截图、CI 运行链接。

你现在的动作：4 步清单

步骤	做什么
①	建/找一个钉钉群，加"自定义机器人"，选加签安全方式
②	抄下机器人 Webhook 地址和 SEC 密钥
③	分别填到 `.env`（本地）或 GitHub Secrets（CI），两个一起填
④	跑一次任务，看群里有没有收到那条通知

常见问题与排查

症状	最可能原因	怎么解
群里没收到	两把钥匙只填了一个	确认 Webhook 和 Secret 都填了且配对
报错"必须同时配置"	只配了 Webhook 没配 Secret（或反之）	两个一起补上
报错"签名不对/非法"	Secret 抄错 / 复制时带了空格	重新逐字符核对 `SEC`，去首尾空格
消息发不出去 / 很长	钉钉单条有长度上限	项目已自动截断；超长会提示"已省略"
通知没发但任务成功	通知本身就是"尽力而为"	属正常，任务成功不受影响（查网络/钥匙即可）

三个通用提醒（不只是钉钉）

钥匙要保密：Webhook + Secret ≈ "往你群里发消息的权限"。别写进代码仓库、别公开分享——这正是走环境变量/Secrets 而不写死的原因。
"尽力而为"的定位：通知是要能容忍失败、失败不反噬主流程的（通读第七篇博客的"主流程/辅助流程分离"）。
明文 URL 可被伪造：所以钉钉才要求加签。任何"公开可打的 Webhook"，都该加"证明是本人发的"这层校验。

落地检查清单

已有一个钉钉群，群内加了"自定义机器人"，选加签方式
已抄下机器人 Webhook 和 SEC 密钥
已把两把钥匙同时配进 .env（本地）或 Secrets（CI）
未把钥匙写进代码仓库 / 未公开分享
已跑一次任务验证群里能收到通知

一句话带走

"接钉钉就三步：去群里建个'自定义机器人'拿到 Webhook 和 SEC 两把钥匙 → 两个一起配进环境变量 → 跑完自动发。记住钥匙要保密、通知要'尽力而为不乱搅乱主结果'。"