> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 钉钉

> 在钉钉中接入和使用专家

将你的 AI 专家接入钉钉工作台，让团队成员在钉钉消息中直接与专家对话。支持单聊和群聊两种场景，消息以多气泡形式呈现，工具调用过程实时通知。

## 接入方式

<AccordionGroup>
  <Accordion title="扫码快速接入（推荐）">
    最简单的接入方式：

    1. 在专家 Studio 的「渠道接入」中选择钉钉
    2. 点击「扫码接入」
    3. 使用钉钉管理员账号扫描二维码
    4. 确认授权，自动配置完成
    5. 在钉钉中搜索机器人名称开始测试

    扫码方式自动完成机器人创建和回调配置。
  </Accordion>

  <Accordion title="手动配置">
    需要精细控制时选择手动方式：

    <Steps>
      <Step title="创建钉钉机器人">
        登录[钉钉开放平台](https://open-dev.dingtalk.com)，进入应用开发 → 创建应用 → 添加「机器人」能力。
      </Step>

      <Step title="配置消息接收">
        在机器人配置页设置消息接收地址（HTTP 模式），将袋袋提供的回调 URL 填入。
      </Step>

      <Step title="填写凭证">
        将钉钉应用的 App Key 和 App Secret 填入袋袋的渠道配置面板。
      </Step>

      <Step title="发布应用">
        在钉钉开放平台提交应用发布，待审核通过后即可使用。
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## 消息格式

钉钉渠道采用「多气泡 + 工具通知」风格：

* 文本回复以 Markdown 卡片消息发送
* 工具调用时发送进度通知消息
* 最终回复在工具完成后统一发送
* 支持 Markdown 基础格式

## 使用场景

### 单聊对话

在钉钉通讯录或搜索中找到机器人，直接发送消息开始一对一对话。适合个人任务和隐私性对话。

### 群聊协作

将机器人添加到群组后，群成员通过 @机器人 发送消息触发回复。适合团队协作、项目讨论等场景。

<Tip>
  将专家添加到项目群中，团队成员可以随时 @专家获取即时帮助，无需离开工作上下文。
</Tip>

## 配置步骤详解（手动模式）

如果你选择手动配置，以下是详细步骤：

<Steps>
  <Step title="创建应用">
    在钉钉开放平台创建「企业内部应用」，填写应用名称和描述。应用名称建议与你的专家名称保持一致。
  </Step>

  <Step title="添加机器人能力">
    在应用的「能力管理」中添加「机器人」能力，设置机器人的头像和描述信息。
  </Step>

  <Step title="配置回调地址">
    在「机器人配置」→「消息接收模式」中选择 HTTP 模式，将袋袋提供的 Webhook URL 填入消息接收地址字段。
  </Step>

  <Step title="配置权限">
    在「权限管理」中添加必要权限：

    * 企业内机器人发送消息
    * 消息发送到会话
    * 获取群会话信息
  </Step>

  <Step title="填入袋袋">
    回到袋袋专家 Studio 的渠道配置面板，填入 App Key 和 App Secret。
  </Step>

  <Step title="测试连通">
    在钉钉中给机器人发送一条测试消息，确认收到正确回复。
  </Step>
</Steps>

## 注意事项

<Warning>
  * 钉钉企业内部应用需要管理员权限才能创建和发布
  * 应用发布后需要等待审核通过
  * 群聊中的机器人需要被管理员添加到群
</Warning>

## 常见问题

<AccordionGroup>
  <Accordion title="机器人不回复">
    * 确认应用已发布且审核通过
    * 确认消息接收地址配置正确
    * 在群聊中确认已 @机器人
    * 检查袋袋服务端日志是否收到回调
  </Accordion>

  <Accordion title="消息延迟较大">
    钉钉消息回调有网络延迟，加上 AI 模型推理时间，总延迟通常在 3-15 秒。使用搜索等工具时会更长。这是正常现象。
  </Accordion>

  <Accordion title="群内其他成员能看到对话吗">
    群聊中的对话所有群成员都可见。如需私密对话请使用单聊模式。
  </Accordion>
</AccordionGroup>

## 相关页面

<CardGroup cols={2}>
  <Card title="渠道总览" icon="layer-group" href="/zh/documentation/channels/overview">
    了解所有 IM 平台概况
  </Card>

  <Card title="飞书接入" icon="message" href="/zh/documentation/channels/feishu">
    飞书渠道配置指南
  </Card>
</CardGroup>