OpenClaw 与飞书机器人联调：本地私有 AI 数字同事部署全指南

最近我把个人 AI 助手的交互界面从网页对话框搬到了飞书里，后端跑的是 Mac 本地部署的 OpenClaw。现在每天早上九点，飞书群里会自动出现一份当天待办简报；下午在手机上随手发一条消息，它就能帮我查资料、整理会议纪要、执行定时脚本，整套闭环完全跑在我的笔记本上。这里面的两个关键词就是 OpenClaw 和飞书机器人，前者负责当“大脑和手脚”，后者负责当“耳朵和嘴巴”。

这套组合最吸引人的地方在于：数据留在本地、不需要额外云服务器、飞书又是很多人日常打开率最高的办公应用。如果你也想把 AI 变成一个真正能干活的“数字同事”，而不是只在网页里聊天，这篇东西应该能帮你少走不少弯路。我会把 Mac 本地部署 OpenClaw 的完整过程、飞书机器人应用的创建细节、两者对接的配置写法，以及我实际踩过的坑全部拆开讲，直接照着做就行。

1. 方案概述：为什么是 OpenClaw 加飞书

1.1 OpenClaw 到底是个什么东西

OpenClaw 可以理解成一个“个人智能体中控台”。它本身不是一个聊天软件，而是一个开源的 AI Agent 框架，把大模型、工具调用、记忆存储、消息渠道这几层东西拼装在一起。你给它接上模型 API，它能调用 Shell 命令、读写文件、定时执行任务；你给它接上聊天渠道，它就变成了一个能随叫随到的助手。

名字里的 Claw 有点“抓手”的意思——它专门负责把你的手伸到各种工具里，然后通过对话去操纵这些工具。最让我满意的一点是它的扩展性：官方默认支持一批内置能力，社区里也有很多现成的技能包可以装，不需要从零写逻辑。

类比一下：你招了一个能力很强但没有任何办公设备的实习生，OpenClaw 就是给他配的电脑、电话和排班表，大模型是他的脑子，飞书则是你们之间对讲机。这套结构非常灵活，脑子可以换（不同模型），对讲机也可以换（不同聊天平台），手脚可以随时加（新工具）。

1.2 飞书在里面扮演什么角色

飞书机器人这套组合里是典型的“消息入口”。它做三件事：把你的消息转发给 OpenClaw，把 OpenClaw 的回复推送给你，还能主动向群聊发送消息、发送卡片、处理简单按钮交互。

选择飞书而不选别的聊天工具，主要原因有三个。第一是触达效率高，飞书 App 在手机和电脑上推送都很及时，比盯着终端日志舒服太多。第二是支持群聊场景，你可以把多个 Agent 或者说多个技能挂在同一个群里，其他人也能用，适合小团队试用。第三是飞书开放平台提供了比较完善的长连接模式，这让本地部署变得异常简单，不需要公网服务器，也不用折腾反向代理。

打个比方，OpenClaw 如果是台高性能工作站，那飞书就是一个随时能打开的远程桌面客户端。你不需要坐在工作站前，也不用给它配公网 IP，它主动连接到飞书那边，消息就能来回传。

1.3 这套组合适合谁，不适合谁

适合的人群大概是这几类：喜欢折腾的个人开发者，想给团队做一个内部 AI 助手的工程师，日常工作记录和待办比较依赖飞书的效率控，以及在意数据隐私、希望原始数据留在自己电脑上的人。

不太适合的场景也有：如果你需要高并发、7x24 小时的稳定服务，本地部署并不合适，笔记本一合盖服务就断了，应该考虑云服务器加常驻进程；如果你完全不懂命令行和配置文件，那上手会有一些门槛，不过照着这篇走一遍也能搞定；再有就是如果团队要求极度标准的权限审计和合规流程，那还是用飞书官方提供的机器人应用市场方案更靠谱。

这套组合的定位就是“个人或小团队的半私有 AI 助理”，性价比很高，但别拿它当生产级 SaaS 用。

2. 开工前的准备：Mac 环境与依赖安装

2.1 建议的机器配置和账号要求

