钉钉机器人怎么接：WorkBuddy 接入全流程拆解
本篇涵盖的知识重点
- 需要一个具有企业管理员权限的钉钉账号，并已开启助理远程控制
- 未加入组织时可在开发者后台创建一个个人企业
- 创建应用后需添加机器人能力，填写名称、描述、预览图后确认发布
- 需开通 Card.Streaming.Write、Card.Instance.Write、qyapi_robot_sendmsg 三个权限
- 凭证为 Client ID（AppKey）与 Client Secret（AppSecret），以及 AES Key 与 Token
- HTTP 模式下消息接收地址需把地址中的 http 改为 https
接入配置路径
配置步骤详解
作用钉钉应用的创建和发布需要管理员权限，普通成员账号无法完成全流程。
操作确认已在电脑上安装 WorkBuddy 并开启了助理远程控制功能；准备一个具有企业管理员权限的钉钉账号。打开浏览器访问钉钉开发者后台，使用管理员账号登录。
注意如果系统提示「该账号还未加入组织」，可以创建一个个人企业，按需填写信息即可；没有钉钉账号可前往钉钉官网下载客户端并创建团队。
作用机器人是消息收发的载体，必须先建应用再挂机器人能力。
操作在开发者后台首页点击「应用开发」，再点击「创建应用」；在创建窗口中填写应用名称与描述，应用类型可以暂时不传，填写完成后点击「保存」。应用创建成功后会自动跳转到「添加应用能力」页面，找到「机器人」选项点击「添加机器人」，填写机器人名称、机器人描述并上传预览图，最后点击「确认发布」。
注意机器人基本信息填写后必须点击「确认发布」，否则机器人配置不会生效。
- 应用名称：内容随便写，自定义名称即可，后续都可以随意修改。
- 应用描述：内容随便写，简单描述用途，后续同样可修改。
- 应用类型：可以暂时不传，不影响后续流程。
- 机器人名称：给机器人起一个名字，会显示在群成员列表里。
- 机器人描述：简单描述功能，帮助同事理解它能干什么。
- 预览图：上传一张机器人头像，建议清晰可辨。
作用权限不开通，机器人收不到消息也发不出消息，是最常见的「配置了但没反应」的原因。
操作在应用详情页左侧菜单点击「权限管理」，在搜索框中分别搜索 Card.Streaming.Write、Card.Instance.Write、qyapi_robot_sendmsg 这三个权限，并逐个点击「立即开通」。
注意三个权限缺一不可；排查无响应问题时优先核对这三项是否已全部开通。
作用WorkBuddy 需要这些值才能完成注册并与钉钉通信。
操作在应用详情页左侧菜单点击「凭证与基础信息」，找到 Client ID（也叫 AppKey）与 Client Secret（也叫 AppSecret）；再点击左侧「开发配置 - 事件订阅」，在「推送方式」中选择「HTTP推送」，点击刷新按钮自动生成 AES Key 和 Token。
注意Client ID、Client Secret、AES Key 和 Token 都非常重要，请妥善保存，不要泄露给他人。
作用注册方式决定消息走长连接还是回调，需要和钉钉侧保持一致。
操作打开 WorkBuddy，点击助理的设置图标后进入助理设置，选择钉钉集成；将刚才获取的 Client ID 和 Client Secret 填入对应输入框，选好模式后点击「注册」。
注意长连接模式点击「注册」配置成功后显示「已连接」；URL 回调模式点击注册后显示「已注册」并生成 Webhook 地址，需点击复制保存。
- WebSocket 长连接模式：适用于个人 / 家庭 / 办公室用户（没有公网 IP），配置更简单，不需要公网地址，开箱即用。
- 使用 URL 回调模式：适用于有服务器、有公网 IP 的用户，需要额外在钉钉开发者后台填写生成的 Webhook 地址。
- 选型建议：没有公网 IP 走长连接；选了 URL 回调就必须完成后续的地址回填与模式切换。
作用URL 回调模式下，钉钉不会自动知道往哪里推消息，地址不回填就等于没接上。
操作返回钉钉开发者后台进入机器人配置页面，下滑到页面底部找到消息接收配置，将「Stream 模式」切换为「HTTP 模式」，在「消息接收地址」中粘贴 Webhook 地址，把地址中的 http 改为 https，点击「发布」保存配置。
注意消息接收地址必须使用 https，使用 http 会导致机器人无响应，这是最容易踩的一个坑。
作用应用必须发布后才能在钉钉中使用，未发布的应用在群里搜不到机器人。
操作点击页面上方的「查看版本详情」，填写版本描述信息，点击「确认发布」提交审核，等待审核通过（通常会很快自动审批）。
注意审核未通过前机器人无法使用；若长时间未通过，可联系企业管理员确认审批状态。
作用两种使用方式的入口不同，搞清楚才能把它放到真正需要协作的地方。
操作群聊：创建或选择一个群聊，点击群右上角的设置按钮，选择「机器人」，点击「添加机器人」，搜索并选择你创建的机器人后确认添加，在群里 @机器人 发送需求。单聊：在钉钉顶部搜索框中搜索机器人的名称，点击机器人进入对话窗口直接发送消息。
注意创建群聊时请确保群的「归属组织」与创建机器人时的组织相同，否则在群里找不到机器人。
- 第一步 创建或选择群聊：群的「归属组织」必须与创建机器人时的组织相同。
- 第二步 添加机器人到群聊：群设置 → 机器人 → 添加机器人 → 搜索并选择 → 确认添加。
- 第三步 开始使用：在群里 @机器人 并发送需求，WorkBuddy 会自动执行任务并回复结果。
常见故障排查
- 如果您还没有钉钉账号，请前往钉钉官网下载客户端并创建团队；提示「该账号还未加入组织」时可创建一个个人企业。
- 必须开通 Card.Streaming.Write、Card.Instance.Write、qyapi_robot_sendmsg 三个权限，缺一不可。
- Client ID（AppKey）、Client Secret（AppSecret）、AES Key 和 Token 都非常重要，请务必妥善保存，不要泄露给他人。
- HTTP 模式下，粘贴 Webhook 地址后必须把地址中的 http 改为 https，否则机器人无响应。
- 机器人没有响应：确认应用已发布并通过审批；检查 Webhook 配置是否正确且使用 https 协议；确保电脑上的 WorkBuddy 正在运行且助理已开启；确认三个权限都已正确开通。
- 在群里找不到机器人：确认机器人应用已发布；确认群聊的「归属组织」与机器人所属组织相同；尝试重启钉钉客户端。
练手任务
```markdown
我要在钉钉开发者后台创建一个用于连接 WorkBuddy 的应用。请帮我整理一份填写清单，表格列包含：配置项、是否必填、填写建议、后续能否修改。需覆盖应用名称、应用描述、应用类型、机器人名称、机器人描述、机器人预览图这几项，并注明官方文档的原话要求。
```得到一张含必填标记与可修改说明的填写清单，可直接照着填完创建流程。
```markdown
请帮我整理一份钉钉机器人接入 WorkBuddy 所需的权限核对表。表格列包含：权限名、作用、在哪里搜索、开通动作、未开通的后果。必须包含 Card.Streaming.Write、Card.Instance.Write、qyapi_robot_sendmsg 这三项，并在表尾说明排查无响应问题时权限检查所处的优先级。
```得到一张权限核对表，三项权限齐全，且明确权限检查在排查流程中的位置。
```markdown
我的钉钉机器人收不到消息，怀疑是消息接收地址配置有问题。请帮我写一份专项排查指引，包含：正确的完整配置路径（从机器人配置页面到消息接收地址）、模式切换的具体操作、地址协议的强制要求、一个常见错误示例及其后果。用编号步骤输出，步骤中要写清按钮名。
```得到一份含完整路径与按钮名的排查指引，能定位并修正地址协议类问题。
本文基于官方文档再创作，具体以官方文档站实际展示为准。