企业官网建设流程全解析

这段时间一直有人问我：想把 AI 接到飞书里，到底是直接在飞书开放平台裸写一个回调，还是用现成的中间层框架？我两条路都试过，最后稳定跑起来的是基于 OpenClaw 对接飞书的方案。这篇文章会把从零到一的完整过程写下来：飞书后台怎么开应用、权限怎么勾、事件订阅为什么建议用长连接、OpenClaw 这边每一项配置到底有什么用，以及在本地跑通以后我踩过的五个坑。内容尽量保姆级，刚接触飞书开放平台的人跟着走也能搭出自己的 AI 助手。

先交代一下背景。我需要在飞书里放一个能随叫随到的助手，用途包括日常问答、整理群里零散信息、偶尔写点周报素材。官方自带的那点机器人能力不够灵活，我们的模型接口、提示词、知识库都要自己接。这个时候摆在面前的选择就变成了：自己写事件订阅和消息收发，还是找一个像 OpenClaw 这样的工具把脏活接过去。我实测下来，后者能省掉大量跟业务无关的重复劳动，但前提是你要搞清楚它每一层配置在干什么。

1. 为什么我最终选了 OpenClaw 而非"裸接"飞书 API

很多新手一开始的想法是：飞书开放平台把事件推给我，我拿到消息文本，调一下大模型接口，再把结果发回群聊，这不就完事了？理论上是这样，但真去实现的时候会发现，中间横着一大堆跟"AI"毫无关系的活。

1.1 裸接飞书 API 要自己扛多少事

首先是事件订阅。飞书会推送各种事件，你需要验签、解密、判断事件类型，还要处理推送重试。其次是凭证管理，App Access Token 有时效，过期要刷新，刷新要处理并发。消息层面也有坑：普通消息、群消息、@ 消息字段结构不完全一样，图片和文件还要额外调素材接口。等这些跑通了，你又得考虑消息去重，因为飞书在网络抖动或服务超时的时候会重投事件，不去重模型就会把同一句话吃两遍。

这还只是"接进来"的部分。"发出去"同样不省心：发送频率限制、错误重试、消息格式转义、超长文本截断。再往后是会话管理：多个人同时问问题，各自的上下文怎么隔离，历史记录存内存还是存数据库。说实话，这些东西我一个人也能写，但写出来以后要维护，要加功能，要排障，周期会拉得很长。

1.2 OpenClaw 替我接管的四件事

换成 OpenClaw 之后，我的体感是它把最烦的四类活接过去了。

一是飞书通道接入。App ID、App Secret 配进去，它自己去建立长连接、维护心跳、处理断线重连。二是事件解析与去重。收到的飞书事件被解析成统一结构，message_id 去重由它内部完成。三是会话上下文管理。它按 chat_id 维护会话维度，按发送人区分角色，我只需要关心系统提示词和上下文轮数。四是大模型调用与回发。模型服务的配置、超时、重试，以及最终把回复发回飞书的动作，都封装成了配置项。

可以说，OpenClaw 把"渠道适配"和"大脑接入"解耦了。我之后如果想把飞书换成别的聊天平台，或者换一家模型服务商，改动都集中在配置层，不用动业务逻辑。这一点在长期维护里非常重要。

1.3 先用一张表判断你适不适合这个方案

也不是所有场景都适合用 OpenClaw。我整理了一张简单的判断表，你可以对照自己的情况看。

我的结论是：如果你想搭的是"带自己大脑"的飞书助手，OpenClaw 这类消息中间层是性价比很高的选择；如果你只是想要一个能聊天的玩具，那确实没必要上这个方案。

2. 飞书开放平台侧的准备：二十分钟就能完成的配置

不管 OpenClaw 多好用，飞书侧的基础配置才是所有事情的前提。这部分我踩过一些弯路，所以会把操作路径写得具体一些。

2.1 创建企业自建应用与启用机器人