先说硬件。我用的是 Apple Silicon 芯片的 Mac，M 系列跑 Node.js 服务和一般的 Agent 任务非常轻松，Intel 芯片的老款也能跑，只是风扇声音会明显一些。内存方面 16G 是舒适区，8G 也能跑，但别指望在这台机器上同时跑本地大模型和 OpenClaw，会很吃力。磁盘剩余空间建议留出 10G 以上，因为 Node 依赖和日志文件都会占地方。

系统版本建议 macOS 14 以上，旧版本理论上也能装，但 OpenClaw 的依赖比较新，遇到兼容性问题的概率会上升。另外你还需要两个账号级的东西：一个飞书开放平台账号（最好你是这个企业的管理员，或者至少允许自建应用），一个 LLM 的 API Key——无论你用的是哪家模型服务，这个 Key 是必需的，因为 OpenClaw 本身不产生模型推理能力。

准备好这些之后，先做一个快速自检：终端能正常打开，brew --version有输出，node -v能看到版本号。如果这些命令报错，先走下面两节把基础环境补齐。

2.2 安装 Homebrew、Node.js 和 Git

在 Mac 上装开发依赖，Homebrew 基本是绕不开的。安装命令如下：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

这个过程会要求你输密码，并且可能需要安装 Xcode Command Line Tools，耐心等它跑完就好。装完以后接着装 Node.js、Git 和 Python3（部分技能脚本会用到）：

brew install node git python3

然后检查版本：

node -v npm -v git --version

Node 建议装 20 LTS 以上的版本，OpenClaw 对现代 JavaScript 语法有依赖，版本太老会直接跑不起来。如果你之前装过旧版 Node，用brew upgrade node升一下再继续。

这里有个很容易被忽略的细节：OpenClaw 的安装和运行都会用到 npm 全局缓存目录，如果你是用 Homebrew 装的 Node，权限一般没问题；但如果你是官网 pkg 包安装的，偶尔会遇到EACCES权限报错。真遇到了，不要习惯性加sudo，那会把 npm 全局目录权限搞乱，正确做法是把 npm 的全局前缀改到用户目录下，或者直接用npx方式运行项目。

2.3 检查端口占用和基础服务

OpenClaw 默认会监听 3000 端口，这是很多 Web 脚手架的传统默认值。在开始安装之前，最好先确认这个端口没有被别的服务占用：

lsof -i :3000

如果这条命令没有输出，表示端口空闲；如果有输出，说明你机器上某个进程已经占用了 3000 端口，比如常见的开发服务器、Docker 端口映射等。解决办法有两个：一是把占用进程关掉，二是等一下部署完成后把 OpenClaw 端口改到 3100 或别的空闲端口。

默认选 3000 的原因很实际：大量周边生态工具都预设了这个端口，比如后面要说到的隧道工具，默认就是映射本地 3000 端口，跟着默认走能少改很多配置。另外可以顺手测试一下本机网络连通性，curl http://localhost:3000/health这个地址后面会用来自检服务状态，现在即使提示连接失败也没关系，属于正常情况。

3. 本地部署 OpenClaw：五分钟跑起核心服务

3.1 拉取项目并完成初始化

环境准备好之后，部署 OpenClaw 本身其实非常快。以当前主流版本的安装方式为例，用 npx 直接初始化一个项目：

npx openclaw@latest init my-claw cd my-claw cp .env.example .env npm install

npx openclaw@latest init这行命令会生成一个可运行的样板工程，里面已经帮你搭好了 Agent 配置、渠道配置、目录结构和环境变量示例。npm install会把项目依赖全部拉下来，这一步耗时取决于网络状况，我实际测试中慢的时候等了三五分钟都很正常，不要以为卡住了。

初始化完成后你会看到这样一个目录结构：

my-claw ├── src # 核心逻辑和扩展代码 ├── config # Agent 配置、渠道配置 ├── skills # 技能包目录，放可复用的功能模块 ├── memory # 记忆库数据，对话历史沉淀在这里 ├── logs # 运行日志 └── .env # 环境变量，密钥都放这里

这个结构其实很清晰：config里定义 Agent 的身份和对话策略，skills里放各种能力插件，memory目录在运行后会自动生成，不需要手动改。你需要重点关注的就两个文件：.env和config目录下的配置文件。

