OpenClaw 钉钉机器人接入指南:企业内部应用、Stream 长连接与流式 AI Card 实战
OpenClaw 钉钉机器人接入指南:企业内部应用、Stream 长连接与流式 AI Card 实战
钉钉(DingTalk)是 OpenClaw 中文社区版内置支持的官方聊天渠道之一,本文围绕 钉钉机器人渠道文档 展开,完整讲解从钉钉开放平台创建企业内部应用、在 OpenClaw 中安装官方连接器、配置凭证与访问策略,到通过 Stream 长连接接收消息并以流式 AI Card 实时回复的端到端流程。读完本文,你将掌握 openclaw-cn channels add、openclaw-cn pairing approve、多 Agent 路由绑定等核心操作,并能独立排查机器人不响应、Token 认证失败等常见问题。
核心特性一览
钉钉渠道在 OpenClaw 中属于生产就绪(production-ready)状态,支持机器人私聊与群组对话,其主要特性包括:
- 官方连接器接入:通过官方
@dingtalk-real-ai/dingtalk-connector插件接入钉钉机器人,中文社区版提供同名包装插件(见 extensions/dingtalk-connector/package.json)。 - Stream 长连接模式:无需公网服务器,钉钉主动通过长连接把消息推送到本地网关,适合个人与家庭环境部署。
- 流式 AI Card 回复:回复以 AI Card 卡片形式呈现,支持实时打字机效果。
- 确定性路由:回复始终返回钉钉渠道,模型不会自行选择输出渠道。
- 会话隔离:私聊共享主会话;群组之间相互独立隔离。
从渠道注册表看,dingtalk-connector 在 src/channels/registry.ts 中被注册为核心聊天渠道之一,并支持 dingtalk、dingding 两个别名(见 src/channels/registry.ts),在 CLI 与配置中均可使用。
快速开始:两种添加方式
添加钉钉渠道有两种途径,均可完成插件安装、凭证录入与网关配置。
方式一:通过安装向导添加(推荐)
如果刚完成 OpenClaw 安装,直接运行向导:
openclaw-cn onboard
向导会引导你依次完成:
- 安装官方钉钉插件;
- 输入应用 Client ID 与 Client Secret;
- 输入 Gateway Token;
- 启动网关。
配置完成后,用以下命令检查网关状态:
openclaw-cn gateway status—— 查看网关运行状态;openclaw-cn logs --follow—— 实时查看日志。
方式二:通过命令行添加
已完成初始安装的用户,可以直接运行:
openclaw-cn channels add
在交互式提示中选择 钉钉 (官方连接器),按提示输入三个必填参数即可。插件元数据中的 selectionLabel 正是“钉钉 (官方连接器)”,见 extensions/dingtalk-connector/src/channel.ts。
配置完成后:
openclaw-cn gateway status—— 查看网关运行状态;openclaw-cn gateway restart—— 重启网关以应用新配置;openclaw-cn logs --follow—— 实时查看日志。
第一步:创建钉钉企业内部应用
钉钉机器人依托“企业内部应用”运行,需要企业管理员或开发者权限。
1. 打开钉钉开放平台
访问钉钉开放平台开发者后台,使用钉钉账号(需企业管理员或开发者权限)登录。
2. 创建企业内部应用
- 点击左侧菜单 应用开发 > 企业内部开发;
- 点击 创建应用;
- 选择 钉钉应用,填写应用名称和描述。
3. 获取应用凭证
进入应用详情页,在 基础信息 页面复制:
- Client ID(即 AppKey,格式如
dingxxxxxx); - Client Secret(即 AppSecret)。
注意:请妥善保管 Client Secret,不要分享给他人。AppKey/AppSecret 不要混淆。
4. 开启机器人能力
在应用详情页进入 添加应用能力 > 机器人:
- 点击 添加 开启机器人能力;
- 在机器人配置中填写机器人名称和描述;
- 消息接收模式 选择 Stream 模式(无需公网服务器,这是 OpenClaw 本地网关能直接接收消息的关键前提)。
5. 配置权限
在 权限管理 页面,搜索并添加以下三个必要权限:
| 权限名称 | 说明 |
|---|---|
Card.Streaming.Write |
向 AI Card 推送流式内容(打字机效果必需) |
Card.Instance.Write |
创建和更新 AI Card 实例 |
qyapi_robot_sendmsg |
机器人发送消息 |
提示:根据实际需求,可能还需要添加文档读写等其他权限(例如让 Agent 读写钉钉文档)。
6. 发布应用
- 在 版本管理与发布 页面点击 创建新版本;
- 填写版本说明后提交;
- 选择应用可见范围(建议先设为 全员 进行测试);
- 点击 确认发布。
只有发布后的应用才能被机器人服务正常调用,未发布的应用在后续测试阶段会出现“机器人不响应”等异常。
第二步:配置 OpenClaw
通过向导配置(推荐)
运行:
openclaw-cn channels add
选择 钉钉 (官方连接器),然后按提示安装官方插件并输入凭证。交互过程大致如下:
◇ 安装 钉钉 插件?
│ 钉钉官方插件
◇ 输入钉钉应用 Client ID
│ dingxxxxxxxxxxxxxx
◇ 输入钉钉应用 Client Secret
│ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
◇ 输入 Gateway 认证 Token(openclaw.json 中 gateway.auth.token 的值)
│ your-gateway-token
Gateway Token 说明:钉钉官方插件通过 HTTP 请求本地 Gateway,需要认证 Token。如果尚未配置 gateway.auth.token,可以先设置一个随机字符串(例如运行 openssl rand -hex 16 生成),在两处填写相同的值即可。
从 extensions/dingtalk-connector/src/onboarding.ts 的实现看,向导的 configure 流程会:以已有配置为 initialValue 预填 Client ID / Client Secret / Gateway Token;若未单独配置过 gatewayToken,则自动回退读取 gateway.auth.token 作为默认值。提交后,applyDingtalkConnectorConfig 会做三件事(见 extensions/dingtalk-connector/src/onboarding.ts):
- 写入
channels.dingtalk-connector下的clientId、clientSecret、gatewayToken,并置enabled: true; - 强制打开
gateway.http.endpoints.chatCompletions.enabled = true(这是连接器调用本地网关所必需); - 若
gateway.auth.mode未设置则设为"token",若gateway.auth.token未设置则写入刚输入的 Gateway Token。
也就是说,向导会在你输入凭证的同时,自动补齐网关侧认证与 HTTP 端点的配套配置,避免漏配导致 401。
通过配置文件配置
编辑 ~/.openclaw/openclaw.json:
{
"channels": {
"dingtalk-connector": {
"enabled": true,
"clientId": "dingxxxxxxxxxxxxxx",
"clientSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"gatewayToken": "your-gateway-token",
"dmPolicy": "pairing"
}
},
"gateway": {
"auth": {
"mode": "token",
"token": "your-gateway-token"
},
"http": {
"endpoints": {
"chatCompletions": {
"enabled": true
}
}
}
}
}
重要:
channels.dingtalk-connector.gatewayToken必须与gateway.auth.token保持一致,官方插件通过此 Token 验证 Gateway 身份。同时必须开启gateway.http.endpoints.chatCompletions.enabled,否则连接器无法把消息转发给本地网关处理。
除了上述字段,插件配置 Schema 还允许 gatewayPassword(备用网关密码)与 sessionTimeout(会话超时,非负整数)两个可选字段,见 extensions/dingtalk-connector/src/channel.ts;enabled、clientId、clientSecret 均为常规必填/可选字段。插件通过 reload.configPrefixes: ["channels.dingtalk-connector"] 声明,因此修改该配置前缀下的内容即可触发热重载,无需手动重建配置。
第三步:启动并测试
1. 启动网关
openclaw-cn gateway
2. 验证连接
启动后查看日志,确认钉钉 Stream 连接成功:
openclaw-cn logs --follow
正常启动日志应包含:
[dingtalk-connector] [__default__] 启动钉钉 Stream 客户端...
[dingtalk-connector] [__default__] 钉钉 Stream 客户端已连接
插件在运行时以固定账号 default 运行(defaultAccountId: () => "default",见 extensions/dingtalk-connector/src/channel.ts),因此日志中的 [__default__] 是预期输出。
3. 发送测试消息
在钉钉中搜索机器人名称找到刚创建的机器人,发送一条消息。
4. 配对授权
默认情况下(dmPolicy: "pairing"),机器人会回复一个 配对码。你需要批准此代码:
openclaw-cn pairing approve dingtalk-connector <配对码>
该命令的用法与参数约束定义在 src/cli/pairing-cli.ts,支持 pairing approve <channel> <code> 与 pairing approve --channel <channel> <code> 两种形式。批准后即可正常对话,机器人将以流式 AI Card 形式实时输出回复。
访问控制
私聊访问
- 默认:
dmPolicy: "pairing",陌生用户会收到配对码; - 批准配对:
openclaw-cn pairing list dingtalk-connector # 查看待审批列表 openclaw-cn pairing approve dingtalk-connector <CODE> # 批准 - 白名单模式:通过
channels.dingtalk-connector.allowFrom配置允许的用户 staffId。
群组访问
群组策略(channels.dingtalk-connector.groupPolicy):
"open"—— 允许群组中所有人(默认);"allowlist"—— 仅允许groupAllowFrom中的用户;"disabled"—— 禁用群组消息。
获取用户 staffId
钉钉侧的访问控制(白名单、多 Agent 绑定)都依赖用户的 staffId,可通过以下方式获取:
方法一(推荐):
- 启动网关并给机器人发消息;
- 运行
openclaw-cn logs --follow查看日志中的senderStaffId字段。
方法二:
查看配对请求列表:
openclaw-cn pairing list dingtalk-connector
配对请求列表中同样包含发起配对用户的 staffId。
常用命令
| 命令 | 说明 |
|---|---|
/status |
查看机器人状态 |
/reset |
重置对话会话 |
/model |
查看/切换模型 |
网关管理命令
| 命令 | 说明 |
|---|---|
openclaw-cn gateway status |
查看网关运行状态 |
openclaw-cn gateway install |
安装/启动网关服务 |
openclaw-cn gateway stop |
停止网关服务 |
openclaw-cn gateway restart |
重启网关服务 |
openclaw-cn logs --follow |
实时查看日志输出 |
故障排除
机器人不响应消息
- 确认 Stream 连接已建立:查看日志是否有
钉钉 Stream 客户端已连接; - 确认应用已发布且机器人能力已开启;
- 确认消息接收模式为 Stream 模式(而非 HTTP 回调);
- 查看日志:
openclaw-cn logs --follow。
Gateway Token 认证失败
错误日志包含 401 或 认证失败 时:
- 确认
channels.dingtalk-connector.gatewayToken与gateway.auth.token相同; - 确认
gateway.http.endpoints.chatCompletions.enabled: true(连接器依赖该 HTTP 端点把钉钉消息转交本地网关); - 重新运行配置向导更新凭证:
openclaw-cn channels add(向导会自动补齐上述两处配置)。
Client ID / Client Secret 错误
- 在钉钉开放平台检查应用状态是否为已发布;
- 重新复制 Client ID 和 Client Secret(注意不要混淆 AppKey/AppSecret);
- 更新配置:
openclaw-cn channels add,重新选择钉钉并输入正确凭证。
机器人在群组中不响应
- 确认机器人已被添加到该群组;
- 确认
groupPolicy不为"disabled"; - 在群组中 @ 机器人后发送消息(默认需要 @);
- 查看日志:
openclaw-cn logs --follow。
Client Secret 泄露怎么办
- 在钉钉开放平台重置 Client Secret;
- 运行
openclaw-cn channels add重新配置; - 重启网关。
高级配置:多 Agent 路由
通过 bindings 配置,可以用一个钉钉机器人对接多个不同功能的 Agent。例如,私聊交给 main Agent,某个群组交给独立的 assistant Agent:
{
"agents": {
"list": [
{ "id": "main" },
{
"id": "assistant",
"workspace": "~/assistant-workspace"
}
]
},
"bindings": [
{
"agentId": "main",
"match": {
"channel": "dingtalk-connector",
"peer": {
"kind": "dm",
"id": "staff_id_xxx"
}
}
},
{
"agentId": "assistant",
"match": {
"channel": "dingtalk-connector",
"peer": {
"kind": "group",
"id": "group_id_xxx"
}
}
}
]
}
匹配规则说明:
| 字段 | 说明 |
|---|---|
agentId |
目标 Agent 的 ID,需要在 agents.list 中定义 |
match.channel |
渠道类型,固定为 "dingtalk-connector" |
match.peer.kind |
对话类型:"dm"(私聊)或 "group"(群组) |
match.peer.id |
用户 staffId 或群组 conversationId |
完整配置示例
{
"channels": {
"dingtalk-connector": {
"enabled": true,
"clientId": "dingxxxxxxxxxxxxxxxxxx",
"clientSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"gatewayToken": "your-gateway-token",
"dmPolicy": "pairing",
"groupPolicy": "open",
"allowFrom": ["staff_id_xxx"],
"groupAllowFrom": ["staff_id_xxx", "staff_id_yyy"]
}
},
"gateway": {
"auth": {
"mode": "token",
"token": "your-gateway-token"
},
"http": {
"endpoints": {
"chatCompletions": {
"enabled": true
}
}
}
}
}
配置参考
| 配置项 | 说明 | 默认值 |
|---|---|---|
channels.dingtalk-connector.enabled |
启用/禁用渠道 | true |
channels.dingtalk-connector.clientId |
应用 Client ID(AppKey) | - |
channels.dingtalk-connector.clientSecret |
应用 Client Secret(AppSecret) | - |
channels.dingtalk-connector.gatewayToken |
Gateway 认证 Token | - |
channels.dingtalk-connector.dmPolicy |
私聊策略 | pairing |
channels.dingtalk-connector.allowFrom |
私聊白名单(staffId 列表) | - |
channels.dingtalk-connector.groupPolicy |
群组策略 | open |
channels.dingtalk-connector.groupAllowFrom |
群组白名单 | - |
gateway.auth.mode |
网关认证模式 | - |
gateway.auth.token |
网关认证 Token | - |
gateway.http.endpoints.chatCompletions.enabled |
启用 HTTP Chat Completions | false |
补充(来自插件 Schema):除上表字段外,插件配置还支持
gatewayPassword(备用密码)与sessionTimeout(会话超时秒数,最小值 0),字段定义见 extensions/dingtalk-connector/src/channel.ts。
dmPolicy 策略说明
| 值 | 行为 |
|---|---|
"pairing" |
默认。未知用户收到配对码,管理员批准后才能对话 |
"allowlist" |
仅 allowFrom 列表中的用户可对话,其他静默忽略 |
"open" |
允许所有人对话(需在 allowFrom 中加 "*") |
"disabled" |
完全禁止私聊 |
支持的消息类型
接收
- ✅ 文本消息
- ✅ 图片
- ✅ 文件
- ✅ 音频
- ✅ 视频
- ✅ @提及
发送
- ✅ 流式 AI Card(实时打字机效果)
- ✅ 文本消息
- ✅ 图片
- ✅ 文件
- ✅ 音频
- ✅ 视频
需要说明的是,从插件 capabilities 声明看(见 extensions/dingtalk-connector/src/channel.ts),该渠道当前不启用投票、线程、原生命中命令、表情回应与消息编辑等扩展能力,核心定位是可靠的文本/多媒体对话与流式卡片回复。
小结
钉钉渠道为 OpenClaw 中文社区版提供了一条零公网服务器依赖的接入路径:钉钉侧选择 Stream 消息接收模式,OpenClaw 侧通过官方 @dingtalk-real-ai/dingtalk-connector 连接器建立长连接,配合本地网关的 chatCompletions HTTP 端点完成消息转发,最终以流式 AI Card 呈现实时回复。整个接入过程只需完成“开放平台创建应用 → 向导填写三凭证 → 启动网关 → 配对批准”四个环节;上线后可通过 dmPolicy、groupPolicy、allowFrom 精确控制谁能与你的专属 AI 助手对话,也能借助 bindings 让同一个机器人按私聊/群组路由到不同 Agent。相关配置样例、源码实现与插件声明均可在 docs/channels/dingtalk-connector.md、extensions/dingtalk-connector/src/channel.ts、extensions/dingtalk-connector/src/onboarding.ts 与 src/channels/registry.ts 中进一步查阅。


