企业官网建设流程全解析

直接把 OpenClaw 接进飞书这件事，我前前后后折腾了两轮才算是真正跑通。先说结论：OpenClaw 这个开源智能体框架本身并不复杂，飞书开放平台的能力也足够完善，真正让你想摔键盘的地方几乎全集中在权限配置、事件订阅、消息格式这些细节上。所以这篇手册我打算换个讲法，不按官方文档那种"照着填就行"的节奏来，而是按我实际踩坑的顺序，把每一步为什么这么做、这么配置，以及出了问题怎么定位，一次说清楚。

如果你手头正好有 OpenClaw 环境，想让它变成一个你飞书群里随叫随到的智能助手，或者你只是想把"AI 接入 IM"这件事摸一遍，这篇可以直接当成一份操作笔记来参考。内容里涉及代码和配置的部分都是基于我实际用过的方案整理的，不同版本细节可能会有差异，但排查思路和配置逻辑是通用的。

1. 接入前先搞清楚：OpenClaw 和飞书分别扮演什么角色

在动手配任何东西之前，我建议你先想明白一件事：你要做的不是"把 OpenClaw 装进飞书"，而是要在两个完全独立的系统之间搭一座桥。

OpenClaw 这边，它本质上是一个智能体运行时。你可以把它理解成一个只在本机或服务器上运行、没有固定界面的"AI 大脑"。它接收你给的任务指令，然后通过内部规划、调用工具、执行脚本，最终返回一个结果。它天生不依赖某个具体的聊天软件，所以它不会主动去连飞书，而是需要你提供接入途径。

飞书这边，它的角色是"交互前端"。它负责把用户的话收集起来，通过开放平台的事件订阅机制告诉你的后端服务，同时也负责把后端返回的内容以机器人消息的形式发到群里。换句话说，你要做的核心工作就是：让 OpenClaw 能处理飞书推过来的消息，并能通过飞书 API 把处理结果发回去。

这个定位想清楚之后，你就知道接下来的工作会分成三大块：飞书开放平台侧的应用配置、OpenClaw 侧的工具启用来接收消息、还有消息格式与命令交互的设计。每一块都有各自的坑，但飞书侧的坑更多也更隐蔽。

提示：如果你的目的是"让群成员都能调用 AI"，那务必在动手前确认你们团队的使用边界。机器人本质上是代替个人在群里发言，消息的发送人、可见范围这些都需要在飞书后台做合理的权限收口，不建议直接给所有成员开放最高权限。

2. 整体架构形态：事件订阅为主，主动推送为辅

从我实测的经验来看，OpenClaw 接飞书最稳定的方案是：飞书开放平台使用事件订阅（长连接模式）把群消息实时推给 OpenClaw，OpenClaw 处理完后通过飞书 API 主动把回复发到指定群或会话。这套架构下，飞书侧不需要暴露任何公网回调地址，省掉了内网穿透、反向代理这些额外组件，部署成本低很多，稳定性也有保障。

这个方案该怎么选，其实就一个核心取舍：你是让飞书来找你，还是定时去飞书那问。事件订阅属于前者，飞书一有消息就推过来，实时性好，消息不乱序，适合聊天场景。轮询方式属于后者，你得每隔几秒调一次"获取消息"的接口，不仅实时性差、容易漏消息，还会因为重复拉取消耗 API 配额。所以除非你是做定时巡检这种低频任务，否则不用考虑轮询。

还有一个很多人会纠结的点：用长连接还是用 Webhook 回调。我的建议很简单，新项目一律优先长连接模式。Webhook 需要你提供公网可访问的 HTTPS 地址，还涉及签名验证、重试机制，每次调试都要把内网服务暴露出去，安全性和便利性都差一些。长连接是飞书 SDK 在本地维持一个 WebSocket 通道，消息直接推到你本地，断开后 SDK 还会自动重连，对于本地开发和个人项目来说这是最省心的模式，不需要任何网关层。

架构定了之后，整个链路的调用流程是这样的：

1. 用户在飞书群里 @ 机器人并输入指令
2. 飞书服务器通过长连接把事件推给 OpenClaw 的飞书适配层
3. OpenClaw 内部识别触发条件，把指令交给智能体处理
4. 智能体执行任务（可能调工具、查数据、跑脚本）
5. 处理完成后 OpenClaw 获取结果，再调用飞书 API 把消息发回群聊

