跳到主要内容

钉钉集成配置指南

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

📋 目录​

✅ 前置条件​

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

  • 具有管理员权限的钉钉企业账号
  • 访问钉钉开放平台的权限
  • 具有管理员权限的 Wegent 实例
  • 在 Wegent 中至少配置了一个智能体（Team）

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

  1. 登录钉钉开放平台
  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来自步骤 3dingxxxxxxxx
Client Secret来自步骤 3xxxxxxxxxxxxxxxx
默认智能体处理消息的智能体从列表中选择
默认模型覆盖模型（可选）留空使用智能体默认模型
启用 AI 卡片使用流式 AI 卡片✅ 推荐启用
  1. 点击 保存 创建通道
  2. 切换 启用 开关激活通道

✔️ 步骤 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 文档​

钉钉官方资源​

获取帮助​

将您的 AI 智能体连接到钉钉，赋能您的团队！ 🚀