ClawHub

dws-chat

API key required
Security

钉钉群聊消息专用 skill。查询/获取/发送群消息、按群名搜索群、把机器人加入现有群、拉取今日或指定日期群记录时必须加载（群聊场景优先于 dws-cli）。 触发示例：获取群消息、帮我获取群、查群、群：、今天的消息、群聊记录、发送群消息、把机器人加进群、添加机器人到群、dws-chat。 用户只提供群名时禁止索要 groupId/openConversationId，须先 chat search 解析群再拉消息。 命令入口：skills/dws-chat/scripts/dws_agent.py；未登录须 get_device_auth_link.py 发设备授权链接（禁止让用户自行 dws auth login）；禁止裸 dws。

Install

openclaw skills install dws-chat

dws-chat — 钉钉群聊消息 Skill

本 skill 自包含于各 agent 的 {workspace}/skills/dws-chat/。多 agent 凭证隔离只通过 scripts/dws_agent.py 实现。

触发与分工

收到下列任一表述时，必须先 read 本 SKILL.md，不要先纯文字追问。

场景用户说法（不限于）
查消息获取群消息、查群、今天的消息、群聊记录、看看群里
带群名群：{名称}、{名称}群 今天的消息
发消息往群里发、发送到群、群通知
机器人入群把机器人加到群、添加机器人到群、机器人进群
点名 skill用 dws-chat、dws chat skill

与 dws-cli 的分工：群聊 / IM（查历史、搜群、发消息、搜机器人、机器人入群）走本 skill；表格/日历/审批等仍用 dws-cli。

标准执行顺序

1. read 本 SKILL.md（若未加载）
2. dws_agent.py auth status -f json
3. 未登录 → get_device_auth_link.py → 按「未登录回复模板」发链接 → 结束
4. 已登录 → 按「常见任务」执行命令

未登录时禁止执行 chat / message send 等业务命令；禁止仅文字提示用户跑 dws auth login。

未登录回复模板（强制）

auth status 出现 authenticated: false / token_valid: false / 任何「未登录」字样时：

  1. 下一条 tool call：python3 skills/dws-chat/scripts/get_device_auth_link.py
  2. 从输出 ---DWS_DEVICE_AUTH--- 块解析 verification_url、user_code（合法 URL 含 login.dingtalk.com/oauth2/device/verify.htm?user_code=，禁止 open.dingtalk.com，禁止编造）
  3. 照下方格式发给用户，结束本轮：
还未登录，无法访问群聊数据。同时生成了新的授权链接，请完成钉钉授权：

授权地址：{verification_url}
授权码：{user_code}

请在 15 分钟内打开链接完成授权，完成后回复「已授权」。
完成后我将继续为你{待办说明}。

{待办说明} 填用户原诉求（如：拉取「dws测试群」今天的消息）。用户回「已授权」后再次 auth status，成功则继续被打断的步骤。

常见任务

命令均通过 dws_agent.py 执行（下文省略前缀 python3 skills/dws-chat/scripts/dws_agent.py）。flag 详情以 <cmd> --help 与 references/dws-chat-commands.md 为准。

A. 按群名查群消息（默认流程，禁止索要 groupId）

1. chat search --query "<群名>"  → 取 openConversationId
2. 按下表选 --time / --forward → chat message list
3. 汇总回复（发送人 / 时间 / 正文）
用户诉求推荐参数
今天 / 指定日期之后的消息--time "<YYYY-MM-DD> 00:00:00" --forward --limit 100（必须带 --time）
最近 N 条（不限时间）--forward=false --limit <N>（从新到旧）
指定时间窗口--time "<start>" --forward --limit 100 + 分页（hasMore=true 时用最后一条 createTime 续拉）

实测：chat message list 不带 --time + 默认 --forward=true 时，对部分群（尤其挂 CSpace 协作空间的群，chat search 返回 extension.newCSpaceIdIM 非空）会返回空。拉今日消息必须显式 --time。

返回 0 条的诊断顺序（不要直接告诉用户「群里没消息」）

  1. 重试：换 --forward=false --limit 50（从新到旧拿最近消息）
  2. 仍 0 条：去掉 --time、--forward=false --limit 100 再试
  3. 仍 0 条：用 chat conversation-info --group <id> 确认能查到群、当前用户是群成员
  4. 三步都 0 条才告知用户「该群在 {日期} 无可见消息」

