企业官网建设流程全解析

1. 为什么企业 IM 集成总卡在 webhook 与鉴权这一层

OpenClaw 钉钉和飞书集成方案研究，说到底是在解决一个很具体的问题：本地跑的 AI 智能体，怎么让钉钉群和飞书群里的同事真正用起来。OpenClaw 本身是一个本地优先的个人 AI 智能体，具备系统级执行能力，能读写文件、跑命令、控浏览器，但它默认的交互入口是终端和 WebChat。企业里真正高频的沟通发生在钉钉和飞书，所以把这两个平台接进来，才算把 AI 能力送到同事手边。

我接触过不少团队，卡点几乎都集中在两处。第一处是 webhook 回调：钉钉和飞书都要求你的服务能被平台侧访问到，或者建立一条长连接通道，很多人本地起服务后不知道回调地址该填什么，填了也不通。第二处是鉴权配置：AppKey、AppSecret、CorpId、AgentId、VerificationToken、EncryptKey 这一堆参数，少填一个就是 401 或者签名校验失败，报错信息还特别含糊。

这篇内容面向需要打通企业 IM 与 AI 能力的开发者，目标很明确：产出一份可复制的集成配置清单与联调验证步骤。我会把 webhook 回调、事件订阅、鉴权参数逐层拆开，给出 endpoint 与鉴权参数的填写示例，以及回调连通性测试的具体动作。模型侧统一走 TaoToken 的 OpenAI 兼容接口，这样钉钉和飞书两个通道共用一套模型配置，不用分别维护。

需要先说明一点：钉钉和飞书在消息接收模式上的设计差异很大。飞书支持 WebSocket 长连接模式，本地开发不需要公网 IP；钉钉的机器人消息接收推荐 Stream 模式，同样是长连接，但配置项和飞书完全不同。理解这个差异，是后面所有配置能跑通的前提。

2. TaoToken 前置准备：把模型通道先打通

在动钉钉和飞书之前，我建议先把模型通道跑通。原因很简单：如果 IM 集成调通了但模型调用失败，你很难判断是通道问题还是模型问题。先把模型侧独立验证，后面排障会轻松很多。

TaoToken 提供 OpenAI SDK 兼容的 API 服务，OpenClaw 的模型配置系统正好支持openai-completions这种 API 类型，所以对接起来是顺的。你需要先拿到一个 API Key，然后确认 Base URL 和要用的 Model ID。

第一步，获取 API Key。访问 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 创建密钥，复制保存好，这个 Key 后面会填到 OpenClaw 的模型配置里。

第二步，确认接入端点。TaoToken 的 API 地址是 https://taotoken.net/api ，OpenAI 兼容模式下，chat completions 的完整路径是 https://taotoken.net/api/v1/chat/completions 。注意这里/api后面接/v1，和某些服务直接给/v1的写法不同，填错会 404。

第三步，选一个 Model ID。你可以先在模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 看看当前可用的模型列表，挑一个适合日常问答的。记下它的准确 ID，比如常见的对话模型 ID 格式。

这里有个容易踩的坑：OpenClaw 的模型配置里，baseUrl填的是到/v1这一层，还是到根路径，取决于它的拼接逻辑。稳妥的做法是先按https://taotoken.net/api/v1填，然后用命令行测试，如果报 404 再调整。我实测下来，OpenAI 兼容客户端一般期望baseUrl包含/v1。

把这三样东西准备好——API Key、Base URL、Model ID——后面配置钉钉和飞书通道时，模型部分直接复用，不用重复折腾。如果你后面要做长期编码或 Agent 类任务，可以了解下 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite ，按用量规划会更省心。

3. 可复制配置：钉钉 Stream 与飞书长连接的完整参数

这一节是核心，我把钉钉和飞书的配置拆成可直接复制的片段。先讲清楚配置文件的位置：OpenClaw 在 macOS 下的主配置是~/.openclaw/openclaw.json，模型和通道都写在这一个文件里。

3.1 模型配置片段（TaoToken）

先写模型部分，这是两个通道共用的基础：

