> 内容来源：Onevium 官方文档
> 文章: 连接钉钉机器人
> 原文: https://onevium.com/zh/docs/channels/dingtalk
> 语言：简体中文
> 更新于: 2026-09-09
> 适用版本: 1.1.22
> 功能状态: 已发布

---

# 连接钉钉机器人

配置钉钉 Stream 机器人，在 Onevium 中连接，并检查消息与卡片的实际结果。

## 连接钉钉 Stream 机器人

创建企业机器人，把凭据填入 Onevium 1.1.22，再验证群消息进入项目助手。这里使用企业应用的 Stream 凭据，不是群自定义 Webhook 地址。

## 创建并发布机器人

1. 打开[钉钉开发者后台](https://open-dev.dingtalk.com/)，创建企业内部应用。
2. 到**应用能力 → 添加应用能力 → 机器人**，填写名称、图标、描述和消息预览图。
3. **消息接收模式**选择 **Stream**，发布/保存机器人。接收 URL 是 HTTP 模式的配置，本流程不用填写。
4. 发布应用，将测试用户纳入可用范围，把机器人加入测试群。
5. 在应用凭据中取得 **Client ID / App Key** 与 **Client Secret / App Secret**。

步骤依据钉钉[机器人配置指南](https://open.dingtalk.com/document/orgapp/configure-the-robot-application)及[官方 Stream SDK 说明](https://github.com/open-dingtalk/dingtalk-stream-sdk-nodejs)。普通机器人消息通过 Stream 机器人回调接收，不需要另编一个事件订阅主题。

## 开通消息和卡片能力

在应用的**权限管理**搜索下列准确能力名称，组织要求审批时先完成审批：

| 用途           | 平台权限名称                             | Onevium 使用接口                                                         |
| ------------ | ---------------------------------- | -------------------------------------------------------------------- |
| 群聊和私聊回复      | 企业内机器人发送消息权限                       | `/v1.0/robot/groupMessages/send`、`/v1.0/robot/oToMessages/batchSend` |
| 创建卡片、更新最终状态  | 互动卡片实例写权限                          | `/v1.0/card/instances/createAndDeliver`、`/v1.0/card/instances`       |
| 逐步更新 AI 卡片文字 | AI卡片流式更新权限（`Card.Streaming.Write`） | `/v1.0/card/streaming`                                               |

对应官方[群消息接口](https://open.dingtalk.com/document/orgapp/the-robot-sends-a-group-message)、[创建投放卡片](https://open.dingtalk.com/document/orgapp/create-and-deliver-cards)、[更新卡片](https://open.dingtalk.com/document/orgapp/interactive-card-update-interface)及[流式卡片指南](https://open.dingtalk.com/document/orgapp/typewriter-effect-streaming-ai-card)。按功能配置即可，不需要把所有带“消息”“卡片”的权限全部勾选。

## 在 Onevium 注册连接

打开**渠道 → 新建渠道 → 单个机器人 → 钉钉**，填写 App Key 和 App Secret，点击**注册凭据**。Stream 检查通过后继续配置。

| 字段     | 首次示例            |
| ------ | --------------- |
| 机器人名称  | `项目助手`          |
| 描述     | `回答演示项目的问题`     |
| 模型     | 已在普通对话验证的提供商/模型 |
| 工作目录   | 演示项目目录          |
| 会话模式   | 每人独立会话          |
| 聊天范围   | 首次选仅群聊          |
| 自动批准操作 | 每项操作前询问         |
| 系统提示词  | 下方简短指令          |

```text
回答选定演示项目的问题。
检查代码或文档时给出文件依据。
连接测试时，在当前会话记住测试代号。
不要仅为回答问题而修改文件。
```

保存后核对运行状态，停止时点击启动。平台提供“测试长连接”入口时，应在 Onevium 连接期间测试。简易表单用 App Key 作为机器人代码的回退值，没有单独的自定义卡片模板字段。

## 验证往返和上下文

在测试群 @机器人：“测试代号 beta-27。”第二轮再 @它询问代号。核对两轮回复可读，并在 Onevium 找到对应会话。

需要私聊时，调整**聊天范围、私聊策略**；**允许用户**填写平台用户 ID，每行一个，不填显示名称。已有聊天另有**聊天设置 → 会话模式**，上下文意外共享时检查这里。

## 理解流式卡片

1.1.22 使用内置 AI 卡片模板。用户不需要随意新建模板再把 ID 填入 Onevium，这个版本也没有相应输入项。

遇到模板错误时保留平台错误和模板 ID，检查卡片权限，再确认是否收到可读的回退消息。组织无法使用内置模板时，应反馈版本兼容问题；创建另一个 ID 的模板不会改变客户端内置选择。文件、成员和群历史访问也应与文字回复分别开通和测试。

## 按现象排错

| 现象       | 下一步                              |
| -------- | -------------------------------- |
| 注册失败     | 核对 Key/Secret、机器人发布状态和 Stream 模式 |
| 已连接但收不到  | 检查应用可用范围、群成员和实际 @方式              |
| 收到后卡住    | 查看 Onevium 会话中的模型错误和待审批动作        |
| 空卡片或卡片失败 | 检查实例写入/流式权限和模板错误，核对最终回退文字        |

## 下一步

上下文共享见[渠道设置](https://onevium.com/zh/docs/team-channels)，定期投递见[自动化](https://onevium.com/zh/docs/scheduled-runs)。其他平台可参考[飞书接入](https://onevium.com/zh/docs/channels/feishu)。