3.2 配置大模型 API Key

没有大模型 Key，OpenClaw 就等于是个没有脑子的空壳。打开.env文件，你会看到类似这样的占位符：

OPENAI_API_KEY=sk-xxx OPENAI_BASE_URL=https://api.example.com/v1 OPENAI_MODEL=gpt-4o-mini

把这三个值替换成你自己的配置。OPENAI_BASE_URL 这里特别说明一下，它不一定非得是某个固定厂商的地址，OpenClaw 兼容 OpenAI 格式的 API，所以那些提供兼容接口的模型服务都可以填进来。

如果你更在意隐私，想完全离线运行，可以接本地的 Ollama 服务：

OPENAI_BASE_URL=http://localhost:11434/v1 OPENAI_MODEL=qwen2.5:7b

用本地模型的好处是数据完全不出本机、不用花 API 费用，代价是回复质量和推理速度都不如云端大模型。我的建议是：平时接云端模型用，需要处理敏感内容时切换到本地模型，OpenClaw 配置切换起来也不算麻烦。

3.3 启动服务并做健康检查

依赖装好、模型也配好之后，启动就比较简单了：

npm run start

如果一切正常，你会看到类似这样的日志：

[openclaw] core service started at http://localhost:3000 [openclaw] memory store ready [openclaw] agent "assistant" ready

这时候用另一个终端窗口做一次健康检查：

curl http://localhost:3000/health

返回{"status":"ok"}就说明核心服务已经在正常跑了。这里我建议你把日志级别调到 debug 模式，方便后面排查问题：

LOG_LEVEL=debug npm run start

debug 日志虽然看起来啰嗦，但里面会显示每个事件的收发情况，对接飞书时你就能直观看到“飞书消息进来了”“Agent 开始生成回复”这些关键节点。

到这里，OpenClaw 本体已经跑起来了，但它目前还只是一个“没有接入任何消息渠道的 AI 内核”。接下来要做的是去飞书开放平台创建并配置机器人应用，让飞书上的消息能找得到你本地的这个服务。

4. 飞书后台配置：创建机器人应用

4.1 创建企业自建应用

打开飞书开放平台，进入开发者后台，选择创建企业自建应用。注意这里一定选“企业自建应用”，不是“商店应用”也不是“网页应用”，因为我们要接的是企业内部的机器人能力。

应用名称可以随便起，我当时起的名字是“本地助手”，简短好认就行。创建完成后，第一件事是进入“应用能力”页面，给应用添加“机器人”能力。这一步很关键，没有添加机器人能力，后面所有消息功能都无从谈起。

这里有个大家容易忽略的点：应用默认只有创建者自己可见，其他人搜索不到。要让团队里其他成员也能使用这个机器人，必须走完后面的“发布版本”流程，等版本审核通过后，应用在租户内才真正生效。

4.2 获取 App ID 和 App Secret

进入“凭证与基础信息”页面，你会看到两个核心凭证：App ID 和 App Secret。App ID 是应用的唯一标识，通常以cli_开头；App Secret 相当于应用的密码，用于换取访问令牌。

App Secret 有一个特点：它只在创建时完整显示一次，之后后台只会显示隐藏态，所以拿到后第一时间复制到安全的地方。我个人的习惯是直接存到密码管理器里，并且.env文件里也留一份，因为接下来几步马上要用的。

可能有人会问：App Secret 泄露了有什么风险？简单说，有了 App ID 和 App Secret，别人就可以以这个应用的身份调用飞书开放平台的 API，比如读取机器人的权限范围内能访问的消息和资源。所以这个密钥一定要保护好，不要提交到 Git 仓库，不要贴到群里，.env文件默认也应该被.gitignore排除掉。

4.3 开通消息权限和事件订阅

接下来是配置里最容易踩坑的一步：权限和事件订阅。

在“权限管理”页面，需要手动开通以下权限：

只开通单聊不群聊，或者只开通读取不开通下载，都会导致后续功能“半残”。比如你让机器人帮忙“看这张图并描述一下”，如果没开im:resource，它会告诉你“收不到图片资源”，但根因其实是权限没配全。