先登录飞书开放平台后台，选择创建"企业自建应用"。名字可以起得正式一点，比如"团队 AI 助手（测试）"，图标和描述随便填，后续都能改。创建完进入应用详情页，左侧菜单里找到"凭证与基础信息"，这里能看到两个非常重要的东西：App ID 和 App Secret。App ID 是应用的唯一标识，App Secret 相当于密码，这两个值之后要填进 OpenClaw 的配置里，务必保存好，不要贴到公开仓库。

接着在左侧找到"应用能力"，把"机器人"能力打开。这一步是让应用成为真正的"机器人账号"，不开启的话，后面在飞书里根本搜不到这个应用。开启后可以顺便设置机器人的名称和头像，群成员看到的机器人形象就是这里定义的。

2.2 权限勾选：我建议的权限清单与用途

飞书的权限管理是按 API 维度开的，少开一个权限，某个功能就静默失败，而且错误提示往往不明显。我最开始只开了发消息权限，结果机器人能发不能收，排查半天才发现是接收消息的权限没开。

我最终勾选的权限大致是这几类，不同版本的飞书后台在名称上可能略有差异，以实际开通页面为准：

权限管理页里可以直接搜索权限关键词，找到后逐一点击开通。注意有些权限点开后还需要企业管理员审核，自建应用通常可以自行审批，但如果你的账号不是管理员，就要走一遍审批流程。

2.3 事件订阅：本地调试首选长连接模式

这是很多新手最容易懵的地方。飞书的机器人要接收消息，必须在"事件订阅"里配置接收方式。官方提供两种方式：一种是 Webhook 请求地址，飞书把事件 POST 到你提供的公网 URL；另一种是长连接模式，通过 WebSocket 把事件推送到本地。

我的建议是：本地开发和内网调试，首选长连接。原因很直接——你不需要准备一个公网可访问的回调地址，不需要额外的网关转发，OpenClaw 启动后自己会建立连接，飞书主动把事件推过来。等上线部署到服务器后再考虑要不要切回 Webhook。

在事件订阅页面，添加事件时搜索"接收消息"，也就是 im.message.receive_v1，订阅它即可。另外页面里有一个"加密策略"，可以设置 Encrypt Key。我的经验是第一步先不开启加密，把整条链路跑通后再回来开，否则验签环节一错，你根本分不清是配置问题还是加密问题。

2.4 最容易漏的"发布版本"步骤

后台把应用能力、权限、事件都配好了，不代表飞书里立刻就能搜到这个机器人。还差一步：创建版本并发布。左侧菜单"版本管理与发布"里，创建新版本，设置可用范围。第一次建议只把自己和一两个测试账号加进去，避免机器人还没调好就被全公司看到。

提交版本后，如果你是应用管理员，一般可以直接通过；不是的话需要等管理员审批。发布完成后，再回到飞书客户端搜索应用名称，才能找到机器人。我在这个步骤上卡过很久，一度以为权限配置有问题，其实是忘了发布版本。

提示：每次修改后台的权限、事件订阅或机器人设置，都要重新创建一个新版本并发布，否则线上应用不会生效。这个规则很容易被忽略。

3. 写下第一个能回话的机器人：OpenClaw 配置逐项说明

飞书侧准备好之后，终于轮到 OpenClaw。这一节我会把安装和配置拆开来讲，尽量让每个配置项都落到"它在链路里干什么"的层面。

3.1 安装方式：容器与二进制怎么选

OpenClaw 的部署方式常见有两种：容器方式和二进制方式。我的建议是：服务器上长期跑，用容器；本地快速验证，用二进制。

容器方式的好处是环境隔离、升级方便。启动命令大概长这样，其中镜像地址以你拿到的官方仓库为准：

docker pull ${OPENCLAW_IMAGE} docker run -d \ --name openclaw-feishu \ -v $(pwd)/config.yaml:/app/config.yaml \ -e LLM_API_KEY=${LLM_API_KEY} \ ${OPENCLAW_IMAGE}

二进制方式更简单，下载对应平台的压缩包，解压后直接运行。它的优点是启动快、资源占用小，适合在笔记本上边改配置边重启测试。不管哪种方式，核心都是同一个东西：一份配置文件。

