钉钉接入让 Hawa Code 能收听钉钉消息事件(消息、reaction、已读、撤回),并在开启回复能力后让 Agent 直接回复钉钉会话,形成双向闭环。
它由内置 MCP Server @dahawa/hawa-channel 提供,基于 Channel 协议 注入通知,鉴权托管给钉钉 CLI dws(使用当前用户 OAuth 登录,无需 AppKey/AppSecret)。
能做什么
钉钉事件 ──▶ dws event +listen-im(长连接)──▶ hawa-channel(规范化)
│
▼ notifications/hawacode/channel
Hawa Code 主 Agent 上下文
Agent 回复 ──▶ send_dingtalk_message(MCP 工具)──▶ dws chat +messages-send ──▶ 钉钉
- 收听:别人 @ 你、给你发单聊、群里发言、表情回复、已读、撤回等事件实时进入 Agent 上下文。
- 回复:Agent 收到事件后,可调用 MCP 工具把回答发回对应的单聊或群。
前置条件
- Node.js ≥ 20。
- 安装钉钉 CLI
dws,并完成当前用户 OAuth 登录:
dws --version
dws auth status --format json # 确认已登录
hawa-channel 启动时会自动检查 dws 可用性与登录状态,未登录会直接报错退出,不会静默失败。
启用方式
在 hawa-code 项目的 .mcp.json 中添加:
{
"mcpServers": {
"channel": {
"command": "npx",
"args": ["-y", "@dahawa/hawa-channel"],
"env": {
"WEBHOOK_ENABLED": "false",
"DINGTALK_ENABLED": "true",
"DINGTALK_LISTEN_KIND": "at-me",
"DINGTALK_EVENTS": "message"
}
}
}
}
Webhook 与钉钉可独立开关(WEBHOOK_ENABLED=false 时无需配置 WEBHOOK_SECRET)。
环境变量
| 环境变量 | 默认值 | 说明 |
|---|---|---|
DINGTALK_ENABLED |
false |
是否启动钉钉事件监听 |
DINGTALK_LISTEN_KIND |
at-me |
监听范围,见下表 |
DINGTALK_EVENTS |
message |
逗号分隔:message / reaction / read / recall |
DINGTALK_USER_QUERY |
无 | kind=sender 时必填,用户查询条件 |
DINGTALK_CHAT_QUERY |
无 | kind=group 时必填,群查询条件 |
DINGTALK_SEND_ENABLED |
false |
是否注册 send_dingtalk_message 回复工具 |
DWS_BIN |
dws |
dws 可执行文件名或绝对路径 |
DWS_PROFILE |
无 | dws profile;监听与回复必须使用同一个 |
LOG_LEVEL |
info |
debug / info / warn / error |
监听范围(LISTEN_KIND)
| kind | 范围 | 可用事件 |
|---|---|---|
at-me |
@当前用户的消息(默认) | 仅 message |
all-direct |
全部单聊消息 | 仅 message |
all-group |
全部群消息 | 仅 message |
sender |
指定用户,需 DINGTALK_USER_QUERY |
四类事件均可 |
group |
指定群,需 DINGTALK_CHAT_QUERY |
四类事件均可 |
配置示例——监听指定群的消息和 reaction:
{
"DINGTALK_ENABLED": "true",
"DINGTALK_LISTEN_KIND": "group",
"DINGTALK_CHAT_QUERY": "研发群",
"DINGTALK_EVENTS": "message,reaction"
}
Agent 收到什么
事件被规范化为统一格式后注入上下文:
| 事件 | 注入正文示例 |
|---|---|
| 消息 | [钉钉消息] 张三: 帮我看下构建日志 |
| reaction | [钉钉 reaction] 张三: 点赞 |
| 已读 | [钉钉已读] 张三: msg_xxx |
| 撤回 | [钉钉撤回] 张三: msg_xxx |
- 非文本消息以类型标签展示:
[图片] / [语音] / [视频] / [文件] / [位置] / [链接] / [富文本]。 meta携带messageId、sender、chatId、msgtype、timestamp等,Agent 可用conversationId或senderOpenDingtalkId定位回复目标。
回复钉钉(send_dingtalk_message)
回复能力默认关闭(避免 Agent 意外对外发消息),显式开启后才注册工具:
{
"DINGTALK_SEND_ENABLED": "true"
}
工具参数:
| 参数 | 必填 | 说明 |
|---|---|---|
content |
是 | 回复文本,去除首尾空白后 1~4000 字符 |
conversationId |
二选一 | 会话 ID(群或单聊),来自事件的 meta |
userOpenDingtalkId |
二选一 | 用户开放 ID,来自事件的 meta |
两个目标参数必须且只能提供一个。工具实际调用 dws chat +messages-send --as user 发送,是否弹出权限确认取决于 hawa-code 自身的工具权限设置。
排错
| 现象 | 排查 |
|---|---|
启动报 dws OAuth is not logged in |
执行 dws auth login 完成 OAuth,检查 DWS_BIN、DWS_PROFILE |
| 收不到事件 | 核对 LISTEN_KIND、用户/群查询条件、事件类型;日志出现 dingtalk listener ready 表示监听就绪 |
| 监听频繁重启 | 正常重连行为(指数退避 + dws 订阅状态检查);若持续失败看 LOG_LEVEL=debug 的 dws stderr |
tools/list 没有回复工具 |
确认 DINGTALK_SEND_ENABLED=true 并重新连接 MCP Server |
| 无日志 | hawa-channel 运行日志写 stderr(MCP stdout 只承载协议),提高 LOG_LEVEL 查看 |
原理简述
- 不自建协议:复用
dws event +listen-im长连接订阅 IM 事件,订阅维护、self-loop 过滤由 dws 负责;hawa-channel 只消费其 stdout 的 NDJSON 事件流并做字段规范化。 - 鉴权托管:使用 dws 当前用户 OAuth(开源 normal 模式免 AppKey/AppSecret),hawa-channel 不接触、不存储任何钉钉密钥;凭据由 dws 自行保存在
~/.dws。 - 健壮性:进程退出按指数退避自动重连,重连前先查询
dws event status,尊重 dws 的订阅保护(冷却期不强行重建订阅)。 - 统一出口:规范化后统一通过 MCP notification(
notifications/hawacode/channel,source=dingtalk)注入 Agent;回复反向走 MCP 工具调用 dws,全程不经 shell。
欢迎了解使用 Hawa Code https://www.hawacode.com/docs/