我那天下午盯着屏幕看了整整十分钟——OpenClaw 在 WSL2 里跑起来了飞书机器人也配上去了我兴冲冲地在测试群里给机器人发了一句你好对面回我的不是一句你好而是一段冷冰冰的英文报错access not configured.当时我第一反应是 OpenClaw 的配置出了问题回头翻配置、翻日志、重启服务折腾一个小时毫无进展。后来才想明白这个报错根本不是 OpenClaw 抛出来的它只是把飞书开放平台返回的错误原封不动递到了我面前。换句话说我的 OpenClaw 没问题是飞书那边觉得你这个应用没有资格调用这个接口。这篇文章就是那次排错的完整复盘。如果你也在部署 OpenClaw 接入飞书时遇到access not configured照着下面的思路走一遍大概率能在半小时内找到根因。文章会从报错根源聊起再给一份不会漏项的飞书后台配置清单、OpenClaw 侧的标准配置最后是我实测下来最顺的一条排查链路。适合刚把 OpenClaw 跑通、正在接飞书的开发者看也适合在飞书开放平台上第一次做自建应用的同学参考。1. 先理解access not configured到底是谁在报错排错的第一步永远是定位报错来源。很多人在这一步就被带偏了以为 OpenClaw 有问题于是去翻它的源码、换版本、重装依赖结果白忙一场。1.1 报错源头这不是 OpenClaw 的错误文案access not configured这个英文短语在 OpenClaw 的代码仓库里你是搜不到完整匹配的。它来自飞书开放平台的 API 网关是飞书服务端在校验你的应用请求时返回的错误信息。大致含义是当前调用的接口所对应的权限在你这个应用上没有被配置好。拿生活里的场景类比你拿着公司门禁卡走进写字楼没问题应用凭证有效但用同一张卡去刷资料室的门门禁响了拒绝提示该卡未配置资料室权限。这时候你不会怪刷卡机OpenClaw而是应该去行政那边查卡片的权限配置飞书开放平台后台。所以当你看到这个报错第一反应不应该是OpenClaw 坏了而是飞书里的应用配置有问题。这个认知到位了后面排查才不会跑偏。1.2 飞书权限模型的三个关键概念能力、权限范围、Token想把问题彻底搞懂得先知道飞书开放平台对应用能不能调某个接口这件事是怎么管理的。我拆成三块来看这也是后面所有配置操作的底层逻辑。应用能力应用有没有开启某个功能模块。比如你的应用要当机器人发言那必须在应用能力里先启用机器人要操作多维表格得先看有没有开通相关的应用能力。能力没开权限配得再全也是白搭。权限范围Scope应用能调用哪些具体 API、读取哪些数据。比如发送消息需要im:message相关权限接收消息事件需要订阅im.message.receive_v1。飞书后台的权限管理页面可以随时添加权限但注意——加完之后并不代表马上生效还要走发布流程。Token 类型应用调用飞书接口前要先拿 Token。最常用的两种一种是tenant_access_token代表以应用身份调用OpenClaw 这种机器人场景基本都用它另一种是user_access_token代表以某个用户身份调用需要走 OAuth 授权。如果你把需要 user token 的接口拿到 tenant token 的身份下去调也会得到权限相关报错。这三个概念任意一个出问题都可能被飞书网关统一报成access not configured。常见的触发情况我整理成了下面这张表现象常见根因机器人不会说话一调发消息接口就报错应用没有开启机器人能力调用某个 API 直接报access not configured对应权限没有添加到应用权限列表权限列表里明明有但还是报错添加权限后没有创建版本并发布线上未生效之前能用改完权限后突然报错改权限后没发新版本线上权限被旧版本覆盖能发单聊不能发群聊群聊涉及的权限或可用范围没配置好文档、多维表格相关操作报错对应的云文档/多维表权限未开通或未发布我实际踩过一条最典型的坑权限管理里加了im:message然后很自信地在本地测试结果飞书一直报access not configured。我当时代码都查完了最后才发现——权限加完还要发布版本线上根本不知道我加了新权限。2. OpenClaw 接入飞书时的标准配置路径既然问题大概率出在配置上那我们就从配置源头开始捋。下面这套路径是我前前后后部署过多台机器后沉淀下来的按顺序做完能避开 90% 的权限坑。2.1 飞书开放平台后台该做的事从建应用到发布版本首先要有一个飞书账号最好把自己定位成企业管理员或者开发者然后去飞书开放平台创建应用。这里我建议创建企业自建应用因为测试阶段可以自己控制可用范围不用走复杂的审核流程。创建应用之后按这个顺序操作启用机器人能力进入应用能力页面找到机器人点击启用。启用后你会在机器人设置里看到机器人的名字和头像这个会直接显示在飞书客户端里。添加权限进入权限管理页面在搜索框里输入用到的权限关键字。最基础的消息权限建议加这些im:message或更细的im:message:send发送消息im:message.receive_v1接收消息事件这其实是一个事件订阅不是普通权限im:chat:read读群信息后续群聊测试用如果想读取用户基本资料可以加contact:user.base:read搜索到权限后点击开通这一步只是把权限挂到应用上还没生效。配置事件订阅进入事件订阅页面订阅im.message.receive_v1接收消息事件。这里需要填一个请求地址也就是飞书把事件推给你的回调地址。还要配置Verification Token和Encrypt Key这两个值后面要原封不动填到 OpenClaw 里。创建版本并发布进入版本管理与发布创建新版本填版本号和更新说明然后提交发布。这一步才是权限真正生效的时刻。企业自建应用发布通常即时生效不需要等审核。注意我在这一步反复吃过亏——权限管理里加了权限忘了点创建版本并发布结果在 API 调试台里怎么调都报权限错误。飞书的逻辑是后台列表里可以看到新权限但线上运行时用的还是最近一次发布版本里的权限集。改完任何权限都记得重新发一次版本。2.2 OpenClaw 侧要改的配置项OpenClaw 装好之后根目录下会生成一份配置文件通常放在~/.openclaw/下面文件名常见的是openclaw.config.ts或openclaw.config.json具体后缀取决于你用哪种格式初始化的。你需要在这个文件里把飞书渠道的信息填进去。配置的大概结构如下{ channels: [ { type: feishu, appId: cli_xxxxxxxx, appSecret: xxxxxxxxxxxxxxxx, verificationToken: xxxxxxxx, encryptKey: xxxxxxxx, botName: 你的机器人名字 } ] }字段和飞书后台的对应关系我建议直接对着抄不要凭记忆填OpenClaw 配置字段飞书后台位置appId凭证与基础信息 App ID形如cli_开头appSecret凭证与基础信息 App SecretverificationToken事件订阅 Verification TokenencryptKey事件订阅 Encrypt Key需开启加密后才有botName应用能力 机器人 机器人名称这里需要多说一句不同版本的 OpenClaw 配置字段名可能有细微差异比如有些版本用app_id而不是appId有些版本把encryptKey放在单独的加密配置块里。以你自己那个版本的官方配置示例为准但核心思路都一样——这四五个值必须和飞书后台完全一致。填完之后记得重启 OpenClaw它不会热加载配置文件。很多朋友改完配置发现还是报错最后发现进程没重启改了个寂寞。2.3 最容易漏的两处事件订阅请求地址与 Encrypt Key这一节要单独拿出来说因为我在网上看到太多人卡在这两个地方而报错信息五花八门有的根本不像权限问题。请求地址飞书后台事件订阅里那个请求地址必须填一个公网可访问的 URL。怎么理解飞书服务器收到消息后要把事件 POST 到这个地址上OpenClaw 里的飞书渠道就是在这个地址上等你的事件。如果你的 OpenClaw 跑在本地电脑上没有公网 IP那就需要用一个临时公网映射工具把本机的端口暴露出去或者直接把 OpenClaw 部署在一台有公网 IP 的服务器上。配置完请求地址后飞书会立刻发一个 URL 验证请求OpenClaw 需要正确响应并返回 challenge。如果地址不可达、超时、返回内容不对后台会明确显示请求地址验证失败。很多人的排查误区是我这个地址自己浏览器能打开为什么飞书验证失败因为飞书是从外部公网访问你的地址和你在内网浏览器访问不是一回事。Encrypt Key如果你在飞书后台开启了事件加密Encrypt Key会用于对事件内容进行 AES 加密。OpenClaw 侧必须配置同一个 Encrypt Key否则收到事件后解密失败表现就是回调验证不过或者消息进来后没有反应。反过来如果后台没开加密OpenClaw 里却填了一个 key也可能解析异常。我自己的习惯是最开始测试阶段干脆不启用事件加密只把 Verification Token 配上减少一个变量。等所有链路跑通了再回头开加密验证加密配置。这样出了错你能明确知道是哪个环节的问题。3. 完整排查链路让access not configured现出原型配置没问题但报错还是出现了怎么办下面这条排查链路是我实测下来最高效的按步骤走每一步都能帮你缩小范围。3.1 第一步先把报错上下文定性不要一上来就改配置先回答一个问题这个报错是在什么操作之后出现的是 OpenClaw 启动时就报错还是给机器人发消息时报错是日志里刷出来的错误还是飞书机器人回给你的文本是事件订阅验证阶段报错还是发消息/收消息阶段报错这几个场景指向的根因完全不同。给机器人发消息后它回复access not configured这通常意味着消息事件确实推到了 OpenClaw但 OpenClaw 在处理完想调用飞书 API 响应时权限不够。而如果启动时就报错那大概率是 OpenClaw 初始化飞书应用时获取 tenant_access_token 失败问题在 App ID/App Secret 上。同时把 OpenClaw 的日志打开。如果你是用npx openclaw前台启动的日志会直接滚动在终端里如果放后台了去~/.openclaw/logs目录下找日志文件。日志里报错通常会带 HTTP 状态码、飞书返回的错误码和request_id这几个信息后面排查都能用到。3.2 第二步逐个核对飞书后台的生效状态这一步看起来简单但绝大多数access not configured都倒在下面这几项里机器人能力是否启用应用能力 机器人确认状态是已启用。权限列表是否包含所需权限权限管理里搜一下im:message等关键字确认你要用的接口权限已经添加。是否发布了最新版本版本管理与发布里看线上版本是不是包含你刚加权限的那一版。可用范围是否覆盖测试人员如果你的应用可用范围只设了某几个成员那其他人或测试群触发操作时会被拒绝。事件订阅是否验证通过事件订阅页面确认系统提示请求地址验证成功。其中第 3 项是最隐蔽的坑。我见过有人权限列表里权限全都在但线上版本还是三周前那个空权限版本结果调接口一直报access not configured。这种问题看权限列表根本看不出来必须去看版本管理与发布里的线上版本状态。3.3 第三步用 API 调试工具直接验证飞书接口到了这一步我们要做一个很关键的动作把 OpenClaw 从疑犯名单里暂时摘出去直接用裸请求去调飞书 API。如果裸请求都报错那问题 100% 在飞书应用侧如果裸请求正常再回头查 OpenClaw 也不迟。飞书开放平台自带一个API Explorer调试工具里面可以选应用、选接口、填参数然后直接以你这个应用的身份发起真实调用返回结果非常直观。我强烈建议你先在这里把发送消息这个接口调通。如果你想看得更透可以用命令行直接跑。先拿 tokencurl -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \ -H Content-Type: application/json \ -d {app_id:cli_xxxx,app_secret:xxxx}正常返回会有一个tenant_access_token字段和过期时间。拿到 token 后再调发送消息接口curl -X POST https://open.feishu.cn/open-apis/im/v1/messages \ -H Authorization: Bearer t-xxxx \ -H Content-Type: application/json \ -d {receive_id:ou_xxxx,msg_type:text,content:{\text\:\hello\}}这里receive_id要填对方的open_id就是你那个测试账号自己的open_id。怎么拿在飞书后台的API Explorer里选获取用户 ID之类接口查询或者直接翻飞书后台用户管理界面。如果 curl 返回里出现access not configured飞书侧嫌疑彻底坐实如果 curl 返回成功说明应用本身没问题那焦点就回到 OpenClaw 的配置或它请求参数上。3.4 第四步回到 OpenClaw 配置逐项对照裸请求成功、OpenClaw 还报错那就要细查 OpenClaw 侧了。我按概率从高到低列一下密钥填错最常见的是把App Secret填成了Verification Token或者把Encrypt Key和Verification Token搞混。这几个字符串长得几乎一模一样肉眼很难分出来。建议把飞书后台的值复制出来用文本对比工具和配置文件里的值逐字符比对连末尾空格也不要放过。配置后没重启前面提过OpenClaw 不会热加载配置。改了配置不重启进程里还是旧参数。Token 类型用错确认 OpenClaw 里的飞书渠道是以应用身份tenant_access_token运行不要设置成需要用户 OAuth 的登录态模式。请求参数错误比如发给用户时用了错误的receive_id类型OpenClaw 内部生成的请求会因此被飞书拒绝报错有时也会套上权限的外壳。如果到这一步还查不出来把日志里的request_id、报错时间和 OpenClaw 版本记录下来提交给飞书开放平台官方工单附上你在后台的权限配置截图。让平台侧帮你查这个 request 到底是被哪条权限策略拦下来的。4. 排掉之后还容易炸的雷回调、命令前缀与消息权限access not configured解决之后不代表就能高枕无忧。下面的雷是我和身边朋友在 OpenClaw 飞书这条路上接着踩到的提前说清楚能帮你少走弯路。4.1 事件订阅验证的三种失败姿势事件订阅本身是个大雷区。即便权限全对回调地址这块也能卡你半天。最常见的三种姿势全是我见过或踩过的姿势一地址不可达。飞书后台保存请求地址时会从公网发一个 URL 验证请求过来。你的服务必须监听在公网映射的那个端口上而且防火墙不能拦它。如果后台一直提示验证失败或验证中先检查自己本机端口是不是真的对外可达。姿势二OpenClaw 还没启动就去点验证。有些人先把地址填进去保存再跑去启动 OpenClaw结果验证请求发过来时服务还没起来自然失败。正确顺序是先启动 OpenClaw确认日志里飞书渠道监听成功再把地址填进后台保存。姿势三加密配置不一致。后台加密开关没开OpenClaw 里却填了 Encrypt Key或者后台开了加密OpenClaw 没填——这两种情况都会导致飞书后台显示验证失败或解密失败。先把两边开关调成一致的再验证。给一个最少走弯路的操作顺序启动 OpenClaw → 确认本地监听和日志正常 → 浏览器访问回调地址确认有响应 → 到飞书后台填请求地址 → 等待验证成功提示 → 发一条消息测试。4.2 单聊、群聊和回复消息的权限边界很多人测试时就挑最简单的单聊场景通了就觉得万事大吉。实际上单聊和群聊在权限模型里是有差异的。单聊里机器人能和用户一对一对话前提是用户在你应用的可用范围内群聊里机器人要被拉到群里而且应用可用范围要覆盖这个群。权限范围也要看清楚。如果 OpenClaw 后续要读取群成员列表、群名称你得有im:chat:read之类的权限否则调用群信息接口时飞书照样会拒绝。有些群操作走的是im:chat:readonly不同的只读/读写权限别搞混。还有一个容易漏的场景机器人收到消息后是回复那条消息还是再发一条新消息。从飞书权限角度看两者都需要im:message发送权限但回复场景里 OpenClaw 还会用到事件里携带的message_id如果事件订阅没有正确把消息 ID 传进来回复就会失败而且报错有时候很含糊。所以我在测试时会把收到消息→回复文本手动触发→主动发消息两个路径都测一遍分开排查。4.3 进阶表格、多维表格、文档等扩展操作需要什么OpenClaw 接入飞书后很多人不止想让机器人聊聊天还想让它发消息卡片、发送表格、操作多维表格。这些扩展功能的权限模型和纯消息完全不一样而且是另一个access not configured高发区。拿飞书多维表格举例OpenClaw 如果要在多维表格里写入记录或读取视图数据需要开通多维表格相关权限比如bitable:app、bitable:table、bitable:record。发送飞书表格文件也会涉及云空间权限drive:drive或docs相关权限。如果只配了消息权限调这些接口时飞书一样会回access not configured因为它和你发消息通不通没任何关系。一个比较实用的权限组合表如下功能需求建议开通的权限收发单聊/群聊文本消息im:message、im:message.receive_v1读取群信息、群成员im:chat:read读取用户基本信息contact:user.base:read发消息卡片/富文本im:message:send及消息卡片相关能力读写多维表格数据bitable:app、bitable:table、bitable:record操作云文档docs、drive:drive相关权限注意云文档和多维表格这类权限往往受企业管理员策略控制如果管理员限制了应用访问某些知识库或表格OpenClaw 调接口时可能既不会报access not configured也不会说权限不足而是直接给你一个云文档特有的permission denied错误。报错文案不同但本质都是权限没到位。5. 我踩过多次这个坑之后刻意养成的几个习惯最后不写什么总结了就分享几个我在反复被access not configured折磨之后硬逼着自己养成的操作习惯。这些才是真正值钱的东西。第一把改权限和重新发布版本牢牢绑在一起。我在飞书后台只要动过权限管理、可用范围、事件订阅任意一项下一步无条件去创建版本并发布。飞书的权限生效机制就是这个调性后台列表里的东西不等于线上运行时的东西。把它当成和改完配置要重启服务一样的肌肉记忆能省掉大量时间。第二遇到报错先飞书后台截图再动代码。飞书后台的页面状态是排查的第一现场而不是 OpenClaw 的日志。权限管理页面、版本发布页面、事件订阅页面这三张截图拍下来90% 的情况你已经能看出问题在哪了。第三裸命令验证永远比直觉可靠。怀疑某个接口的时候直接用 curl 或 API Explorer 以应用身份调一次让飞书亲口告诉你到底有没有权限。这一步能把OpenClaw 的问题和飞书应用的问题干净利落地切开不会再出现我那天晚上对着配置来回改的无效工作。第四保存好request_id和报错时间。如果动用所有手段还查不出来这组信息就是你和飞书官方工单、OpenClaw 社区沟通时最有力的凭证。光说我报错了没用把请求 ID 和时间线摆出来能帮对方几分钟内定位。OpenClaw 是好工具飞书也是很成熟的平台两者之间的权限契约却藏在很多不起眼的细节里。希望这篇复盘能帮你少熬一个我那样的夜。