3.2 五段配置逐项拆解

OpenClaw 的配置文件是 YAML 格式。我第一次看到的时候觉得字段不少，其实拆开看就是五段。下面是我整理的一个最小可运行示例：

app: id: "cli_xxxxxxxx" secret: "xxxxxxxxxxxxxxxx" encrypt_key: "" # 飞书后台如果开启加密策略，这里必填 platform: type: feishu receive_mode: websocket # 长连接模式，不需要公网回调地址 llm: api_base: "https://your-llm-provider.example.com/v1" api_key: "${LLM_API_KEY}" model: "${YOUR_MODEL_NAME}" bot: system_prompt: "你是一个团队 AI 助手，回答保持简短、结构化、不客套。" history_rounds: 6 only_at_bot: true # 群聊里只响应 @ 机器人的消息 allowed_chat_ids: [] # 限制哪些会话可以使用，留空则全部允许

先看 app 段。app.id 填飞书后台上拿到的 App ID，app.secret 填 App Secret。encrypt_key 对应飞书后台"事件订阅"里的加密策略，如果你后来开启了 Encrypt Key，一定要把它填进来，否则事件体解不开。

platform 段里，type 固定为 feishu。receive_mode 填 websocket，这就是我们前面说的长连接模式。如果你的 OpenClaw 版本支持，也可以填 webhook，但需要额外配置公网回调地址和证书。

llm 段是大模型的接入配置。api_base 是模型服务的地址，api_key 是密钥，model 是你要使用的具体模型名。只要模型服务商提供兼容接口，这套配置就可以通用。环境变量方式管理 api_key 是个好习惯，比如${LLM_API_KEY}，避免密钥硬编码进配置文件。

bot 段是整个助手的"性格"和策略。system_prompt 决定机器人的人设和表达风格。history_rounds 是上下文轮数，我调到 6 左右比较平衡：太少，多轮对话会断片；太多，token 消耗大，模型响应也变慢。only_at_bot 和 allowed_chat_ids 是群聊控制的关键，后面进阶部分会详细说。

3.3 首次启动：日志告诉你链路是否真的通了

配置写好后，启动 OpenClaw。我这边日志出现类似的四行，基本就说明链路通了：

[INFO] feishu websocket connected [INFO] event received, type=im.message.receive_v1 [INFO] llm response ok, tokens=128 [INFO] message sent to chat_id=oc_xxx

这四行分别对应：长连接建立、收到飞书事件、模型返回结果、发送回复成功。你可以对照这个顺序排查问题。如果连第一行都没有，说明长连接没建立起来；如果卡在第三行，多半是模型配置有问题；如果卡在第四行，大概率是发送权限没配好。

3.4 第一次联调：搜到机器人并完成一次对话

配置跑起来后，打开飞书客户端，在搜索框里输入你给应用起的名字，应该能找到机器人。点进去发一句"你好"。正常情况下几秒内会收到回复。

如果没有回复，我建议按这个顺序排查：先看日志有没有出现"event received"，确认事件到底有没有进来；再看有没有"llm response ok"，确认模型有没有返回；最后看有没有"message sent"或者报错信息，确认消息有没有发出去。三步一查，问题基本就定位了。这一步跑通，剩下的就是打磨体验和踩坑排错。

4. 一条消息从飞书到 AI 再回到飞书的完整旅程

联调通了之后，你可以开始正常使用了。但如果你想后续稳定运行、顺利排障，还是得理解一条消息在内部到底经历了什么。这部分我把底层流程掰开讲。

4.1 事件进来之后：验签、解析、去重

用户在飞书里给机器人发消息，飞书开放平台会把事件推送到 OpenClaw，前提是你订阅了 im.message.receive_v1。长连接模式下，事件会通过 WebSocket 实时到达。

OpenClaw 收到事件后，先做验签和解密。如果你配置了 encrypt_key，它会用这个密钥解开事件体；没配置的话就直接读取明文。解析完成后，它会从事件里提取关键字段：消息内容、发送者、会话 ID、消息 ID。

