最近我把个人 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 芯片的 MacM 系列跑 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 --versionNode 建议装 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 openclawlatest init my-claw cd my-claw cp .env.example .env npm installnpx openclawlatest init这行命令会生成一个可运行的样板工程里面已经帮你搭好了 Agent 配置、渠道配置、目录结构和环境变量示例。npm install会把项目依赖全部拉下来这一步耗时取决于网络状况我实际测试中慢的时候等了三五分钟都很正常不要以为卡住了。初始化完成后你会看到这样一个目录结构my-claw ├── src # 核心逻辑和扩展代码 ├── config # Agent 配置、渠道配置 ├── skills # 技能包目录放可复用的功能模块 ├── memory # 记忆库数据对话历史沉淀在这里 ├── logs # 运行日志 └── .env # 环境变量密钥都放这里这个结构其实很清晰config里定义 Agent 的身份和对话策略skills里放各种能力插件memory目录在运行后会自动生成不需要手动改。你需要重点关注的就两个文件.env和config目录下的配置文件。3.2 配置大模型 API Key没有大模型 KeyOpenClaw 就等于是个没有脑子的空壳。打开.env文件你会看到类似这样的占位符OPENAI_API_KEYsk-xxx OPENAI_BASE_URLhttps://api.example.com/v1 OPENAI_MODELgpt-4o-mini把这三个值替换成你自己的配置。OPENAI_BASE_URL 这里特别说明一下它不一定非得是某个固定厂商的地址OpenClaw 兼容 OpenAI 格式的 API所以那些提供兼容接口的模型服务都可以填进来。如果你更在意隐私想完全离线运行可以接本地的 Ollama 服务OPENAI_BASE_URLhttp://localhost:11434/v1 OPENAI_MODELqwen2.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_LEVELdebug npm run startdebug 日志虽然看起来啰嗦但里面会显示每个事件的收发情况对接飞书时你就能直观看到“飞书消息进来了”“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:message读取消息内容im:message.p2p接收单聊消息im:chat读取群聊信息im:resource下载图片和文件资源只开通单聊不群聊或者只开通读取不开通下载都会导致后续功能“半残”。比如你让机器人帮忙“看这张图并描述一下”如果没开im:resource它会告诉你“收不到图片资源”但根因其实是权限没配全。然后进入“事件订阅”页面这一步的选择会影响整个部署架构。你会看到两种接收方式一种是长连接模式另一种是回调模式。我强烈建议你选长连接模式这也是本地部署最简单的方案。选好模式之后订阅事件添加im.message.receive_v1这个事件会在用户给机器人发消息时触发。为什么长连接模式对本地部署这么友好因为长连接是 OpenClaw 主动向飞书的 WebSocket 网关发起连接消息会沿着这个连接主动推过来完全不需要你有公网 IP也不需要配置 HTTPS 回调地址。回调模式则要求飞书能访问到你本地的一个公网地址否则消息根本进不来这对本地开发来说非常难受。4.4 发布版本让机器人真正生效配置都完成后进入“版本发布”页面创建应用版本填写版本号、更新说明然后提交发布。如果审批人是你自己几秒就通过了如果企业有管理员审核流程可能要多等一会儿。很多第一次接触飞书开放平台的人都会卡在这一步明明应用创建好了、机器人能力也添加了但拿手机一搜根本搜不到这个机器人。原因基本就是版本还没发布。只有发布成功的应用才算正式在租户内注册机器人也才具备被添加和收消息的资格。发布成功后建议在飞书客户端搜索一下应用名找到机器人并进入会话。此时你给它发消息会得到“消息已送达但没有响应”的效果——因为还没把 OpenClaw 和飞书连起来这很正常下一步就是关键的对接环节。5. 让 OpenClaw 与飞书“握手”对接与验证5.1 把飞书密钥写进 OpenClaw回到 Mac 终端在.env文件末尾追加飞书相关配置FEISHU_APP_IDcli_xxxxx FEISHU_APP_SECRETxxxxx FEISHU_EVENT_MODEwebsocketFEISHU_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 理解消息流转链路培养排查直觉对接成功之后建议你把整条消息数据流刻在脑子里之后排查问题会快很多。完整链路是这样的飞书用户发送消息消息先到飞书服务器飞书服务器通过长连接推送到本地 OpenClawOpenClaw 解析事件判断消息来源、内容、会话 IDAgent 编排层接管消息结合记忆和上下文生成提示词大模型 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 常见问题速查表现象可能原因解决方式日志没有收到任何事件长连接未建立检查 App ID、App Secret确认websocket established日志飞书后台显示连接异常本地服务未启动或网络波动重启 OpenClaw确认 3000 端口正常监听消息收到但机器人无回复模型 API Key 失效或额度不足检查模型配置用 curl 手动测试 API 连通每条消息回复两遍长连接和回调同时开启事件订阅模式二选一收到消息回复很慢模型推理慢或工具调用过多换更快模型、精简 Agent 指令链图片和文件无法读取缺少im:resource权限补开权限并重新发布版本端口占用启动失败3000 被其他服务占用修改 OpenClaw 端口或用 lsof 清理占用进程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 自动完成杂事”的上限有了新的认知。 
长河君 · 2026/10/16 6:46:09 · 阅读 1.2k 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 芯片的 MacM 系列跑 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 --versionNode 建议装 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 openclawlatest init my-claw cd my-claw cp .env.example .env npm installnpx openclawlatest init这行命令会生成一个可运行的样板工程里面已经帮你搭好了 Agent 配置、渠道配置、目录结构和环境变量示例。npm install会把项目依赖全部拉下来这一步耗时取决于网络状况我实际测试中慢的时候等了三五分钟都很正常不要以为卡住了。初始化完成后你会看到这样一个目录结构my-claw ├── src # 核心逻辑和扩展代码 ├── config # Agent 配置、渠道配置 ├── skills # 技能包目录放可复用的功能模块 ├── memory # 记忆库数据对话历史沉淀在这里 ├── logs # 运行日志 └── .env # 环境变量密钥都放这里这个结构其实很清晰config里定义 Agent 的身份和对话策略skills里放各种能力插件memory目录在运行后会自动生成不需要手动改。你需要重点关注的就两个文件.env和config目录下的配置文件。3.2 配置大模型 API Key没有大模型 KeyOpenClaw 就等于是个没有脑子的空壳。打开.env文件你会看到类似这样的占位符OPENAI_API_KEYsk-xxx OPENAI_BASE_URLhttps://api.example.com/v1 OPENAI_MODELgpt-4o-mini把这三个值替换成你自己的配置。OPENAI_BASE_URL 这里特别说明一下它不一定非得是某个固定厂商的地址OpenClaw 兼容 OpenAI 格式的 API所以那些提供兼容接口的模型服务都可以填进来。如果你更在意隐私想完全离线运行可以接本地的 Ollama 服务OPENAI_BASE_URLhttp://localhost:11434/v1 OPENAI_MODELqwen2.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_LEVELdebug npm run startdebug 日志虽然看起来啰嗦但里面会显示每个事件的收发情况对接飞书时你就能直观看到“飞书消息进来了”“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:message读取消息内容im:message.p2p接收单聊消息im:chat读取群聊信息im:resource下载图片和文件资源只开通单聊不群聊或者只开通读取不开通下载都会导致后续功能“半残”。比如你让机器人帮忙“看这张图并描述一下”如果没开im:resource它会告诉你“收不到图片资源”但根因其实是权限没配全。然后进入“事件订阅”页面这一步的选择会影响整个部署架构。你会看到两种接收方式一种是长连接模式另一种是回调模式。我强烈建议你选长连接模式这也是本地部署最简单的方案。选好模式之后订阅事件添加im.message.receive_v1这个事件会在用户给机器人发消息时触发。为什么长连接模式对本地部署这么友好因为长连接是 OpenClaw 主动向飞书的 WebSocket 网关发起连接消息会沿着这个连接主动推过来完全不需要你有公网 IP也不需要配置 HTTPS 回调地址。回调模式则要求飞书能访问到你本地的一个公网地址否则消息根本进不来这对本地开发来说非常难受。4.4 发布版本让机器人真正生效配置都完成后进入“版本发布”页面创建应用版本填写版本号、更新说明然后提交发布。如果审批人是你自己几秒就通过了如果企业有管理员审核流程可能要多等一会儿。很多第一次接触飞书开放平台的人都会卡在这一步明明应用创建好了、机器人能力也添加了但拿手机一搜根本搜不到这个机器人。原因基本就是版本还没发布。只有发布成功的应用才算正式在租户内注册机器人也才具备被添加和收消息的资格。发布成功后建议在飞书客户端搜索一下应用名找到机器人并进入会话。此时你给它发消息会得到“消息已送达但没有响应”的效果——因为还没把 OpenClaw 和飞书连起来这很正常下一步就是关键的对接环节。5. 让 OpenClaw 与飞书“握手”对接与验证5.1 把飞书密钥写进 OpenClaw回到 Mac 终端在.env文件末尾追加飞书相关配置FEISHU_APP_IDcli_xxxxx FEISHU_APP_SECRETxxxxx FEISHU_EVENT_MODEwebsocketFEISHU_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 理解消息流转链路培养排查直觉对接成功之后建议你把整条消息数据流刻在脑子里之后排查问题会快很多。完整链路是这样的飞书用户发送消息消息先到飞书服务器飞书服务器通过长连接推送到本地 OpenClawOpenClaw 解析事件判断消息来源、内容、会话 IDAgent 编排层接管消息结合记忆和上下文生成提示词大模型 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 常见问题速查表现象可能原因解决方式日志没有收到任何事件长连接未建立检查 App ID、App Secret确认websocket established日志飞书后台显示连接异常本地服务未启动或网络波动重启 OpenClaw确认 3000 端口正常监听消息收到但机器人无回复模型 API Key 失效或额度不足检查模型配置用 curl 手动测试 API 连通每条消息回复两遍长连接和回调同时开启事件订阅模式二选一收到消息回复很慢模型推理慢或工具调用过多换更快模型、精简 Agent 指令链图片和文件无法读取缺少im:resource权限补开权限并重新发布版本端口占用启动失败3000 被其他服务占用修改 OpenClaw 端口或用 lsof 清理占用进程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 自动完成杂事”的上限有了新的认知。