LobeHub
LobeHub

将 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 字段。

将机器人添加到群聊

要在钉钉群中使用机器人:

  1. 打开群的 群设置 → 机器人 → 添加机器人
  2. 按名称搜索您的企业内部应用机器人并添加
  3. 在消息中 @ 机器人以触发回复

钉钉只会推送 @ 机器人的群消息;单聊中机器人会收到全部消息。

接入策略

两个独立的策略控制入站消息,默认都为 开放。

允许的用户 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。