然后进入“事件订阅”页面，这一步的选择会影响整个部署架构。你会看到两种接收方式：一种是长连接模式，另一种是回调模式。我强烈建议你选长连接模式，这也是本地部署最简单的方案。选好模式之后，订阅事件添加im.message.receive_v1，这个事件会在用户给机器人发消息时触发。

为什么长连接模式对本地部署这么友好？因为长连接是 OpenClaw 主动向飞书的 WebSocket 网关发起连接，消息会沿着这个连接主动推过来，完全不需要你有公网 IP，也不需要配置 HTTPS 回调地址。回调模式则要求飞书能访问到你本地的一个公网地址，否则消息根本进不来，这对本地开发来说非常难受。

4.4 发布版本，让机器人真正生效

配置都完成后，进入“版本发布”页面，创建应用版本，填写版本号、更新说明，然后提交发布。如果审批人是你自己，几秒就通过了；如果企业有管理员审核流程，可能要多等一会儿。

很多第一次接触飞书开放平台的人都会卡在这一步：明明应用创建好了、机器人能力也添加了，但拿手机一搜，根本搜不到这个机器人。原因基本就是版本还没发布。只有发布成功的应用，才算正式在租户内注册，机器人也才具备被添加和收消息的资格。

发布成功后，建议在飞书客户端搜索一下应用名，找到机器人并进入会话。此时你给它发消息，会得到“消息已送达但没有响应”的效果——因为还没把 OpenClaw 和飞书连起来，这很正常，下一步就是关键的对接环节。

5. 让 OpenClaw 与飞书“握手”：对接与验证

5.1 把飞书密钥写进 OpenClaw

回到 Mac 终端，在.env文件末尾追加飞书相关配置：

FEISHU_APP_ID=cli_xxxxx FEISHU_APP_SECRET=xxxxx FEISHU_EVENT_MODE=websocket

FEISHU_EVENT_MODE这个参数建议写死为websocket，代表走长连接模式。如果你的 OpenClaw 版本支持 JSON 配置，也可以把飞书配置写到config/agents.json中，效果类似：

{ "channels": { "feishu": { "appId": "cli_xxxxx", "appSecret": "xxxxx", "eventMode": "websocket", "botName": "本地助手" } } }

两种写法本质没什么区别，都是让 OpenClaw 在启动时去读取飞书应用的 App ID 和 App Secret，然后换取访问令牌。需要注意的一点是：修改配置后必须重启 OpenClaw 进程，配置才会重新加载，这是很多人改了没生效的第一原因。

5.2 如果一定要用回调模式：隧道工具怎么选

虽然长连接模式是目前最推荐的方式，但有些旧版本的 OpenClaw 或是你想从局域网内另一台设备访问，可能还是会用到回调模式。回调模式的核心问题是：飞书服务器需要能访问到你的 Mac 地址，而本地开发环境一般不在公网。

解决办法是拉一个临时公网地址，把本机 3000 端口映射出去：

brew install ngrok ngrok http 3000

运行后你会看到一个https://xxxx.ngrok.io形式的公网地址，把这个地址填到飞书事件订阅的回调地址里，并在回调地址后面拼上 OpenClaw 的 webhook 路径，形如https://xxxx.ngrok.io/webhook/feishu。然后飞书后台会发送一个验证请求，OpenClaw 正确响应后事件订阅状态会变成“连接正常”。

这里我多说一句：隧道工具适合本地开发调试，不要长时间把本地服务暴露在公网上，调试完就及时关掉，避免敏感数据暴露。另外如果你的 OpenClaw 只支持回调模式，那推荐尽早升级到支持长连接的版本，长连接的维护成本比回调低一个数量级。

5.3 启动服务并做端到端测试

配置完成并确认事件订阅状态正常后，重启本地服务：

npm run start

这次启动后，日志中会出现新的关键信息：

[openclaw] feishu channel connected [openclaw] websocket established

看到这两行，就说明 OpenClaw 已经成功接到飞书的长连接了。现在去飞书里给机器人发一条“你好”，注意观察终端日志。日志应该依次出现类似下面的内容：

[event] im.message.receive_v1 from user_xxxxx [agent] receiving message: 你好 [agent] generating response... [agent] response generated [openclaw] feishu message sent

