钉钉 Bot 接入
把 Multica 智能体接入你自己的钉钉 app——在钉钉开放平台创建一个 Stream 模式的机器人、复制它的 AppKey 与 AppSecret、粘贴进 Multica，然后就能在钉钉里私聊它、在群里 @ 它，或输入 /issue。
把任意智能体接入一个钉钉 Bot，团队就能在钉钉里直接使用它——私聊 Bot、在群里 @ 它、发截图给它，或者输入 /issue 直接创建一个 Multica issue，不用打开应用。
钉钉集成由社区维护：每个版本都会随包发布，但不附带官方支持 SLA。遇到问题请提到 GitHub issues。
钉钉走的是自带应用（bring-your-own-app，BYO）模式：workspace 管理员创建一个钉钉 app，给它加一个 Stream 模式的机器人，再把它的凭证粘贴进 Multica。每个智能体都有它自己的钉钉 app——所以多个智能体可以在同一个组织里各自拥有一个独立、可单独 @ 的 Bot。（这一点和 Lark 不同，Lark 的绑定是扫码安装流程。）
整个设置流程在下面，大约五分钟。最后你会得到两个凭证粘贴进 Multica：
- 一个 AppKey —— app 的 client id
- 一个 AppSecret —— app 的 client secret
设置你的钉钉 app
1. 创建 app 并添加一个 Stream 模式的机器人
- 打开钉钉开放平台，创建一个企业内部应用。
- 进入该应用，添加机器人能力。
- 在机器人设置里，把消息接收模式设为 Stream 模式（推送模式）。正是这一项让 Bot 通过一条长连接向外推送接收消息，而不是去接收一个 webhook。
这就是 Multica 在平台层所需的一切——它通过 Stream 模式向外连接，所以你不用配置任何公网地址：
| 配置项 | 为什么需要它 |
|---|---|
| 企业内部应用 | 承载机器人、并签发 AppKey / AppSecret 凭证的那个 app 容器。 |
| 机器人能力 | 创建被 @ 和发回复用的那个 Bot 身份。 |
| Stream 模式 | Bot 通过一条长连接的 Stream 向外连接——无需任何公网 webhook / URL。 |
| 机器人发送权限 | 让 Bot 能把消息发回钉钉（智能体的回复以及主动消息）。 |
| 消息读取权限 | 让 Bot 能接收单聊消息，以及群里 @ 了它的消息。 |
这里既没有 webhook URL，也没有 OAuth 重定向 URL，因为机器人跑在 Stream 模式上，而 BYO 不使用 OAuth。
钉钉没有原生的「正在输入」/ 表情回应指示器，所以——和 Slack 不同——Bot 会在开始处理时先回一条简短的「正在处理」提示，完整回复在智能体处理完后送达。短时间内连发的多条消息会合并为一条提示。
2. 给机器人授权
给机器人授予它需要的权限，让它既能接收消息又能把消息发回去（机器人消息发送权限）。没有发送权限，智能体能跑，但它的回复发不出来。
3. 复制 AppKey 和 AppSecret
打开该应用的 凭证与基础信息，复制：
- AppKey —— 这就是你 app 的 client id
- AppSecret —— 这就是你 app 的 client secret
4. 在 Multica 里连接它
- 在 Agents → 你的智能体 打开该智能体 → Integrations tab（或左侧栏的 Integrations 区块）。
- 点击 Connect DingTalk。
- 粘贴 AppKey 和 AppSecret，然后点击 Connect。
- 智能体显示 Connected to DingTalk。Bot 现在通过它自己的 Stream 连接在监听了。
这两个凭证必须来自同一个钉钉 app，而那个 app 恰好对应一个智能体。连接一个已经连到别的智能体或 workspace 的 app 会被拒绝。要把一个 app 挪到另一个智能体，先断开它；用一个新的 app 重新连接某个智能体，会就地更新那个智能体的 Bot。
要给多个智能体做这套设置？每个智能体都把整套流程走一遍——每个智能体都有自己的钉钉 app 和自己的一对 AppKey / AppSecret，它们会在你的组织里显示成各自独立的 Bot。
这个集成能做什么
| 入口 | 行为 |
|---|---|
| 智能体 → Integrations | 所有者和管理员能看到 Connect DingTalk；连接后它会变成一个 Connected to DingTalk 徽标，并带一个 Disconnect 操作。 |
| 私聊 Bot | 工作区成员在单聊里直接给 Bot 发消息。这段对话会成为该智能体的一个 Multica chat 会话；每一条消息都会被读取。 |
| 群里 @ 它 | 把 Bot 加进群再 @ 它。只有 @ 它的那条消息会被读取——Bot 不会监听整个群。 |
| 发图片 | 单聊里的图片、或群里随 @ 一起发的图片，都会进入对话让智能体看到——支持 PNG、JPEG、GIF、WebP、BMP，每条消息最多 4 张、每张不超过 10 MB。每张图片都会复制进 Multica 存储，所以钉钉的临时链接过期后，它在对话里依然可见。文件和语音不支持。 |
/issue 命令 | 以 /issue <标题> 开头，会按输入直接、同步地以你的身份创建 Multica issue，并在原对话中返回 issue 编号和标题；后续行会作为描述。同一条钉钉消息中的图片只附在聊天消息上，不会复制到直接创建的 issue。 |
/new 命令 | 以 /new <你的消息> 开头，会让这条消息在不带旧上下文的情况下运行。单独发送 /new 会把同样的 fresh 意图留给下一条非空消息，不会创建空 turn；已有对话记录保持不变。 |
| 回复 | 智能体的答复会被发回同一个单聊或群里。 |
使用 Bot（成员）
第一条消息：绑定你的账号
第一次 @ 或私聊 Bot 时，它会回一条 绑定你的账号 提示，指向产品内的 /dingtalk/bind 页面。点开链接、登录 Multica，你的钉钉身份就会绑定到你的 Multica 成员身份——正是这一步让智能体能以你的身份行事（比如 /issue 会把 issue 记在你名下）。这个链接是一次性的，大约 15 分钟后过期；再给 Bot 发条消息就能拿到一个新的。
只有工作区成员才能使用 Bot。如果你不是成员，或者跳过了身份绑定，Bot 不会运行——你的消息会被丢弃（仅出于审计目的记录，不保存消息内容）。
对话与命令
- 在群里 —— 把 Bot 加进群，然后
@your-bot <你的消息>。每次追问都要重新 @ 它一下（Bot 只读取 @ 了它的消息）。 - 在单聊里 —— 打开 Bot 并直接给它发消息；不用 @，每一条消息都会被读取。
- 发图片 —— 直接发截图或照片，带不带文字都行；它们会进入对话，供智能体查看。支持 PNG、JPEG、GIF、WebP、BMP；每条消息最多 4 张，每张不超过 10 MB。
- 创建 issue —— 发送
/issue Safari 上登录跳转坏了，需要时可在后续行补充描述。Multica 会同步创建 issue，并在聊天中返回编号和标题。同一条消息中的图片只保留在聊天消息上，不会附到 issue。 - 重新开始 —— 发送
/new <你的消息>，让这条消息不带旧上下文运行；也可以单独发送/new，把 fresh 意图应用到下一条非空消息。两种方式都不会删除已有对话记录。
管理与断开
工作区级别的管理在 Settings → Integrations：
- Connected bots 列出工作区里每个 Bot 以及它各自绑定的智能体（所有成员都能看到）。
- Disconnect 仅限 所有者 / 管理员。它会让 Bot 停止接收钉钉消息并拆掉它的连接；安装记录会保留以便审计，之后你可以重新连接。
权限
- 连接 / 断开 需要工作区所有者或管理员。
- 和 Bot 对话 需要你是工作区成员且已绑定钉钉身份。其余的人一律被丢弃。
- 对于被丢弃的消息，绝不保存消息内容——只记录一个丢弃原因，用于审计。
自部署配置
在 Multica Cloud 上这个集成已经可用——可跳过本节。
自部署时，在你设置好静态加密密钥之前，钉钉是关闭的。这个密钥会在每个 app 的 AppSecret 落库前对其加密；AppKey 作为非敏感的安装路由标识明文保存。BYO 在部署层面不需要 OAuth client id/secret——每个安装用的都是管理员粘贴进来的那对凭证。
-
生成一个 32 字节的密钥并设置到 API 服务器：
MULTICA_DINGTALK_SECRET_KEY=<base64-encoded 32-byte key>例如：
openssl rand -base64 32。 -
重启 API。在密钥设置好之前，Settings → Integrations 会显示一条「DingTalk integration not enabled」提示，Connect DingTalk 入口也会保持隐藏。
这个密钥必须正好解码出 32 字节——openssl rand -base64 32 就能做到。把它当成一个长期有效的密钥：轮换或丢失它会让已存储的凭证无法解密，迫使每个 Bot 重新连接。「绑定你的账号」链接是用你的 Web 应用地址（MULTICA_APP_URL，未设置时回退到 FRONTEND_ORIGIN）拼出来的——正常部署里这个值本来就有，不需要额外配置。