1. 项目概述与核心价值
最近在团队里，我们遇到了一个挺实际的小问题：每周一早上，都需要有人手动在钉钉群里@一下项目负责人，提醒他准备周会材料。这事儿说大不大，但总有人会忘，或者因为忙别的事而耽搁。作为一个喜欢用技术解决重复性劳动的人，我就在想，能不能让机器自动干这个活儿？于是，就有了这个“钉钉添加自定义机器人，实现每周定时@某人”的小项目。
简单来说，这个项目的核心就是自动化和定时。它利用钉钉群聊自带的“自定义机器人”功能，创建一个能接收外部指令的“小助手”。然后，我们通过编写一个简单的脚本（比如用Python），让这个脚本在每周的固定时间（比如周一早上9点），自动向钉钉机器人发送一条包含特定@人员信息的消息。最终，机器人就会在群里发出这条消息，完美替代了人工操作。
听起来是不是挺简单的？确实，它的技术门槛不高，但带来的价值却很实在。首先，它解放了人力，把团队成员从重复、机械的提醒任务中解脱出来。其次，它保证了提醒的准时和准确，机器永远不会忘记，也不会发错人。最后，它还是一个非常好的自动化入门实践，涉及了API调用、定时任务、消息构建等多个基础但实用的技能点。无论你是运维、开发，还是项目管理人员，掌握这个小技巧，都能让你的日常工作更高效、更智能。
2. 整体方案设计与思路拆解
要实现“定时@某人”，我们需要拆解成两个核心部分：消息的发送和任务的定时。整个方案的链路是：一个定时触发器，在指定时间启动我们的消息发送脚本，脚本通过HTTP请求调用钉钉机器人的Webhook地址，将构造好的消息推送到钉钉群。
2.1 核心组件选型与考量
1. 消息发送端：Python脚本为什么选Python？从相关热搜词如“python安装”、“python零基础入门教程”的高频出现就能看出，Python以其语法简洁、库丰富、社区活跃的特点，成为了自动化脚本的首选语言。对于调用HTTP API（钉钉机器人本质就是一个Webhook）这种任务，Python的requests库几行代码就能搞定，学习成本极低。相比之下，虽然热搜里也有“c# 钉钉oa审批上传附件”，但C#通常用于更复杂的桌面或服务端应用，对于这种轻量级脚本有点“杀鸡用牛刀”。因此，Python是我们的不二之选。
2. 定时触发器：系统Crontab定时方案有很多，比如在脚本里用while True加sleep，或者使用Python的schedule库，甚至像热搜里提到的“system.threading.timer 定时 10ms 不成功”这种编程语言自带的定时器。但对于“每周执行一次”这种系统级的、长期稳定的定时任务，Linux/Unix系统的Crontab或Windows系统的任务计划程序是最可靠、最标准的方案。它们独立于我们的脚本进程，由操作系统内核管理，即使服务器重启也能自动恢复。特别是“crontab定时执行shell脚本”这个热搜词，直接点明了最佳实践。我们将采用Crontab来触发我们的Python脚本。
3. 可选进阶：Jenkins热搜词中“jenkins自动部署”、“jenkins自动化部署”的出现，提示了另一种更工程化的思路。如果你所在的环境已经有Jenkins（一种持续集成/持续部署工具），完全可以创建一个Jenkins的Pipeline任务，利用其内置的“Build periodically”功能（本质上也是一个Cron表达式）来定时执行你的Python脚本。这样做的好处是，可以方便地集中管理多个定时任务、查看执行日志和历史记录，适合团队协作和更复杂的自动化流程。但对于个人或简单场景，直接用系统Crontab更轻量。
方案流程图（概念）：
[定时器 Crontab] --（每周一9:00触发）--> [Python脚本] --（HTTP POST请求）--> [钉钉机器人Webhook] --（推送消息）--> [钉钉群聊]2.2 钉钉机器人原理浅析
钉钉自定义机器人，本质上是一个Webhook。你在钉钉群里添加机器人时，钉钉的后台会为你生成一个独一无二的URL（即Webhook地址）。这个URL就是一个接收HTTP POST请求的端点。当任何客户端（比如我们的Python脚本）向这个URL发送一个符合钉钉要求的JSON格式消息时，钉钉服务器就会“替”这个机器人，把这条消息发布到对应的群里。
理解这一点至关重要：我们的脚本并不直接“登录”钉钉或“控制”机器人，它只是向一个公开的API地址发送了一段数据。这决定了我们实现方式的安全性和局限性。安全性在于，你只需要保管好这个Webhook地址（它包含了密钥），无需暴露钉钉账号密码。局限性在于，机器人只能被动接收信息并发送，不能主动爬取群聊记录或进行复杂交互。
3. 实操步骤详解：从零到一
下面，我将带你一步步完成整个配置。请准备好：一个钉钉账号（并有一个你有权限添加机器人的群）、一台Linux服务器或Mac/Windows电脑（用于运行脚本和定时任务）、以及基础的命令行操作知识。
3.1 第一步：在钉钉群中添加自定义机器人
这是所有工作的起点，我们需要获取那个关键的Webhook地址。
- 打开钉钉群聊：进入你想要接收提醒的钉钉群。
- 点击群设置：在PC端钉钉，点击群右上角的“...”或设置图标；在手机端，点击群右上角的人形图标进入群设置。
- 找到“智能群助手”：在群设置中，找到“智能群助手”选项并点击。
- 添加机器人：在智能群助手页面，点击“添加机器人”。
- 选择“自定义”机器人：在机器人列表里，找到“自定义”机器人，点击“添加”。
- 设置机器人信息：
- 机器人名字：起个易懂的名字，比如“周会提醒小助手”。
- 安全设置（最关键的一步！）：这里有三种方式，强烈建议至少选择一种，否则你的Webhook地址一旦泄露，任何人都可以往你的群里发消息。
- 自定义关键词：机器人只会发送包含至少一个你所设定关键词的消息。例如，你设置关键词为“周会”，那么你的脚本发送的消息中必须含有“周会”二字，否则发送会失败。这对于我们的场景很合适，我们可以在消息里固定加上“周会提醒”。
- 加签：钉钉会提供一个密钥，你需要用这个密钥和时间戳生成一个签名，并随请求一起发送。安全性最高，但脚本端需要多一点计算。
- IP地址（段）：限定只有来自特定IP地址的请求才会被处理。适合脚本部署在固定服务器的情况。
- 为了简单起见，我们演示选择“自定义关键词”，并设置为“提醒”。
- 完成并获取Webhook：阅读并同意条款后，点击“完成”。钉钉会弹出一个页面，里面最重要的信息就是“Webhook”地址，格式类似
https://oapi.dingtalk.com/robot/send?access_token=XXXXXX。请立即复制并妥善保存这个地址，因为它只会显示这一次！
注意：安全设置是必须的。不要使用没有任何安全设置的机器人，那相当于把你家大门钥匙放在了网上。
3.2 第二步：编写Python消息发送脚本
现在，我们有了Webhook地址，接下来就要编写一个能向这个地址发送正确格式消息的Python脚本。
首先，确保你的环境安装了Python（参考热搜词“python安装教程”）和requests库。如果没有安装requests，在命令行执行pip install requests。
创建一个文件，例如dingtalk_reminder.py，然后用代码编辑器打开。
#!/usr/bin/env python3 # -*- coding: utf-8 -*- import requests import json import sys def send_dingtalk_message(webhook_url, at_mobiles, at_all=False): """ 发送钉钉群机器人消息 :param webhook_url: 机器人的Webhook地址 :param at_mobiles: 需要@的钉钉账号绑定的手机号列表，如 ['13800138000', '13900139000'] :param at_all: 是否@所有人，默认为False """ # 钉钉机器人消息体 headers = {'Content-Type': 'application/json;charset=utf-8'} # 构建@信息 at_data = {} if at_mobiles: at_data['atMobiles'] = at_mobiles if at_all: at_data['isAtAll'] = at_all # 构建消息内容。注意：这里必须包含你创建机器人时设置的“自定义关键词”，例如“提醒” # 消息类型为text，也可以支持markdown、link等，这里用最简单的text。 content = f"提醒：各位同事，每周项目例会将在10分钟后开始，请负责人 @{at_mobiles[0]} 准备好相关材料。\n请准时参加！" data = { "msgtype": "text", "text": { "content": content }, "at": at_data } try: # 发送POST请求 response = requests.post(webhook_url, headers=headers, data=json.dumps(data)) result = response.json() if result.get('errcode') == 0: print(f"消息发送成功: {result.get('errmsg')}") else: print(f"消息发送失败: {result}") sys.exit(1) # 非零退出码，便于Crontab捕获失败 except Exception as e: print(f"请求发生异常: {e}") sys.exit(1) if __name__ == '__main__': # 在这里替换成你的实际信息 WEBHOOK_URL = 'https://oapi.dingtalk.com/robot/send?access_token=你的实际token' # 需要@的人的手机号（必须是他钉钉账号绑定的手机号） AT_MOBILES = ['13800138000'] send_dingtalk_message(WEBHOOK_URL, AT_MOBILES, at_all=False)脚本关键点解析：
- 消息结构：钉钉机器人API要求一个特定的JSON结构。
msgtype指定消息类型，text对象里的content是正文，at对象用于指定@谁。 - @人功能：通过
atMobiles字段实现，值是一个手机号列表。重要：这个手机号必须是对方钉钉账号的绑定手机号，不一定是他在群里显示的昵称。你可以让同事在钉钉“我的信息”里查看。 - 关键词匹配：我们的消息正文
content里包含了“提醒”二字，这对应了创建机器人时设置的关键词。如果忘记加，消息会发送失败。 - 错误处理：脚本对网络请求和钉钉返回的错误码进行了基本处理，并在失败时使用
sys.exit(1)退出。这对于Crontab定时任务非常重要，因为Crontab可以通过检查脚本退出状态码来知道任务是否成功，进而决定是否发送报警邮件（如果配置了的话）。
你可以先在命令行手动运行这个脚本测试一下：python3 dingtalk_reminder.py。如果一切正常，你的钉钉群应该会立刻收到这条@人的消息。
3.3 第三步：使用Crontab配置每周定时任务
脚本测试成功后，我们就需要让它每周一自动运行。这里以Linux/Mac系统的Crontab为例（Windows用户可以使用“任务计划程序”，原理类似）。
打开Crontab编辑界面：在终端输入
crontab -e。如果是第一次使用，可能会让你选择编辑器，选熟悉的就好（比如nano或vim）。添加定时任务规则：在打开的文件末尾，添加一行。Crontab的语法是：
* * * * * command-to-be-executed - - - - - | | | | | | | | | +----- 星期几 (0 - 7) (星期天=0或7) | | | +------- 月份 (1 - 12) | | +--------- 日期 (1 - 31) | +----------- 小时 (0 - 23) +------------- 分钟 (0 - 59)我们需要每周一早上9点执行。假设我们的Python脚本放在
/home/yourname/scripts/dingtalk_reminder.py。- 分钟：0（整点）
- 小时：9（早上9点）
- 日期：*（每天，由星期字段限定）
- 月份：*（每月）
- 星期几：1（星期一，注意0和7都代表周日）
- 命令：需要指定Python解释器的全路径，并使用脚本的全路径。可以用
which python3命令查看你的Python3路径，通常是/usr/bin/python3。
因此，添加的行如下：
0 9 * * 1 /usr/bin/python3 /home/yourname/scripts/dingtalk_reminder.py保存并退出：在nano编辑器里按
Ctrl+X，然后按Y确认，再按回车保存。在vim里按Esc，然后输入:wq回车。验证任务：可以输入
crontab -l列出当前用户的所有定时任务，检查是否添加成功。
关于时间的注意事项：Crontab使用的是系统时区。请确保你的服务器或电脑的系统时区设置正确（例如Asia/Shanghai）。你可以用date命令查看当前系统时间和时区。
4. 进阶优化与问题排查
基础功能实现后，我们可以让它更健壮、更灵活。同时，也分享几个我踩过的坑。
4.1 脚本功能增强
上面的基础脚本只能发固定文本。我们可以让它更智能：
支持Markdown格式：钉钉机器人支持Markdown消息，可以让提醒更美观，比如加粗、列表等。只需修改
msgtype和消息体：data = { "msgtype": "markdown", "markdown": { "title": "周会提醒", "text": f"""## 周会提醒 **会议时间**：每周一 9:10 **会议主题**：项目进度同步 **参会人员**：全体项目组成员 **特别提醒**：请负责人 @{at_mobiles[0]} 准备好本周项目报告。 > 请准时参加！ """ }, "at": at_data }动态内容：可以从文件、数据库或简单的配置中读取本周的会议主题、主持人等信息，让提醒内容每周不同。
import datetime week_num = datetime.datetime.now().isocalendar()[1] # 获取今年的第几周 content = f"提醒：第{week_num}周项目例会将在10分钟后开始，请负责人 @{at_mobiles[0]} 准备好材料。"使用加签提高安全性：如果你在创建机器人时选择了“加签”安全设置，那么Webhook地址会带有一个
timestamp和sign参数。你的脚本需要动态计算这个签名。钉钉官方文档有示例，核心是使用HMAC-SHA256算法：import time import hmac import hashlib import base64 import urllib.parse timestamp = str(round(time.time() * 1000)) secret = '你的加签密钥' secret_enc = secret.encode('utf-8') string_to_sign = f'{timestamp}\n{secret}' string_to_sign_enc = string_to_sign.encode('utf-8') hmac_code = hmac.new(secret_enc, string_to_sign_enc, digestmod=hashlib.sha256).digest() sign = urllib.parse.quote_plus(base64.b64encode(hmac_code)) webhook_url = f'你的原始Webhook×tamp={timestamp}&sign={sign}'
4.2 常见问题与排查实录
在实际部署中，你可能会遇到以下问题：
问题1：Crontab任务不执行。
- 排查思路：
- 检查Crontab服务：确保
crond服务正在运行（systemctl status cron或service crond status）。 - 检查命令路径：Crontab的执行环境与用户登录环境不同，可能找不到
python3命令。务必在命令中使用绝对路径（如/usr/bin/python3和脚本的绝对路径）。 - 检查文件权限：确保Python脚本有可执行权限（
chmod +x dingtalk_reminder.py），并且Crontab所属用户有读取和执行该脚本的权限。 - 捕获输出：Crontab默认会将命令的输出（包括错误信息）通过邮件发送给用户。但邮件可能没配置。一个更好的调试方法是将输出重定向到日志文件：
这样，所有打印信息（包括错误）都会记录到0 9 * * 1 /usr/bin/python3 /path/to/script.py >> /tmp/dingtalk_cron.log 2>&1/tmp/dingtalk_cron.log文件中，方便查看。
- 检查Crontab服务：确保
问题2：钉钉收不到消息，但脚本显示发送成功（errcode=0）。
- 排查思路：
- 检查机器人是否被移除：去群里看看机器人还在不在。
- 检查安全设置：最常见的原因！确认你发送的消息完全符合创建机器人时的安全规则。如果是“自定义关键词”，消息里必须原封不动地包含那个词。如果是“加签”，检查签名计算是否正确，时间戳是否在有效期内（钉钉要求请求时间戳与服务器时间相差不超过1小时）。
- 检查@的手机号：确认
atMobiles里的手机号，是否确实是目标成员在钉钉APP“我的”-“设置与隐私”-“我的信息”里显示的绑定手机号。很多同事会用工作邮箱登录，但绑定手机号可能是另一个。
问题3：消息能收到，但没有成功@到人。
- 原因与解决：
- 消息类型不支持@：只有
text和markdown类型的消息支持at字段。如果你误用了其他类型，at会失效。 - 手机号格式错误：
atMobiles必须是一个字符串列表，如['13800138000']，而不是一个字符串或数字。 - 用户不在本群：被@的用户的钉钉账号必须在该群内，否则@不会生效（但消息仍会发出）。
- 消息类型不支持@：只有
问题4：如何@多个人？
- 解决方案：非常简单，在
AT_MOBILES列表里添加多个手机号即可。
消息内容里可以灵活处理，例如：AT_MOBILES = ['13800138000', '13900139000', '13600136000']content = f"提醒：请 {', '.join([f'@{m}' for m in AT_MOBILES])} 注意，会议即将开始。"
4.3 使用Jenkins作为定时引擎（可选）
如果你团队使用Jenkins，用它来管理这个定时任务会更规范。创建一个“自由风格”的软件项目，在“构建触发器”里勾选“Build periodically”，并填写Cron表达式（如H 9 * * 1，H表示哈希，用于分散负载，避免整点同时触发大量任务）。在“构建”步骤里，选择“执行shell”或“Execute Windows batch command”，然后填入执行Python脚本的命令。
这样做的好处是，Jenkins会保存每次构建的完整控制台输出，成功失败一目了然，还可以配置构建失败后发送邮件通知等功能，非常适合企业级的自动化管理。
5. 安全与维护建议
这个小项目虽然简单，但涉及API密钥和自动化操作，安全和稳定性不容忽视。
保护Webhook地址：你的Webhook地址包含了
access_token，这相当于机器人的密码。绝对不要将它提交到公开的代码仓库（如GitHub）。最佳实践是：- 将
WEBHOOK_URL作为环境变量读取：WEBHOOK_URL = os.environ.get('DINGTALK_WEBHOOK')。 - 或者存储在一个单独的、不被版本控制的配置文件里（如
config.ini），并在.gitignore中忽略它。 - 在服务器上，可以通过
export DINGTALK_WEBHOOK='your_url'设置环境变量。
- 将
定期检查与更新：
- 机器人有效性：钉钉机器人长期不使用可能会被禁用，定期手动发条消息测试一下。
- 被@人员：团队成员变动时，及时更新脚本中的手机号列表。
- 脚本逻辑：如果会议时间、频率发生变化，记得更新Crontab表达式和脚本中的提醒内容。
设置监控：最怕的就是定时任务悄无声息地失败了。除了查看Crontab日志，可以做一个简单的“心跳”监控。让脚本每次执行成功后，向另一个专门用于监控的渠道（如另一个钉钉群、一个日志文件）发送一条“执行成功”的消息。如果连续几次没有收到成功消息，你就知道该去排查了。
通过以上步骤，一个稳定、可靠的钉钉定时提醒机器人就搭建完成了。它就像一位不知疲倦的助理，每周都会准时、准确地帮你完成提醒工作。这个项目麻雀虽小，却涵盖了自动化脚本、API调用、系统定时任务等多个实用知识点，是提升工作效率、迈入自动化门槛的一个绝佳起点。
