OpenClaw 配置接入钉钉机器人：openclaw.json 骨架与回调验证

1. 为什么要在 OpenClaw 里接钉钉机器人OpenClaw 是一个可以本地部署、通过插件扩展通道的 AI 助手框架它本身不绑定任何聊天平台而是靠 channels 把消息接进来、把回复送出去。钉钉机器人就是其中一条通道你在钉钉里建一个企业内部应用开启机器人能力再把凭证写进 OpenClaw 的 openclaw.json之后群里 一下机器人或者单聊发一句话OpenClaw 就能收到并回复。适合谁用适合已经在用钉钉办公、想把告警通知、值班问答、CI 结果播报接到群里的团队也适合想拿 OpenClaw 做企业内部助手的开发者。我这次落地的场景很具体公司运维群需要把服务异常、构建失败、定时巡检结果推到钉钉群同时希望群里能直接问“昨天那个报错是什么原因”由 OpenClaw 调模型回答。整条链路的关键就两个文件——钉钉开发者后台的应用配置以及本地~/.openclaw/openclaw.json里的channels.dingtalk-connector节点。下面按“钉钉侧准备 → OpenClaw 侧配置 → 回调验证 → 排错”的顺序走一遍配置骨架可以直接复制。2. 钉钉侧准备应用、权限与凭证2.1 创建机器人应用并开启 Stream 模式登录钉钉开发者后台进入「应用开发 - 钉钉应用」创建应用填名称、描述、头像。创建后在「添加应用能力」里选「机器人」进入机器人配置页消息接收模式选Stream这是重点OpenClaw 的 dingtalk-connector 走的是 Stream 长连接不是 HTTP 回调地址所以不需要公网 IP也不需要配回调 URL。基础信息填完保存。2.2 权限清单在「权限管理」里至少开这几项否则消息发不出去或卡片渲染失败权限用途机器人消息发送相关权限向单聊/群聊发消息媒体文件上传相关权限发图片、语音、视频、文件Card.Instance.Write创建和投放卡片实例Card.Streaming.Write卡片流式更新2.3 发布应用并记录四个凭证填版本信息后保存并发布管理员审批通过后应用显示「已上线」。然后回到「凭证与基础信息」页记下四个值Client ID原 AppKey、Client Secret原 AppSecret、Corp ID企业 ID、Agent ID应用 ID。这四个值后面要写进 openclaw.json其中 OpenClaw 配置里实际用到的是 Client ID 和 Client SecretCorp ID 和 Agent ID 建议一并留存排查问题时对得上号。3. 安装钉钉插件并写 openclaw.json 骨架3.1 安装官方插件Windows 下以管理员身份运行 PowerShellLinux/macOS 直接执行openclaw plugins install dingtalk-real-ai/dingtalk-connector装完验证是否加载openclaw plugins list输出里 DingTalk 那一行状态应为loaded。如果显示 not loaded先确认 OpenClaw 版本与插件兼容再重装一次。3.2 openclaw.json 配置骨架打开配置文件Windows 示例notepad $HOME/.openclaw/openclaw.json在文件里加入下面这段骨架把三个占位值换成你自己的{ channels: { dingtalk-connector: { clientId: 你的钉钉 Client ID, clientSecret: 你的钉钉 Client Secret, gatewayToken: 你的 Gateway 认证 token, gatewayPassword: , sessionTimeout: 1800000 } }, gateway: { auth: { mode: token, token: 你的 Gateway 认证 token }, http: { endpoints: { chatCompletions: { enabled: true } } } } }字段说明clientId/clientSecret必填来自钉钉应用凭证gatewayToken必填值等于gateway.auth.token两处必须一致gatewayPassword可选与 token 二选一sessionTimeout可选单位毫秒默认 30 分钟。注意gateway节点通常在你安装时已经存在不要把整段覆盖上去只把auth和http部分追加到已有节点下否则会丢掉原有配置。3.3 用命令写入的替代方式不想手改 JSON也可以用命令逐项写openclaw config set channels.dingtalk-connector.enabled true openclaw config set channels.dingtalk-connector.clientId 你的Client_ID openclaw config set channels.dingtalk-connector.clientSecret 你的Client_Secret openclaw config set channels.dingtalk-connector.gatewayToken 你的gatewayToken openclaw config set channels.dingtalk-connector.dmPolicy open openclaw config set channels.dingtalk-connector.groupPolicy opendmPolicy和groupPolicy设为 open 表示单聊和群聊都允许触发企业内网环境按需收紧。写完重启网关openclaw gateway restart4. 验证回调连通性与消息触达配置写完不等于通了要分两步验证网关是否正常、消息是否真的能进出。第一步确认网关进程和端口状态openclaw gateway status看到 running 且 auth mode 为 token 即可。第二步打开钉钉客户端搜索你创建的那个机器人应用进入聊天窗口发一句“你好”。如果 OpenClaw 侧日志出现收到消息、并返回模型回复说明 Stream 长连接和 chatCompletions 端点都通了。群聊场景则把机器人拉进群 它提问观察群里是否收到回复。想更直观地看链路可以临时把日志级别调高openclaw gateway logs --follow发消息时观察日志里 dingtalk-connector 的收发记录能快速定位是钉钉侧没推过来还是 OpenClaw 侧没回出去。5. 本篇常见错排查机器人无响应。先openclaw gateway status确认网关在跑再回钉钉后台确认机器人消息接收模式是 Stream然后核对 openclaw.json 里的 Client ID / Client Secret 是否和凭证页一致。改完任何一项都要openclaw gateway restart配置不会热加载。报错 401 Unauthorized。典型日志是响应中断: Gateway error: 401 - {error:{message:Unauthorized,type:unauthorized}}。这基本是 gateway 认证没对上检查 openclaw.json 里gateway.auth.token与channels.dingtalk-connector.gatewayToken是否完全相同以及auth.mode是否为 token。两处不一致是最常见的原因。消息能进但回复发不出。回钉钉后台看权限是否漏开尤其是机器人消息发送权限和卡片相关权限。权限变更后需要重新发布应用版本管理员审批通过才生效。卡片渲染失败或流式更新中断。确认 Card.Instance.Write 和 Card.Streaming.Write 都已开启且应用版本已发布上线。6. 后续怎么用起来配置跑通后OpenClaw 侧就可以按你的业务接模型和工具了。如果你只是想让群里能问答直接在钉钉里 机器人即可如果要把告警、构建结果主动推到群里可以在 OpenClaw 里配置对应的触发逻辑通过 chatCompletions 端点把消息投递到钉钉通道。需要长期跑编码类或 Agent 类任务的话用 Coding Plan 更合适只是想验证模型对话效果可以先在模型对话里试接入和排障过程中要查凭证、看文档直接去 API Keys 页面拿 key再对照接入文档逐项核对字段。地址统一走 https://taotoken.net/api 文档和控制台入口都在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 上能找到。最后提醒一句openclaw.json 是纯文本改之前先备份一份尤其是 gateway 节点追加配置时别把原有内容覆盖掉。我踩过的坑就是第一次直接把整段 JSON 贴进去结果原来的 gateway 配置被冲掉重启后所有通道都断了回滚备份才恢复。