1. 为什么要在飞书里接入 OpenClaw企业 IM 场景的真实痛点很多团队已经在飞书里完成了日常沟通、审批、文档协作但 AI 能力往往还停留在「另开一个网页标签」的阶段。员工想问一句产品文档怎么写、这段报错什么意思得先切到浏览器、登录某个平台、再复制粘贴回来一来一回注意力就散了。OpenClaw 这类对话平台的价值就是把这层能力直接塞进飞书这个企业 IM 里让机器人和群聊、单聊融为一体。我先把结论说清楚OpenClaw 绑定飞书本质是两件事——在飞书开放平台拿到一对应用凭证App ID 和 App Secret再把这对凭证填进 OpenClaw 的集成配置里最后配好事件订阅回调让飞书的消息能推到 OpenClaw、OpenClaw 的回复能回到飞书。听起来简单但真正卡人的地方在于App ID 复制不全、App Secret 权限没开、回调地址填错、事件订阅没勾对任何一个环节出问题机器人就是「装死」。这篇教程面向的是想在企业协作场景里快速跑通机器人接入的开发者或运维同学。你不需要是飞书专家但需要有一个具备开发者权限的企业账号以及一台能跑 OpenClaw 的机器本地或服务器都行。我会把飞书端的应用创建参数、权限清单、回调地址模板全部给成可复制的形式再附一条消息收发验证动作让你配完就能看到机器人回话。顺便说一句OpenClaw 本身调用大模型时如果不想每个模型都单独配一套 Key可以用 TaoToken 做统一 Key 管理一个 Key 走多个模型配置上会省心不少。这个后面在配置章节会具体展开。先明确一下整体链路避免你配到一半不知道自己在哪一步飞书开放平台创建企业自建应用 → 拿到 App ID / App Secret → 配置权限与事件订阅 → 填回调地址 → OpenClaw 侧填入凭证 → 飞书发消息 → OpenClaw 收到并回复。这条链路里飞书端是「信任源」OpenClaw 端是「消费方」。凭证是钥匙事件订阅是门铃回调地址是门牌号。三者缺一不可。2. 前置准备飞书应用凭证与 OpenClaw 环境怎么配这一节把「动手之前必须准备好的东西」讲透包括飞书开放平台的应用创建、App ID 与 App Secret 的获取位置、权限清单以及 OpenClaw 侧的运行环境。很多人失败不是败在配置而是败在准备阶段就漏了权限。2.1 飞书开放平台创建企业自建应用登录飞书开放平台open.feishu.cn用具备开发者权限的企业管理员账号进入「开发者后台」。选择对应企业后点击「创建企业自建应用」。这里有个容易踩的坑一定要选「企业自建应用」不要选「商店应用」后者面向的是上架到应用市场的场景审核流程完全不同个人或内部团队用不上。创建时填写应用名称比如OpenClaw助手、应用描述、图标。名称建议带上团队标识方便后续在飞书客户端里搜索。创建完成后进入应用详情页左侧导航找到「凭证与基础信息」。在「应用凭证」区域你会看到两个关键字段App ID 的格式是以cli_开头后面跟约 32 位字符例如cli_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p。点击右侧复制图标完整保存。App Secret 默认是隐藏的显示成5f8xxxxxxxxxxxxxxxxxx这种形式需要点击显示按钮才能看到完整值。这个值相当于应用密码泄露了别人就能冒充你的应用调用接口所以别贴到公开仓库、别硬编码进前端。注意App Secret 如果怀疑泄露可以在同一页面点击重置重置后旧值立即失效记得同步更新 OpenClaw 侧的配置。2.2 权限清单机器人要能收能发光有凭证还不够飞书应用默认没有任何消息权限。你需要在「权限管理」里开通以下能力否则机器人收不到消息、也发不出去权限项用途是否必开im:message读取与发送单聊、群聊消息必开im:message.group_at_msg接收群里 机器人 的消息群聊场景必开im:message.p2p_msg接收单聊消息单聊场景必开im:chat获取群信息、群成员建议开contact:user.base:readonly读取用户基础信息建议开开通后记得点击「创建版本」并提交发布。企业自建应用一般需要管理员审批审批通过后权限才真正生效。这一步经常被忽略导致「权限明明开了却没反应」。2.3 事件订阅与回调地址飞书通过事件订阅把消息推给你的服务。在「事件与回调」页面选择「将事件发送至开发者服务器」填写回调地址例如https://your-domain.com/openclaw/feishu/event如果你在本地调试没有公网域名可以用内网穿透工具把本地端口映射出去但注意企业环境里要遵守公司网络规范。回调地址必须是 HTTPS飞书会做校验。订阅的事件类型至少勾选im.message.receive_v1接收消息im.message.message_read_v1消息已读可选填完回调地址后飞书会发送一个 challenge 校验请求你的服务需要原样返回 challenge 值才算验证通过。OpenClaw 的飞书适配层一般已经内置了这个逻辑你只要保证服务在跑、地址可达即可。2.4 OpenClaw 运行环境OpenClaw 可以跑在本地也可以跑在服务器。核心是它能对外提供回调接口并且能访问飞书开放平台的 API。环境上建议Node.js 18 或对应的运行时能出网访问飞书 API 和大模型 API一个稳定的进程管理方式systemd、pm2 或容器如果你用 TaoToken 统一管理模型 Key只需要在 OpenClaw 的模型配置里填一次 Base URL 和 Key后面切换模型不用改代码。TaoToken 的 API 地址是https://taotoken.net/apiKey 在控制台的 API Keys 页面生成。3. 可复制配置OpenClaw 侧填入凭证与模型参数这一节是全文最核心的部分所有配置都给成可直接复制的形式。配置分两块飞书凭证接入以及模型调用参数用 TaoToken 统一 Key。3.1 OpenClaw 飞书集成配置在 OpenClaw 的集成配置里找到飞书Feishu选项填入从飞书后台拿到的凭证。不同版本的 OpenClaw 配置形式可能是 JSON 或 TOML下面给一份通用的 JSON 配置片段路径按你实际的配置文件位置调整比如config/integrations/feishu.json{ feishu: { enabled: true, appId: cli_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p, appSecret: 5f8xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, verificationToken: your_verification_token, encryptKey: your_encrypt_key, eventPath: /openclaw/feishu/event, botName: OpenClaw助手 } }这里的verificationToken和encryptKey也在飞书「事件与回调」页面能找到。如果你没开启加密encryptKey可以留空但生产环境建议开启避免回调内容被篡改。如果你用的是 TOML 风格配置等价写法是[feishu] enabled true appId cli_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p appSecret 5f8xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx verificationToken your_verification_token encryptKey your_encrypt_key eventPath /openclaw/feishu/event botName OpenClaw助手填完后保存重启 OpenClaw 服务让配置生效。3.2 模型调用TaoToken 统一 Key 配置OpenClaw 要回复消息背后得有大模型。如果你每个模型都单独配 Key管理起来很乱。用 TaoToken 的话只需要一套 Base URL Key就能在多个模型之间切换。在 OpenClaw 的模型配置里填{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, modelId: claude-sonnet-4-20250514, maxTokens: 4096, temperature: 0.7 } }三个关键字段对齐一下Base URLhttps://taotoken.net/apiAPI Key在 TaoToken 控制台的 API Keys 页面生成格式一般是sk-开头Model ID按你要用的模型填比如 Claude 系列、GPT 系列具体以文档里的模型列表为准提示Model ID 一定要和 TaoToken 文档里列出的名称完全一致大小写、连字符都不能错否则会报模型不存在。如果你用的是 Claude Code 这类编码工具TaoToken 也支持通过环境变量接入export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoTokenKey这样 Claude Code 就会走 TaoToken 的通道不用改工具本身的代码。3.3 回调地址与事件订阅对齐回到飞书「事件与回调」页面把回调地址填成 OpenClaw 实际暴露的地址。假设你的服务跑在https://your-domain.com事件路径配的是/openclaw/feishu/event那飞书里就填https://your-domain.com/openclaw/feishu/event填完点击保存飞书会立刻发一个校验请求。如果 OpenClaw 服务正常页面会提示「验证成功」。如果提示失败先检查服务是否在跑、地址是否可达、路径是否和配置里一致。4. 验证请求发一条消息看机器人是否回话配置完不代表跑通必须做一次端到端验证。这一步我会给一条具体的验证动作以及成功结果的判断标准。4.1 发布应用并添加到飞书在飞书开放平台点击「创建版本」并提交发布管理员审批通过后在飞书客户端搜索你的应用名称比如OpenClaw助手把它添加为联系人或者拉进一个测试群。4.2 发送验证消息在单聊里给机器人发一句你好帮我确认一下接入是否正常或者在群里 机器人 发送同样内容。4.3 观察结果正常情况下几秒内你会收到机器人的回复。同时OpenClaw 的服务日志里应该能看到类似的事件记录[feishu] received event: im.message.receive_v1 [feishu] message content: 你好帮我确认一下接入是否正常 [model] request to taotoken, modelclaude-sonnet-4-20250514 [model] response received, tokens... [feishu] reply sent to chat_idoc_xxxxxxxx如果日志里能看到received event和reply sent说明整条链路通了。如果只看到received event没有reply sent问题多半在模型调用如果连received event都没有问题在飞书事件订阅或回调地址。4.4 用 curl 直接验证回调可达性如果你想绕过飞书先确认自己的回调服务是活的可以用 curl 模拟一次请求curl -X POST https://your-domain.com/openclaw/feishu/event \ -H Content-Type: application/json \ -d {type:url_verification,challenge:test_challenge_123}如果服务正常应该返回{challenge:test_challenge_123}这一步能快速区分「服务没起来」和「飞书配置不对」两类问题。5. 常见报错排查401、回调失败、模型无响应怎么解配置过程中最容易遇到几类报错我按真实错误信息对照着讲方便你直接定位。5.1 401 Unauthorized / invalid app credentials这个报错通常出现在 OpenClaw 调用飞书 API 时说明 App ID 或 App Secret 不对。排查顺序确认 App ID 是完整的cli_开头 32 位没有多复制空格确认 App Secret 没有过期或被重置过确认应用已经发布并通过审批未发布的应用凭证调用接口会失败如果报错信息里带app_id not found基本就是 App ID 复制错了。5.2 local proxy failed / connection refused这类报错说明 OpenClaw 访问外部 API 时网络不通。常见原因服务器出网被限制需要放行对飞书和大模型 API 的访问回调地址填的是内网地址飞书从公网访问不到本地调试没做端口映射排查时先用curl -v https://open.feishu.cn确认能出网再确认回调地址是公网可达的 HTTPS。5.3 reading choices 报错 / 模型返回结构异常如果你在日志里看到类似reading choices的报错说明模型返回的数据结构不符合预期。常见原因Base URL 填错请求打到了非兼容接口Model ID 不存在返回了错误对象而不是标准的 choices 结构API Key 无效返回了鉴权错误排查时先确认 Base URL 是https://taotoken.net/api再确认 Model ID 和文档一致最后确认 Key 有效。可以用一条 curl 直接测模型接口curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:ping}]}能正常返回 choices 就说明模型侧没问题。5.4 OAuth 相关报错 / 授权失败如果报错里出现 OAuth、scope、permission denied 字样说明飞书应用权限没开全或没生效。回到「权限管理」确认im:message等权限已开通并且应用版本已发布审批。权限变更后必须重新发布版本否则不生效。5.5 机器人不回复但日志无异常这种情况多半是事件订阅没勾对。确认「事件与回调」里勾选了im.message.receive_v1并且回调地址验证通过。另外群聊场景要确认勾了im:message.group_at_msg否则 机器人 的消息不会推过来。6. 长期使用建议把 Key 和配置管起来跑通之后接下来要考虑的是长期维护。几个实用建议第一App Secret 和 TaoToken Key 都不要写死在代码里用环境变量或密钥管理服务。OpenClaw 支持从环境变量读取配置这样换 Key 不用改代码。第二模型调用统一走 TaoToken 的 Base URL切换模型只改 Model ID不用动鉴权逻辑。如果你后面要接 Coding Plan 做长期编码任务也可以在 TaoToken 控制台里统一管理额度。第三回调地址和事件订阅变更后记得重新验证。飞书在配置变更后会重新发 challenge 校验服务必须在线。第四日志里保留 chat_id 和 message_id方便排查具体哪条消息没回复。但注意不要记录消息正文里的敏感信息。如果你还没生成 TaoToken Key可以去控制台的 API Keys 页面创建接入细节可以对照接入文档想先试试模型效果直接用模型对话页面验证长期编码或 Agent 场景可以看 Coding Plan。把这几步走完OpenClaw 在飞书里的机器人就能稳定跑起来了。
