跳到主要内容

连接器

团队空间的所有者和管理员可在 设置 → 团队配置 中接入外部工具。钉钉群机器人和云效创建位于 快速创建（见下文）；云效工作项定时同步位于 连接器，详见云效连接器。普通成员可以查看接入状态和使用说明，但不能新增、启停或移除。

钉钉群机器人​

钉钉群机器人可以把群里的文本消息快速创建为 AntTodo 任务。它复用当前团队空间已经启用的钉钉 SSO 应用及 AppSecret，不需要再向 AntTodo 提交一套机器人密钥。

必须使用同一个钉钉应用

请在 配置 AntTodo 单点登录的同一个企业内部应用 中开启机器人能力，不要另外创建一个使用不同 Client ID / Client Secret 的机器人应用。否则钉钉回调签名无法通过。

前置条件​

开始前请确认：

  • 当前团队空间已启用钉钉单点登录。
  • SSO 的 CorpId、AppKey（Client ID）和 AppSecret（Client Secret）均来自同一个企业内部应用。
  • 操作者是 AntTodo 团队空间的所有者或管理员，同时具有钉钉应用管理权限。
  • 需要使用机器人的成员包含在钉钉应用可见范围内，并至少使用钉钉 SSO 登录过 AntTodo 一次。

需要申请的权限​

群机器人接收消息和通过消息中的 sessionWebhook 回复，不需要额外申请“发送工作通知”权限，也不需要 AgentId。

但 AntTodo 需要把群消息中的钉钉用户映射为团队成员，因此同一个应用仍需具备单点登录和通讯录读取权限：

权限点 / 控制台常见名称是否必需用途
Contact.User.mobile必需获取手机号，用于关联 AntTodo 账号
Contact.User.Read必需获取登录用户基本信息和 unionId
qyapi_get_member（通讯录成员读权限）必需根据 unionId 获取企业 userid，使机器人能识别发送者、负责人和参与人
企业内机器人发送消息 / 发送工作通知群机器人不需要仅在使用 AntTodo 的“钉钉通知”渠道时需要

若同时使用 AntTodo 的钉钉工作通知，还需填写 AgentId，并申请发送工作通知相关权限。详见通知配置。

权限新增或调整后，需要重新发布钉钉应用版本，并让成员重新使用钉钉 SSO 登录一次，以补全企业 userid 映射。

1. 在 AntTodo 接入机器人​

  1. 使用团队空间所有者或管理员账号进入 设置 → 团队配置 → 快速创建。
  2. 在页面中找到“钉钉群机器人”。
  3. 若页面提示尚未启用 SSO，点击“先启用 SSO”并完成配置。
  4. 点击“接入”。每个团队空间只能接入一个钉钉群机器人。
  5. 接入后点击“查看详情”，复制页面展示的 机器人消息接收地址。

消息接收地址由 AntTodo 自动生成。请完整复制，不要修改域名、路径或查询参数。

2. 在钉钉应用中开启机器人​

  1. 登录钉钉开发者后台，打开配置 AntTodo SSO 的企业内部应用。
  2. 进入 应用能力 → 机器人，开启机器人配置。
  3. 填写机器人名称、图标、简介、描述和消息预览图。
  4. 将 消息接收模式 设置为 HTTP 模式。AntTodo 当前不使用 Stream 模式。
  5. 将从 AntTodo 复制的地址粘贴到 消息接收地址。
  6. 点击“发布（保存）机器人”。
直接使用 AntTodo 消息预览图

点击下载钉钉群机器人消息预览图，然后上传到钉钉后台的 机器人消息预览图。文件为 PNG 格式，尺寸为 1536 × 1024，大小约 1.2 MB，可清楚展示“群消息创建任务 → 机器人返回任务详情”的使用效果。

消息预览图只用于添加机器人和应用审核时展示，不包含真实成员信息，也不会影响消息接收地址或机器人运行。

AntTodo 钉钉群机器人消息预览：成员在群聊中创建任务，机器人返回负责人、标签、截止时间和任务链接

消息接收地址必须是公网可访问的 HTTPS 地址。AntTodo 已在服务端校验钉钉请求的 timestamp 和 sign，AppSecret 只保存在 Supabase Vault 中，不会出现在回调地址或浏览器中。

本连接器使用钉钉回调和 sessionWebhook 回复，不依赖固定的服务器出口 IP。若同一应用还会自行调用其他钉钉 OpenAPI，请按那些接口的要求配置服务器出口 IP 白名单。

钉钉官方参考：

3. 发布钉钉应用​

仅保存机器人配置还不够，必须继续发布整个企业内部应用：

  1. 进入 应用发布 → 版本管理与发布 → 创建新版本。
  2. 填写版本号和版本描述。
  3. 在“待发布内容”中勾选 机器人；若应用已有工作台应用，请同时保留对应工作台发布内容，避免原入口被下线。
  4. 设置应用可见范围，覆盖所有需要使用机器人的成员或部门。
  5. 点击 保存 → 直接发布。

可参考钉钉官方的发布应用说明。

4. 将机器人加入群聊​

