★ FEATURED ARTICLE 1. 为什么要在钉钉里跑 OpenClaw场景与痛点拆解OpenClaw 是一个开源的 AI 自动化执行框架核心能力是把大模型的说变成做——读写文件、跑命令、调工具、串流程。它本身支持多渠道接入而钉钉是国内办公场景里落地成本最低的渠道之一。把两者接起来之后你在钉钉群聊或私聊里 一下机器人就能让 OpenClaw 在服务器上执行任务把结果以 Markdown 消息回推到会话里。适合谁适合手里有一台常开服务器、团队日常沟通在钉钉、又想让 AI 真正参与工作流日报汇总、日志排查、定时推送、文档处理的开发者和运维同学。但真正动手时坑比想象中多。我见过最多的三类问题一是 Gateway 起来了但钉钉渠道一直显示未连接日志里反复重连二是私聊能通、群里 了没反应三是消息发出去了OpenClaw 那边报reading choices之类的模型响应解析错误。这些问题的根因往往不在钉钉侧而在 Gateway 的渠道配置、插件白名单、模型 API 三者之间的衔接上。这篇就按装框架 → 配 Gateway → 装钉钉插件 → 建钉钉应用 → 填配置 → 验证回执 → 排错的顺序走一遍每一步都给可复制的片段和验证动作目标是让你从零到消息闭环跑通。需要先明确一个概念边界OpenClaw 的 Gateway 是消息路由与会话管理的核心进程它负责接收各渠道进来的消息、分发给 Agent 执行、再把结果路由回原渠道。钉钉插件是挂在 Gateway 上的一个 channel adapter负责和钉钉开放平台的 Stream 长连接或 Webhook 打交道。模型 API 则是 Agent 的大脑三者缺一不可。很多人只配了前两个忘了模型结果机器人收到消息却吐不出内容误以为是钉钉的问题。下面按顺序来。2. 前置准备Node 环境、钉钉应用与模型 API Key 获取这一节把动手前必须齐活的东西列清楚缺一样后面都会卡。Node.js 环境。OpenClaw 要求 Node.js ≥ 22低于这个版本在安装原生依赖时会编译失败。验证命令node -v # 期望输出 v22.x.x 或更高如果版本不够用 nvm 切换最省事nvm install 22 nvm use 22钉钉侧的准备。你需要一个具有企业管理员权限的钉钉账号因为创建企业内部应用、添加机器人能力、发布版本这些操作都在开发者后台完成。这里有个关键选择用企业内部应用Stream 模式还是自定义机器人Webhook 模式。前者走 WebSocket 长连接不需要公网 IP权限体系完整支持私聊和群聊双向交互是绝大多数场景的正解后者只是在群里单向推消息配置简单但功能受限适合纯告警推送。本文主线走 Stream 模式Webhook 模式在配置章节给对照片段。模型 API Key。OpenClaw 自身不带模型能力必须外接。你可以用任意兼容 OpenAI 协议的服务这里以 TaoToken 为例走通全流程——它提供统一的 API 入口模型 ID 和 Base URL 在控制台可见。获取步骤打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后进入控制台在 API Keys 页面创建一个 Key 并保存好模型对话入口在 https://taotoken.net/api 对应的对话页可以直接试跑模型确认 Key 可用。如果你打算长期跑编码类 Agent 任务Coding Plan 页面有套餐说明按需选择即可。记住三个要素Base URL、API Key、Model ID后面配置里三件套必须齐全缺一个就会出现 401 或空响应。部署环境。本地 Mac/Windows 可以跑通验证但企业场景建议放云服务器7×24 常开。服务器需要能正常访问钉钉开放平台域名。如果你的环境里有出网代理务必把钉钉相关域名加进NO_PROXY否则 Stream 长连接会被代理干扰表现为反复重连export NO_PROXYdingtalk.com,.dingtalk.com,api.dingtalk.com,oapi.dingtalk.com,wss-open-connection.dingtalk.com这一步很多人忽略结果排查半天以为是凭证错了。先把环境变量设好再往下走。3. 可复制配置Gateway、钉钉插件与模型三件套这一节是全文的核心所有片段都可以直接抄改。顺序是装框架 → 初始化 Gateway → 装钉钉插件 → 写配置文件 → 重启生效。安装与初始化。全局安装后跑一次 onboard 向导向导里渠道绑定可以先跳过后面单独配npm install -g openclaw-cnlatest openclaw-cn onboard --install-daemon--install-daemon会把 Gateway 注册成守护进程开机自启、崩溃重启。装完确认状态openclaw-cn gateway status安装钉钉插件。OpenClaw 本体不带钉钉通道必须装插件。装完用plugins list确认加载openclaw-cn plugins install moltybob/dingtalk openclaw-cn plugins list # 列表中应出现 dingtalk新版 OpenClaw 有插件白名单机制不显式声明信任的插件可能不加载。编辑~/.openclaw/openclaw.json加入{ plugins: { allow: [dingtalk] } }Gateway 与钉钉渠道配置。这是最容易写错的一段。完整配置片段如下路径就是~/.openclaw/openclaw.json字段名和原文保持一致{ plugins: { allow: [dingtalk] }, channels: { dingtalk: { enabled: true, clientId: your-app-key, clientSecret: your-app-secret, corpId: your-corp-id, robotCode: your-robot-code, agentId: your-agent-id, dmPolicy: open, groupPolicy: open, messageType: markdown } }, models: { default: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-your-taotoken-key, model: your-model-id } } }字段逐个说清楚clientId/clientSecret对应钉钉后台的 AppKey/AppSecretcorpId在企业信息页拿robotCode是机器人唯一标识在机器人配置页可见agentId可选但推荐填发消息时会用到dmPolicy和groupPolicy控制私聊和群聊的触发策略open表示允许生产环境建议改allowlist并配白名单。messageType用markdown回复支持富文本可读性好很多。模型段的三件套是重点baseUrl填https://taotoken.net/apiapiKey填你创建的 Keymodel填控制台里看到的模型 ID。三者必须匹配否则会出现 401 或reading choices报错。如果你用命令行配置也行openclaw-cn config set models.default.baseUrl https://taotoken.net/api openclaw-cn config set models.default.apiKey sk-your-taotoken-key openclaw-cn config set models.default.model your-model-idWebhook 模式对照。如果你只用自定义机器人做单向推送渠道段换成{ channels: { dingtalk: { enabled: true, webhook: https://oapi.dingtalk.com/robot/send?access_tokenxxxx, secret: your-custom-bot-secret } } }注意 Webhook 模式只能推、不能收Agent 无法在群里被 触发别拿它做交互场景。重启生效。配置写完必须重启 Gatewayopenclaw-cn gateway restart重启后 Gateway 会重新加载插件和渠道配置钉钉插件开始尝试建立 Stream 长连接。这一步之后才进入验证环节。4. 验证请求与成功结果连通性检查与消息回执确认配置写完不代表跑通必须逐层验证。我按渠道状态 → 连接日志 → 私聊回执 → 群聊回执 → 模型响应五步走每步都有明确的成功标志。第一步渠道状态。运行openclaw-cn channels list钉钉渠道应显示为已连接connected。如果显示未连接或 error先别急着改配置看下一步日志。第二步连接日志。开一个终端跟日志openclaw-cn logs -f成功建立 Stream 连接时会出现类似[dingtalk] Connected to DingTalk server的日志行。如果反复出现重连、超时八成是网络或凭证问题对照第 5 节的排查表处理。第三步私聊回执。在钉钉里搜索你创建的机器人名称进入私聊窗口发一句你好。预期行为消息经 Stream 长连接进入 GatewayAgent 调用模型生成回复再通过钉钉 API 回推到私聊。成功标志是几秒内收到 Markdown 格式的回复。如果收到消息但无回复看日志里有没有模型调用报错——这一步能区分是钉钉通道问题还是模型 API 问题。第四步群聊回执。把机器人拉进一个测试群建议新建一个只有你和机器人的群避免默认群屏蔽第三方机器人消息在群里 机器人 发指令。成功标志是群内收到回复。如果私聊通、群聊不通基本是groupPolicy没设open或者机器人没真正加入群。第五步模型响应确认。如果前四步都通但回复内容是空的或报错单独验证模型三件套。用 curl 直接打一次 APIcurl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-your-taotoken-key \ -H Content-Type: application/json \ -d {model:your-model-id,messages:[{role:user,content:ping}]}返回里有choices数组且内容非空说明 Key、Base URL、Model ID 三件套正确。如果这里就报 401问题在 Key报 model not found问题在 Model ID返回结构异常检查 Base URL 是否多了或少了/v1路径。这一步单独验证过后面排错就能快速定位责任方。你也可以直接在模型对话页手动发一条消息对照确认账号侧模型可用。五步全绿闭环就算跑通了。整个过程里日志是你最好的朋友任何一步失败都先看日志再动手改。5. 本篇常见错排查401、local proxy failed 与 reading choices这一节按真实报错对照每条给现象、根因、动作。排错的原则是先分层定位钉钉侧 / Gateway 侧 / 模型侧再针对性修别一上来就重装。报错一HTTP 401 Unauthorized。现象是日志里模型调用返回 401钉钉里机器人收到消息但不回复。根因几乎都是 API Key 错误或过期。动作核对models.default.apiKey是否和 TaoToken 控制台里创建的一致注意有没有多余空格确认 Base URL 是https://taotoken.net/api而不是别的路径如果 Key 刚轮换过重启 Gateway 让新配置生效。顺带检查钉钉侧的 AppKey/AppSecret 是否填反——clientId填 AppKeyclientSecret填 AppSecret填反了会表现为连接建立失败而非 401但一起核对省得来回。报错二local proxy failed / 连接超时。现象是钉钉渠道反复重连日志出现代理连接失败或超时。根因是出网代理拦截了钉钉的 WebSocket 长连接。动作设置NO_PROXY环境变量把钉钉域名排除然后重启 Gatewayexport NO_PROXYdingtalk.com,.dingtalk.com,api.dingtalk.com,oapi.dingtalk.com,wss-open-connection.dingtalk.com openclaw-cn gateway restart如果 Gateway 是守护进程方式跑的环境变量要写进服务配置或启动脚本里光在 shell 里 export 对已启动的进程无效。这是很多人踩的坑export 了但没重启或者重启了但守护进程没继承环境变量。报错三Cannot read properties of undefined (reading choices)。现象是钉钉里发消息后无回复日志里模型响应解析报reading choices。根因是模型 API 返回的结构不符合 OpenAI 兼容格式常见于 Base URL 指错打到了非兼容端点、Model ID 不存在导致返回错误对象、或 Key 无效返回鉴权错误体。动作先用第 4 节的 curl 单独验证三件套确认返回体里有choices字段检查baseUrl是否精确为https://taotoken.net/api确认model字段填的是控制台里真实存在的模型 ID。三件套对齐后重启问题基本消失。报错四OAuth / 授权相关错误。现象是钉钉侧提示授权失败或应用无权限。根因是钉钉应用权限没配全或版本没发布。动作回开发者后台检查权限管理里是否加了成员读取、发送应用消息、发送群消息这几项确认应用版本已发布只在后台保存机器人配置不算发布要走版本管理与发布流程确认corpId和企业一致。报错五插件未加载。现象是plugins list里没有 dingtalk或渠道显示未连接。动作确认plugins.allow白名单包含dingtalk重新执行openclaw-cn plugins install moltybob/dingtalk检查~/.openclaw/openclaw.json是否是合法 JSON这个文件支持 JSON5但语法错误仍会导致整体加载失败用校验工具过一遍。报错六群聊无响应但私聊正常。动作确认groupPolicy为open确认机器人已被添加到目标群换一个新建的测试群验证排除默认群策略干扰。排查时建议开 debug 日志看详细调用链openclaw-cn logs --level debug日志里能看到每条消息的入站、模型请求、出站回执三段哪段断了修哪段比盲猜高效得多。6. 长期运行与扩展Coding Plan、Skills 与接入文档跑通之后接下来考虑的是稳定性和能力扩展。企业场景里机器人不是玩具要能长期扛住日常消息量。长期编码与 Agent 任务。如果你打算让 OpenClaw 承担代码生成、日志分析、定时任务这类持续性的 Agent 工作模型调用量会明显上升按量计费不如套餐划算。TaoToken 的 Coding Plan 面向长期编码场景套餐和额度在 https://taotoken.net/api 对应的 coding-plan 页面可以查看按团队实际用量选档即可。选之前先用模型对话页跑几条真实任务估算单次 token 消耗再决定档位别拍脑袋。Skills 扩展。OpenClaw 的 Skills 机制让它从能聊变成能做。装技能的命令很直接openclaw-cn skills install pdf openclaw-cn skills install email装完之后钉钉里发帮我把这个 PDF 转成摘要这类指令Agent 就会调用对应技能执行。技能加载有优先级工作区技能 本地技能 内置技能同名覆盖。每个技能目录里要有SKILL.md说明文件才会被识别自己写技能时别漏。多群接入。一个机器人服务多个群时可以在渠道配置里用instances挂多个实例每个实例独立凭证{ channels: { dingtalk: { enabled: true, instances: { sales-group: { clientId: xxx, clientSecret: yyy }, support-group: { clientId: aaa, clientSecret: bbb } } } } }安全与运维。生产环境把dmPolicy和groupPolicy改成allowlist并配白名单避免任意成员触发高权限操作Client Secret 和 API Key 不要提交到代码仓库用普通用户权限跑 Gateway别用 root定期更新 OpenClaw 和插件版本。频率上注意钉钉自定义机器人每分钟 20 条的限制超限会被限流 10 分钟批量推送场景把消息合并成 Markdown 摘要再发。接入文档与 Key 管理。配置过程中如果字段含义拿不准接入文档页有完整的参数说明和示例路径在 https://taotoken.net/api 对应的 doc 入口API Key 的创建、轮换、禁用都在 console 的 api-keys 页面操作建议给不同环境建不同的 Key方便出问题时快速定位和吊销。Claude Code 相关的接入配置在 ClaudeCodeAnthropic 页面有专门说明如果你同时用 Claude Code 做开发可以对照着把模型端点统一到同一套配置上减少维护成本。最后给一个实操建议把~/.openclaw/openclaw.json纳入版本管理脱敏后每次改配置前先备份改完gateway restart再跑一遍第 4 节的五步验证。这套流程走顺了后面加渠道、换模型、扩群都是十分钟的事。
阅读完成 · 觉得有帮助？