这里有个容易被忽略的环节：去重。飞书在事件投递失败或服务端超时时，会按一定策略重投同一事件，也就是说同一个 message_id 可能被推送两次。OpenClaw 内部会记录最近处理过的消息 ID，重复事件直接丢弃。如果没有这一层，模型会把同一句话连续处理两遍，用户就会看到机器人重复回复。

4.2 会话与上下文是怎么组织的

OpenClaw 处理完事件后，会决定这次对话属于哪个会话。它是按 chat_id 区分的，也就是"这一个群/这一场私聊"算一个会话。会话内部再区分 sender_id，因为群聊里有好几个人，需要分清每句话是谁说的。

组织上下文的时候，它会拼接三部分内容：系统提示词、最近几轮对话历史、当前这条新消息。history_rounds 控制的就是中间那部分长度。比如设为 6，就保留最近 6 轮交互记录。超过 6 轮的老消息会被丢弃，这是为了控制 token 长度，避免模型"遗忘前面的重点"，也避免响应变慢。

我之前遇到过一个体验问题：聊了几十轮之后，机器人开始前后矛盾。排查下来就是 history_rounds 设得太小，早期约定好的信息全被丢掉了。后来我把关键约定写进 system_prompt，才彻底解决。这是一个值得记住的经验——重要信息要放进系统提示词，而不是依赖很长的对话历史。

4.3 模型调用与消息回发：先应答、再异步干活

上下文准备好之后，OpenClaw 会把消息列表发送给配置好的模型服务，拿到完整回复文本，再调用飞书消息 API，以机器人的身份把文本发回对应的 chat_id。

这里有一个架构层面的重点：收到事件后的"应答"和"业务处理"是分离的。飞书推送事件给长连接，OpenClaw 会立刻返回一个确认应答，告诉飞书"我收到了"，然后再在后台异步执行模型调用和消息发送。为什么要这么设计？因为飞书对事件处理有时间要求，如果 OpenClaw 在收到事件的回调里同步去调模型，一旦模型响应慢几秒，就会触发飞书侧的超时重投，导致事件重复进入。

异步化之后，即使模型调用花了一二十秒，飞书那边也不会反复重投。不过你也要注意，模型响应过慢时，用户在飞书里的等待体验仍然不好，这属于另一个层面的优化，我后面在坑五里会讲。理解了这个"先应答、再干活"的机制，你就明白为什么重复回复、超时这类问题，很多时候要从异步和幂等设计去解决，而不是一味加大模型超时时间。

5. 我实测过程中踩过的五个坑，以及完整排查过程

这五个坑是我从零对接时真实遇到的。每个我都会按"现象—排查链路—根因—解决"的方式写，希望能帮读者少走弯路。

5.1 坑一：飞书里搜不到机器人，私聊提示"应用不可用"

第一次配完飞书后台，我满心期待去搜应用，结果搜不到机器人，或者能搜到但点进去提示应用不可用。后来才明白是"版本发布"这一步没做。

排查链路很简单：回到开放平台后台，打开"版本管理与发布"，看看当前有没有已生效的版本。没有的话就创建一个版本，把可用范围设置成自己和测试组，点发布。如果你是应用管理员，状态很快变成已发布；不是的话需要等审批。

根因其实就是：后台改配置不等于线上生效，必须通过版本发布这个动作把配置发布到运行环境。这个坑十个人里至少有五个会踩，而且踩过之后会觉得特别蠢，因为答案就在眼前，只是没人告诉你。

5.2 坑二：事件收到了，机器人就是不回话

飞书侧能收到我发的消息，OpenClaw 日志里也出现了"event received"，但后面没有模型响应，也没有消息发出去。这说明问题出在模型调用环节。

排查的时候我先把日志级别调高，看到模型调用抛出的错误是认证失败。我第一反应是 API Key 写错了，检查配置文件发现没问题。然后我用命令直接测了一下模型接口：

curl ${API_BASE}/chat/completions \ -H "Authorization: Bearer ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{"model":"${MODEL_NAME}","messages":[{"role":"user","content":"hello"}]}'