你可以把这段链路理解成一次完整的"前台 - 接线员 - 后台专员 - 回访"流程。飞书是前台，OpenClaw 适配层是接线员，智能体的规划与工具调用是后台专员，最后一次 API 调用就是回访。每一环都有可能出现自己的问题，所以后面排查的时候我也会按照这个链路逐段排查。

3. 飞书侧完整配置流程与权限细节

3.1 创建应用、开启机器人能力

先登录飞书开放平台，进入开发者后台，创建企业自建应用。这一步有个小提醒：如果你用的是个人飞书账号，可能需要先创建一个企业或者加入一个已有企业，因为机器人能力目前只对企业内部应用开放。我自己当时就是卡在这里，用个人账号找半天都没找到"创建应用"入口。

创建应用之后，找到"添加应用能力"，选择机器人。这里会生成一个机器人，默认情况下它是没有任何权限的，必须继续配权限。开启机器人能力的同时，页面里会展示机器人的名称和头像，我建议把名字起得跟功能相关，比如"项目助理""运营助手"，这样群成员一眼就知道这个机器人是干什么的。

3.2 权限配置是第一个大坑

应用创建好之后，进入"权限管理"页面，这一步是坑最多的环节。你要找的权限不是一两个，而是一组。我在实际配置中至少需要以下几类：

• im:message（读取单聊和群聊消息）——用于接收用户发来的消息
• im:message:send_as_bot（以机器人身份发送消息）——用于回复用户
• im:chat（获取群信息、群成员列表）——用于定位消息来自哪个群、谁发的
• im:resource（读取图片、文件等资源）——如果你希望机器人能处理图片或文件消息
• contact:user.base:readonly（读取用户基本信息）——可选，用于获取发送者姓名，提升交互体验

这里要特别强调：配置完权限并不等于立刻生效。飞书的权限体系里，权限变更后必须创建应用版本并发布，等待管理员审核通过后才会生效。这个"发布版本"的步骤特别容易被忽略，我一开始就是卡在这，机器人一直报没有权限，结果发现应用根本没发布，权限列表全是空转。

还有一件事容易忽略：你打开"机器人"能力后，默认只有应用管理员能使用机器人，普通成员在群里是看不到这个机器人的。所以你还得在"可用范围"里配置哪些人可以使用，或者直接设为全员可用。如果你是自己开发自己用，可以先把可用范围设为仅你自己，调试通过后再扩大范围。

3.3 事件订阅配置：长连接模式与事件选择

进入"事件订阅"页面，订阅方式选"使用长连接接收事件"。SDK 会负责维护连接，你本地不需要额外装什么服务。但是有一个关键步骤：需要添加事件。

目前我们最需要的事件是im.message.receive_v1（消息接收），这个是机器人接收飞书消息的核心事件。选完事件后，有的版本还会要求你设置事件回调的加密策略。如果开了加密，OpenClaw 侧在解析消息时就要对应解密，所以如果你不想第一条消息就卡在解密上，可以先把加密关掉，等整体流程跑通之后再考虑开。

订阅完事件后页面上会显示"请求地址"或"连接状态"。长连接模式下，只要你的本地服务启动并且 SDK 连接成功，这里就会显示已连接。如果你在这里看到的是"未配置"或"未连接"，那说明服务没起来，或者 app id / secret 配错了。

注意：飞书后台的事件订阅页有个"事件状态"字段，首次配置后它会显示"待订阅"。这时候你不需要在页面上做任何额外确认，真正激活是靠本地服务启动后 SDK 自动注册。如果本地没跑起来，这里会一直挂起，很多教程会忽略这个细节，导致你反复刷新页面以为没配置上。

3.4 拿到三个关键凭证

在飞书开放平台的"凭证与基础信息"页面，你能拿到三个对 OpenClaw 来说至关重要的值：

• App ID：应用的唯一标识，形如cli_xxxx
• App Secret：应用的密钥，用于获取访问令牌，形如一串长字符串
• Verification Token（旧版叫法）或 Encrypt Key：用于签名验证或加密，如果是长连接模式且不开启加密，这一项可能用不到，但建议还是保存下来

这三个凭证在 OpenClaw 的配置中会分别填入对应环境变量。注意不要把 App Secret 提交到任何公开的代码仓库或者贴到群里，一旦泄露任何人都能冒充你的机器人发消息。我有个习惯，本地调试时把环境变量写入一个单独的.env文件，并确保这个文件被.gitignore忽略。

