钉钉集成
钉钉集成提供两种能力：
- 任务助手：每个空间一个系统助手。从钉钉集成页绑定后，可以在钉钉群里根据聊天上下文整理需求并创建任务，也可以查询和修改该空间的任务。
- Agent 机器人：把你创建的 Agent 接到钉钉，在私聊和群聊中收发消息。
两种能力彼此独立，可以同时使用，但必须分别配置。任务助手不是普通 Agent：它不会出现在 Agent 列表、处理人选择器和站内私聊里。
一、钉钉任务助手：给每个空间一个钉钉入口
钉钉任务助手是系统为每个空间提供的内置助手，用来在钉钉里整理需求并创建 HiFox 任务。它不是从「创建 Agent」表单建出来的。
能做什么？
- 在钉钉群里 @ 机器人，根据当前话题上下文整理需求并创建任务；
- 查询、修改该空间里的 HiFox 任务；
- Agent 发出的文件会回到原来的钉钉会话。
它只在钉钉里工作。站内不能私聊或 @ 它，Agent 列表、处理人选择器和独立对话入口里也找不到它。它处理过的任务、评论和活动里仍会显示为执行者。
如何绑定
- 打开 外部应用集成，进入钉钉详情页。
- 在 任务助手 分组里，找到你加入的空间。
- 选择 绑定钉钉。
- 选择运行该空间任务助手的 Runtime。
- 在同一对话框里扫码，完成钉钉机器人绑定。
每个空间只能有一个任务助手。列表显示的是你加入的空间，而不是已经存在的助手。没有绑定的空间就是待处理项。绑定对话框会同时完成创建助手和扫码，不需要先去 Agent 页新建。
绑定后可以在同一分组里编辑 Runtime、补充附加提示词，或解绑钉钉、移除助手。系统已内置在钉钉里创建任务的提示词；你填写的附加提示词会追加在后面。
需要把某个你自己创建的 Agent 接到钉钉时，继续使用下面的 Agent 机器人，而不是任务助手。
二、钉钉机器人：在钉钉中控制 HiFox Agent
- 将一个 HiFox Agent 连接为钉钉机器人；
- 在钉钉私聊中直接和 Agent 对话；
- 在群聊中 @ 机器人，让 Agent 回复；
- 分别控制是否响应私聊和群里被 @；
- Agent 发出的文件会回到原来的钉钉会话；
- 在 HiFox 中查看、调整或断开已有绑定。
钉钉消息进入的是 Agent 外部会话，不会自动变成 HiFox 任务。如果对话中形成了需要分配、追踪或验收的工作，建议把它整理成 HiFox 任务，再指派给 Agent。
连接前需要准备什么？
一个 Agent 同一时间只能绑定一个钉钉入口。已经绑定钉钉的 Agent 不会再次出现在可选列表中。
从哪里进入？
你可以从两个位置配置：
- 进入组织后，打开 外部应用集成，在钉钉卡片上点击设置或管理；
- 进入某个 Agent 的详情页，在集成区域选择 绑定钉钉，这种方式会直接绑定当前 Agent。
卡片名称、按钮文案以线上为准。
连接钉钉机器人
推荐用扫码创建：
- 打开 连接钉钉。
- 选择要绑定的 Agent。
- 等待系统生成注册码。
- 用钉钉扫码创建应用，或点击 打开链接。
- 在钉钉中完成授权。授权完成后，凭据会自动填入。
- 返回 HiFox，等待状态变为已连接。
如果扫码创建后应用还在审核、Client Secret 尚未放出，可以等审核通过后，从钉钉复制 ClientId 和 ClientSecret，改用「手动填写」完成连接。具体入口以线上为准。
不要把 ClientId、ClientSecret 粘贴到任务评论、聊天消息或公开文档中。
在钉钉中怎么使用？
私聊
安装完成后，可以直接给机器人发私信。是否响应私聊，取决于该绑定的触发设置。
群里被 @ 到
把机器人拉进群后，在群里 @ 它并输入问题或指令。是否响应群 @，同样取决于触发设置。
钉钉机器人当前没有飞书 / Slack 那套表情触发、群消息直接触发。触发开关以 Agent 集成页线上为准。
新开对话
在已有的钉钉私聊或群会话中，发送 /new 可以开始一个新的 Agent 会话：
也可以把新会话的首条提示词写在命令后：
新会话不会带上之前的上下文。/new 只会新开 Agent 会话，不会自动创建 HiFox 任务。
连接后会发生什么？
常见消息流程如下：
- 用户在钉钉中向机器人发送私聊，或在群里 @ 机器人；
- HiFox 接收事件并找到对应绑定；
- 消息进入该 Agent 的外部会话并触发运行；
- Agent 生成回复；
- 回复和文件返回原会话。
管理和断开
钉钉详情页会列出当前组织中已有的 Agent 绑定。你可以查看每个入口绑定的 Agent，刷新状态，或断开不再需要的绑定。
断开后，该钉钉入口将停止把新消息发送给对应 Agent。已有 HiFox 会话和历史消息不会因此自动删除。需要恢复时，请重新完成扫码或手动填写凭据。
常见问题
为什么没有可选 Agent？
可能还没有创建 Agent，或者所有可用 Agent 都已经绑定钉钉。一个 Agent 只能绑定一个钉钉入口。
扫码后为什么一直等待授权？
请确认已经在钉钉中完成创建与授权，而不只是打开页面。如果注册码过期，点击 重试 生成新的。如果应用还在审核，Client Secret 可能尚未放出，审核通过后再用「手动填写」。
收不到钉钉消息怎么办？
先确认绑定仍显示为已连接，再检查对应的 私聊 或 群里被 @ 到 触发设置是否开启。群聊中还需要 @ 该机器人。
钉钉消息会自动变成 HiFox 任务吗？
不会。消息进入的是 Agent 外部会话。需要跟踪状态、处理人、评论或验收标准的工作，请在 HiFox 中创建任务并指派给 Agent。