{ "models": { "mode": "merge", "providers": { "taotoken": { "baseUrl": "https://taotoken.net/api/v1", "apiKey": "你的_TaoToken_API_Key", "api": "openai-completions", "models": [ { "id": "你的模型ID", "name": "TaoToken 对话模型" } ] } } }, "agents": { "defaults": { "model": { "primary": "taotoken:你的模型ID" } } } }

注意primary的写法是provider:modelId，中间用冒号。这个格式写错，OpenClaw 启动时会提示找不到模型。

3.2 钉钉通道配置

钉钉这边，你需要在钉钉开放平台创建应用，拿到 Client ID（也就是 AppKey）、Client Secret、Robot Code、Agent ID、Corp ID。消息接收模式必须选 Stream，这是钉钉侧的前提，选错了后面长连接建不起来。

{ "channels": { "dingtalk": { "enabled": true, "clientId": "dingxxxxxxxx", "clientSecret": "你的AppSecret", "robotCode": "dingxxxxxxxx", "corpId": "dingxxxxxxxx", "agentId": "123456789", "dmPolicy": "open", "groupPolicy": "open", "messageType": "markdown", "debug": false } } }

几个参数说明：robotCode通常和clientId相同，但有些应用会不一样，以开放平台显示为准。dmPolicy控制单聊策略，open表示任何人都能私聊机器人；groupPolicy控制群聊策略。生产环境建议改成pairing或allowlist，避免陌生人触发。

3.3 飞书通道配置

飞书这边，在飞书开放平台创建企业自建应用，拿到 App ID 和 App Secret。飞书推荐用 WebSocket 长连接模式，本地开发不需要公网回调地址。

{ "channels": { "feishu": { "enabled": true, "appId": "cli_xxxxxxxx", "appSecret": "你的AppSecret", "connectionMode": "websocket", "dmPolicy": "pairing", "groupPolicy": "allowlist", "requireMention": true, "verificationToken": "你的VerificationToken", "encryptKey": "你的EncryptKey", "debug": false } } }

connectionMode填websocket是关键，填成webhook就需要公网地址了。requireMention设为true表示群里必须 @机器人 才响应，避免刷屏。verificationToken和encryptKey在飞书事件订阅页面能找到，如果飞书侧没开加密，encryptKey可以留空。

3.4 合并后的完整配置

把上面三段合并到一个openclaw.json里，就是一份可用的配置。改完文件后，用openclaw config verify校验格式，再重启网关服务。这里提醒一句：JSON 里不能有注释，尾逗号也会导致解析失败，改完最好用python3 -m json.tool ~/.openclaw/openclaw.json过一遍。

4. 验证请求：从模型连通到回调联调

配置写完不代表通了，这一节讲怎么一步步验证。顺序很重要：先验模型，再验通道，最后验端到端。

4.1 验证模型连通

先用命令行直接测模型，绕开 IM 通道：

openclaw chat --model "taotoken:你的模型ID" --prompt "你好，回复一句话"

如果这条命令能返回内容，说明 TaoToken 的 Base URL、API Key、Model ID 三件套是对的。如果报 401，检查 API Key 是否复制完整；如果报 404，检查baseUrl是不是多了或少了/v1；如果报模型不存在，检查 Model ID 拼写。

4.2 验证钉钉 Stream 连接

启动网关服务，观察日志：

openclaw gateway --port 18789 --verbose

在另一个终端看钉钉通道日志：

tail -f ~/.openclaw/logs/channels/dingtalk.log

如果 Stream 连接建立成功，日志里会出现连接已建立的记录。然后去钉钉群里 @机器人 发一条消息，观察日志是否收到事件。收不到的话，先确认钉钉开放平台的消息接收模式确实是 Stream，再确认应用已经发布且机器人在可见范围内。

4.3 验证飞书长连接与回调

飞书这边，先确认 WebSocket 连接状态：

openclaw channels status feishu

然后在飞书开放平台的事件订阅页面，确认已经添加了im.message.receive_v1事件。飞书长连接模式下，事件是通过 WebSocket 推送的，不需要你填回调 URL，但事件类型必须订阅对。

在飞书群里 @机器人 发消息，看日志：

tail -f ~/.openclaw/logs/channels/feishu.log

4.4 回调连通性测试动作

