把 AI 接进钉钉这件事，我前后折腾了三个周末，最后发现真正的坑基本都集中在钉钉开放平台那一层：权限配错、加签算法算错、机器人发了消息群里却看不到。OpenClaw 本身反而是最省心的部分。如果你也想在钉钉群里养一个“AI 同事”，让它定时发日报、回答群成员提问、把模型算出来的结论推成卡片，这篇教程就是给最初期的你准备的。我会先讲清楚 OpenClaw 负责什么、钉钉负责什么，再按两条真实链路走一遍，最后把最容易踩的坑整理成速查表。整个过程不需要你会 Java，懂一点 Python、能把 YAML 配置明白就够了。
1. 先把 OpenClaw 和钉钉的角色分清楚
1.1 OpenClaw 是一个“技能调度中枢”
最近在技术社区看到不少人在搜“OpenClaw 部署”“Ollama 部署 OpenClaw”，它本质上是一个开源智能体执行平台。你可以把它理解成一个中控台：给它一个任务，它会按照已经定义好的 Skill（技能）列表去拆解执行——需要查数据库就去调数据库接口，需要推理就去调用模型，需要发消息就去请求外部应用。模型层可以接云端 API，也可以接本地通过 Ollama 部署的开源模型，所以网上才会有“OpenClaw 只能用接入 API 的方式使用算力吗”这种讨论，答案是可以混着用，本地模型省钱，云端模型省心。
那么 OpenClaw 和钉钉对接以后是什么场景？简单说，就是把钉钉群当成智能体的交互入口，把群里的消息当成触发事件，让 OpenClaw 里的技能在收到消息或定时任务后跑起来。没有钉钉这一环，OpenClaw 就是一台只会埋头计算的服务，只能在命令行里手动触发，业务方根本用不上。接上钉钉之后，任何会用聊天软件的人都能直接跟它交互，这才是落地。
1.2 钉钉开放平台实际上给了我们三条通道
对接钉钉最容易懵的就是通道太多。我建议先记住三类：
- 自定义群机器人 Webhook：有一个 URL 就能往里推消息，单向输出，适合告警、日报、通知。
- 企业内部应用机器人：正经的双向通信方式，能接收群消息、回复消息、查用户信息，适合做互动问答。
- Stream 长连接事件订阅：钉钉把消息事件主动推送到你的客户端，不需要公网 IP，也不需要在服务器上配 HTTPS 证书。
这三类不是互斥关系。想做到全双工，通常就是企业应用机器人加上 Stream 模式一起用。为了更直观，我把它整理成了下面的对照表。
| 通道 | 通信方向 | 配置难度 | 典型用途 |
|---|---|---|---|
| 自定义群机器人 Webhook | 单向推送 | 低 | 定时日报、监控告警、通知广播 |
| 企业应用机器人 + Stream 模式 | 双向收发 | 中 | 群里 @ 机器人问答、任务触发 |
| 企业应用机器人 + HTTP 回调 | 双向收发 | 中高 | 需要公网回调地址的团队 |
1.3 对接完成后能得到什么
我实际跑起来的两个场景可以给你参考。第一个是每天早上 9 点，OpenClaw 去数据库拉取前一天的订单量，调用本地模型做一段总结，生成 Markdown 卡片推到项目群里，整个过程全自动。第二个是群成员在群里 @ 机器人问“昨天华东区的销售额多少”，OpenClaw 识别意图、查数据、把结果回复到当前会话。前者只需要 Webhook 单向推送，后者才需要双向链路。
把这两个场景在写代码之前想清楚，能帮你判断自己到底需要复杂方案还是简单方案——这是我最想强调的一点，不要在需求都没分清的时候就去把所有权限都申请一遍。
2. 动手前必须准备好的三样东西
2.1 钉钉侧的账号和组织权限
能不能创建企业内部应用，直接取决于你是否是钉钉组织的管理员或子管理员。很多新手卡在第一关：登录钉钉开放平台以后，发现根本没有“企业内部应用”的入口，十有八九是权限不够。
我实测下来的流程是：用管理员账号登录 open.dingtalk.com，在「应用开发」菜单下找到「企业内部应用」，然后点击创建。如果页面提示没有权限，那就得先联系管理员，让管理员帮你开通应用开发者权限。这里有个小建议：尽量申请一个独立的子管理员账号来操作开放平台，不要直接拿超级管理员日常登录。原因很简单，超级管理员的权限范围太大，一旦 AppSecret 泄露，攻击面会很吓人。
2.2 OpenClaw 侧先跑通一个最小环境
OpenClaw 的部署方式会因为版本不同略有差异，但逻辑是一致的。我在确认它是否准备好对接钉钉时，只看三件事：
- 确认 OpenClaw 服务进程已经跑起来；
- 用一个最简单的 Skill（echo 技能）手动触发一次，确认能正常返回结果；
- 确认 OpenClaw 能访问模型服务，比如本地 Ollama 的 API 端口，或者远程模型接口。
这三步里任何一步挂掉，都不要急着去碰钉钉。否则后面出了问题，你会分不清到底是模型的问题、OpenClaw 的问题还是钉钉的问题，排查成本会翻倍。
如果你是在 ARM 小主机这类低功耗设备上部署 OpenClaw，模型选择建议用小体量模型，并且做一次“预热”，先把模型加载进内存。不然群里第一次 @ 机器人时，响应时间可能长达十几秒，体验很差。
2.3 准备一个测试群和常用工具
不管做推送还是做双向对话，都强烈建议单独建一个测试群，把机器人拉进去，避免在生产群里反复发送调试消息打扰同事。测试群两三个人就够了，自己在里面随便发消息，错误日志不尴尬。
工具方面，需要一个 Python 3.8 以上的环境，最好能用虚拟环境隔离依赖。会用到的库主要是 requests 和钉钉官方的 dingtalk-stream。顺便说一句，不要把密钥直接写在代码里，我习惯用.env文件加载环境变量，后面在 OpenClaw 的配置里引用来引用去也方便。
3. 钉钉侧配置教学：两个通道分别怎么开
3.1 先走通最简单的 Webhook 推送通道
把 Webhook 当成陪练，链路最短，能最快确认钉钉侧配置没问题。
在测试群里添加自定义机器人的入口是：群设置 -> 智能群助手 -> 添加机器人 -> 自定义机器人。填写机器人名称之后，安全设置强烈建议选“加签”。为什么不是自定义关键词？因为关键词会对消息内容做限制，比如我推送的 Markdown 内容里必须有“通知”两字，否则消息会被拒收，这对内容自由度太不友好。IP 白名单则对动态 IP 环境不友好，家里和公司 IP 一变就废。
加签的算法官方文档写得很清楚，但网上贴的代码版本参差不齐。我直接给你贴一份实测可用的：
import time import hmac import hashlib import base64 import urllib.parse def dingtalk_sign(secret: str): 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 = urllib.parse.quote_plus(base64.b64encode(hmac_code)) return timestamp, sign这里有几个细节特别容易踩坑，我一个个说。
第一，timestamp 必须是毫秒级字符串，不是秒，如果你用time.time()直接转字符串，结果只有一个，签名永远对不上。第二，官方签名算法里是“时间戳 + 换行符 + secret”，换行符别漏了。第三，sign 拼接的时候是在 Webhook URL 后面加×tamp=xxx&sign=yyy，不是把参数放到请求体里。
还有一个隐蔽问题：不同语言的 Base64 结果在 URL 编码上处理不一致，如果你发现签名偶尔能过偶尔报错，看一下 sign 里是不是有+号变成了空格。Python 的quote_plus处理是正确的。
3.2 要双向通信就开企业内部应用机器人
单向推送搞定以后，再做双向通信会顺畅很多。
在企业应用后台配置机器人的消息接收模式时，我推荐选 Stream 模式。原因是 Stream 模式不需要公网回调地址、不需要配置 HTTPS 证书，钉钉服务器会主动向你的客户端建立一条长连接，把消息事件推过来。这特别适合本地开发或内网部署的环境。
操作的路径一般是：开发管理 -> 消息接收模式 -> Stream 模式。选完以后，页面会生成新的 Client ID 和 Client Secret。注意！这里生成的 Client Secret 和创建应用时的 AppSecret 不是同一个东西。我见过好几个人拿 AppSecret 去填 Stream 的 ClientSecret，结果就是连不上。这也是我反复强调要仔细看配置页的原因。
配置完 Stream 模式后，把机器人发布到组织，然后拉到测试群里发一条 @ 消息。如果 Stream 连接正常，你会在客户端日志里看到一条事件推送，看到的那一刻基本就可以确定链路通了。
3.3 权限点申请：一次给到能干活就够了
钉钉开放平台的权限体系很考验耐心，一上来就把所有权限全勾上，既没必要也有安全隐患。做 OpenClaw 对接初期，我们实际上只需要这几个：
| 权限点 | 用途 | 是否必须 |
|---|---|---|
| 成员信息读取 | 拿到发送人 userid 和昵称 | 做权限校验时建议开 |
| 机器人发送群消息 | 机器人主动/被动在群里说话 | 必须 |
| Stream 消息接收 | 接收群消息事件 | 必须 |
| 卡片模板读写 | 发送更复杂的交互卡片 | 非必须 |
申请完权限之后不是立刻生效的，实测有时候要等一两分钟。如果你在调用接口时返回 Forbidden，先检查应用是不是还在“开发中”状态，其次是等权限生效后再试。把应用从“开发中”切换到“已发布”这一步，很多新手会漏掉。
4. OpenClaw 与钉钉连通：我的实测过程
4.1 从单向推送开始，写一个日报推送 Skill
老规矩，先做最简单的。在 OpenClaw 的技能目录下创建一个 dingtalk_report 技能，核心逻辑就是调用钉钉 Webhook 把文本或 Markdown 发到群里。
我用的是前面那段签名代码，然后封装一个简单的推送函数：
import requests import json def push_dingtalk_text(text: str, webhook: str, secret: str): timestamp, sign = dingtalk_sign(secret) url = f"{webhook}×tamp={timestamp}&sign={sign}" payload = { "msgtype": "markdown", "markdown": { "title": "OpenClaw 日报", "text": f"### OpenClaw 自动推送\n{text}" } } resp = requests.post(url, json=payload) return resp.json()为什么选择 markdown 消息类型而不是 text？因为在群里可读性好很多，标题、加粗、列表都能正常显示。钉钉对 Markdown 的支持有限，保留简单的标题和列表语法就够了，不要整太复杂的样式。
推送函数写好后，手动执行一次技能，确认测试群能收到消息。之后再把它接入 OpenClaw 的定时任务或者事件触发，就成了正式的日报机器人。我坚持先做推送练手的原因在于：双向交互要考虑消息去重、会话上下文、超时回复等问题，而推送只涉及一个 HTTP 请求，是链路最短的场景，能最快确认钉钉侧配置全对。
4.2 再做双向通信：群里 @ 机器人，OpenClaw 回答
双向通信的实现分四步：连接 Stream、接收消息、交给 OpenClaw 处理、把结果回复到当前会话。
代码骨架大概是这样的：
import dingtalk_stream from dingtalk_stream import AckMessage def on_message(msg: dingtalk_stream.ChatbotMessage): data = msg.data content = data.get("text", {}).get("content", "") content = content.replace("@", "", 1).strip() # 把消息交给 OpenClaw 的 skill 去处理 answer = openclaw_dispatch(content) # 回复到当前会话 dingtalk_reply.send(data["sessionWebhook"], answer) return AckMessage.STATUS_OK, "" def main(): client = dingtalk_stream.DingTalkStreamClient({ "client_id": "...", "client_secret": "..." }) client.register_callback(dingtalk_stream.ChatbotMessage, on_message) client.start_forever()有几个很实际的细节。消息里的text是一个字典，内容在content字段里，不要直接拿data["text"]当字符串处理。回复消息的方式可以直接发到sessionWebhook，这个地址每个会话动态生成，不需要额外权限就能发消息，是最简单的回复方式。
此外，如果任务执行时间很长——比如要调一次本地模型跑复杂的推理，整个耗时超过几秒——我建议先给群里回复一句“收到，正在处理”，然后异步执行任务，处理完再补发结果。否则钉钉在交互模式里长时间没有应答，会表现为机器人“失联”，体验很糟糕。
4.3 把对话记忆和权限控制考虑进去
只做“问一句答一句”太浪费 OpenClaw 的能力了，实际上用户会连续追问，比如“昨天的数据呢”“算一下华东区的”，这时候就需要跨轮次的记忆能力。
我建议在技能里加一个简单的dingtalk_memory模块：按conversationId + 日期建一张 SQLite 表，存最近 N 轮的对话摘要。每次收到新消息时，把历史摘要拼进 prompt，再调用模型，效果会一下子提升一个档次。这条对群场景特别重要，因为一个群里可能有几十人提问，如果不按会话隔离，上下文会乱成一锅粥。
权限控制也不要忽略。像“删除数据”“修改配置”这类高危操作，我默认全部禁止，只有在技能入口处校验senderStaffId在白名单里时才放行。用白名单判断而不是在业务逻辑里到处写 if，结构要清晰得多。
4.4 上线前的自检清单
每次我部署新的 OpenClaw 钉钉连接器，都会过一遍这个清单，几乎能堵住 90% 的问题：
- Webhook 推送消息是否成功到达测试群；
- 加签拼接是否正确，重跑一次签名算法是否稳定；
- Stream 客户端是否保持长驻运行，断开后能否自动重连；
- 长耗时任务是否先回复了“正在处理”再异步执行；
- OpenClaw 的日志是否按“钉钉事件 -> 技能处理 -> 模型调用 -> 回复消息”四个阶段分开打印，方便排查。
日志分级这一点容易被忽略。一开始我也把所有信息全混在 stdout 里，出了问题根本不知道卡在哪一环。后来改成每个阶段打一个前缀，例如[dingtalk]、[skill]、[model]、[reply]，排查效率翻了不止一倍。
5. 常见问题与排查技巧实录
5.1 返回 ok 但群里没有消息
这是发生频率最高的问题。钉钉接口返回{"errcode":0,"errmsg":"ok"}，结果群里的消息就是看不见。大概率的原因有三个。
第一，自定义机器人的安全设置没通过。比如你选的是自定义关键词，但推送内容里没有那个关键词，消息就会被静默拒绝，接口照样返回 ok。第二，机器人已经被移出群，或者群内停用了机器人。第三，Markdown 内容触发了钉钉的内容限制，这个比较隐蔽，接口返回 ok，但实际没有投递成功。我的排查顺序是：先检查消息文本是否包含要求的关键词，再检查机器人是否还群里，最后看 Markdown 语法是否含有被拦截的标签。
5.2 加签出现 sign 不匹配
签名问题死磕过的人应该都有印象。我总结出四个高频原因：
- timestamp 用的是秒而不是毫秒；
- timestamp 与钉钉服务器时间差超过 1 小时，钉钉会直接拒绝；
- 拼接签名时换行符丢失，
字符串 = 时间戳 + "\n" + secret； - Base64 编码后带
+号，没做 URL 编码。
只要这四项逐一对上，sign 不匹配基本都能解决。还有一个不太起眼但很常见的坑是：系统时钟不正确。如果你的服务器是物理机且没有做 NTP 时间同步，时间偏差超过小时级别，签名绝对验不过。
5.3 Stream 连接不上或者反复断开
Stream 模式连不上，先检查三件事。首先是 Client ID 和 Client Secret 是否对应 stream 模式生成的那一对，而不是 AppKey 和 AppSecret。其次是机器人是否已经发布上线，还在开发中状态的应用无法建立有效连接。最后是重复实例问题：钉钉允许同一应用建立多个 Stream 连接，但会踢掉旧连接。如果你本地调试跑了一个脚本，OpenClaw 服务里又跑了一个，后启动的实例会把前一个挤下线，表现出来就是连接反复断开。这种问题在日志里会看到 session 冲突之类的记录。
5.4 OpenClaw 回复慢或者超时
本地模型冷启动是最常见的原因。第一次调用时模型权重还在加载，会非常慢。解决办法是提前触发一次“预热”调用，把模型常驻内存。还有一个因素是配置的模型参数量对于当前设备的算力来说太大了，这种情况只能换更小体量的模型，或者降低生成参数中的最大 token 数。
OpenClaw 侧的超时设置也要检查。默认的超时时间可能只有 30 秒甚至更短，但如果模型推理本身就需要几十秒，那一定是超时报错。建议把超时时间设置成任务预估耗时的两倍，留足余量。下面的表是我遇到过的几个经典问题的汇总。
| 问题现象 | 大概率原因 | 解决办法 |
|---|---|---|
| 接口返回 ok 但群内无消息 | 安全设置未通过、机器人被移出群 | 检查关键词/加签配置，确认机器人状态 |
| sign 不匹配 | 毫秒/秒混淆、时间偏差、Base64 未编码 | 校准系统时间，核对签名算法 |
| Stream 反复断开 | ClientSecret 填错、重复实例连接 | 确认密钥对，确保只有单个实例 |
| OpenClaw 回复超时 | 模型冷启动、超时时间过短 | 预热模型，调大超时时间 |
| 权限调用返回 Forbidden | 应用未发布、权限未生效 | 发布应用，等待权限生效 |
最后再分享一个我实际使用中的体会：对接这类办公工具，一定要先做单向推送再做双向交互，每一步都能稳定跑通再进入下一步。不要着急把复杂功能全部一次接上，否则出问题时你会同时面对“钉钉配置对不对”“OpenClaw 技能写没写对”“模型回答质量差”三个变量，根本无从下手。等单向链路稳定之后，扩展双向对话、卡片回执、审批流联动这些玩法就都是水到渠成的事了。