机器人只能加入与应用归属企业一致的 内部群：

  1. 在钉钉客户端打开目标内部群。
  2. 进入 群设置 → 群管理 → 机器人 → 添加机器人。
  3. 在“企业机器人”中选择刚发布的机器人。
  4. 点击 添加 → 完成。

若列表中找不到机器人，请检查应用是否已发布、发布内容是否包含机器人、应用可见范围是否覆盖当前成员，以及群归属企业是否与应用一致。详见钉钉官方的添加机器人入群。

5. 验证接入​

在目标群中发送：

@机器人 帮助

收到使用说明后，再测试创建任务：

@机器人 新建 修复登录问题 @负责人 #前端 明天下午3点

机器人会回复任务标题、负责人、标签、截止时间和 AntTodo 任务链接。

消息解析规则：

  • 新建、创建、新建任务 和 创建任务 均为可选命令词。
  • 首位被 @ 且已完成钉钉身份映射的成员作为负责人，其余成员作为参与人。
  • #标签 必须完整匹配发送者可管理且名称唯一的团队标签；无权限、不存在或重名的标签会被忽略。
  • “明天”“周五”“下午三点”，以及 2026.9.2 / 2026-09-02 / 2026/9/2 等带年份数字日期，按 Asia/Shanghai 解析。
  • 没有负责人时任务保持未指派；没有有效标签时进入收集箱。
  • 图片、文件等非文本消息不会创建任务。

常见问题​

提示“请先关联 AntTodo 账号”​

发送者尚未通过当前团队的钉钉 SSO 建立身份映射。请使用团队登录地址完成一次钉钉登录后重试。

如果成员已经登录过，但仍无法识别，请确认 qyapi_get_member 已开通并发布，然后让该成员重新登录一次。

机器人没有收到消息或提示配置不可用​

依次检查：

  1. 机器人消息接收模式是否为 HTTP。
  2. 消息接收地址是否与 AntTodo「快速创建」页面显示的地址完全一致。
  3. 机器人能力与 AntTodo SSO 是否属于同一个企业内部应用。
  4. 钉钉 SSO 和群机器人是否均处于启用状态。
  5. 机器人配置和应用版本是否都已发布。

机器人无法添加到群​

确认目标群是内部群，群归属企业与应用归属企业一致，并且当前成员在应用可见范围内。

重试后是否会重复创建任务​

不会。AntTodo 使用钉钉消息 ID 做幂等处理，同一条消息被钉钉重复投递时只会创建一个任务。

管理已接入连接器​

在 设置 → 团队配置 → 快速创建 中：

  • 所有成员可以查看状态、最近成功使用时间和配置步骤。
  • 所有者和管理员可以复制回调地址、启用、停用或移除机器人。
  • 停用或移除机器人不会修改钉钉 SSO 配置。
  • SSO 被停用后，连接器记录仍会保留，但不会处理群消息；重新启用 SSO 后可恢复。

云效创建​

云效创建把任务输入框里的云效链接变成带「云效」标记的外部待办。它与云效连接器共用同一套字段映射（标题、描述、计划日期、目标标签和图片转存），但不会定时同步，也不需要选择项目、工作项类型或完成状态。

每个团队空间最多接入一条云效创建。任意成员都可以粘贴链接导入；所有者和管理员负责接入、启停、移除和轮换个人令牌。

前置条件​

  • 操作者是 AntTodo 团队空间的所有者或管理员。
  • 已准备云效中心版组织 ID 和个人访问令牌。令牌权限与云效连接器相同。
  • 目标标签对该管理员具有编辑权限。云效类型待办必须挂到标签下。

1. 在 AntTodo 接入​

  1. 使用所有者或管理员账号进入 设置 → 团队配置 → 快速创建。
  2. 在市场中找到「云效创建」，点击「接入」。
  3. 填写组织 ID 和个人令牌，点击验证；通过后选择「同步到该标签下」。
  4. 保存并接入。接入后即可在任务创建框粘贴云效链接。

支持的链接形态：

  • 短链：https://devops.aliyun.com/projex/req/HQGS-354
  • 短链后带标题：https://devops.aliyun.com/projex/req/HQGS-354# 《标题…》（# 后的标题会被忽略，以云效接口为准）
  • 完整路径：https://devops.aliyun.com/projex/project/{projectId}/{category}/{workitemId}

其中 req / bug / task / risk 分别对应需求、缺陷、任务和风险。

2. 粘贴后的行为​

  • 未接入或已停用时，会提示先到 设置 → 快速创建 接入，不会把链接当成普通待办标题。
  • 若该工作项已被任一云效连接器同步到当前团队空间，会打开已有待办，避免重复创建。
  • 新导入的待办由粘贴者作为创建人；粘贴者或云效创建接入人可以勾选完成，并回写云效工作项状态。
  • 同一链接重复粘贴不会产生第二份待办。

管理已接入的云效创建​

在 设置 → 团队配置 → 快速创建 中：

  • 所有成员可以查看组织 ID、目标标签、令牌提示和最近使用时间。
  • 所有者和管理员可以启用、停用、轮换令牌或移除接入。
  • 云效创建不会出现在连接器市场的定时同步列表中，也不会进入云效同步的定时任务。