1. OpenClaw 接入飞书为什么总卡在鉴权链路OpenClaw 是一个开源、本地优先的 AI 代理网关简单说就是让大模型在你自己的电脑或服务器上 7×24 小时跑着能执行命令、浏览网页、操作文件还能挂到飞书、Telegram、Discord 这些聊天平台上当机器人用。飞书接入是问得最多的场景之一因为企业内网里飞书是现成的 IM把 AI 代理塞进去团队里谁都能 一下就用。但真正动手的人会发现飞书开放平台的配置链路比想象中长创建自建应用、开机器人能力、批量导权限、配事件订阅、发版本这一套走完只是平台侧回到命令行还要启用插件、填 App ID 和 App Secret、配对私信、群组测试。中间任何一环断了表现都是「机器人不回消息」而日志里可能只给你一句access not configured。更麻烦的是鉴权。飞书用 App ID App Secret 换 tenant_access_tokenOpenClaw 这边要拿这个 token 去调消息接口同时 AI 模型侧还要另一套 Key 去请求大模型。两套鉴权混在一起排查新手很容易懵——到底是飞书没配对还是模型 Key 没配好这篇教程把两件事拆开飞书平台侧按步骤配到位模型侧用 TaoToken 统一 Key 打通。TaoToken 是一个 API 聚合通道一个 Key 就能调多家模型省得你在 OpenClaw 里为每个模型单独填 Base URL 和 Key。下面从零开始每一步都给可复制的配置和验证命令。适合谁看已经装好 OpenClaw、想接飞书但卡在鉴权或事件订阅的人以及想用统一 Key 管理模型调用、不想在多个平台间来回切的人。全程不需要公网 IPWebSocket 长连接本地就能跑通。2. TaoToken 统一 Key 与 OpenClaw 模型通道前置配置在碰飞书之前先把模型侧的路铺好。OpenClaw 本身是个网关它自己不产模型能力得指向一个模型 API。默认配置里你可能要填 OpenAI 或 Anthropic 的地址和 Key但如果你手上有多个模型想切换或者想用一个 Key 统一管理TaoToken 的 API 通道会更省事。TaoToken 的 API 入口是https://taotoken.net/api兼容 OpenAI 的接口格式。也就是说OpenClaw 里凡是让你填 OpenAI Base URL 的地方换成这个地址Key 换成 TaoToken 的 Key就能直接跑。模型 ID 按你实际要用的填比如gpt-4o、claude-3-5-sonnet这类具体以 TaoToken 控制台里列出的为准。先去 TaoToken 控制台拿 Key。打开https://taotoken.net/api-keys登录后创建一个 API Key复制出来。这个 Key 就是后面 OpenClaw 配置里的模型凭证。注意别把它提交到代码仓库跟飞书 App Secret 一样属于敏感信息。拿到 Key 之后OpenClaw 的模型配置通常写在openclaw.json里。不同版本字段名可能略有差异但核心就三样Base URL、API Key、Model ID。下面是一个可复制的配置片段路径按你实际的配置文件位置来一般在用户目录下的.openclaw/openclaw.json或项目根目录{ models: { default: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, model: gpt-4o } } }如果你用的是 TOML 格式的配置等价写法是这样[models.default] provider openai-compatible baseUrl https://taotoken.net/api apiKey sk-你的TaoTokenKey model gpt-4o填完之后先别急着接飞书单独验证模型通道通不通。OpenClaw 一般有 doctor 或直接对话的命令你可以先跑一次自诊断openclaw doctor如果输出里模型部分显示连接正常说明 TaoToken 通道没问题。要是报 401多半是 Key 复制错了或者前面多了空格报 model not found就是 Model ID 写错了回 TaoToken 控制台核对一下模型列表。这一步的意义在于把「模型能不能调通」和「飞书能不能收发消息」两个问题隔离开。后面飞书出问题你就能确定不是模型侧的锅。我试过先不隔离结果飞书配对码都拿到了机器人还是回空消息最后发现是模型 Key 没填对白白在飞书后台翻半天。3. 飞书开放平台应用创建与事件订阅可复制配置飞书这侧是整个接入里步骤最多的部分我按实际操作顺序拆开每步都给可复制的值。先打开飞书开放平台用飞书账号登录点右上角「创建企业自建应用」。应用名称随便填比如AI-Bot描述按需图标可以用默认。创建完进入应用详情页点左侧「凭证与基础信息」记下两个值App ID 格式像cli_xxxxxxxxxxApp Secret 点复制。这两个值后面openclaw channels add向导里要填。接着点左侧「添加应用能力」→「机器人」→ 添加。然后进「权限管理」点「批量导入/导出权限」把下面这段 JSON 粘进去覆盖原有内容一键导入{ scopes: { tenant: [ aily:file:read, aily:file:write, application:application.app_message_stats.overview:readonly, application:application:self_manage, application:bot.menu:write, cardkit:card:read, cardkit:card:write, contact:user.employee_id:readonly, corehr:file:download, event:ip_list, im:chat.access_event.bot_p2p_chat:read, im:chat.members:bot_access, im:message, im:message.group_at_msg:readonly, im:message.p2p_msg:readonly, im:message:readonly, im:message:send_as_bot, im:resource ], user: [ aily:file:read, aily:file:write, im:chat.access_event.bot_p2p_chat:read ] } }确认权限列表后点「申请开通」→「确认」。这里im:message和im:message:send_as_bot是收发消息的核心im:chat.members:bot_access管机器人进群别漏。然后是事件订阅这是最容易配错的一步。点左侧「事件与回调」→「事件配置」→「订阅方式」选「长连接接收事件WebSocket」保存。选 WebSocket 的好处是不用配公网 IP也不用 ngrok本地跑 OpenClaw 就能收飞书推送。接着点「添加事件」依次加这四个事件标识作用im.message.receive_v1接收消息核心事件im.message.message_read_v1消息已读回执im.chat.member.bot.added_v1机器人进群im.chat.member.bot.deleted_v1机器人被移出群im.message.receive_v1必须加少了它机器人收不到任何消息。加完进「版本管理与发布」→「创建版本」版本号填1.0.0发布说明随便写保存后确认发布。个人自建应用一般免审提交后自动通过页面上会提示「本次发布免审提交后自动通过并在线上生效」。到这里飞书平台侧就配完了。回到终端启用飞书插件openclaw plugins enable feishu输出里出现Enabled plugin feishu. Restart the gateway to apply.就是成功配置写进了openclaw.json原文件自动备份成.json.bak。如果看到plugins.allow is empty的警告那是提示你没配插件白名单系统可能自动加载其他已装插件。没特殊需求忽略即可要精确控制就在openclaw.json里把plugins.allow设成受信任的插件 ID 列表。验证插件状态openclaw plugins listfeishu显示loaded就是启用成功disabled就是没启用重跑 enable 再重启 Gateway。4. 渠道配置、配对与消息回调验证实操插件启用后跑渠道配置向导openclaw channels add向导会一步步问你按下面选步骤提示选择/输入1Configure chat channels now?Yes2Select a channelFeishu/Lark (飞书)3输入凭证方式Enter App Secret4Enter Feishu App Secret粘贴你的 App Secret5Enter Feishu App ID粘贴cli_xxxxxxxxxx6Feishu connection modeWebSocket (default)7Which Feishu domain?Feishu (feishu.cn) - China8Group chat policyOpen - respond in all groups (requires mention)9是否继续添加渠道Finished (Done)10Configure DM access policies now?Yes11Feishu DM policyPairing12Add display names?No13Bind channel accounts to agents?No配完在 OpenClaw 网页端「频道」里能看到飞书渠道已启用。私信策略选了 Pairing意味着只有配对过的用户才能私信机器人。现在去飞书客户端在聊天列表找到刚创建的机器人发任意一条私信。机器人会回一条包含配对码的消息类似OpenClaw: access not configured. Your Feishu user id: *********** Pairing code: HDHAHSDE Ask the bot owner to approve with: openclaw pairing approve feishu HDHAHSDE保持 Gateway 运行另开一个终端审批openclaw pairing approve feishu HDHAHSDE输出Approved feishu sender ...就是配对成功。这时候再给机器人发消息它就能正常回复了。如果回复是空的或者报错先看模型通道回第 2 节确认 TaoToken 的 Base URL 和 Key 没问题。群组测试在飞书里建个测试群进群设置 → 机器人 → 添加搜你的应用名加进去。然后在群里 机器人发消息AI-Bot 介绍一下你自己机器人正常回复说明消息回调、鉴权、模型调用整条链路都通了。这里验证的其实是飞书事件im.message.receive_v1推送到 OpenClawOpenClaw 拿 tenant_access_token 调飞书发消息接口同时用 TaoToken 的 Key 调模型生成回复三件事都成功。5. 接入飞书常见报错排查401、local proxy failed 与收不到消息接入过程里报错集中在几个地方我按真实遇到的整理。401 报错如果日志里出现401 Unauthorized先分清是飞书侧还是模型侧。飞书侧 401 通常是 App Secret 填错或应用没发布模型侧 401 是 TaoToken Key 无效。看日志上下文openclaw logs --channel feishu能看到飞书相关请求模型请求一般在通用日志里。TaoToken 的 Key 确认从https://taotoken.net/api-keys复制完整别带空格。local proxy failed这个报错一般是 OpenClaw 尝试走本地代理连模型 API 失败。检查你的openclaw.json里 Base URL 是不是写成了https://taotoken.net/api别多加路径或斜杠。如果系统里设了 HTTP_PROXY 之类的环境变量先清掉再试本地代理和直连冲突会导致这个错。reading choices 报错日志里出现reading choices或类似字段读取失败通常是模型返回格式不符合 OpenAI 兼容格式。确认 TaoToken 通道用的是openai-compatibleproviderModel ID 填的是 TaoToken 支持的模型。如果填了个不存在的模型名返回体里没有choices字段就会报这个。OAuth 相关报错如果看到 OAuth token 获取失败多半是飞书应用凭证问题。回开放平台确认 App ID 和 App Secret重新跑openclaw channels add覆盖配置。飞书自建应用不需要 OAuth 授权码流程用的是 tenant_access_token如果配置里混进了 OAuth 字段删掉。收不到消息按顺序查——Gateway 是否在跑openclaw gateway status事件订阅是否加了im.message.receive_v1且是 WebSocket 模式应用是否已发布机器人是否已加进群。四个都确认了还不行看日志openclaw logs --channel feishu。机器人回复为空这基本跟飞书无关是模型侧问题。跑openclaw logs --follow看详细日志再openclaw doctor自诊断。重点核对 TaoToken 的 Base URL、Key、Model ID 三件套是否齐全且正确。群聊太吵机器人响应所有消息确实烦。重新跑openclaw channels add在群聊策略那步选Allowlist只让指定群组触发。插件显示 disabled重跑openclaw plugins enable feishu然后openclaw gateway restart。日常管理命令备着openclaw gateway # 启动 Gateway openclaw gateway status # 查看运行状态 openclaw gateway restart # 重启 openclaw plugins list # 插件状态 openclaw channels add # 重配渠道 openclaw logs --follow # 实时日志 openclaw doctor # 自诊断6. 统一 Key 打通消息与鉴权后的长期用法链路跑通之后日常用起来其实就两件事飞书侧的消息收发和模型侧的调用。飞书侧配好一次基本不用动除非你要改群聊策略或加新事件。模型侧用 TaoToken 统一 Key 的好处这时候体现出来——想换模型只改openclaw.json里的 Model IDBase URL 和 Key 都不用动飞书那边完全无感。如果你打算长期跑编码类或 Agent 类任务比如让机器人在群里帮忙查代码、跑命令、做自动化可以考虑 TaoToken 的 Coding Plan按用量走比单次调用更划算具体在https://taotoken.net/coding-plan看。日常调试模型回复效果用模型对话页面直接测https://taotoken.net/chat不用每次都走飞书绕一圈。接入文档在https://taotoken.net/doc里面有各语言的调用示例和参数说明。API Key 管理还是https://taotoken.net/api-keysKey 泄露了及时在这里吊销重建。最后说个实际经验飞书事件订阅用 WebSocket 长连接本地跑没问题但如果你把 OpenClaw 部署在服务器上注意 Gateway 进程别被系统休眠杀掉用 systemd 或 supervisor 托管一下。另外配对码是一次性的换用户要重新配对别想着一个配对码给全团队用。群聊里 机器人触发是默认行为想让它主动响应所有消息得改策略但那样会很吵不建议。