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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_PROXY="dingtalk.com,.dingtalk.com,api.dingtalk.com,oapi.dingtalk.com,wss-open-connection.dingtalk.com"

这一步很多人忽略，结果排查半天以为是凭证错了。先把环境变量设好，再往下走。

3. 可复制配置：Gateway、钉钉插件与模型三件套

这一节是全文的核心，所有片段都可以直接抄改。顺序是：装框架 → 初始化 Gateway → 装钉钉插件 → 写配置文件 → 重启生效。

安装与初始化。全局安装后跑一次 onboard 向导，向导里渠道绑定可以先跳过，后面单独配：

npm install -g openclaw-cn@latest 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/AppSecret；corpId在企业信息页拿；robotCode是机器人唯一标识，在机器人配置页可见；agentId可选但推荐填，发消息时会用到；dmPolicy和groupPolicy控制私聊和群聊的触发策略，open表示允许，生产环境建议改allowlist并配白名单。messageType用markdown，回复支持富文本，可读性好很多。

模型段的三件套是重点：baseUrl填https://taotoken.net/api，apiKey填你创建的 Key，model填控制台里看到的模型 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-id

Webhook 模式对照。如果你只用自定义机器人做单向推送，渠道段换成：

{ "channels": { "dingtalk": { "enabled": true, "webhook": "https://oapi.dingtalk.com/robot/send?access_token=xxxx", "secret": "your-custom-bot-secret" } } }

注意 Webhook 模式只能推、不能收，Agent 无法在群里被 @ 触发，别拿它做交互场景。

重启生效。配置写完必须重启 Gateway：

openclaw-cn gateway restart

重启后 Gateway 会重新加载插件和渠道配置，钉钉插件开始尝试建立 Stream 长连接。这一步之后才进入验证环节。

4. 验证请求与成功结果：连通性检查与消息回执确认

配置写完不代表跑通，必须逐层验证。我按"渠道状态 → 连接日志 → 私聊回执 → 群聊回执 → 模型响应"五步走，每步都有明确的成功标志。

第一步，渠道状态。运行：

openclaw-cn channels list

钉钉渠道应显示为已连接（connected）。如果显示未连接或 error，先别急着改配置，看下一步日志。

第二步，连接日志。开一个终端跟日志：

openclaw-cn logs -f

成功建立 Stream 连接时会出现类似[dingtalk] Connected to DingTalk server的日志行。如果反复出现重连、超时，八成是网络或凭证问题，对照第 5 节的排查表处理。

第三步，私聊回执。在钉钉里搜索你创建的机器人名称，进入私聊窗口，发一句"你好"。预期行为：消息经 Stream 长连接进入 Gateway，Agent 调用模型生成回复，再通过钉钉 API 回推到私聊。成功标志是几秒内收到 Markdown 格式的回复。如果收到消息但无回复，看日志里有没有模型调用报错——这一步能区分是"钉钉通道问题"还是"模型 API 问题"。

第四步，群聊回执。把机器人拉进一个测试群（建议新建一个只有你和机器人的群，避免默认群屏蔽第三方机器人消息），在群里 @机器人 发指令。成功标志是群内收到回复。如果私聊通、群聊不通，基本是groupPolicy没设open，或者机器人没真正加入群。

第五步，模型响应确认。如果前四步都通但回复内容是空的或报错，单独验证模型三件套。用 curl 直接打一次 API：

curl 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填 AppKey，clientSecret填 AppSecret，填反了会表现为连接建立失败而非 401，但一起核对省得来回。

报错二：local proxy failed / 连接超时。现象是钉钉渠道反复重连，日志出现代理连接失败或超时。根因是出网代理拦截了钉钉的 WebSocket 长连接。动作：设置NO_PROXY环境变量把钉钉域名排除，然后重启 Gateway：

export NO_PROXY="dingtalk.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 节的五步验证。这套流程走顺了，后面加渠道、换模型、扩群都是十分钟的事。