📌 本文摘要

本指南用于把 UOSAI 助手 接入到 钉钉（DingTalk）。

你只需要照着做：创建钉钉应用 → 添加机器人并选择 Stream 模式 → 创建 AI 消息卡片 → 开通权限 → 发布版本 → 拿到 Client ID/Secret → 在 UOSAI 后台填入 → 验证连接通道 → 测试。

🚀 开始前你需要准备什么

• 你能登录 钉钉开放平台：https://open-dev.dingtalk.com/

• 你的钉钉账号在企业内具备 开发者权限（没有权限会创建不了应用/开通不了权限）

• 你本地已经启动了 UOSAI，并能打开应用设置。

  

💡 1.创建钉钉应用（企业内部应用）

1. 登录钉钉开放平台：https://open-dev.dingtalk.com/

   注意：创建钉钉应用前，请确保你的账号具备开发者权限。

   

2. 在左侧目录树中选择 “企业内部应用” -> “钉钉应用” -> “创建应用”
   

   3.填写应用名称、图标等信息后保存。

   

   💡 2.添加机器人，并设置消息接收模式为 Stream

   1. 在应用配置里找到“机器人”相关入口，点击 添加机器人。

   

   2. 点击按钮进入机器人配置。

      

   3. 填写机器人简介、描述、预览图等，点击发布。

   4. 非常关键：消息接收模式选择 Stream 模式。

      

      💡 3.创建消息卡片（推荐：AI 卡片）

      这一步用于让钉钉侧可以使用 AI 互动卡片能力。按项目当前文档建议，推荐配置。

      1. 登录 钉钉卡片平台：https://open-dev.dingtalk.com/fe/card
      2. 左侧选择 “模板管理” -> “新建模板”。
      3. 按下列信息配置模板：

      • 卡片类型：消息卡片

      • 卡片模板场景：AI 卡片

      • 关联应用：选择你刚创建的钉钉应用

        

      4. 进入卡片模板编辑页面后，无需修改内容，点击左上角ID（非必需，流式卡片体验较好），提示复制成功后，依次点击 “保存” 和 “发布”。（保存好id信息，若丢失可回到该页面寻找）

         

      💡 4.授予应用必要权限

      1. 回到钉钉开放平台，进入：“应用开发” -> “钉钉应用”。

      2. 点击你的应用名称进入详情。

         

      3. 左侧进入 “开发配置” -> “权限管理”。

      4. 搜索并申请以下权限（按文档要求）：

      • 搜索 Card：勾选

        • 互动卡片实例写权限

        • AI卡片流式更新权限

          

        • 搜索 qyapi_robot_sendmsg：开通

        • 企业内机器人发送消息权限

          如果你申请权限时提示需要管理员审批，请按企业流程完成审批，否则机器人可能无法发消息或更新卡片。

          💡 5.发布应用版本（不发布通常无法给企业用户使用）

          1. 左侧进入 “应用发布” -> “版本管理与发布”，点击** “创建新版本”**。

             

          2. 填写版本号、可见范围等，点击 “保存”，再点击** “确认发布”**。

             
             

             💡 6. 获取凭证信息（Client ID / Client Secret）

             1. 左侧进入 “基础信息” -> “凭证与基础信息”。

             2. 复制并保存：Client ID 和 Client Secret

                

             💡 7.在 UOSAI 后台完成钉钉配置

             1. 确保 UOSAI 已启动。
             2. 找到 找到IM接入中的 钉钉 / DingTalk 的配置项：
             • 打开“启用/开关”
             • 将第3步的card ID 和 第 6 步的 Client ID 和Client Secret 填入对应位置
             4. 点击 保存配置。
                

             💡8.测试是否接入成功

             1. 启动 uos-ai。

             2. 在钉钉群里与机器人对话（或 @ 机器人）。（进群 - 添加 - 搜索添加正确的机器人 - 完成添加）

                
                如果机器人能正常回复，说明接入成功。

                常见问题

                Q1：机器人收不到消息？

                • 确认第 2 步选择的是 Stream 模式
                • 确认第 8 步 验证连接通道 已保存
                • 确认权限已申请并通过审批（第 3 步）

                Q2：机器人能收消息，但发不出去？

                • 优先检查是否开通了 qyapi_robot_sendmsg（第 3 步）
                • 再检查 UOSAI 后台的Client ID 和 Client Secret 是否填错（第 7 步）

                安全提示

                • Client Secret 属于敏感信息：不要公开分享、不要提交到公开仓库。
                • 建议使用密码管理器保存。

                飞书（Feishu）接入配置指南

                QQ（机器人） 接入配置指南