需在钉钉群配置加签模式自定义机器人并复制access_token与加签密钥，在dify中创建ai agent、添加webhook工具并严格匹配hmac-sha256认证，再通过提示词、知识库和响应映射实现消息双向转换与多步推理。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
在钉钉群中创建可接收消息的自定义机器人
你需要先让Dify能接收到钉钉群里的每一条@消息，这要求钉钉端必须配置一个具备Webhook能力的自定义机器人。打开目标测试群→点击右上角「群设置」→进入「智能群助手」→点击「添加机器人」→选择「自定义」。
安全设置中【务必选择“加签”模式】，这是当前钉钉最新版强制要求的鉴权方式，选“自定义关键词”或“IP白名单”将导致后续Dify无法通过签名验证，连接直接失败。
创建完成后，立即复制两个关键值：webhook地址中?access_token=后的一串32位字符；以及「加签密钥」字段下显示的完整32位字符串。这两个值将在Dify侧配置时作为身份凭证使用，丢失需重新生成。
配置Dify应用并启用Webhook触发器
登录Dify控制台→点击「创建应用」→选择「AI Agent」类型→填写名称如「钉钉HR助手」→点击「创建」进入编辑页。
左侧导航栏切换到「工具」→点击「+ 添加工具」→选择「Webhook」→在「URL」栏粘贴你从钉钉复制的完整webhook地址（含access_token参数）→「请求方法」选POST→「认证方式」选「HMAC-SHA256」→在「密钥」栏粘贴刚才记下的加签密钥。
这一步必须严格匹配钉钉加签算法：Dify会用该密钥对收到的原始消息体做HMAC-SHA256哈希，并与钉钉Header中传来的x-dingtalk-signature比对。密钥少一位、多一个空格、或用了旧版MD5加签都会返回401错误。
构建钉钉消息到Dify的双向映射逻辑
Agent的核心在于理解钉钉发来的消息结构，并把Dify的响应转成钉钉能渲染的格式。Dify默认接收的是标准JSON，但钉钉发送的是带text.content和sender.staffId等字段的嵌套对象。
第一步：在Dify「提示词」模块的「系统提示词」末尾追加说明：
“你正在为钉钉群聊服务，输入消息来自钉钉OpenAPI，用户ID为{{user_id}}，群ID为{{group_id}}，原始文本内容在text.content字段中。所有回复必须为纯文本，禁用Markdown、代码块、链接。”
第二步：在「上下文」→「知识库」中上传公司《考勤制度V3.2.pdf》《报销流程图解.docx》，确保文件名含版本号——Dify会按文件名排序优先匹配最新版，避免员工查到过期规则。
第三步：回到「工具」页，点击刚添加的Webhook工具右侧「编辑」→勾选「启用响应解析」→在「响应映射」区域填入：{"msgtype": "text", "text": {"content": "{{response}}"}}。
这行JSON告诉Dify：把你的输出原样塞进钉钉要求的text.content字段里，否则钉钉会因格式错误拒收消息。
测试与调试：用真实消息流验证端到端通路
在钉钉测试群中@你的机器人，发送“年假怎么算？”。
如果3秒内无回复，立即检查Dify后台「监控」→「日志」页：若出现signature verification failed，说明加签密钥粘贴错误或webhook地址被手动修改过；若出现invalid json in response，说明你在提示词里写了“请用加粗强调重点”，而钉钉不识别Markdown加粗语法。
成功响应后，再发一句“帮我把下周技术分享会通知改成下午三点”，观察是否触发工具调用——此时Dify应自动调用内置的日历工具（需提前在「工具」中启用），而非仅靠知识库作答。这标志着Agent已具备多步推理能力，不是简单问答机器人。
