---
sidebar_position: 2
---

# 钉钉集成配置指南

本指南详细介绍如何在 Wegent 中配置钉钉 IM 通道集成。

---

## 📋 目录

- [前置条件](#-前置条件)
- [步骤 1：创建钉钉应用](#-步骤-1创建钉钉应用)
- [步骤 2：配置应用权限](#-步骤-2配置应用权限)
- [步骤 3：获取应用凭证](#-步骤-3获取应用凭证)
- [步骤 4：启用消息流模式](#-步骤-4启用消息流模式)
- [步骤 5：在 Wegent 中配置 IM 通道](#-步骤-5在-wegent-中配置-im-通道)
- [步骤 6：验证连接](#-步骤-6验证连接)
- [步骤 7：测试集成](#-步骤-7测试集成)
- [钉钉特定功能](#-钉钉特定功能)
- [常见问题](#-常见问题)
- [相关资源](#-相关资源)

---

## ✅ 前置条件

在设置钉钉集成之前，请确保您具备：

- [ ] 具有管理员权限的钉钉企业账号
- [ ] 访问[钉钉开放平台](https://open.dingtalk.com)的权限
- [ ] 具有管理员权限的 Wegent 实例
- [ ] 在 Wegent 中至少配置了一个智能体（Team）

---

## 🔧 步骤 1：创建钉钉应用

1. 登录[钉钉开放平台](https://open.dingtalk.com)
2. 导航至 **应用开发** → **企业内部应用**
3. 点击 **创建应用**
4. 填写应用信息：
   - **应用名称**：您的机器人名称（如 "Wegent AI 助手"）
   - **应用描述**：机器人用途的简要描述
   - **应用图标**：上传合适的图标

---

## 🔐 步骤 2：配置应用权限

为您的应用启用以下权限：

**机器人权限：**
- `qyapi_robot_sendmsg` - 发送机器人消息
- `qyapi_chat_manage` - 管理群聊

**AI 卡片权限（用于流式响应）：**
- `Card.Instance.Write` - 创建和更新 AI 卡片实例
- `Card.Streaming.Write` - 流式写入 AI 卡片内容

**用户信息权限：**
- `Contact.User.Read` - 读取用户信息
- `Contact.User.mobile` - 访问用户手机号（可选）

> 💡 **提示**：AI 卡片权限是实现流式响应效果所必需的。如果不启用这些权限，机器人将无法使用 AI 卡片功能，只能使用普通文本消息模式。

---

## 📝 步骤 3：获取应用凭证

1. 在应用设置中，导航至 **凭证与基础信息**
2. 复制以下值：
   - **Client ID** (AppKey)
   - **Client Secret** (AppSecret)

> ⚠️ **安全提示**：请妥善保管您的 Client Secret。切勿分享或提交到版本控制系统。

---

## 🔄 步骤 4：启用消息流模式

1. 在应用设置中，进入 **机器人配置**
2. 启用 **消息接收模式**：Stream 模式
3. 这允许 Wegent 通过 WebSocket 接收消息，无需配置回调 URL

---

## ⚙️ 步骤 5：在 Wegent 中配置 IM 通道

1. 以管理员身份登录 Wegent
2. 导航至 **管理后台** → **IM 渠道**
3. 点击 **添加渠道**
4. 填写配置：

| 字段 | 描述 | 示例 |
|------|------|------|
| **通道名称** | 此通道的显示名称 | "钉钉机器人" |
| **通道类型** | 选择平台 | 钉钉 |
| **Client ID** | 来自步骤 3 | `dingxxxxxxxx` |
| **Client Secret** | 来自步骤 3 | `xxxxxxxxxxxxxxxx` |
| **默认智能体** | 处理消息的智能体 | 从列表中选择 |
| **默认模型** | 覆盖模型（可选） | 留空使用智能体默认模型 |
| **启用 AI 卡片** | 使用流式 AI 卡片 | ✅ 推荐启用 |

5. 点击 **保存** 创建通道
6. 切换 **启用** 开关激活通道

---

## ✔️ 步骤 6：验证连接

1. 在 IM 渠道列表中检查通道状态
2. 状态应显示 **已连接**（绿色指示器）
3. 查看运行时长和最近错误信息（如有）

---

## 🧪 步骤 7：测试集成

1. 打开钉钉并找到您的机器人
2. 发送测试消息："你好"
3. 验证是否收到 AI 响应

---

## 🎨 钉钉特定功能

### 群聊机器人

将机器人添加到钉钉群聊：

1. 在群聊中点击 **群设置** → **智能群助手**
2. 点击 **添加机器人**
3. 选择您创建的机器人
4. 机器人现在可以响应群聊中的 @提及

### 单聊机器人

用户可以通过以下方式与机器人单聊：

1. 在钉钉中搜索机器人名称
2. 点击机器人卡片
3. 开始对话

### AI 卡片流式响应

钉钉 AI 卡片提供丰富的流式响应体验：

- 实时显示生成中的内容
- 支持 Markdown 格式
- 代码块语法高亮
- 可折叠的长内容

---

## ❓ 常见问题

### 连接问题

#### 通道显示"已断开"

**可能原因：**
1. Client ID 或 Client Secret 无效
2. 网络连接问题
3. 钉钉 API 服务中断

**解决方案：**
1. 在钉钉开放平台验证凭证
2. 检查 Wegent 服务器的网络连接
3. 尝试重启通道
4. 检查钉钉服务状态

#### 消息未被接收

**可能原因：**
1. 钉钉中未启用 Stream 模式
2. 机器人权限未配置
3. Wegent 中通道未启用

**解决方案：**
1. 验证钉钉应用设置中已启用 Stream 模式
2. 检查所有必需权限已授予
3. 确保通道已启用（开关已打开）

### 响应问题

#### 机器人无响应

**可能原因：**
1. 默认智能体未配置
2. 智能体未分配模型
3. 速率限制

**解决方案：**
1. 验证通道已选择默认智能体
2. 确保智能体有可用的模型配置
3. 检查通道状态中的速率限制错误

#### 响应缓慢或不完整

**可能原因：**
1. AI 卡片流式传输问题
2. 网络延迟
3. 响应内容过大

**解决方案：**
1. 尝试临时禁用 AI 卡片流式传输
2. 检查网络连接
3. 系统会在流式传输失败时回退到同步模式

### 用户问题

#### 用户未被识别

**可能原因：**
1. 用户映射配置问题
2. 钉钉用户信息不可访问

**解决方案：**
1. 检查钉钉应用中的用户权限
2. 验证用户映射配置
3. 联系管理员配置企业用户映射

#### 用户创建失败

**可能原因：**
1. 缺少 `Contact.User.Read` 权限
2. 钉钉员工 ID 获取失败

**解决方案：**
1. 确保已授予读取用户信息的权限
2. 重新授权应用权限
3. 检查钉钉用户是否在企业组织架构中

---

## 🔗 相关资源

### Wegent 文档
- [IM 通道集成概述](./im-channel-integration.md) - 通用 IM 集成概念和功能
- [智能体设置](../settings/agent-settings.md) - 为 IM 通道配置智能体
- [配置模型](../settings/configuring-models.md) - 设置 AI 模型

### 钉钉官方资源
- [钉钉开放平台文档](https://open.dingtalk.com/document/)
- [钉钉 Stream 模式指南](https://open.dingtalk.com/document/orgapp/receive-message)
- [钉钉机器人开发指南](https://open.dingtalk.com/document/robots/develop-robots)
- [企业内部应用开发指南](https://open.dingtalk.com/document/isvapp-server/create-an-application)

### 获取帮助
- 📖 查看 [Wegent 常见问题](../../faq.md)
- 🐛 提交 [GitHub Issue](https://github.com/wecode-ai/wegent/issues)
- 💬 钉钉开放平台技术支持

---

<p align="center">将您的 AI 智能体连接到钉钉，赋能您的团队！ 🚀</p>