结果同样报错。换到模型服务商的控制台自己调试，才发现是模型名写错了。我用的模型服务商对模型名的大小写和版本号有严格区分，填错一个字符就返回错误。这是很常见的坑：OpenClaw 配置没错，错在模型服务商侧的名称或密钥本身。

5.3 坑三：长连接反复断连，日志一片 reconnecting

跑了一段时间后，我发现 OpenClaw 的日志里经常出现连接断开、重新建立连接的记录。最频繁的时候几分钟一次，虽然最终会自动恢复，但断连期间消息会延迟，体验很差。

排查链路比较曲折。我先检查了 OpenClaw 配置，确认 receive_mode 没错；又检查飞书后台的事件订阅，确认长连接模式没有变化。最后翻日志发现一个规律：断连发生在长时间没有消息交互之后。这就指向了一个典型场景——本地网络环境里，空闲连接会被 NAT 或防火墙策略清理掉，飞书的长连接如果有一段时间没有心跳交互，就会被掐断。

解决方式分两步。第一步，在本地调试时，我换了一个更稳定的网络环境，断连频率明显下降。第二步，我后来把正式环境放到服务器上跑，问题基本消失。如果你在自己电脑上开发，遇到长连接断连且不需要本机调试的时候，建议优先考虑服务器部署，而不是反复折腾网络设置。

5.4 坑四：群里没人 @，机器人也抢答

接入群聊后，我发现一个问题：群里只要有新消息，机器人就会接话，哪怕大家只是在闲聊，根本没人 @ 它。这是因为 OpenClaw 默认情况下会响应群聊里的所有消息。

排查时我看了事件内容，飞书推送的 im.message.receive_v1 事件里会包含 mentions 字段，里面是这条消息 @ 的所有人。如果其中包含机器人自己的 ID，才算真正被 @ 了。OpenClaw 的 only_at_bot 配置就是用来做这个判断的。

我的解决方式是把 bot 段里的 only_at_bot 设为 true，并在 allowed_chat_ids 里维护允许响应的群名单。这样私聊消息全量响应，群聊只响应 @ 机器人的消息，其他群消息一律忽略。注意改完配置要重新启动 OpenClaw，配置文件不会热更新。

5.5 坑五：模型响应稍慢，飞书重复投递导致机器人重复回复

这个坑最隐蔽。现象是模型偶尔响应慢，用户只发了一条消息，机器人却回复了两遍。一开始我以为是 OpenClaw 的 bug，后来才定位到是"事件重投"和"发送侧没有幂等"共同作用的结果。

事件重投的机制前面讲过：飞书认为事件没被成功处理，就会重新推送。如果 OpenClaw 处理超时，同一个事件进来了两次，理论上内部去重应该能拦住，但如果第一次处理还没结束就收到重投，两条处理线程可能同时进入模型调用。另外，即使事件只处理了一次，如果发送消息时网络超时，发送 API 被重试，也可能造成重复发送。

我的处理方式是双管齐下。第一，在配置里给模型调用设置了更保守的超时时间，并把 history_rounds 调小，减少 prompt 长度，从源头降低响应延迟。第二，在 OpenClaw 的发送环节，我确认它支持基于消息幂等键去重，如果版本里没开这个能力，就要在模型调用前先记录处理中的 message_id，加一个简单的"正在处理则不重复处理"的判断。这个坑提醒我：IM 机器人项目，去重和幂等从来不是可有可无的装饰，而是线上稳定性的基本盘。

5.6 一张速查表收尾这五个坑

下面这张表是我自己留的排查速查表，直接贴出来。

6. 进阶玩法：把飞书 AI 助手从"能用"变成"好用"

跑通基础机器人之后，很多团队会想让它更"能干"一点。这一节是我目前在用的几个进阶配置方向，按投入产出比排序。

6.1 让机器人处理图片、文件和语音消息

飞书消息不只是文本，用户还可能发图片、文件、语音。事件里会对这些非文本消息打上类型标记，比如 image 消息会带 image_key，文件消息会带 file_key。要真正获取原始素材，需要调用飞书的素材下载接口，这就需要前面 2.2 里提到的 im:resource 权限。

