将 LobeHub 连接到钉钉
通过将钉钉渠道连接到您的 LobeHub 代理,组织内的成员可以直接在钉钉中与 AI 助手对话:既可以单聊,也可以在群聊中 @ 机器人。
前置条件
- 一个拥有有效订阅的 LobeHub 账户
- 一个钉钉组织账号,并具备在钉钉开发者后台创建企业内部应用的权限
连接模式
LobeHub 支持两种钉钉机器人连接模式:
- WebSocket — 对应钉钉的 Stream 模式:LobeHub 主动与钉钉建立出站长连接,无需公网回调地址。这是钉钉官方推荐的方式,也是新机器人的默认模式。
- Webhook — 对应钉钉的 HTTP 回调 模式:钉钉把每条消息推送到 LobeHub 的回调地址。如果您的机器人已经配置了消息接收地址,请使用此模式。
注意: LobeHub 中选择的连接模式必须与钉钉开发者后台中机器人的 消息接收模式 一致。
第一步:创建钉钉企业内部应用机器人
打开开发者后台
访问 open-dev.dingtalk.com,使用您的钉钉组织账号登录。
创建企业内部应用
进入 应用开发 → 企业内部应用,点击 创建应用。填写应用名称(例如 "LobeHub 助手")、描述和图标,然后保存。
复制应用凭证
打开应用,进入 凭证与基础信息,复制以下内容:
- Client ID(原 AppKey,通常以
ding开头) - Client Secret(原 AppSecret)
重要提示: 请妥善保管您的 Client Secret,切勿发到群聊或出现在公开截图中。
添加机器人能力
在应用中进入 添加应用能力,添加 机器人。填写机器人名称、头像、简介等信息。
设置消息接收模式
在机器人配置页设置 消息接收模式:
- Stream 模式 — 对应 LobeHub 默认的 WebSocket 连接模式,无需填写回调地址。
- HTTP 回调 — 对应 LobeHub 的 Webhook 模式。完成第二步后,再把 LobeHub 的回调地址粘贴到这里。
保存机器人配置。
开通权限
进入 权限管理,开通:
qyapi_robot_sendmsg— 企业内机器人发送消息权限。机器人在临时回复会话之外发送消息(例如主动单聊、群发)时需要此权限。
如果希望助手读取用户发送的文件、图片等附件,建议同时开通机器人接收消息的文件下载相关权限。
第二步:在 LobeHub 中配置钉钉
打开渠道设置
在 LobeHub 中,导航到您的代理设置,然后选择 渠道 标签页。从平台列表中点击 DingTalk(钉钉)。
输入应用凭证
填写以下字段:
- Client ID(AppKey) — 钉钉应用的 Client ID
- Client Secret(AppSecret) — 钉钉应用的 Client Secret
- RobotCode(可选)— 大多数情况下留空即可。企业内部应用机器人的 RobotCode 就是 Client ID,留空时自动使用。仅当机器人页面显示的编码不同时填写。
选择连接模式
在 高级设置 中,选择 连接模式:
- WebSocket(默认)— 适用于使用 Stream 模式 的机器人
- Webhook — 适用于使用 HTTP 回调 的机器人。保存后复制回调地址用于下一步
保存配置
点击 保存配置。LobeHub 会保存机器人,然后通过钉钉的 accessToken 接口校验凭证并建立连接:
- Client ID 或 Client Secret 无效时,配置仍会保存,但连接失败,页面会显示钉钉返回的错误。修正凭证后再次保存即可重新连接。
- 钉钉返回的权限、网络或限流问题也会提示出来,修正后重试即可。
您的凭证将被加密并安全存储。
- 在 WebSocket 模式 下,LobeHub 会自动通过 Stream 模式连接钉钉。
- 在 Webhook 模式 下,保存后将显示 Webhook URL。回到钉钉开发者后台的机器人配置,把它粘贴为机器人的消息接收地址并保存。
Webhook 模式的签名与加密
使用 HTTP 回调时,无需在 LobeHub 或钉钉中配置额外的签名或加密参数:
- 签名: 钉钉在每次回调的请求头中携带
timestamp(毫秒时间戳)和sign。LobeHub 使用您填写的 Client Secret 按Base64(HmacSHA256(timestamp + "\n" + Client Secret))计算并比对。签名缺失、不匹配,或timestamp与当前时间相差超过 1 小时,请求都会被拒绝并返回401。 - 加密: 机器人消息回调的请求体是明文 JSON,因此没有 Token 或
aes_key需要填写。钉钉 事件订阅 中的这两项不用于此回调。回调内容由 HTTPS 保护,因此 Webhook URL 必须是公网可访问的 HTTPS 地址。LobeHub Cloud 已满足此要求;自托管部署请通过公网 HTTPS 域名访问 LobeHub 后再复制该地址。
轮换 Client Secret 后: 请同时在 LobeHub 中更新。否则钉钉的回调会因签名不匹配而被拒绝,机器人将不再回复。
第三步:发布应用
创建并发布版本
在钉钉开发者后台进入 版本管理与发布,创建新版本并发布。企业内部应用发布无需平台审核。
设置可见范围
发布时设置 可见范围,把需要使用机器人的成员或部门包含进来。不在可见范围内的成员无法搜索到机器人,也无法与它对话。
第四步:测试连接
在 LobeHub 的渠道设置中点击 测试连接 以验证凭证。然后在钉钉中按名称搜索机器人,单聊发送一条消息。机器人应通过您的 LobeHub 代理进行回复。
填写你的平台身份(推荐)
高级设置里有一个可选字段影响日常使用体验,建议一开始就填好。
你的平台用户 ID
也就是你在组织内的钉钉 userId(员工 ID)——不是手机号,也不是个人资料里的钉钉号。用于:
- 配对审批 — 当 私信策略 为 配对审批 时为必填项,
/approve <code>是属主命令,runtime 会用这个 ID 校验发起人。 - AI 工具主动推送 — 让 Agent 能主动联系你(提醒、通知),把内部用户引用映射到你的钉钉账号。
- 防自锁 — 自动被 允许的用户 信任,给同事收紧 bot 时不会把自己挡在外面。
获取方式(任选其一):
- 在钉钉管理后台 → 通讯录 → 成员详情中查看 userId;
- 在单聊中给机器人发送
/whoami。
把这个 ID 粘贴到 LobeHub 高级设置的 你的平台用户 ID 字段。
将机器人添加到群聊
要在钉钉群中使用机器人:
- 打开群的 群设置 → 机器人 → 添加机器人
- 按名称搜索您的企业内部应用机器人并添加
- 在消息中 @ 机器人以触发回复
钉钉只会推送 @ 机器人的群消息;单聊中机器人会收到全部消息。
接入策略
两个独立的策略控制入站消息,默认都为 开放。
允许的用户 ID(全局)
填入 允许的用户 后,单聊和群聊 @ 都必须来自列表里的钉钉 userId。留空则不做用户级过滤。
私信策略
- 开放 (Open)(默认) — 可见范围内的任何成员都可以与机器人单聊(若设置了全局白名单则受其约束)。
- 白名单 (Allowlist) — 单聊需要发送者在 允许的用户 里。和
Open的差别在白名单为空时:Allowlist模式全部拒绝。 - 配对审批 (Pairing) — 与
Allowlist共享同一份名单,但非名单用户被拒后会收到一次性配对码,由你(属主)通过/approve <code>审批。审批通过的用户会被自动追加到 允许的用户。需先填 你的平台用户 ID,并需要部署 Redis。 - 禁用 (Disabled) — 机器人忽略所有单聊,只在群聊里被
@时回复。
群组策略
控制机器人会在哪些钉钉群里响应。
- 开放 (Open)(默认) — 在机器人加入的任何群里被
@都响应。 - 白名单 (Allowlist) — 只在 允许的频道 列出的群里响应(填写群会话 ID
openConversationId,通常以cid开头)。 - 禁用 (Disabled) — 忽略所有群聊流量,机器人只接受单聊。
跨平台细节见 渠道概览。
配置参考
| 字段 | 是否必需 | 描述 |
|---|---|---|
| Client ID(AppKey) | 是 | 钉钉企业内部应用的 Client ID |
| Client Secret(AppSecret) | 是 | 钉钉企业内部应用的 Client Secret(加密存储) |
| RobotCode | 否 | 默认使用 Client ID。仅当机器人页面显示的编码不同时填写 |
| 连接模式 | 否 | websocket(默认,钉钉 Stream 模式)或 webhook(钉钉 HTTP 回调) |
| Webhook URL | — | Webhook 模式保存后显示;粘贴到机器人的消息接收地址 |
| 字符限制 | 否 | 每条回复消息的最大字符数(默认值和上限均为 4000) |
| 并发模式 | 否 | queue(默认)、burst 或 debounce — 并发消息的合并方式 |
| 允许的用户 | 否 | 钉钉 userId。全局闸门 — 单聊和群聊 @ 都受其约束 |
| 私信策略 | 否 | open(默认)、allowlist、pairing 或 disabled — 控制谁可以与机器人单聊 |
| 群组策略 | 否 | open(默认)、allowlist 或 disabled — 控制机器人在哪些群中响应 |
| 允许的频道 | 否 | 钉钉群会话 ID。仅在群组策略为白名单时使用 |
功能限制
- 不支持消息编辑 — 钉钉机器人消息无法编辑,因此不会流式展示中间步骤,只发送最终回复。
- 不支持表情回应 — 钉钉机器人没有表情回应接口。
- 群聊附件 — 在群里 @ 机器人时,钉钉不会推送语音、视频和文件消息;请改在单聊中发送。
- 出站文件 — 有公网地址的图片会以图片形式发送;助手发送的其他文件会以链接形式送达。
故障排除
- 连接时提示凭证无效: 从 凭证与基础信息 重新复制 Client ID 和 Client Secret,注意不要带空格。
- 连接时提示权限或网络错误: 确认应用未被停用、应用的 IP 白名单(如有)允许 LobeHub 访问;如果钉钉提示限流,请稍后重试。
- 连接失败并提示切换连接模式: 当前部署不支持 WebSocket 模式。请切换到 Webhook,并把机器人设置为 HTTP 回调。
- 收不到消息(WebSocket 模式): 确认机器人的消息接收模式为 Stream 模式,并且包含机器人能力的应用版本已经发布。
- 收不到消息(Webhook 模式): 确认机器人使用 HTTP 回调,且消息接收地址与 LobeHub 中显示的 Webhook URL 一致。
- 回调返回
401 Invalid signature: LobeHub 中的 Client Secret 与该应用当前的 Client Secret 不一致(常见于轮换之后),或回调的timestamp与当前时间相差超过 1 小时。重新复制 Client Secret 并保存;如果请求经过代理转发,确认timestamp和sign请求头被原样保留。 - 搜索不到机器人: 检查应用的 可见范围 是否包含该成员,以及应用是否已发布。
- 群聊不回复: 确认机器人已加入该群,且消息中 @ 了机器人;同时检查高级设置中的 群组策略。
- 单聊不回复: 检查 私信策略。如果是
Allowlist,确认发送者的userId已在 允许的用户 中。 - 一段时间后回复失败或无法主动发消息: 确认已在 权限管理 中开通
qyapi_robot_sendmsg。