禁止把 0 条归因为「机器人不在群内」—— dws 用用户身份读取，与机器人无关。

  • 用 chat message list --group（已下线的 mcp ... list_conversation_message_v2 勿用）
  • chat search 0 条 → 告知未找到，建议用户换关键词或确认全名；多条 → 列群名供用户选；唯一允许追问群名的场景

B. 发送群消息

身份命令
用户身份chat message send --group <id> --title <t> --text <c>
机器人身份chat message send-by-bot --robot-code <code> --group <id> --title <t> --text <c>
自定义 Webhookchat message send-by-webhook --webhook <url> --title <t> --text <c>

robot-code 用 chat bot search 取；若机器人尚未在群内，先走 §C 入群。

C. 把机器人加入现有群（危险，需确认）

1. chat bot search --name "<机器人名>"      → 取 robotCode（仅当前用户有权限）
2. chat search --query "<群名>"              → 取 openConversationId
3. 向用户展示「机器人名 + 群名」摘要等确认
4. chat group members add-bot --robot-code <code> --id <openConversationId> --yes

--id 是 openConversationId（非内部 groupId）。报错 PAT_MEDIUM_RISK_NO_PERMISSION 时按 CLI 返回的链接补 OAuth scope。

D. 给个人发单聊消息

1. contact user search --query "<姓名>"     → 取 userId
2. chat message send --user "<userId>" --title <t> --text <c>

危险操作（执行前必须确认 + 加 --yes）

命令影响
chat group members add-bot修改群成员（机器人入群）
chat group members remove移除群成员
chat message recall / recall-by-bot撤回消息

确认流程：展示操作摘要（操作 + 目标 + 影响范围）→ 用户明确同意 → 加 --yes 执行。

严格禁止 (NEVER DO)

  • 未加载本 skill 就追问「需要 groupId / openConversationId」（用户给群名时必须自行 chat search）
  • 让用户自跑 dws auth login / dws login（必须 get_device_auth_link.py 生成链接）
  • 直接运行裸 dws（必须 dws_agent.py / get_device_auth_link.py）
  • 使用 ~/.dws 或其它 agent 的 {workspace}/.dws
  • 编造授权链接、open.dingtalk.com 链接、编造群 ID
  • 用 curl / HTTP / 浏览器替代 dws 做群聊业务
  • 拉今日 / 指定日期消息时省略 --time（必空，对 CSpace 群直接返回空）
  • 把 chat message list 返回 0 条归因为「机器人不在群」/「无权限」（dws 用用户身份读取；先按 §A 诊断顺序排查）

严格要求 (MUST DO)

  • 业务命令一律 python3 skills/dws-chat/scripts/dws_agent.py ... -f json
  • 危险操作先向用户确认，同意后再加 --yes
  • 参数以 dws_agent.py <cmd> --help 为准；参考文档与 --help 冲突时以 --help 为准

错误处理

  1. 失败 → 加 --verbose 重试一次
  2. stderr 含 RECOVERY_EVENT_ID=<id> → dws_agent.py recovery execute --event-id <id> -f json
  3. 仍失败 → 报完整错误给用户，禁止自行尝试替代方案
  4. 登录失效 → 走「未登录回复模板」，不要用 ~/.dws
  5. 重置本 agent 凭证 → 删 {workspace}/.dws 与 {workspace}/.dws_home 后重新授权

部署与凭证隔离（一句话）

  • 一 agent ↔ 一 HOME ↔ 一套 token；dws_agent.py 注入 HOME={workspace}/.dws_home、DWS_CONFIG_DIR={workspace}/.dws、DWS_DISABLE_KEYCHAIN=1，详见 references/isolation.md
  • 安装、跨机部署、清理、平台矩阵 → references/install.md
  • 沙盒 agent 在容器内安装即天然隔离；脚本会自动识别 /workspace（stderr sandbox=yes）
  • Windows：本机 PowerShell 执行 install.ps1 安装 dws.exe；用 py -3 skills/dws-chat/scripts/...；不需要 WSL/Docker（见 references/install.md）
More in Security