OpenClaw 是否内置了素材下载、下载后是否交给模型处理，要看具体版本。如果支持，你就能让机器人"看图说话"，接视觉模型实现图片问答。如果不支持，我的建议是至少配一个友好的兜底回复，比如"我目前只能处理文字消息，图片功能正在接入中"，而不是让消息石沉大海。

6.2 群聊控制：只响应 @ 或只管指定群

群聊是飞书机器人最高频的使用场景，但也是最容易失控的地方。前面坑四里提到的 only_at_bot 只是第一层控制，更进一步的做法是维护白名单和黑名单。

我目前的配置是：私聊全部响应；群聊只响应配置在 allowed_chat_ids 里的群，且必须 @ 机器人。对于临时拉进新群试用的情况，可以临时把群 ID 加进白名单，用完就删。这个配置看起来简单，但能避免很多尴尬场面——机器人在一个完全不相关的群里突然插一句话，所有人都会莫名其妙。

6.3 把对话记忆接到 Redis 或数据库，别用内存硬扛

OpenClaw 默认的会话上下文是放内存里的，好处是快，坏处是重启即失忆。如果你的机器人只是偶尔聊几句，内存模式够用。但如果你希望它记住用户偏好、跨天保留重要信息，就要把会话存储接到 Redis 或数据库。

配置上通常只需把存储后端指过去，业务代码不用动。举个例子，周报助手场景里，用户周一告诉机器人"我负责数据平台"，周五写周报时它还记得这条信息，体验就会自然很多。对于日报、周报这类周期性任务，持久化会话几乎属于刚需。

6.4 给机器人挂一个外部知识库

只靠模型自带知识，飞书助手充其量是个"聪明但不懂你们团队"的通用助手。想让它回答项目规范、系统架构、历史决策这类内部问题，需要挂外部知识库。

通用的做法是 RAG：把团队文档切段、向量化、存进向量库，用户提问时先做相似检索，把命中片段注入到模型上下文里。OpenClaw 本身不负责知识库，但它负责组织模型输入。你可以把注入逻辑做成一个中间层：先让 OpenClaw 拿到用户问题，再去向量库检索，最后把"检索结果+对话历史+当前问题"一起交给模型。这样知识库和模型解耦，换存储、换检索逻辑都很方便。

6.5 定时推送、多环境隔离与多机器人并存

最后聊两个团队协作场景下的技巧。

定时推送方面，飞书机器人可以用消息 API 主动往群里发消息。借助调度组件，比如 cron，可以每天固定时间推送早报、巡检结果、任务提醒。OpenClaw 在这里扮演的角色是稳定的消息通道，你只需要调用它的发送接口或者直接调飞书 API。

多环境隔离方面，我维护了 dev 和 prod 两套飞书应用，用不同的 App ID 和 App Secret，配置文件通过环境变量区分。这样在开发环境里乱改提示词、反复重启，都不会打扰线上用户。多机器人并存的时候，记得把 system_prompt 和 allowed_chat_ids 区分开，比如一个用于技术答疑、一个用于行政通知，别让两个机器人共用一套会话状态。

如果你要从零开始搭一个飞书 AI 助手，我建议的顺序是：先在飞书后台把应用、权限、事件订阅整明白，再跑通 OpenClaw 的"收到消息—模型回复—消息发回"这四行日志，之后再考虑知识库、定时任务这些锦上添花的功能。越往后越依赖前面链路的稳定性。

最后再说一个反复提醒自己的点：所有密钥都放进环境变量或密钥管理服务，不要写进配置仓库。我早期图省事把 App Secret 直接写在配置文件里，后来换了两套配置就要到处改，才发现环境变量管理才是正经做法。飞书对接这件事，真正困难的地方从来不是某个配置项，而是整条链路里每一环你都清楚它在干什么。把这篇文章里的流程走通一遍，你大概率比那些只会跑现成 Demo 的人更懂自己的 AI 助手。