如果机器人回了你“你好”或者一句正常的应答，整条链路就彻底通了。

实际测试中，从发消息到收到回复会有 1 秒到 3 秒的延迟，这很正常，因为中间要经历消息传输、Agent 编排、大模型推理、结果返回等多个环节。如果延迟超过 10 秒，问题大概率出在大模型 API 的响应速度上，而不是 OpenClaw 或飞书本身。

5.4 理解消息流转链路，培养排查直觉

对接成功之后，建议你把整条消息数据流刻在脑子里，之后排查问题会快很多。完整链路是这样的：

飞书用户发送消息，消息先到飞书服务器；飞书服务器通过长连接推送到本地 OpenClaw；OpenClaw 解析事件，判断消息来源、内容、会话 ID；Agent 编排层接管消息，结合记忆和上下文生成提示词；大模型 API 处理提示词并返回回复；OpenClaw 调用飞书消息 API，把回复发回给用户。

这条链路里的每一段都可能出问题，但每一段也都有对应的日志输出。看到日志停在哪一步，问题基本就定位在哪一段：停在event环节说明飞书接入有问题，停在generating response说明模型侧有问题，停在message sent说明飞书消息 API 返回异常。把这个排查思路养成习惯，后续遇到任何机器人的怪问题都不会太慌。

6. 常见问题排查与避坑记录

6.1 机器人不回复，按这套顺序排查

这个问题最让人头大，但它的原因往往不复杂。我建议严格按照“飞书后台 - 本地日志 - 模型状态 - 权限配置”的顺序排查。

第一步，去飞书开放平台的事件订阅页面看连接状态，如果显示“连接异常”，问题在长连接，检查 App ID 和 App Secret 是否配对正确，以及本地服务是否真的启动了。第二步，看本地日志有没有收到im.message.receive_v1事件，如果日志里压根没有事件进来，说明消息根本没推过来，问题在事件订阅配置或权限发布阶段。第三步，确认模型 API Key 是否过期、额度是否用完，这在日志里通常表现为模型请求超时或返回 401 错误。第四步，检查机器人是否添加了足够的权限，比如只开了读取消息权限但没开发送消息权限，就会出“收到消息但回不出去”的诡异情况。

一个很容易反复踩的细节是：你改了飞书后台的权限或事件配置后，必须重新创建版本并发布，改动才会对线上生效。经常有人开了新权限，马上去飞书测试，权限还是旧的，容易误判。

6.2 消息重复推送和响应超时

有次我配置完对接后，每条消息机器人都会回复两遍。一开始以为是 OpenClaw 的 bug，后来检查发现我把长连接模式的事件订阅和回调模式的事件订阅同时开启并都指向了同一个机器人。这就等于同一个消息被两个通道各推了一次，OpenClaw 自然回复了两遍。解决方案很简单：事件订阅里长连接和回调只能二选一，不要同时启用。

响应超时问题也很常见。飞书回调模式对 HTTP 响应时间有限制，如果你的 Agent 链路比较长，比如接了好几个工具、多轮内部调用，很容易触发超时。但切换到长连接模式后，这个问题基本就消失了，因为长连接模式下飞书不关心你多久回消息，消息通过 WebSocket 推给你，回复也走 API 异步返回。

如果你坚持用回调模式，可以把 OpenClaw 的处理方式改成“先立即返回 HTTP 200，处理完再调用飞书 API 主动推送”，这也是很多机器人平台的推荐实践。

6.3 权限申请被拒和找不到机器人

如果你在飞书里搜索不到刚创建的机器人，绝大多数情况是版本未发布。去开放平台的版本管理页面看一眼，确认应用状态是“已发布”。如果你是个人开发者，把“可用范围”设置为全员或至少包含你自己的账号，平时测试会方便很多。

权限申请被拒的情况也有，通常发生在企业管理员审核的流程里。如果你的机器人要读取群消息或组织通讯录信息，这些敏感权限审核会严格一些。我的建议是，初期只申请最必要的那几个消息权限，够用就行；后续真需要更高级功能，单独发起一次权限申请并写清楚用途，通过率会高很多。

6.4 常见问题速查表

7. 进阶玩法：从“聊天机器人”到“数字助手”

7.1 定时任务：把日报和提醒主动推送到群里

