1. OpenClaw 接入钉钉的真实场景与链路拆解
OpenClaw 是一个开源的个人 AI Agent 网关，它能把你本地的模型调用、工具执行、消息通道统一到一个 WebSocket Gateway 里管理。你可以把它理解成一个"AI 消息中枢"：一边连着模型（GLM、Claude、GPT 都行），一边连着聊天软件（Telegram、Discord、钉钉），中间用 skills 做能力编排。适合谁？适合想把 AI 助手塞进企业内部 IM、又不想把数据全交给第三方 SaaS 的开发者和小团队。
我这次的目标很具体：让 OpenClaw 在钉钉里跑起来，员工在钉钉群里 @机器人 就能触发 AI 回复，并且用 ClawHub 上的 skills 做消息处理编排。整条链路是：钉钉机器人回调 → openclaw-china 插件 → OpenClaw Gateway → 模型 API（通过 TaoToken 统一鉴权）→ 回复推回钉钉。
为什么模型调用要单独走 TaoToken？因为 OpenClaw 支持 OpenAI 兼容接口，而 TaoToken 提供统一的 Base URL 和 Key 管理，你不用在 OpenClaw 配置文件里硬编码各家厂商的 Key，换模型只改一个 Model ID 就行。这对后面调试 rate limit、切换模型特别省事。
链路里最容易出问题的三个点：一是钉钉机器人回调地址和加解密配置，二是 openclaw-china 插件的安装方式（新版禁止 URL 安装），三是模型通道的鉴权。下面按顺序拆。
先说前置条件。你需要 Node ≥ 22，macOS 或 Linux 都行，Windows 建议 WSL2。钉钉这边需要一个企业应用（个人也能申请），拿到 Client ID 和 Client Secret。模型这边注册 TaoToken 拿 Key。这些准备好，后面就是复制粘贴的事。
我实测下来，整个流程从零到钉钉里收到 AI 回复，大概 40 分钟，其中一半时间花在钉钉后台找配置项。所以下面我会把钉钉后台的每一步都写清楚，避免你来回翻菜单。
2. TaoToken 前置：统一 Key 与 API 通道配置
在动 OpenClaw 之前，先把模型通道打通。OpenClaw 的模型配置写在~/.openclaw/openclaw.json里，它支持 OpenAI 兼容的 provider。TaoToken 的 API 地址是https://taotoken.net/api，这是一个 OpenAI 兼容端点，你只需要 Base URL + API Key + Model ID 三件套。
先去 TaoToken 控制台创建 API Key。地址是 https://taotoken.net/api-keys ，登录后点"创建密钥"，复制出来，形如sk-xxxxxxxx。这个 Key 只显示一次，存好。
然后确认你要用的 Model ID。TaoToken 的模型列表在 https://taotoken.net/models 可以查，常见的有claude-sonnet-4-5、gpt-4o、glm-4.7-flash等。Model ID 必须和平台上的完全一致，大小写敏感，写错了会报model not found。
这里有个坑：OpenClaw 默认的 provider 配置里，baseUrl要写到/v1这一层还是根路径？实测 TaoToken 的 OpenAI 兼容端点是https://taotoken.net/api，OpenClaw 会自动补/v1/chat/completions，所以 Base URL 填https://taotoken.net/api即可，不要自己加/v1，否则会变成/api/v1/v1/...报 404。
配置方式有两种：命令行openclaw config set，或者直接编辑 JSON。我推荐直接编辑 JSON，因为 provider 结构嵌套较深，命令行容易写错层级。文件路径~/.openclaw/openclaw.json，用你熟悉的编辑器打开。
如果你还没装 OpenClaw，先装：
npm install -g openclaw@latest openclaw onboard --install-daemononboard过程中会问你要不要配置 channel，先跳过，我们后面手动配钉钉。模型这一步也可以先跳过，直接编辑 JSON。
装完后确认版本：
openclaw --version看到类似OpenClaw 2026.2.21-2就对了。接下来编辑配置文件，把 TaoToken 作为 provider 写进去。具体 JSON 片段在下一节给出，这里先说明字段含义：providers是一个对象，key 是 provider 名字（随便起，比如taotoken），value 里baseUrl填 TaoToken 地址，apiKey填你的 Key，models数组里列出你要用的 Model ID。
为什么要用 TaoToken 而不是直连某一家？因为 OpenClaw 的模型切换很频繁，调试阶段你可能今天用 GLM 明天用 Claude，如果每家都配一个 provider，配置文件会越来越乱。TaoToken 把多家模型收敛到一个端点，你只维护一个 Key，换模型只改 Model ID。这对后面做 skills 编排时的模型路由也有好处。
配好后先别急着接钉钉，用 OpenClaw 自带的对话测试一下模型通道通不通。命令是：
openclaw agent --message "你好，测试一下"如果返回正常文本，说明模型通道 OK。如果报API: rate limit或401，先排查 Key 和 Model ID，别往下走。这一步不通，后面钉钉接上了也是白搭。
3. 可复制配置：openclaw.json 与钉钉回调参数
这一节是核心，所有配置都给你可复制的片段。先看~/.openclaw/openclaw.json的完整结构。注意：如果你之前 onboard 生成过配置，不要整个覆盖，只把providers和channels两段合并进去。
{ "providers": { "taotoken": { "type": "openai", "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的TaoToken密钥", "models": [ "claude-sonnet-4-5", "glm-4.7-flash" ] } }, "agents": { "default": { "provider": "taotoken", "model": "claude-sonnet-4-5" } }, "channels": { "dingtalk": { "enabled": true, "clientId": "dingksa2c0om03kfjggp", "clientSecret": "你的ClientSecret", "robotCode": "你的RobotCode", "enableAICard": false, "dmPolicy": "open", "groupPolicy": "open", "messageType": "markdown", "debug": false } }, "gateway": { "http": { "endpoints": { "chatCompletions": { "enabled": true } } } } }几个关键点。providers.taotoken.type必须是openai，因为 TaoToken 是 OpenAI 兼容协议。agents.default里指定默认用哪个 provider 和 model，这样钉钉消息进来时 OpenClaw 知道调哪个模型。channels.dingtalk里的clientId和clientSecret来自钉钉后台，robotCode通常和 Client ID 相同，但有些企业应用里是独立的，以钉钉后台显示为准。
enableAICard设为 false 是因为 AI 卡片模式在部分钉钉版本里渲染有问题，先用普通 markdown 消息，稳定后再开。dmPolicy和groupPolicy都设open，意思是私聊和群聊都允许触发，生产环境建议改成白名单。
如果你不想编辑 JSON，也可以用命令行逐条设置：
openclaw config set channels.dingtalk.enabled true openclaw config set channels.dingtalk.clientId dingksa2c0om03kfjggp openclaw config set channels.dingtalk.clientSecret 你的ClientSecret openclaw config set channels.dingtalk.enableAICard false openclaw config set gateway.http.endpoints.chatCompletions.enabled true但 provider 那段命令行不好写，还是建议编辑 JSON。
接下来装 openclaw-china 插件。OpenClaw 官方目前支持 Telegram、Discord 等，国内 IM 靠社区插件。openclaw-china 是 BytePioneer-AI 维护的插件集，包含钉钉、飞书等通道。
安装统一包（含所有渠道）：
openclaw plugins install @openclaw-china/channels或者只装钉钉单个渠道：
openclaw plugins install @openclaw-china/dingtalk注意：不要同时装统一包和单渠道包，会冲突。另外，网上有些教程教你用 URL 直接安装插件，当前版本（2026年2月）已经禁止这种方式，必须用 npm 包名安装，否则会报plugin install from url is not allowed。
装完后验证插件加载：
openclaw plugins list应该能看到@openclaw-china/dingtalk在列表里，状态是 enabled。
钉钉后台这边，你需要做四步。第一步，登录钉钉开放平台，进入"应用开发"→"企业内部应用"，创建一个应用。第二步，在应用能力里添加"机器人"，填写机器人名称和图标，消息接收模式选"HTTP 回调"或"Stream 模式"。openclaw-china 用的是 Stream 模式（长连接），不需要你暴露公网地址，这点对本地开发很友好。第三步，发布应用版本，等审核通过（企业内部应用通常秒过）。第四步，在"凭证与基础信息"里复制 Client ID 和 Client Secret。
Stream 模式的好处是你不用配公网回调 URL，OpenClaw 主动连钉钉的 WebSocket，本地跑就行。这也是为什么gateway.http.endpoints.chatCompletions.enabled要设 true，OpenClaw 内部用 HTTP 端点做消息分发。
配置写完后重启 Gateway：
openclaw gateway --force--force会先杀掉占用默认端口的进程再启动，避免port already in use。
4. 验证请求：从本地对话到钉钉端到端测试
配置写完，先做三层验证，逐层排除问题。
第一层，模型通道。前面已经测过openclaw agent --message，再测一次确认配置生效：
openclaw agent --message "用一句话介绍你自己"正常返回说明 provider 配置没问题。如果报reading choices错误，通常是返回体结构不对，检查 Base URL 是不是多写了/v1。
第二层，Gateway 健康检查。启动 Gateway 后，另开一个终端：
openclaw health输出里应该看到 gateway 状态ok，channels 里 dingtalk 状态connected。如果 dingtalk 显示disconnected，看日志：
openclaw logs常见的是clientId or clientSecret invalid，回去核对钉钉后台的凭证。
第三层，钉钉端到端。打开钉钉，搜索你刚创建的应用名，进入机器人对话，发一条消息：
你好，帮我总结一下今天的待办如果一切正常，几秒内会收到 AI 回复。第一次可能会慢一点，因为要建立 Stream 连接。
我实测时遇到一个情况：钉钉里发消息没反应，但openclaw health显示 connected。查日志发现是messageType设成了markdown但钉钉应用没开 markdown 权限。解决办法是在钉钉后台"机器人"配置里勾选"消息卡片"或改用text类型。改完重启 Gateway 就好了。
再测群聊。把机器人拉进一个群，@它发消息。群聊触发需要groupPolicy为open，且钉钉后台机器人配置里要允许群聊。如果群里 @ 没反应，先确认是不是 @ 了正确的机器人（有些企业有多个机器人）。
端到端通了之后，可以测一下 skills。ClawHub 是 OpenClaw 的公共 skills 注册中心，所有 skills 都是公开的。先装 clawhub CLI：
npm i -g clawhub clawhub login clawhub whoamilogin会自动打开浏览器授权。登录后搜索一个 skill：
clawhub search "github"安装：
clawhub install github-repo-stats装完后 skill 位于~/.openclaw/workspace/skills/github-repo-stats/，里面有一个SKILL.md描述文件。OpenClaw 启动时会自动扫描这个目录，把 skills 注册进 agent 的能力列表。
你可以写一个自定义 skill 来处理钉钉消息。目录结构：
~/.openclaw/workspace/skills/ └── dingtalk-todo/ ├── SKILL.md └── handler.jsSKILL.md里写触发条件和描述，handler.js里写处理逻辑。OpenClaw 会根据消息内容匹配 skill，匹配到就调用 handler。这样你就能在钉钉里实现"发消息自动建待办""发消息查工单"之类的编排。
验证 skill 是否加载：
openclaw skills list看到你的 skill 在列表里就说明注册成功。然后在钉钉里发一条能触发该 skill 的消息，看是否走了自定义逻辑。
5. 本篇常见错排查：401、local proxy failed 与 OAuth
这一节把我在配置过程中踩过的报错都列出来，对照排查。
报错一：401 Unauthorized
出现在openclaw agent或钉钉回复时。原因通常是 TaoToken Key 写错或过期。检查openclaw.json里providers.taotoken.apiKey是否完整，有没有多余空格。另外确认 Key 没有在控制台被禁用。如果 Key 没问题，检查baseUrl是不是https://taotoken.net/api，写成https://taotoken.net会 404，写成https://taotoken.net/api/v1会变成/api/v1/v1/chat/completions报 404。
报错二：local proxy failed
这个报错通常出现在 Gateway 启动时，提示本地代理端口被占用或无法绑定。OpenClaw 默认 Gateway 端口是 18789，如果被其他进程占用，用--force重启：
openclaw gateway --force如果还不行，换端口：
openclaw gateway --port 18790同时检查系统代理设置。OpenClaw 会读取环境变量HTTP_PROXY/HTTPS_PROXY，如果这些变量指向一个不可用的地址，就会报local proxy failed。临时清掉：
unset HTTP_PROXY HTTPS_PROXY openclaw gateway --force报错三：reading choices或cannot read property 'choices' of undefined
这是模型返回体解析失败。OpenClaw 期望 OpenAI 格式的choices数组，如果返回的是错误对象或空体，就会报这个。排查顺序：先确认 Base URL 正确，再确认 Model ID 在 TaoToken 平台存在，最后看 Key 是否有该模型的权限。用 curl 直接测一下：
curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{"model":"claude-sonnet-4-5","messages":[{"role":"user","content":"hi"}]}'如果 curl 返回正常但 OpenClaw 报错，说明是 OpenClaw 配置里的 Base URL 多写了路径。
报错四：钉钉 OAuth 或invalid client
出现在钉钉通道连接时。检查clientId和clientSecret是否和钉钉后台一致。注意 Client Secret 里可能包含-和_，复制时别漏字符。另外确认应用已发布，未发布的应用凭证不生效。如果用的是 Stream 模式，确认钉钉后台机器人配置里"消息接收模式"选的是 Stream，不是 HTTP 回调。
报错五：plugin install from url is not allowed
前面提过，当前版本禁止 URL 安装插件。改用 npm 包名：
openclaw plugins install @openclaw-china/dingtalk如果 npm 安装报网络错误，检查 npm registry 配置，或者用pnpm add -g替代。
报错六：Rate limit exceeded（ClawHub）
clawhub search或clawhub install时出现。先确认已登录：
clawhub whoami如果未登录，执行clawhub login。登录后还有限流，等几分钟再试。另外确认安装的 skill 名字拼写正确，clawhub search的结果里复制完整名字。
报错七：钉钉消息发出但无回复
openclaw health显示 connected，但消息没触发 agent。检查gateway.http.endpoints.chatCompletions.enabled是否为 true。这个端点负责把钉钉消息转成 chat completion 请求，如果关了，消息进来也不会调模型。另外看openclaw logs里有没有message received日志，如果没有，说明钉钉消息根本没到 OpenClaw，检查钉钉后台的机器人权限和 Stream 连接状态。
排查时养成看日志的习惯：
openclaw logs --follow实时滚动日志，发一条钉钉消息，看日志里走了哪些步骤，哪一步断了，一目了然。
6. 语义一致 CTA：把链路固化下来
链路跑通后，建议把配置固化。openclaw.json备份一份，钉钉凭证和 TaoToken Key 用环境变量管理，别硬编码在文件里。OpenClaw 支持从环境变量读取 provider 配置，你可以在 JSON 里写"apiKey": "${TAOTOKEN_API_KEY}"，然后启动前 export。
模型通道这边，TaoToken 的 Key 管理页面在 https://taotoken.net/api-keys ，你可以按项目创建多个 Key，方便轮换和审计。接入文档在 https://taotoken.net/doc ，里面有 OpenAI 兼容接口的详细说明和示例代码。如果你要验证某个模型是否可用，可以直接在 https://taotoken.net/chat 里对话测试，确认 Model ID 和返回格式。
长期跑编码类 Agent 或需要稳定模型调用的场景，可以看 Coding Plan：https://taotoken.net/coding-plan ，它针对高频调用做了配额优化。控制台在 https://taotoken.net/console ，可以看调用量和余额。
Claude Code 相关的接入配置，参考 https://taotoken.net/claude-code ，里面写了 Anthropic 协议的 Base URL 和 Key 配置方式，和 OpenClaw 的 OpenAI 兼容配置是两套，别混用。
最后一步，把 skills 目录纳入版本管理。~/.openclaw/workspace/skills/下的自定义 skill 用 git 管理，ClawHub 上装的公共 skill 记录在package.json或一个清单文件里，换机器时一键恢复。这样你的钉钉 AI 助手就是一个可复制、可迁移的工程，而不是一堆散落的配置。
