OpenClaw接入飞书报错access not configured？权限配置与排查全攻略

我那天下午盯着屏幕看了整整十分钟——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。常见的触发情况我整理成了下面这张表：

我实际踩过一条最典型的坑：权限管理里加了im:message，然后很自信地在本地测试，结果飞书一直报access not configured。我当时代码都查完了，最后才发现——权限加完还要发布版本，线上根本不知道我加了新权限。

2. OpenClaw 接入飞书时的标准配置路径

既然问题大概率出在配置上，那我们就从配置源头开始捋。下面这套路径是我前前后后部署过多台机器后沉淀下来的，按顺序做完，能避开 90% 的权限坑。

2.1 飞书开放平台后台该做的事：从建应用到发布版本

首先要有一个飞书账号，最好把自己定位成企业管理员或者开发者，然后去飞书开放平台创建应用。这里我建议创建"企业自建应用"，因为测试阶段可以自己控制可用范围，不用走复杂的审核流程。

创建应用之后，按这个顺序操作：

1. 启用机器人能力：进入"应用能力"页面，找到机器人，点击启用。启用后你会在"机器人"设置里看到机器人的名字和头像，这个会直接显示在飞书客户端里。

2. 添加权限：进入"权限管理"页面，在搜索框里输入用到的权限关键字。最基础的消息权限建议加这些：

   • im:message或更细的im:message:send（发送消息）
   • im:message.receive_v1（接收消息事件，这其实是一个事件订阅，不是普通权限）
   • im:chat:read（读群信息，后续群聊测试用）
   • 如果想读取用户基本资料，可以加contact:user.base:read

   搜索到权限后点击开通，这一步只是把权限挂到应用上，还没生效。

3. 配置事件订阅：进入"事件订阅"页面，订阅im.message.receive_v1（接收消息）事件。这里需要填一个"请求地址"，也就是飞书把事件推给你的回调地址。还要配置Verification Token和Encrypt Key，这两个值后面要原封不动填到 OpenClaw 里。

4. 创建版本并发布：进入"版本管理与发布"，创建新版本，填版本号和更新说明，然后提交发布。这一步才是权限真正生效的时刻。企业自建应用发布通常即时生效，不需要等审核。

注意：我在这一步反复吃过亏——权限管理里加了权限，忘了点"创建版本并发布"，结果在 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 配置字段名可能有细微差异，比如有些版本用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都倒在下面这几项里：

1. 机器人能力是否启用：应用能力 > 机器人，确认状态是"已启用"。
2. 权限列表是否包含所需权限：权限管理里搜一下im:message等关键字，确认你要用的接口权限已经添加。
3. 是否发布了最新版本：版本管理与发布里，看"线上版本"是不是包含你刚加权限的那一版。
4. 可用范围是否覆盖测试人员：如果你的应用可用范围只设了某几个成员，那其他人（或测试群）触发操作时会被拒绝。
5. 事件订阅是否验证通过：事件订阅页面确认系统提示"请求地址验证成功"。

其中第 3 项是最隐蔽的坑。我见过有人权限列表里权限全都在，但线上版本还是三周前那个"空权限"版本，结果调接口一直报access not configured。这种问题看权限列表根本看不出来，必须去看"版本管理与发布"里的线上版本状态。

3.3 第三步：用 API 调试工具直接验证飞书接口

到了这一步，我们要做一个很关键的动作：把 OpenClaw 从疑犯名单里暂时摘出去，直接用裸请求去调飞书 API。如果裸请求都报错，那问题 100% 在飞书应用侧；如果裸请求正常，再回头查 OpenClaw 也不迟。

飞书开放平台自带一个"API Explorer"调试工具，里面可以选应用、选接口、填参数，然后直接以你这个应用的身份发起真实调用，返回结果非常直观。我强烈建议你先在这里把"发送消息"这个接口调通。

如果你想看得更透，可以用命令行直接跑。先拿 token：

curl -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 侧了。我按概率从高到低列一下：

1. 密钥填错：最常见的是把App Secret填成了Verification Token，或者把Encrypt Key和Verification Token搞混。这几个字符串长得几乎一模一样，肉眼很难分出来。建议把飞书后台的值复制出来，用文本对比工具和配置文件里的值逐字符比对，连末尾空格也不要放过。
2. 配置后没重启：前面提过，OpenClaw 不会热加载配置。改了配置不重启，进程里还是旧参数。
3. Token 类型用错：确认 OpenClaw 里的飞书渠道是以应用身份（tenant_access_token）运行，不要设置成需要用户 OAuth 的登录态模式。
4. 请求参数错误：比如发给用户时用了错误的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，因为它和你发消息通不通没任何关系。

一个比较实用的权限组合表如下：

注意，云文档和多维表格这类权限往往受企业管理员策略控制，如果管理员限制了应用访问某些知识库或表格，OpenClaw 调接口时可能既不会报access not configured，也不会说"权限不足"，而是直接给你一个云文档特有的permission denied错误。报错文案不同，但本质都是权限没到位。

5. 我踩过多次这个坑之后刻意养成的几个习惯

最后不写什么总结了，就分享几个我在反复被access not configured折磨之后，硬逼着自己养成的操作习惯。这些才是真正值钱的东西。

第一，把"改权限和重新发布版本"牢牢绑在一起。我在飞书后台只要动过权限管理、可用范围、事件订阅任意一项，下一步无条件去创建版本并发布。飞书的权限生效机制就是这个调性：后台列表里的东西不等于线上运行时的东西。把它当成和"改完配置要重启服务"一样的肌肉记忆，能省掉大量时间。

第二，遇到报错先飞书后台截图，再动代码。飞书后台的页面状态是排查的第一现场，而不是 OpenClaw 的日志。权限管理页面、版本发布页面、事件订阅页面这三张截图拍下来，90% 的情况你已经能看出问题在哪了。

第三，裸命令验证永远比直觉可靠。怀疑某个接口的时候，直接用 curl 或 API Explorer 以应用身份调一次，让飞书亲口告诉你到底有没有权限。这一步能把"OpenClaw 的问题"和"飞书应用的问题"干净利落地切开，不会再出现我那天晚上对着配置来回改的无效工作。

第四，保存好request_id和报错时间。如果动用所有手段还查不出来，这组信息就是你和飞书官方工单、OpenClaw 社区沟通时最有力的凭证。光说"我报错了"没用，把请求 ID 和时间线摆出来，能帮对方几分钟内定位。

OpenClaw 是好工具，飞书也是很成熟的平台，两者之间的权限契约却藏在很多不起眼的细节里。希望这篇复盘能帮你少熬一个我那样的夜。