钉钉机器人接入教程：长连接模式绑定 WorkBuddy 并在群里 @ 它派活
从创建钉钉应用、开通机器人权限、取 Client ID/Secret，到 WorkBuddy 钉钉集成的 WebSocket 长连接与 URL 回调两种模式，全流程实操加常见问题排查。
钉钉是中小企业渗透率最高的协同工具之一，但也最容易沦为"打卡 + 收通知"的工具。群里每天几百条消息，真正需要人处理的没几条，剩下的全是催办、回执、同步、确认这类机械动作。
给钉钉挂一个 WorkBuddy 机器人，改的是协作姿势：谁在群里 @机器人 一句话，它把活领走、在你电脑上的 WorkBuddy 执行，再把结果贴回群里。人从"传话筒"退回成"决策者"。
两种接入模式，先选对 #
钉钉集成提供两种模式，选错是失败的最主要来源。
| 对比项 | WebSocket 长连接（强烈推荐） | URL 回调 |
|---|---|---|
| 前置条件 | 电脑能上网即可，无公网 IP 也能用 | 需要一台有公网 IP 的服务器 |
| 要填什么 | Client ID、Client Secret | 还要填 AES Key、Token、回调地址 |
| 配置步骤 | 少，填完点注册 | 多，还要回钉钉后台改模式 |
| 中小企业适配度 | 高 | 低，需要服务器和网络权限 |
| 典型场景 | 个人/家庭/办公室无固定 IP | 已有自建服务器、要做统一网关 |
一句话：没有公网 IP，一律选长连接。 有公网 IP 且要和其他系统统一收口的，才考虑 URL 回调。
前置条件 #
- 电脑上已安装 WorkBuddy，并已开启「助理」的远程控制。
- 钉钉账号需具备企业管理员权限——钉钉机器人的创建、权限开通、发布审核基本都要管理员角色，个人账号多半卡在第一步。
七步接入流程 #
第 1 步：创建应用并开通机器人能力
登录钉钉开发者后台 → 「应用开发」→「创建应用」→ 填写应用名称、描述、应用类型 → 创建。
进入应用详情 →「添加应用能力」→ 选择「机器人」→ 填写机器人名称、描述、预览图 → 确认发布。
机器人名称务必直观，比如「AI 助理-生产排产」，同事在群里找的是这个名字。
第 2 步：开通权限
左侧「权限管理」→ 搜索框逐项搜索并开通：
| 权限点 | 用途 |
|---|---|
Card.Streaming.Write | 卡片消息流式输出 |
Card.Instance.Write | 卡片实例写入（可交互卡片） |
qyapi_robot_sendmsg | 机器人发消息能力 |
搜不到某一条时，以开发者后台实际展示的权限列表为准，按名字对上即可。
第 3 步：取 Client ID 与 Client Secret
左侧「凭证与基础信息」→ 复制 Client ID（AppKey） 和 Client Secret（AppSecret）。这两个值就是机器人的身份证，后面要填进 WorkBuddy。
复制时留意有没有多余空格或换行，粘进配置框容易带进来，导致报"认证失败"。
第 4 步：配置事件订阅
左侧「开发配置 → 事件订阅」→ 推送方式选择「HTTP 推送」→ 点刷新，系统会自动生成 AES Key 和 Token。
这两个值务必单独保管好（建议存进你们的密码管理或内网记事本），后面切 URL 回调模式还要用。
第 5 步：在 WorkBuddy 里绑定
WorkBuddy → 助理设置 → 集成(BETA) → 钉钉集成 → 配置，把第 3 步的 Client ID 与 Client Secret 填进去，然后二选一：
- 选「WebSocket 长连接」：填完直接点注册，显示「已连接」即完成。到这步就结束了，公网服务器都不用买。
- 选「URL 回调」：需要先把第 4 步生成的 Webhook 地址填回钉钉——机器人配置页下滑到底部「消息接收配置」，把 Stream 模式切成 HTTP 模式，把 Webhook 粘贴进去（注意把 http 改成 https），然后发布。
第 6 步：发布应用（不做前面全白干）
应用详情 →「版本管理 / 查看版本详情」→ 填版本描述 →「确认发布」→ 等待管理员审核。
审核通过前，群成员是看不到这个机器人的。
第 7 步：让机器人进群，开始 @ 它
- 群聊用法：建群时注意群的归属组织要与机器人所属组织相同——跨组织的群加不进来，这是钉钉的常见坑。建好后 → 群设置 →「机器人」→「添加机器人」→ 选中刚创建的应用 → 在群里 @机器人 + 指令。
- 单聊用法：钉钉顶部搜索框直接搜索机器人名称，搜到就能私聊。
可复制的配置核对清单 #
{
"integration": "dingtalk-assistant",
"clientId": "粘贴 Client ID / AppKey",
"clientSecret": "粘贴 Client Secret / AppSecret",
"eventSubscribeMode": "http",
"aesKey": "第 4 步刷新生成，URL 回调模式才需要",
"token": "第 4 步刷新生成，URL 回调模式才需要",
"runMode": "websocket",
"status": "已连接"
}长连接模式下只看三个绿勾：clientId 非空、runMode 为 websocket、status 为「已连接」。
验证是否成功 #
- 群设置里确认机器人已添加到群。
- 群里 @机器人 发一句文字指令，看是否回复。
- 顶部搜索机器人，单聊发一条指令，看是否回复。
- 发一条涉及电脑本地文件的指令（比如"读一下 D 盘某个 txt 的第三段"）能执行成功——这才是真打通。
前 3 步只证明"消息通了"，第 4 步才证明"它在替你的电脑干活"。
常见坑与 FAQ #
Q1：群里搜不到机器人 / 添加不了。
绝大多数是群归属组织与机器人组织不一致。删了重建一个同组织的群，或在群里让管理员操作添加。
Q2：一直提示认证失败。
Client ID 或 Secret 复制时带了空格、换行，或者用错了应用（测试和正式是两个应用）。清掉重粘一次最有效。
Q3：没有公网 IP，该选哪个模式？
WebSocket 长连接。 它不要求 WorkBuddy 拥有一个能被公网访问的地址，电脑能上网就行。
Q4：AES Key 和 Token 忘了怎么办？
回「开发配置 → 事件订阅」，点刷新会重新生成一套。注意重新生成后旧值立即失效，URL 回调模式下要同步更新到 WorkBuddy。
Q5：权限开通了还是发不了消息。
权限必须随新版本发布才生效。回到第 6 步，发一个版本并等审核通过。
Q6：WebSocket 长连接为什么叫"长"？
因为 WorkBuddy 会持续持有一条连接到钉钉服务的通道，消息一来立刻有人接；URL 模式则是钉钉每次来"敲门"、你的服务器开门迎客。前者对中小企业几乎是无脑更优解。
Q7：机器人回复很慢或断断续续。
看那台电脑是否休眠、WorkBuddy 是否在运行、钉钉集成状态是否还显示「已连接」。长连接怕的就是电脑睡着。
Q8：长连接为什么偶尔会掉线？
长连接是"电脑 → 钉钉服务"之间的一条持续通道，电脑进出睡眠、切换 Wi-Fi、跑流量调度策略都可能把它掐断。稳定跑的做法有三条：电源选项设为永不休眠、网络设置里把 WorkBuddy 加入"允许后台联网/不限制数据"的白名单、集成状态≠已连接时先重启 WorkBuddy 触发重连。
Q9：卡片消息（可交互按钮）能配吗？
钉钉的卡片类权限（如 Card.Streaming.Write、Card.Instance.Write）就是为可交互卡片准备的：机器人可以推一张带"同意/驳回"按钮的卡片，点击回传结果。但这类能力属于锦上添花，先把纯文字指令跑通再上卡片，否则排查面会大很多。
小结 #
钉钉这条链路里，长连接 + 群归属一致 + 发版审核这三件事决定了 90% 的成败。绕开公网服务器这一关，中小企业接入成本能压到最低。
本系列属于「专家与连接器」模块。帮公司批量开通权限、过审核、建群与角色配置，本站提供 1v1 部署陪跑。
相关阅读：企业微信助理接入教程 · 飞书机器人接入教程 · 群机器人 Webhook 与定时推送