# 钉钉接入

连接应用机器人与 Stream，分别验证单聊、群聊和回复。

## 使用应用机器人接入

Nexus 的钉钉通道使用应用机器人与官方 Stream 模式接收单聊或群聊消息。先确认目标 Agent 在 Nexus 内可以回答，再准备有权管理钉钉应用的账号。

Stream 由 Nexus 主动建立连接。普通接入不需要先给服务器新增公网消息回调，但运行机器仍需能访问钉钉服务。

## 通过扫码创建机器人

在 **能力 → 频道 → 钉钉** 打开扫码入口，使用钉钉完成创建或授权。返回 Nexus 后等待配置确认，检查连接状态，再进入配对测试。

如果二维码过期，重新生成。外部授权完成而 Nexus 显示结果待确认时，先读取最新状态，避免重复创建机器人。

## 使用已有应用

已有应用可以手工填写凭据。先在应用后台确认机器人已启用，接收方式为 Stream，且测试成员能够使用它。外部后台入口会随平台更新，以通道中的平台帮助为准。

| 字段 | 应填写什么 | 检查要点 |
| --- | --- | --- |
| Client ID | 应用 AppKey | 与密钥属于同一应用 |
| Client Secret | 应用 AppSecret | 不使用另一应用的凭据 |
| Robot Code | 主动群发 OpenAPI 所需标识 | 普通接收回复不必为填满表单而添加 |
| OpenAPI Base URL | 默认 `https://api.dingtalk.com` | 用于平台接口 |
| Stream Base URL | 默认 `https://api.dingtalk.com` | 用于 Stream 接入 |

地址使用页面默认值，除非管理员给出明确替代端点。保存后检查连接，不把“字段已保存”当成 Stream 已经成功建立。

## 先验证单聊，再验证群聊

从自己的钉钉账号向机器人发送普通消息。在 Nexus **能力 → 配对** 中将该用户绑定到测试 Agent 与会话，再发送下面的请求。

```text
这是钉钉单聊测试，请只回复“钉钉测试已收到”。
```

两端都确认后，将机器人用于测试群，检查应用是否对群成员可用，并核对群对应的配对。单聊与群聊分别测试，不能共用一次验收结论。

## 收发链路怎样定位

Stream 接入负责把请求带到 Nexus；Agent 负责处理；回复还需要有效的外部会话与发送能力。

| 现象 | 先检查什么 |
| --- | --- |
| 连接未建立 | AppKey/AppSecret、Stream 设置与宿主网络 |
| 连接正常但无消息 | 应用可用范围、机器人所在聊天与配对 |
| 有消息但一直等待 | 绑定 Agent 的模型、问题与审批 |
| 处理完成但没有外部回复 | 原会话是否有效、平台发送错误 |

不要用填写 Robot Code 修复所有收发问题。它面向主动群发的特定接口，无法修复错误 AppSecret 或缺失的配对。重试前先看原聊天是否已有回复。

## 长期使用与更换应用

保持 Nexus 宿主在线。更换应用或轮换密钥后，在 Nexus 更新对应配置，再验证单聊与群聊。新应用需要重新核对外部身份和目标 Agent，原应用的测试记录不能证明新应用可用。