如果你用的是 webhook 模式（比如飞书没开长连接，或者钉钉用了 HTTP 回调），需要测试回调地址是否可达。本地服务默认监听127.0.0.1:18789，平台侧访问不到，你需要一个能被平台访问的地址。测试方法：

curl -X POST http://localhost:18789/api/v1/channels/feishu/webhook \ -H "Content-Type: application/json" \ -d '{"type":"url_verification","challenge":"test123"}'

如果返回里带上了challenge的值，说明回调端点本身是活的。平台侧不通，通常是网络可达性问题，不是代码问题。

4.5 端到端成功结果

全部打通后，你在钉钉群 @机器人 问“帮我总结一下今天的待办”，机器人会调用 TaoToken 的模型，把结果以 markdown 消息发回群里。飞书群同理。这时候去看模型调用日志，能看到请求确实打到了 TaoToken 的端点。

5. 本篇常见错排查：401、local proxy failed 与 OAuth 报错

集成过程中最常见的几类报错，我按现象、原因、处理列出来。

5.1 401 鉴权失败

现象：模型调用返回 401，或者钉钉/飞书通道日志里出现鉴权失败。

模型侧的 401，八成是 API Key 问题。检查openclaw.json里apiKey字段有没有多余空格，或者环境变量没生效。可以用 curl 直接测：

curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer 你的Key" \ -H "Content-Type: application/json" \ -d '{"model":"你的模型ID","messages":[{"role":"user","content":"test"}]}'

如果 curl 通但 OpenClaw 不通，说明是配置读取问题，检查配置文件路径和 JSON 格式。

钉钉侧的 401，通常是clientSecret或corpId填错。飞书侧则要确认appSecret正确，且应用已发布。

5.2 local proxy failed

现象：日志里出现local proxy failed或连接被拒绝。

这个报错通常和网络配置有关。先确认网关服务在跑：

lsof -i :18789

如果端口没监听，服务没起来。如果服务在跑但通道连不上，检查是否有环境变量里的代理设置干扰了本地回环地址。本地服务之间的通信不应该走代理，把HTTP_PROXY、HTTPS_PROXY这类变量临时清掉再试：

unset HTTP_PROXY HTTPS_PROXY openclaw gateway restart

5.3 reading choices 相关报错

现象：模型返回解析失败，日志里出现reading 'choices'之类的字样。

这通常是响应格式不符合预期。OpenAI 兼容接口的响应里应该有choices数组，如果 TaoToken 返回的是错误对象，客户端去读choices就会报错。先看完整响应体，确认是不是模型 ID 写错导致返回了错误信息。用上面的 curl 命令看原始返回，比看 OpenClaw 的日志更直接。

5.4 OAuth 与签名校验失败

现象：飞书事件回调返回签名校验失败，或者钉钉提示 OAuth 相关错误。

飞书侧，检查verificationToken和encryptKey是否和开放平台一致。如果飞书开了加密，encryptKey必须填；没开加密却填了，也可能出问题。钉钉侧，Stream 模式下一般不走 OAuth 回调，如果出现 OAuth 报错，多半是应用权限没配全，回到开放平台检查机器人权限和消息权限是否都开了。

5.5 参数对照表

6. 语义一致 CTA：把通道跑通之后

钉钉和飞书的集成链路跑通后，你会发现真正的价值在于把 AI 能力嵌进了同事每天都会打开的 IM 里。不用再教大家装客户端、配环境，@一下机器人就能用。

如果你在配置过程中卡在鉴权参数或回调连通性上，接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 里有更细的端点说明和参数示例，配合 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 重新生成密钥排查，基本能覆盖大部分 401 场景。

想先确认模型侧是否正常，可以直接在模型对话 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 里发一条消息试试，确认通道可用再回来配 IM。如果你打算把 OpenClaw 长期挂在团队里跑编码和自动化任务，Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 的用量规划会比按次调用更可控。

最后留一个我踩过的坑：钉钉和飞书的应用发布后，权限变更不会自动生效，改完权限要重新发布版本。我一开始改完权限直接测，怎么都不通，重新发布后才正常。这个细节官方文档里写得不显眼，但很影响联调节奏。