4. OpenClaw 侧接入：环境安装、配置解读与消息收发实现

4.1 安装与初始化

OpenClaw 的安装方式可以参考官方 README。我以典型的安装路径为例，整体流程如下：

# 安装依赖（以下命令因操作系统差异略有不同） curl -fsSL https://openclaw.example.com/install.sh | bash # 初始化配置目录 openclaw init # 查看配置目录结构 find ~/.openclaw -type f

初始化之后，典型的配置目录大致是这样的：

~/.openclaw/ ├── openclaw.json # 全局主配置 ├── agents/ # 智能体定义目录 │ └── default.yaml # 默认智能体配置 ├── tools/ # 工具启用目录 │ └── feishu.yaml # 飞书工具配置（接入后生成） └── .env # 环境变量文件

如果你初始化之后没有发现tools/目录，也没关系，通常要等你启动后由框架自动创建。核心要修改的其实就两个文件：.env和对应智能体/tool 的配置文件。

4.2 环境变量配置

接下来这一步就是接入的关键。打开.env，填入飞书开放平台的信息。不同版本的环境变量名会有差异，但是逻辑都一样。以我使用的版本为例：

FEISHU_APP_ID=cli_xxxxxxxx FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx FEISHU_ENCRYPT_KEY= # 如果未开启事件加密，留空 FEISHU_EVENT_MODE=websocket

FEISHU_EVENT_MODE=websocket这一项有的人容易忽略。OpenClaw 的飞书工具通常支持两种模式，一种是 webhook 模式（要求公网回调地址），一种是 websocket 长连接模式。我这套方案选 websocket，不需要公网 IP，本地监听即可。

配置完环境变量之后，需要确保它真的被加载。你可以先这样验证：

# 在配置目录下执行 source .env echo $FEISHU_APP_ID

如果输出为空，说明你的 shell 没有正常读取.env，或者 OpenClaw 并未自动加载，需要看下主配置里是否指定了环境变量文件的读取路径。

实操建议：不同的 OpenClaw 版本对配置文件的读取逻辑改动较大，有的版本默认环境变量前缀是OPENCLAW_FEISHU_而不是FEISHU_。如果你填完之后发现日志里依然报"环境变量缺失"，先检查日志里打印的变量名到底是什么，再去对齐命名。这种"按文档填了却识别不到"的情况，十有八九是前缀没对上。

4.3 配置智能体与工具启用

光配置飞书环境变量还不够，你需要在智能体配置中启用飞书工具，并且告诉智能体"飞书消息进来后要怎么处理"。我用的是default.yaml，核心配置大致如下：

name: default model: provider: openai_compatible model_name: qwen-plus tools: - feishu trigger: on_message: true on_command: true

其中tools列表里的feishu表示启用飞书工具。trigger部分的on_message: true表示收到任意消息就触发智能体处理，on_command: true表示类似/xxx的指令也会触发。如果你希望只有 @ 机器人时才响应，需要查一下当前版本的消息过滤参数。

配置好之后启动服务：

openclaw start

正常情况下，启动日志中会出现类似feishu websocket connected的字样。看到这个输出说明飞书长连接建立成功，也就是"飞书 → OpenClaw"这个方向的路已经通了。

4.4 消息收发验证：先跑通"收到消息"

接下来验证接收链路。到飞书群里 @ 机器人然后发一条消息，比如：

@项目助理 你好

然后马上切到终端看 OpenClaw 的日志。你应该能看到类似这样的记录：

[feishu] receive event, type=message, chat_id=oc_xxxx, sender=ou_xxxx, text=你好

如果日志里没出现这条，优先排查三件事：

1. 应用版本是否发布、管理员是否审核通过
2. 事件订阅是否正确添加了im.message.receive_v1
3. 机器人是否真的被你拉进了这个群

如果日志出现了但是后面跟着报错，常见错误包含权限不足、解析失败等，咱们留到第 6 节统一说。

4.5 实现回复：OpenClaw 如何把结果发回飞书

"接收"只是半边天，"回复"是另外半边。OpenClaw 的飞书工具内部封装了发送消息的 API，实际发送走的是im/v1/messages这个接口。简单说，这个接口需要三个关键参数：

• receive_id_type：标识你传入的 ID 是群 ID（chat_id）还是用户 ID（open_id）
• receive_id：接收方标识
• msg_type和content：消息格式和内容，比如text类型时 content 是一段文本

