从钉钉机器人创建、DeepSeek API配置到消息收发与安全上线，拆解可落地的接入流程。 在钉钉内调用 DeepSeek，关键难点不在模型本身，而在企业组织里的身份、权限、消息通道和回复格式。很多团队把 API Key 填进群机器人后发现只能单向推送，是因为自定义机器人只提供 webhook 发送能力，并不接收群成员的对话。要让 DeepSeek 真正成为钉钉里的AI指导老师，需要创建企业内部机器人，打通消息回调，再在服务端完成模型调用与上下文管理。下面按准备、通道、调用、运维四个环节展开。
1. 接入前的账号、权限与模型准备
先处理钉钉侧。管理员登录钉钉开放平台，进入开发者后台，创建企业内部应用。应用创建后记录 Client ID 与 Client Secret，后续用于获取 access_token 或 Stream 连接。在应用能力中启用机器人，设置机器人名称、头像、简介和消息接收模式。若只做群通知，自定义机器人 webhook 足够；若要让成员 @机器人 提问，必须使用企业内部机器人，并申请机器人发送消息、接收消息等权限。发布前还要在版本管理与发布中设置可见范围，否则测试成员看不到机器人。 DeepSeek 侧同样要准备。访问 DeepSeek 开放平台，完成实名与充值，创建 API Key。接口兼容 OpenAI 协议，Base URL 通常为 ，常用模型包括 deepseek-chat 和 deepseek-reasoner。deepseek-chat 响应快、适合日常问答，deepseek-reasoner 在数学、推理和复杂分析上更强，但延迟与 token 成本更高。API Key 只能保存在服务端环境变量或密钥管理服务中，不能写进钉钉前端配置或客户端代码。 运行环境决定后续接入。HTTP 回调需要公网 HTTPS 地址、域名证书和验签逻辑，适合已有网关的团队；Stream 模式通过长连接接收消息，不需要公网回调，适合内网服务器和快速验证。建议准备一台可访问 DeepSeek API 的云服务器或云函数，并部署 Redis 或数据库保存会话上下文和消息幂等记录。若企业有安全审计要求，还要提前规划日志脱敏、内容留存和密钥轮换策略。
2. 打通钉钉消息通道与回调链路
Stream 模式是较轻松的入口。安装钉钉官方 dingtalk-stream SDK，用 Client ID 和 Client Secret 建立 WebSocket 长连接，订阅机器人消息主题。当群成员 @机器人 时，服务端会收到 JSON 事件，其中包含 conversationId、conversationType、senderStaffId、senderNick、text.content、msgId 以及 sessionWebhook。开发者要先把 @机器人 的 mention 文本去掉，再提取真实问题。为防止钉钉重试造成重复回答，可以用 msgId 做 Redis 幂等键，处理成功后标记过期时间。 HTTP 回调模式则需要在开发者后台配置请求网址。钉钉会先发送验证请求，服务端按文档完成签名校验和解密，再返回加密响应。该模式对响应时间敏感，若业务处理超过数秒，钉钉可能重试。稳妥做法是收到消息后先返回成功，再把问题放入队列，由后台任务调用 DeepSeek，最后通过 sessionWebhook 回复。回调地址必须公网可达并启用 HTTPS，Nginx 反向代理时要保留原始请求头和请求体，避免验签失败。 回复通道要和接收通道匹配。Stream 模式可以直接使用 SDK 的 reply 方法，也可以向事件里的 sessionWebhook 发 POST 请求。企业机器人主动发送群消息时，需要先用 Client ID 与 Client Secret 换取 access_token，并缓存到过期前再刷新，然后调用机器人消息发送接口，带上 robotCode、conversationId 或用户 ID。群聊、单聊和普通消息的接口参数不同，权限未开通时通常返回缺少权限或机器人不可用。建议先打通一条最小链路：群内 @机器人，服务端固定回复“已收到”，确认通道无误后再接入 DeepSeek。
3. 调用DeepSeek并组织回复内容
服务端调用 DeepSeek 可以用 OpenAI 兼容 SDK，也可以直接发 HTTP 请求。初始化时设置 base_url 为 ，api_key 从环境变量读取，model 按场景选择。每次请求构造 messages 数组，system 消息用于约束机器人身份，例如“你是钉钉群里的AI指导老师，回答要准确、简洁，涉及步骤时给出可执行建议”。user 消息放入用户问题，必要时附带最近几轮对话。调用时要设置连接超时和读取超时，遇到 429 或 5xx 错误进行有限次重试，避免钉钉侧长时间等待。 上下文管理决定回答是否连贯。可以按 conversationId 加 senderStaffId 组成会话键，在 Redis 中保存最近八到十轮消息，并限制总 token 数。超过限制时，把早期对话压缩成摘要，或只保留与当前问题相关的片段。教学场景还可以先检索课程资料、制度文档或知识库，把命中内容拼接进 system 或 user 消息，形成轻量 RAG。这样能降低模型幻觉，也能让回答更贴近企业内部术语。对身份证号、手机号、成绩等敏感字段，应在入模前脱敏，在日志中避免明文记录。 拿到 DeepSeek 的返回后，要转换成钉钉能展示的内容。短答案用文本消息即可，步骤、代码和表格适合用 Markdown 消息，需要按钮或表单时可使用 ActionCard 或互动卡片。钉钉 Markdown 支持标题、加粗、链接和图片，但复杂表格与超长内容体验不佳，最好分段或摘要后附详情链接。若使用 deepseek-reasoner，返回中可能包含 reasoning_content，直接展示会干扰阅读，应只取最终 content。对于流式输出，简单方案是先回复“正在思考”，再用消息更新接口替换内容；更完整的方案是使用钉钉互动卡片流式更新，但开发量更高。无论哪种，都要准备降级话术，例如“DeepSeek 当前繁忙，请稍后再试”，并把错误码写入日志。
4. 测试发布与运维优化
测试阶段不要把机器人直接推给全员。先在开发者后台把测试人员加入可见范围，在测试群中 @机器人 提问，观察服务端日志、Stream 连接状态和钉钉侧回复。用 curl 或 Postman 单独验证 DeepSeek API Key、余额、网络出口和模型名称，排除模型侧问题。常见故障包括机器人未发布导致不可见、权限未申请导致无法发消息、access_token 未缓存导致频繁刷新、回调验签失败导致钉钉提示配置错误、消息重复处理导致机器人多次回答。逐项检查后，再把问题记录成排错清单，后续上线会快很多。 发布时进入钉钉开放平台版本管理与发布，填写版本说明，提交企业管理员审核，并设置可用部门或人员范围。正式使用后要建立监控指标，包括消息接收量、DeepSeek 调用成功率、平均响应时间、token 消耗和费用趋势。DeepSeek 按输入输出 token 计费，长上下文和推理模型会明显抬高成本，因此要设置预算告警和单用户频率限制。安全上定期轮换 API Key，限制服务器出口 IP，对日志中的用户问题和模型回答做脱敏，必要时保留审计记录以符合企业合规要求。 运维优化要围绕稳定和教学效果展开。高并发时给 DeepSeek 调用加队列和熔断，避免异常流量拖垮服务；回复慢时优先切换 deepseek-chat，或把长回答拆成先摘要后详情。AI指导老师可以把常用场景沉淀为提示词模板，例如课程答疑、作业反馈、教研材料润色、培训话术生成，再按部门配置不同 system 消息。若企业已有钉钉知识库或文档中心，可定期同步索引，让机器人优先引用内部资料。随着调用量增长，再考虑多实例部署、向量检索和互动卡片流式体验，接入就会从一次演示变成可持续的日常工具。