OpenClaw 真正让我觉得值回票价的功能是定时任务。你可以在配置里声明一个 cron 表达式，让它在每天固定时间往飞书群里推送消息。比如我每天早上九点让它生成当日待办简报并发送到工作群：

{ "schedules": [ { "cron": "0 9 * * *", "channel": "feishu", "target": "oc_xxxxxxx", "prompt": "请基于我的待办清单生成今日简报，按优先级排列，直接发送到当前群聊" } ] }

这里的target填的是飞书群的 chat_id，可以在飞书开放平台的调试工具里查到，也可以让机器人加入群后打开日志，从消息事件里抓到群 ID。定时任务配上飞书的消息推送，相当于你多了一个每天早上准时上班的 AI 助理。

7.2 记忆与偏好：让机器人记住你的习惯

OpenClaw 自带的记忆存储是它和普通聊天机器人的重要区别。它在memory目录里维护着长期记忆，你可以直接对它说“以后回复我尽量控制在 200 字以内”“我的项目代号是 X”之类的偏好，之后它会自动把信息写进记忆库，并在后续回答时主动遵守。

我观察下来，记忆功能的实用程度远超预期。比如我在记忆里存了“周报格式：本周重点工作、数据表现、下周计划”，它写出来的周报初稿基本可以直接用；还试过让它记住团队几名同事的分工，之后在群里让它“把这份文档转给负责视觉的同事”，它也能给出合理建议。当然记忆也不是无限存储，它有整理和遗忘策略，不需要你手动清理。

7.3 多角色与多技能编排

如果你觉得一个机器人不够用，OpenClaw 支持配置多个 Agent，每个 Agent 可以有独立的身份、职责和技能组合。例如在同一个飞书群里，你可以有“信息收集助手”“周报助手”“运维值班助手”三个角色，通过触发词或群聊 @ 来区分。

我实际搭过三个助手的配置，体验是把一个通用机器人变成了一个专业化的小团队。信息收集助手负责扒网页和整理链接，周报助手负责汇总本周日志，运维值班助手负责检查本地服务状态和磁盘空间，每个助手都限定在自己的职责范围内，回答质量明显比全能型机器人稳。配置方式是在config/agents.json里增加多个 agent 定义，渠道层会根据消息特征分发到不同的 agent 上。

7.4 把飞书当控制台，让 AI 替你操作工具

最后说一个很酷但需要谨慎使用的方向：通过飞书对话直接操作本地工具。OpenClaw 默认支持调用 Shell 命令，这意味着你可以让机器人帮你执行命令、查系统负载、跑脚本、甚至做简单的部署操作。

这里的安全底线一定要守住。我给机器人配置了命令白名单，只允许执行几类明确安全的命令，比如ls、df -h、ps aux、cat日志文件，不允许执行rm、curl外部下载、sudo等高风险操作。不要把整个 Shell 全部开放给 AI，否则一旦提示词注入或者误操作，后果不可控。这个思路的正当用途是：当你想快速看一下系统状态或者跑一个固定脚本时，不用打开终端一条条敲，直接在飞书里给机器人发一句指令就行。实测下来，这种“聊天框就是控制台”的体验非常上瘾，前提是克制好权限边界。

最后分享几个实操小技巧

整套搭下来，我个人体会最深的一点是：长连接模式是这个方案里最省心的选择，只要密钥配置正确，几乎不用折腾网络层面的东西。而整个流程里最容易踩坑的反而是飞书开放平台那一侧的配置，特别是权限和版本发布，搞不明白就反复报“机器人不回复”的假故障。

最后分享两个小技巧。第一，在给机器人写系统提示词时，明确要求“回复要简短，突出关键信息”，否则大模型经常长篇大论，在飞书里体验很差，尤其是群聊场景。第二，建议先单独建一个只有你自己的测试群，把机器人拉进去调试，等一切稳定后再拉老板和其他同事进来——一方面避免打扰别人，另一方面即使机器人抽风说错话，也只影响你自己，不至于在群里丢人。这套 OpenClaw 加飞书的组合，初看是个小玩具，但真正用起来之后，你会发现自己对“AI 自动完成杂事”的上限有了新的认知。