在 OpenClaw 里，你不需要手写这个 HTTP 调用，框架已经封装好了。但你需要知道回复的两种输出方向：

第一种是"原路回复"。用户在哪条会话里发的消息，机器人的回复就发到哪个会话，对应的接收 ID 就是事件消息里自带的chat_id或者open_id。这种模式最顺滑，适合日常问答。

第二种是"指定目标推送"。你可以主动让 OpenClaw 把消息推到某个固定的群或用户。这个在自动化任务里很有用，比如定时汇总每天的数据，然后推到某固定群。这种模式需要在配置里指定固定的接收 ID，且消息不需要经过用户触发。

我在实际使用中把这两种场景都做了验证，日常对话走原路回复，定时任务走固定群推送。这样配置一次之后基本不用动。

5. 消息交互设计：指令格式与提示词封装

5.1 群聊场景下的指令设计

接入跑通后，你要面对的下一个问题就是：群里的消息五花八门，你的 OpenClaw 不可能什么话都接。如果它把每个人的闲聊都当作任务去处理，结果就是频繁误触发、回复牛头不对马嘴，最后群成员会把机器人当作骚扰源。

我的建议是：不要默认让机器人响应所有消息，而是设计一套触发规则。比较省心的做法是给机器人加上关键词前缀或者是 @ 触发。比如：

• 群成员必须 @ 机器人才能触发响应
• 或者以特定前缀开头，比如AI、/ask、帮我才触发
• 特定频道/群里的所有消息才响应，其他群一概不响应

这些规则在 OpenClaw 的配置里都能设置。我建议至少做到"必须 @ 才触发"，这是最保守也最不容易误伤的做法。

经验之谈：如果你希望机器人在多个人共用的群里运行，最好在提示词里声明身份边界："你是本群的项目助理，只回答与项目协作相关的问题，其他闲聊礼貌拒绝。"这不只是提升体验，也是防止群成员对 AI 能力产生不合理期待。

5.2 提示词封装：让智能体更懂飞书场景

OpenClaw 本身支持自定义提示词（prompt），你可以把飞书的使用场景封装进去。我的做法是在智能体配置里加一段系统提示词，大致内容如下：

你是部署在飞书群聊里的智能助理。你通过飞书消息与用户交互。 用户的每条消息都带有发送者身份、所在群聊等上下文信息。 你需要注意： 1. 回答保持简洁，适合在聊天窗口阅读，不超过 300 字。 2. 涉及项目数据时，优先调用项目查询工具。 3. 你的回复会直接通过飞书发送给用户，不要使用 Markdown 表格。 4. 如果用户的问题超出你的能力范围，直接回复"这个我处理不了"。

这里要特别提一点：飞书消息对 Markdown 表格支持不佳，尤其是移动端，表格展示得很难看。所以我在提示词里明确限制"不要使用 Markdown 表格"，改而使用列表或纯文本。很多第一次接飞书的人容易忽略这个，AI 生成了一大段漂亮的表格，结果飞书里看全是乱码。

5.3 从"被动响应"到"主动推送"

只做被动响应，其实只发挥了 OpenClaw 的三成能力。OpenClaw 最有价值的地方在于：它可以定时执行任务然后主动推送结果到群。比如每天早上 9 点汇总今日待办、每周一生成上周运营数据周报，或者每两小时巡检一次线上服务状态并把异常直接推到群里。

定时任务在 OpenClaw 里的实现方式通常由框架内置的调度器或外部 cron 触发。我目前使用的是外部 cron 的方式，因为更灵活，也方便跟服务器上的运维体系对齐。示例：

# 每天早上 9 点执行一次日报推送 0 9 * * * cd ~/.openclaw && openclaw run agent=default task="生成今日项目进度日报，并发送到飞书群"

注意这里的task是一个自然语言指令，OpenClaw 执行完后会把结果通过飞书工具推送出去。但这里有个前提：你要确保固定推送的群 ID 已经在配置里指定好，否则 OpenClaw 不知道该往哪发。

6. 避坑实录：我在接入过程中遇到的高频问题

这一节是全文最重要的部分。我把接入和运行阶段遇到过的、以及社区里看到过的高频问题整理成一张速查表，并且附上我的排查思路。

6.1 高频坑一："应用未发布"导致所有权限形同虚设

