1. 为什么非要把 OpenClaw 接进飞书
先交代一下背景。OpenClaw 这个项目，本质上是一个可以独立运行的 AI Agent 框架，它不依赖某个特定的大模型厂商，而是可以自己对接模型接口、管理记忆、操作工具，然后跑在各种终端环境里。你可以把它理解成一个"自带躯壳"的智能体：模型是大脑，OpenClaw 是身体，而飞书，就是它对外说话和干活的办公室。
大多数人在刚接触 OpenClaw 时，默认玩法都是在本机终端里和它对话，或者通过网页控制台去操作。这当然没问题，但实际用起来你会发现一个很现实的痛点：命令行窗口一关，Agent 就失联了；想让它定时干活、主动推送结果，更是无从下手。而飞书恰恰是最适合承接这类需求的工作场景入口——它的机器人机制成熟、消息类型丰富（文本、卡片、表格、文件都能发）、权限体系清晰，并且无论是电脑端还是手机端都能随时收到 Agent 的消息。把 OpenClaw 接进飞书之后，你等于给 Agent 装了一个"移动办公室"，人在哪，Agent 就在哪。
这篇教程就是给完全没过过 OpenClaw、甚至对 Agent 部署也没有概念的技术小白准备的。我会从零开始，讲清楚整个接入链路里的每一个环节：环境准备、机器人创建、配置修改、常见报错排查，以及几个让我当初卡了很久的坑。所有步骤都是我在 Windows 和 Linux 两套环境里实际跑过的，照着做基本能一次成功。
2. 先把地基打好：部署 OpenClaw 之前必须搞懂的几件事
2.1 OpenClaw 的运行环境到底需要什么
先别急着敲命令。很多新手最容易犯的错误，就是拿到项目就 clone、拿到命令就执行，结果跑到一半发现环境不对，报错信息又看不懂，最后只能放弃。OpenClaw 的部署要求其实非常明确，我帮你直接列清楚：
- 操作系统：Windows 10/11、Ubuntu 20.04+、macOS 都可以。Windows 上推荐用 WSL2 或者 Git Bash 环境，纯 PowerShell 有时候会遇到路径和权限问题。
- 语言运行时：Node.js 18 以上和 Python 3.10 以上。OpenClaw 的架构里，Node 负责跑核心服务，Python 负责跑一些工具链脚本，两个都要装。
- 包管理器：npm 或 pnpm，建议用 pnpm，它在安装依赖时对冲突的容忍度更高，后面你会省不少事。
- 网络环境：需要能正常访问模型 API 和 GitHub。如果你在国内服务器上部署，建议直接配阿里云、腾讯云的国内镜像源，后续拉依赖会快很多。
如果你是在自己的电脑上玩，Windows 用户我强烈建议先装一个 WSL2，然后在 Ubuntu 虚拟环境里部署。原因很简单：OpenClaw 的很多依赖在 Linux 原生环境下表现更稳定，而且目录权限模型不会像 Windows 那样动不动给你来个 EACCES。
2.2 大模型 API 和 Channel 的关系
OpenClaw 本身不生产模型能力，它需要你配置一个可以调用的大模型 API。这里的逻辑很像你买了个新手机，OpenClaw 是手机，飞书是手机壳，而大模型的 API Key 是 SIM 卡——没插卡，手机壳再好看也打不了电话。
OpenClaw 官方支持很多模型提供方，常见的包括 OpenAI 兼容接口、Anthropic 的 Claude，以及国内厂商提供的兼容接口。这里有一个很多小白会绕晕的概念：Channel。它指的是 OpenClaw 的外部通信渠道，也就是 Agent 通过什么方式和外部世界连接。飞书、Telegram、Discord、Microsoft Teams、Slack 都各自是一个 Channel。你在配置里指定某个 Channel 后，Agent 就会自动初始化对应的机器人适配器，然后监听来自该平台的消息。
所以整个接入链路可以用一句话概括：OpenClaw 是核心引擎，大模型 API 给引擎提供智力，飞书 Channel 给引擎装上对外沟通的嘴和耳朵。这三者缺一不可。
2.3 一个最容易忽略的概念：会话与状态隔离
在开始配置之前，你还需要理解 OpenClaw 的一个核心设计——每个 Channel 下的每个会话（Session）都是独立的。什么意思呢？就是你在飞书群里和 Agent 聊天，它记住的上下文只在那个群里生效；换个群，它什么都不记得。这种设计的好处是，多个团队可以共用同一个 Agent，互不干扰；坏处是，如果你在配置过程中改了模型参数，已经存在的会话不会自动刷新配置，必须重启服务或者新建会话才生效，这个细节后面排查问题时会反复用到。
3. 部署实战：从零开始把 OpenClaw 跑起来
3.1 Windows 和 Linux 下的安装命令对比
安装流程我分两个平台讲。两者逻辑一致，但命令差异需要注意。
先看Ubuntu / Debian 系的安装。打开终端，依次执行：
# 更新系统包索引 sudo apt update && sudo apt upgrade -y # 安装基础依赖 sudo apt install -y git curl build-essential # 安装 Node.js 18+（这里用 Nodesource 源） curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt install -y nodejs # 安装 pnpm sudo npm install -g pnpm # 克隆 OpenClaw 仓库 git clone https://github.com/your-openclaw-repo/openclaw.git cd openclaw # 安装依赖 pnpm install # 初始化配置 pnpm setupWindows 上的流程类似，但建议在 WSL2 里操作。如果你不想用 WSL，直接用 PowerShell 也可以，但要注意以管理员身份运行，并且把 Node 和 Python 都加入系统 PATH。安装完成后，验证一下：
node -v python3 --version pnpm -v这三个命令都能正常输出版本号，说明环境 OK。
3.2 首次启动前的必备配置项
OpenClaw 安装完成后，会在项目根目录生成一个配置文件，通常是openclaw.config.json或.env格式，具体看你下载的版本。首次启动前，你至少要配好以下三个核心项：
第一，模型接入配置。以 OpenAI 兼容接口为例，配置文件里需要这样填：
{ "model": { "provider": "openai-compatible", "baseURL": "https://your-api-endpoint.com/v1", "apiKey": "sk-your-key-here", "model": "gpt-4o-mini" } }如果你用的是 Anthropic Claude，把 provider 改成anthropic即可。有几点需要注意：baseURL 不要漏掉/v1后缀；apiKey 不要硬编码在会被提交到 Git 的配置文件里，推荐用环境变量引用。
第二，Agent 的参数。这里包括 Agent 的名称、系统提示词，以及最大回复 token 数。系统提示词建议一开始就写清楚，后面改起来会影响已存在会话的行为。我自己的经验是，在系统提示词里把"你是谁、你擅长什么、你在什么场景下应该做什么"都写明白，Agent 在飞书里的表现会稳定很多。
第三，启用日志。新手阶段强烈建议把日志级别调到debug。后面接入飞书时，如果机器人没有响应，debug 日志能直接告诉你消息有没有到达 OpenClaw、是配置错误还是网络问题。
完成这三项后，先不要启动飞书 Channel，直接在终端跑一下pnpm start，确认 OpenClaw 本体能正常启动。看到类似 "Agent is ready" 的日志输出，说明地基打好了。
4. 飞书机器人创建全流程：一个真正能用的 Bot 是怎么来的
4.1 在飞书开放平台创建企业自建应用
很多人在这里卡住，是因为不知道飞书机器人必须通过"企业自建应用"的方式来创建。个人用户直接去飞书里搜"机器人"，是找不到创建入口的。
正确路径是这样的：打开飞书开放平台（open.feishu.cn），用你的飞书账号登录，进入开发者后台。然后：
- 点击"创建企业自建应用"，填写应用名称和应用描述。名称建议直接叫"OpenClaw Agent"，方便以后认。
- 创建完成后，进入"应用能力"页面，找到"机器人"能力，点击启用。
- 启用之后，你会在"凭证与基础信息"页面看到 App ID 和 App Secret 两个关键字段。App Secret 只在创建时完整显示一次，务必先复制保存好。
这里多说一句，飞书的权限体系很严格，你的应用要能收发消息，必须给机器人配置相应的权限。在"权限管理"页面，至少开通以下两项权限：
im:message（读取与发送单聊、群组消息）im:message.group_at_msg（在群组中接收 @ 机器人的消息）
如果你后续想用飞书多维表格或文档功能，还需要额外开通docs相关的权限。不过这一步可以先跳过，先把消息链路跑通。
4.2 订阅方式选择：长连接 vs Webhook
飞书开放平台支持两种事件订阅方式，这直接决定了你后面要写的配置：
长连接模式（推荐新手使用）。这种方式下，飞书服务器会把事件推送到你的应用客户端，你的程序主动和飞书保持一个 WebSocket 长连接。优点是不需要公网 IP，不需要配置回调地址，本地开发、内网部署都能用。我强烈建议新手先选这个。
Webhook 模式。飞书把事件 POST 到你提供的公网回调地址上。这种方式适合已经部署在云服务器上、有域名或公网 IP 的场景，配置更灵活，但要求你能处理签名校验和公网安全。
在开放平台的"事件与回调"页面，选择长连接模式，并添加事件订阅，把"接收消息"（im.message.receive_v1）这个事件添加上。然后，你就需要在 OpenClaw 的配置里，把飞书应用的凭据填进去了。
4.3 在 OpenClaw 的飞书 Channel 填什么
这一节是整个教程的实操核心。在 OpenClaw 项目目录下找到配置文件，把飞书相关的配置段填完整，参考如下：
{ "channels": { "feishu": { "enabled": true, "appId": "cli_xxxxxxxxxxxxxx", "appSecret": "your-app-secret", "mode": "websocket", "encryptKey": "", "verificationToken": "" } } }这里逐项解释：
appId：就是你刚才在飞书开发者后台复制的 App ID，形如cli_xxxxx。appSecret：App Secret，注意别和加密密钥混淆了。mode：选websocket就是长连接模式，选webhook则要配合公网回调地址。encryptKey和verificationToken：飞书开放平台里"事件订阅"页面会显示这两个值。如果你开启了"加密"功能就填 encryptKey，没开就留空。verificationToken 一般在 Webhook 模式下用来校验请求真实性，长连接模式可填可不填，但建议还是填上，防止后续切换模式时漏配置。
填完之后，重启 OpenClaw：
pnpm restart如果配置正确，日志里会出现类似 "Feishu channel connected" 的信息，同时你在飞书里搜索你创建的应用名称，会发现一个机器人出现在了你的企业通讯录里。
5. 飞书消息收发测试：打通之后马上要做的三件事
5.1 单聊测试：为什么机器人"已上线"却不理你
配置完成、机器人上线后，第一步是单聊测试。在飞书里找到你的机器人，直接发一句"你好"。正常情况下，Agent 应该很快回复。
但这里有一个新手必踩的坑：你发消息时，机器人可能完全没反应，日志显示一切正常，但飞书侧就是没有任何输出。我排查了很久才意识到，这是飞书的权限隔离机制在起作用——你创建的应用默认只对创建者自己可见。也就是说，只有你本人在飞书里能搜到这个机器人，其他人搜不到，也发不了消息。
解决办法：在飞书开发者后台的"版本管理与发布"页面，创建一个应用版本，提交发布申请，审核通过（企业自建应用通常是管理员秒批）后，机器人才能对全公司可见。如果你只是自己测试，也可以直接在"成员管理"里把你的测试账号加为应用可用成员。
5.2 群聊测试：必须 @ 机器人才会被唤起
单聊跑通后，再建一个群，把机器人拉进群。这里有个重要的交互规则：飞书群聊中，OpenClaw 只在被 @ 时才会响应。也就是说，你在群里直接说"帮我查一下明天的天气"，机器人是不会理你的，必须输入@OpenClaw 帮我查一下明天的天气才行。
这块如果你检查日志发现消息根本没进到 OpenClaw，十有八九是机器人没有配置"接收群消息中 @ 机器人"的权限。回到开放平台，在权限管理里确认im:message.group_at_msg已开通，并且应用版本已经发布生效。
5.3 验证消息格式：让 Agent 输出 Markdown 卡片
飞书机器人支持富文本消息，OpenClaw 也会根据 Agent 的回复内容自动选择消息格式。平文本没问题，但如果你想要更规整的展示效果（比如让 Agent 输出一个列表或者一篇文章），可以在系统提示词里要求它"回复时使用 Markdown 格式，用标题和列表组织内容"。
我这里分享一个实测的小技巧：如果 Agent 输出的 Markdown 在飞书里显示成了纯文本，别急着改代码，先看它回复里是否带了代码块标记。飞书对 Markdown 的支持有限，尤其是代码块和表格，很容易被截断或者排版错乱。建议在提示词里明确要求 Agent"不要使用代码块输出表格，改用列表或纯文本"。后面我会细讲输出截断这个坑。
6. 输出被截断、会话锁冲突：接入飞书后的高频翻车现场
6.1 "session file locked (timeout 60000ms)" 到底是谁的锅
这是个搜索频率极高的报错，完整提示长这样：
agent failed before reply: session file locked (timeout 60000ms)我第一次看到这个报错时完全懵了。日志里唯一有用的信息是"session file locked"，直到我把 OpenClaw 的源码翻了一遍才发现问题根源：OpenClaw 在处理一个会话的请求时，会给该会话加文件锁，防止并发写导致上下文混乱。如果上一个请求没有正常释放锁，下一个请求就会一直等待，直到超时。
这个报错最常见的触发场景有两个：
- 上一个请求因为网络原因（比如模型 API 超时）异常中断，锁没有释放。
- 同一个会话的多个请求几乎同时到达，比如飞书群里同时有几个人 @ 机器人，或者你本地测试工具和飞书同时发了消息。
解决办法其实不复杂。第一，找到 OpenClaw 的会话数据目录，一般在项目根目录下的data/sessions里，把对应会话的.lock文件删掉，然后重启服务。第二，从根源上避免并发——给同一个会话的自然语言交互节奏设计好，别同时多个请求打过去。
但要注意，这个报错还有一个隐藏版本：如果你的飞书 Channel 配置正确，但是 Agent 正在处理一条很长的回复，这时候你又发了一条新消息，新消息可能不会排队，而是直接报错。这是因为飞书长连接模式下，OpenClaw 默认的单会话并发处理策略是"互斥"。想从根上解决，可以在配置里把会话模式改为异步队列（如果版本支持），或者对不同群用不同会话 ID 隔离。
6.2 飞书输出容易被截断：长文本的三种处理思路
这个问题在关键词里出现过很多次：OpenClaw 在飞书里输出长内容时，往往只显示前面一部分，后面突然断了。其实这不是 OpenClaw 的问题，而是飞书单条消息的长度限制所致。飞书机器人单条文本消息是有长度上限的（大约 150KB 的富文本，但纯文本消息限制会更严格），而且超长文本在客户端渲染时也会卡顿。
三种解决思路，按推荐程度排序：
思路一：在提示词里约束输出长度。给 Agent 设定一个输出上限，比如"每次回复控制在 800 字以内，如果内容较多，分多条回复"。这个最简单，也最直接，但对复杂任务不够优雅。
思路二：用飞书的富文本卡片（Interactive Card）。配置 OpenClaw 的飞书 Channel 时，把默认消息类型设为卡片。卡片的承载能力比普通文本强很多，长文可以被折叠，点击展开查看。不过这个配置不是所有 OpenClaw 版本都原生支持，需要确认你的版本更新到了支持卡片模板的构建。
思路三：让 Agent 生成结构化文件再上传。这是我最推荐的做法。当内容超过一定量级时，OpenClaw 可以调用工具生成 Markdown、CSV 或 Excel 文件，然后通过飞书机器人发送到对话里。飞书对文件类型和大小放得比较宽，长文放在文件里，既不会截断，也方便用户保存和二次编辑。实现上，只要在工具配置里开启文件发送能力就行，后面我会专门讲一次。
6.3 时钟与网络问题：一个容易被忽略的隐藏杀手
还有一个不太起眼的坑，就是飞书 API 对请求时间戳校验很严，如果你部署 OpenClaw 的服务器时钟偏差过大，飞书会直接拒绝事件推送，表现为：机器人时好时坏、日志里出现timestamp expired之类的错误。
尤其是云服务器，很多人用的免费试用实例，系统时间可能没同步。解决办法很简单，装个 NTP 同步工具：
sudo apt install ntpdate sudo ntpdate ntp.aliyun.com然后确认系统时间正常后，再重启 OpenClaw。这个坑比较冷门，但我实际遇到过一次，排查了整整半天。
7. 进阶玩法：把 OpenClaw 在飞书里的能力真正用起来
7.1 同时接入多个 Channel：一套 Agent，多渠道触达
OpenClaw 的 Channel 配置是支持多开并存的。你可以在配置文件里同时启用飞书、Microsoft Teams、Telegram 等多个渠道，Agent 共用同一个大脑和记忆，但每个渠道拥有独立的会话空间。
实际使用中，这个特性特别适合跨团队协作场景：产品群用飞书，研发群用 Teams，同一个 Agent 都可以接入，但各群可以独立唤醒、互不干扰。配置方法就是在channels字段下并列添加多个配置块。注意，开启多个 Channel 时，不同 Channel 之间的会话 ID 命名空间是隔离的，不用手动处理冲突。
7.2 让 OpenClaw 对接 Claude Code 和 Codex 生态
在 OpenClaw 的生态里，有一个很常见的诉求是想让 Agent 能调用 Claude Code 或 Codex 这类编程助手的命令行工具。在飞书群里发一条指令，Agent 自动帮你分析代码、生成补丁，然后把结果以消息或文件的形式发回飞书。
具体配置上，你需要做两件事：
- 在 OpenClaw 的工具配置里，开启"Shell 工具"或"自定义工具"能力，允许 Agent 调用本机的命令行程序。
- 把 Claude Code 或 Codex 的可执行文件路径加入 OpenClaw 的工具白名单。
然后，在飞书里对 Agent 说"帮我用 Codex 审查一下 /project/src/main.py 的代码质量"，Agent 就会调用工具，把输出整理后发给你。这里有个安全提醒：给 Agent 开放 Shell 工具等同于给它本机执行权限，务必在配置里限定可执行的命令白名单，不要全部开放，否则一旦被恶意指令利用，后果很严重。
7.3 飞书多维表格和文档：Agent 与办公数据的联动
OpenClaw 接入飞书后，不只是收发消息那么简单。通过飞书开放平台的文档 API，你可以让 Agent 读取多维表格、写入数据、生成文档。这个能力一旦打通，就能做出很多实用的自动化场景。
举个例子，你可以让 Agent 每天定时读取多维表格里的销售数据，生成汇总报告发到群里；也可以在群里要求它"把今天的待办事项写入多维表格"，它就会调用表格 API 新增一条记录。
配置上，除了在权限管理里开通文档读写权限，还需要在 OpenClaw 的工具配置里添加飞书文档工具。我在实际使用中发现，多维表格的 API 字段类型校验比较严格，写入前必须确认字段类型匹配（比如日期字段要传时间戳格式的字符串，而不是"2025-01-01"这种人类可读格式）。这个细节很容易踩坑，建议第一次接入时用一条测试记录反复验证字段映射。
8. 从开源社区到办公场景：OpenClaw 和同类 Agent 框架怎么选
8.1 OpenClaw vs WorkBuddy：没有绝对好坏，只有合不合适
最近大量用户在搜索"OpenClaw和WorkBuddy哪个好"，说明大家确实在选型上犯了难。我个人的使用体会是：
OpenClaw 的优势在于开源、可定制、Channel 抽象做得非常清晰，你可以完全控制 Agent 的行为，想接什么渠道就接什么渠道。缺点是上手门槛偏高，对新手不太友好，文档偏工程化。
WorkBuddy 则更偏向开箱即用的办公助理体验，配置门槛低，针对飞书、钉钉等国内办公软件的场景优化更多。但封闭性更强，个性化定制受限。
我的建议很直接：如果你愿意花几个小时折腾配置，想要的是一个能长期自主掌控的 Agent 底座，选 OpenClaw；如果你就是要快速在团队里上线一个能开会、能整理日报的现成助理，WorkBuddy 可能更省心。这个选择没有标准答案，取决于你愿意投入多少维护成本。
8.2 Windows 用户特别关注：OpenClaw Windows 版和 Shub 安装
很多人问到 "openclaw windowshub 安装"，这里我解释一下。OpenClaw 的 Windows 部署，除了前面讲的 WSL2 方案，还有一种方式是安装它的桌面管理工具（社区里常说的 Windowshub 或控制面板），把 Agent 的启停、日志查看、配置编辑都集成到一个图形化界面里。我个人的评价是：控制面板适合日常巡检和修改配置，不适合初次安装。第一次搭建还是老老实实走命令行，把每个环节看清楚，等跑通了再用面板去管理。
Ubuntu 上的安装路径我在前面已经写了，跟 Windows 的核心步骤一样，区别只在于系统依赖命令不同。如果你手头是阿里云、腾讯云的免费试用服务器，可以在控制台直接选 Ubuntu 22.04 镜像，然后按我前面的步骤操作，配置低一点的 2C4G 实例跑 OpenClaw 完全够用。
最后再补充一个我刚部署完就碰到的坑，也算帮大家打个预防针：版本更新导致的配置格式变化。OpenClaw 迭代速度飞快，网上很多教程写的是旧版格式，你照着配的时候如果发现某个字段不存在、或者配置校验报错，不要急着怀疑自己，先去 GitHub Releases 页面看看版本的变更记录。我写这篇教程时用的配置格式，和你下载到的最新版之间，可能已经有半年多的差异了，字段名、目录结构都会变。遇到这种情况，最靠谱的做法是看官方仓库最新的配置示例文件，对照着改。
这也是我玩 OpenClaw 到现在最大的体会：它的内核设计确实不错，但要真正驾驭它，你得接受它"文档更新永远赶不上代码"的现实。好在社区还算活跃，大部分问题都能在 issue 区和讨论区里找到答案。飞书接入只是第一步，跑通之后你会发现，真正有意思的是怎么设计 Agent 的工作流，让它变成一个能自动干活、能主动汇报的线上同事。