这个坑我判断 90% 的新手都会遇到。你把权限全都勾上了，事件订阅也配了，代码也写了，结果发消息完全没反应。查了很久发现，飞书的应用存在"测试版"和"正式版"的概念。你在开发阶段创建出来的应用，默认是测试状态，只有你或者被添加为开发者/测试成员的人才能使用。要让其他群成员也能用，你必须在"版本管理与发布"里创建一个新版本，提交发布申请，等管理员通过。

所以如果你是自己一个人开发调试，可以直接把你自己的账号设为可用范围，我自己就在这个阶段卡了半小时。调试阶段，可用范围只设自己即可，不用急着全员开放。

6.2 高频坑二：长连接模式下事件订阅"已连接"但实际收不到消息

"已连接"不代表"已订阅"。有几次我启动服务后明明日志显示长连接建立成功，飞书事件订阅页面也显示"已连接"，但群里发消息就是收不到。后来排查发现是订阅的事件列表里没有添加im.message.receive_v1，或者添加了但未保存成功。

这里给个建议：配置事件时，在页面保存后一定要等几秒，然后切换到其他菜单再切回来，确认事件真的在列表里。我遇到过页面显示添加成功，但因为网络问题实际没保存的情况。

6.3 高频坑三：模型返回内容被飞书截断

OpenClaw 处理完任务后生成的内容可能很长，但飞书消息本身有长度限制（文本类型通常是 150KB 左右，实际单条消息建议远小于这个值）。同时，如果模型输出包含了 Markdown 代码块、复杂嵌套引用，飞书的纯文本消息编辑器会原样展示，观感极差。

我实际用下来，最稳定的方式是：在提示词里就做了输出约束——回复不超过 300 字，使用纯文本或简单的列表符号，不要出现代码块和表格。你也可以在 OpenClaw 的工具配置里加一层输出后处理逻辑，把长文本拆成多条消息发送，但这个属于进阶玩法，新手可以先不做，先把单条回复做短做干净。

7. 进阶玩法：从聊天助手升级为自动化协作节点

接入跑通、基础交互稳定之后，你其实已经拥有一个可编程的"数字员工"了。这时候值得考虑的就不再是"怎么聊天"，而是"怎么干活"。

我这里抛几个可以立即落地的方向：

第一，消息驱动的任务流。在群聊里发一条"帮我把这个需求同步给研发"，OpenClaw 通过识别意图，调用项目管理工具的 API 创建任务，然后把任务链接和摘要推回到群里。这等于把一个完整的业务动作压缩成一句话。

第二，自动化数据推送。每天定时从数据库/API 拉取当天的核心数据指标，生成简短文本，推送到管理群。相比大屏看板，这种方式更轻、更不容易被忽略。

第三，多机器人分工。同一个 OpenClaw 实例可以连接多个飞书应用，你可以在配置里按群维度挂载不同智能体。比如一个群挂"项目助理"，另一个群挂"数据分析师"，它们的系统提示词不一样，工具集也可以不一样。这样一套代码，支撑多个业务角色。

我目前实际在跑的组合是 OpenClaw 加飞书多维表格。OpenClaw 处理完数据后，通过飞书 API 把结果写入多维表格，再发通知消息到群里。最终效果是：群成员在群里发一句话，一条新的记录就出现在多维表格里，同时群内收到确认通知。这个链路非常适合做信息收集、审批汇总、周报沉淀等场景。

8. 最后的几点真心话

折腾 OpenClaw 接飞书这件事，最让我头疼的其实不是技术，而是文档版本和实际版本对不上。OpenClaw 迭代快，飞书开放平台本身也在一直改版，网上很多教程写着写着就过时了。如果你照着别人的文章配不通，不要怀疑是自己能力问题，大概率是版本差异。

我给你的建议是：优先看当前版本的官方文档，优先看飞书开放平台后台的实际界面，一切以你眼前看到的为准。配置类的东西没有"通用答案"，但只要链路逻辑是通的，换几个变量名、调几个参数位置，最终都能跑通。

还有一点就是，把 AI 接进办公 IM 这件事，能力越强责任越大。机器人能自动发消息、能写数据，意味着一旦权限配置不当，它可能泄露敏感信息或者误操作生产数据。所以接入后第一件事不是测功能，而是测权限边界：它能读到什么、谁能触发它、它能不能操作数据。这部分的谨慎，值得花时间。