1. 部署前先搞清楚 OpenClaw 的定位不是机器人框架是 Agent 运行时先说结论OpenClaw 不是那种“填个 token 就能跑”的聊天机器人框架它是一个把大模型、工具调用、记忆存储和 IM 入口统一管理起来的 Agent 运行时。你在飞书里发一句“帮我整理这周的会议纪要”它不只是把这句话转发给大模型而是会拆解任务、决定要不要查文档、按什么格式回复最后把结果发回飞书。这个“拆解—决策—执行—回复”的闭环才是它和普通 bot 最大的区别。我在 MacBook 上跑起来之后最直观的感受是它更像一个“住在飞书里的数字员工”而不是一个“聊天插件”。你可以在配置里给它挂技能比如查数据库、读 RSS、跑定时任务、调内部 API它会在多轮对话里自己决定用哪个工具。我第一次跑通时让它在飞书里帮我“查一下本周三下午有没有安排”它居然自己去翻日历服务然后回了一段带时间段的文字。那一刻我意识到这类项目真正值钱的地方不在“能聊天”而在“能办事”。所以如果你只是想做一个“自动回复机器人”OpenClaw 有点杀鸡用牛刀但如果你想要一个可以持续加技能、沉淀记忆、接多种消息入口的个人助手它确实是个好东西。macOS 本地部署的最大优势是数据完全在你自己手里改配置立刻生效调试的时候可以直接看终端日志不用走一遍“提交代码—构建—部署—看云平台日志”的漫长链路。坏处是电脑合盖或者断网它就歇了所以它更适合个人使用和团队小范围试用而不是生产级 7×24 小时服务。项目本身的代码和依赖不算重但它的运行依赖一个大模型 API。OpenClaw 支持 OpenAI 兼容接口所以你可以接任意一家提供这种格式的模型服务也可以接本地模型。我个人建议第一次部署时先用云端模型接口把链路跑通之后再折腾本地模型这样排查问题时会少一个变量。2. 环境准备macOS 上最容易拖延进度的三个前置项很多人部署失败不是 OpenClaw 难装而是环境没准备好。我在第一次部署时就是卡在 Python 版本上整整多花了半小时。下面这三个前置项提前检查好后面会非常顺。2.1 Python 版本macOS 自带的那个不一定够用macOS 系统自带的 Python 3 版本往往偏老而 OpenClaw 对 Python 版本有要求最好是 3.11 以上。如果你直接用系统自带的 Python 建虚拟环境很可能在安装依赖阶段遇到“编译某个包失败”或者“某个依赖版本冲突”的情况。我的建议是先装一个新版 Python再基于它创建虚拟环境。用你习惯的包管理器装就行装完确认一下python3 --version如果输出不是 3.11 或更高就别用这个解释器建环境。一个稳妥的办法是通过包管理器安装然后直接用它的绝对路径建虚拟环境。2.2 虚拟环境与依赖安装工具推荐用 uvOpenClaw 的依赖项不少而且对依赖解析比较敏感。我用 pip 装的时候遇到过“A 包要求某个版本B 包又要求另一个版本”的尴尬局面后来换成 uv 一次就通了。uv 是个用 Rust 写的 Python 包管理器速度比 pip 快一个数量级锁文件处理也靠谱。如果没有 uv先装它brew install uv后面安装 OpenClaw 依赖时uv sync会按照项目里的锁文件精确还原依赖版本能省掉大量手工解决依赖冲突的时间。如果你坚持用 pip 也可以但我强烈建议用 uv这一步能在“装依赖”环节帮你省下 5-10 分钟。2.3 目录结构规划别把所有文件堆在下载目录OpenClaw 运行后会生成数据文件、日志文件、配置文件。我第一次图省事直接放在“下载”目录里后来想改配置要翻半天还差点把下载目录里的文件当配置清了。建议在用户目录下建一个专门的工作目录mkdir -p ~/workspace/openclaw cd ~/workspace/openclaw后面的所有操作都在这一个目录里完成。这样做的好处是项目代码、虚拟环境、数据文件三者都在一起备份和迁移非常方便出问题时也能快速定位。还有一个容易被忽略的点OpenClaw 的项目名和目录名不要带空格和中文虽然 macOS 本身允许但某些依赖工具在解析路径时会出问题。我见过有人因为路径带中文导致 WebSocket 连接异常排查了半天才发现是路径问题。3. 飞书开放平台侧配置自建应用、权限与事件订阅的完整路径飞书侧的配置是整个部署里最“像做产品”的部分因为你要在开放平台上创建一个自建应用然后给这个应用开权限、配事件、发布版本。这里每一步都有讲究我按当时的操作顺序拆开讲。3.1 创建企业自建应用并开启机器人能力进入飞书开发者后台选择“企业自建应用”创建一个新应用。名字随意比如“本地助手”然后进入应用详情页。第一步不是写代码而是先给应用添加“机器人”能力。在“应用能力”页面里找到“机器人”开启它。这一步很关键因为如果没开机器人能力应用在后端能收到事件却没有身份在飞书里发消息——这个坑我后面会专门讲。接着进入“凭证与基础信息”页面把两个东西记下来配置项示例用途App IDcli_a1b2c3d4应用唯一标识OpenClaw 配置里的 app_idApp Secret一串很长的字符串应用密钥用于调用飞书 API这两个字段是后面 OpenClaw 连接飞书的“身份证”先存在一个安全的地方。注意 App Secret 不要泄露到公开文档或代码仓库里。3.2 开通权限只开需要的别全选在“权限管理”页面里按需开通权限。OpenClaw 要正常工作核心权限只有几个权限代码作用im:message读取和发送单聊、群组消息im:message:send_as_bot以机器人的身份发送消息im:chat:readonly可选读取群组基础信息用于群聊场景很多人会图省事把权限全选了我的建议是别这样。权限开太多一方面发布审核时管理员会多问几句另一方面如果应用被攻击攻击者能拿到的能力范围也会变大。只开够用的最小权限原则在任何时候都适用。权限申请通过后进入“版本发布”页面。这一步是很多人忽略的飞书自建应用创建后默认是“未发布”状态未发布的应用只有你自己能看到机器人也无法在真实会话里发消息。你需要创建一个版本填版本号、更新说明、可用范围然后提交发布。如果你自己是企业管理员直接在后台审批通过如果不是就得找管理员帮忙通过。这也是为什么我说“30 分钟”是在“管理员能立刻审批”的理想前提下如果卡在审批环节时间不可控。3.3 事件订阅本地部署选择长连接模式飞书的事件订阅有两种方式Webhook 和长连接。Webhook 模式需要你提供一个公网可访问的回调地址飞书服务器会把事件推送到这个地址上。本地部署没有公网固定地址走 Webhook 往往还要额外配置公网转发比较折腾。长连接模式则是飞书服务器和你的应用之间建立一个长期存活的 WebSocket 连接飞书主动把事件推过来。这对本地部署极其友好不需要公网地址不需要处理回调验签里的“URL 验证”环节只要你的电脑能访问飞书服务器就行。所以我的选择很明确长连接。在“事件订阅”页面订阅方式选“使用长连接接收事件”然后添加事件。OpenClaw 必须要监听的是“接收消息”事件对应的类型是im.message.receive_v1。把这个事件添加到订阅列表里。添加完事件后页面下方会出现一个“加密策略”区域。这里有两个东西Verification Token用于校验请求来源。Encrypt Key用于消息内容加密。在长连接模式下这两项不是必须的但飞书官方建议开启。我的建议是前期为了快速跑通可以都不填先把链路打通跑通之后再回头加上加密避免“一上来就一堆配置”导致不知道哪里错了。如果你开了加密后面 OpenClaw 配置文件里的encrypt_key必须和后台一致否则消息解密会失败。3.4 把飞书配置信息整理成一张表配置完后台后我习惯把所有关键信息汇总到一张表里后面写 OpenClaw 配置文件时直接抄配置字段从哪里获取备注app_id凭证与基础信息形如 cli_...app_secret凭证与基础信息注意保密verification_token事件订阅 - 加密策略如果不填配置里也可以留空encrypt_key事件订阅 - 加密策略如果不填配置里也可以留空订阅事件im.message.receive_v1必须添加到这里飞书侧的准备工作就绪。此时可以先在飞书里找到自己创建的应用打开“机器人”会话试着发一条消息你会看到“当前应用未发布仅开发者可见”之类的提示这很正常等后面 OpenClaw 跑起来连上长连接后这条消息就会被事件系统推送到本地。4. 本地部署实操拉代码、装依赖、写配置文件、跑起来这一节是纯动手环节步骤按顺序做基本不会出大问题。4.1 获取项目与安装依赖进入之前建好的工作目录拉取 OpenClaw 项目代码。仓库地址以你实际拉取到的为准我这里用一个示例路径cd ~/workspace/openclaw git clone https://github.com/openclaw/openclaw.git cd openclaw拉下来之后先看目录结构确认有配置文件模板和依赖清单。接下来创建虚拟环境并安装依赖uv sync如果项目里有pyproject.tomluv sync会自动创建一个.venv虚拟环境并安装所有依赖。装完之后可以检查一下虚拟环境里的 Python 版本source .venv/bin/activate python --version确认是 3.11 以上再继续。依赖安装是整个部署中最容易被网络或版本问题卡住的一环如果uv sync中途失败多半是网络问题换个网络环境再试一次往往就好了。4.2 编写 OpenClaw 的配置文件项目里通常有一个示例配置文件比如config.example.yaml。先复制一份cp config.example.yaml config.yaml然后编辑config.yaml。我当时的配置大概长这样model: provider: openai_compatible base_url: ${LLM_BASE_URL} api_key: ${LLM_API_KEY} model: ${LLM_MODEL} im: feishu: app_id: ${FEISHU_APP_ID} app_secret: ${FEISHU_APP_SECRET} verification_token: encrypt_key: mode: long_connection skills: - name: builtin_basic enabled: true storage: type: sqlite path: ./data/openclaw.db server: host: 127.0.0.1 port: 8080这里我用了环境变量引用好处是密钥不直接写在代码文件里。OpenClaw 支持从.env文件读取环境变量所以在项目根目录创建.env文件cat .env EOF LLM_BASE_URLhttps://你的模型接口地址/v1 LLM_API_KEY你的模型密钥 LLM_MODEL你的模型名 FEISHU_APP_IDcli_你的AppID FEISHU_APP_SECRET你的AppSecret EOF注意.env文件不要提交到 Git 仓库最好在项目的.gitignore里确认一下。模型接口地址必须是 OpenAI 兼容格式也就是说base_url后面要能直接拼接/chat/completions这种路径。如果你不想用环境变量直接写在config.yaml里也能跑但日常使用中很容易手滑把密钥分享出去所以我建议养成用.env的习惯。4.3 启动 OpenClaw 并完成飞书首次对话配置写完后启动服务source .venv/bin/activate openclaw run第一次启动时日志会输出一些初始化信息。关键要看这几行INFO Loading config from config.yaml INFO Connecting to Feishu long connection... INFO Feishu connection established. INFO Agent ready. Waiting for events...看到 “Feishu connection established” 就说明长连接已经建立了。此时去飞书里给机器人发一条消息比如“你好”终端里应该会出现类似这样的日志INFO Received event: im.message.receive_v1 INFO Processing message from [你的飞书昵称] INFO Reply sent to chat: oc_xxxxxxxx飞书会话里也会收到机器人的回复。到这一步整个部署就成功了。如果你发了消息但飞书里没有回复先别急下一节我把最常见的几个坑和完整的排查链路写出来。这些坑我基本都踩过排查思路比答案本身更有用。5. 踩坑实录验签失败、消息不回复、长连接断线的完整排查链路这一节写我在本地部署里真实遇到的三个问题以及我是怎么一步步定位的。排查链路比最终结论更有价值因为不同版本的 OpenClaw 和不同网络环境下同样的表象可能是不同原因。5.1 验签失败本地长连接模式为什么会遇到这个报错先说一个反直觉的现象即使我用的是长连接模式日志里还是出现过验签失败的报错。当时的第一反应是“长连接不是不需要验签吗怎么还会失败”后来才发现问题出在配置文件的verification_token字段和后台不一致。飞书的长连接模式本质上也要做身份校验只是实现方式和 Webhook 不同。如果你在后台开启加密策略后没有把对应的 verification token 填到 OpenClaw 配置里服务启动时连接会建立但第一条消息推过来时就被飞书侧判定为“身份不匹配”于是日志里出现验签失败消息被丢弃。排查链路是这样的确认后台“事件订阅”页面是否填了 Verification Token 或 Encrypt Key。如果填了检查config.yaml里verification_token和encrypt_key是不是和后台完全一致注意不要有空格。如果后台没填配置文件里也要留空字符串不要随便填个占位符。检查本地系统时间是否准确因为验签时飞书会校验时间戳。macOS 偶尔会出现时间偏差导致验签失败。我当时的根因很简单后台开了加密配置文件加密 key 复制的时候多了一个空格。把空格去掉就通了。这种问题用眼睛看不出来建议复制粘贴密钥后做个 trim 再保存。5.2 消息已收到但 Agent 不回复多半不是 Agent 的问题这个坑最迷惑人。日志里明明显示 “Received event: im.message.receive_v1”说明消息已经推送到本地了但飞书里就是没有回复。看起来像是 Agent 生成回复失败其实大概率是应用没有权限发送消息。我排查这个问题时的链路是看日志里有没有调用模型接口的记录。如果连模型请求日志都没有说明消息在更早的环节就被拦了。检查飞书后台“权限管理”确认im:message:send_as_bot权限是否已开通而不是只开通了im:message。检查应用是否已发布。未发布的应用即使收到了事件也无法以机器人身份在会话里发消息。在飞书“机器人”页面确认你用的是机器人身份发消息而不是应用身份。OpenClaw 接入的是机器人能力不是普通的“应用消息”能力。我当时卡在“未发布”状态整整十来分钟因为开发者后台的版本发布入口藏得比较深不仔细找容易漏掉。建议在接入 OpenClaw 之前先把应用发布流程走完并让管理员审批通过。还有一种情况模型接口调用失败但 Agent 没有显式报错。比如模型 API 返回了超时OpenClaw 默认会静默重试重试几次后放弃但不会在日志里打一个大红叉。如果你看到有模型请求日志却没有回复日志多半是模型侧的问题去验证一下模型接口本身是否可用。5.3 长连接断线MacBook 休眠和网络切换是主要元凶长连接模式好用归好用但它有个先天弱点依赖网络持续可用。我在实际使用中遇到过两类断线一类是 MacBook 合盖休眠后系统自动暂停网络活动长连接被服务端判定超时断开。OpenClaw 通常有自动重连机制但重连期间的消息会丢失。这个问题的缓解方案是在飞书后台的机器人设置里加上“事件重推”同时把本地节点的消息记录打开等重连后做一次补偿同步。不过 OpenClaw 对补偿同步的支持度取决于版本所以最稳妥的做法是如果对消息可靠性要求高别让电脑休眠或者用电源适配器时设置“合盖不睡眠”。另一类是网络切换比如从家里 Wi-Fi 切到手机热点出口 IP 变了飞书服务端的长连接可能被重置。这类断线通常会自动重连但重连需要几秒到几十秒。如果你在切网后立刻给机器人发消息很可能报“消息发送失败”或者长时间不回复。我在配置里加了这么一段来缩短重连时间im: feishu: mode: long_connection reconnect_interval: 3 heartbeat_interval: 30heartbeat_interval让连接在空闲时也保持活跃避免被服务端静默回收reconnect_interval控制断线后的重连频率。这两个参数不是每个版本都有具体看项目的配置文档。5.4 半小时时间线复盘到底哪里会超时很多人看到“30 分钟”会怀疑是不是标题党我实际跑下来的感受是如果环境没问题、审批能秒过30 分钟真的够。下面是时间线拆解阶段预计耗时关键动作最容易超时的点环境准备5 分钟检查 Python、安装 uv、建目录系统自带 Python 版本太老飞书配置10 分钟建应用、开权限、配事件、发布管理员审批时间长本地部署10 分钟拉代码、装依赖、写配置网络下载依赖不稳定启动验证5 分钟启动服务、发消息测试配置密钥不匹配这五个环节里真正不可控的是“发布审批”和“依赖下载网络”。如果你是企业管理员审批环节可以自己点通过如果你是普通成员第一次部署最好找管理员在旁边边做边让他审批这样能省掉等待时间。依赖下载如果慢可以考虑先配置镜像源或者换一个网络环境再跑uv sync。6. 让助手更“专属”技能扩展、数据存储与群聊场景跑通只是第一步真正让 OpenClaw 变得好用的是后续的定制。这一节说几个我在实际使用中体验比较深的扩展方向。6.1 技能机制给 Agent 添加“会做的事”OpenClaw 的技能机制简单说就是给 Agent 准备一批工具函数它会在对话中根据用户意图决定要不要调用。比如我给它加了一个查本地笔记数据库的技能它在飞书里收到“帮我找上周关于部署方案的笔记”时会自动调用这个工具而不是凭空编一个答案。配置技能的方式通常是这样的skills: - name: note_search enabled: true path: ./skills/note_search技能一般是一个包含描述文件和执行代码的目录。描述文件里告诉 Agent“这个技能是干什么的、什么时候应该调用、参数是什么”执行代码则是真正干活的函数。我给技能写的描述越具体Agent 调用它的准确率就越高。比如描述文件里写“当用户提到‘笔记’、‘备忘’、‘记录’时调用”比写成“搜索工具”要有效得多。6.2 数据存储与多会话记忆OpenClaw 默认把会话历史存储在本地 SQLite 里这个设计对本地部署很友好。你可以随时备份数据库文件整个会话记录就全带走了。数据库文件默认在配置的storage.path下比如./data/openclaw.db。多会话记忆这块有一个需要留意的点它默认是按会话维度区分的不是按用户区分。也就是说你和机器人在飞书里的私聊以及群里 它的对话会被当成不同会话。如果你希望机器人在不同会话之间共享某些长期记忆需要配置记忆持久化策略把特定信息存到记忆表里。这个功能我还在摸索中但方向是明确的给 Agent 建立一个“长期事实”的存储区域比如你的姓名、常用术语、偏好格式这样它在不同会话里都能保持一致性。6.3 群聊场景机器人 与权限控制本地部署的 OpenClaw 接飞书后完全可以拉到群里使用。群聊场景有一个核心配置是否允许在群里被 后回复。飞书事件订阅里im.message.receive_v1同样会推送群消息所以 OpenClaw 能收到群里的 消息。但群聊比单聊更容易出问题比如多个人同时 机器人OpenClaw 默认是串行处理的一个人问完才处理下一个。如果你希望它并发处理需要调整并发参数但要注意模型接口的速率限制。还有一个实际经验群里消息比较多时日志会比较吵建议在配置里开启“仅响应 机器人的消息”避免它对群里每条消息都做一次意图判断既费 token 又容易误触发。另外群聊里如果有人发了图片、文件、表情包OpenClaw 默认可能不处理这些媒体消息。如果你的场景需要解析图片就要给技能里加一个图像理解工具否则会在消息解析阶段直接把非文本内容丢掉。6.4 后续扩展方向从“能用”到“好用”跑通 OpenClaw 接飞书之后我给它逐步加了几个小能力目前已经变成一个挺顺手的私人助理定时任务每天早上九点把当天的日历摘要推到飞书群。信息聚合订阅几个 RSS 源让它在固定时间把摘要发给我。数据库查询让它读本地的一个轻量数据库按自然语言查询数据。这些能力的共同点是它们都不需要改动 OpenClaw 核心只需要写对应技能然后在配置里启用。如果你也想让助手“干活”而不是“聊天”可以从这几个方向里挑一个自己最需要的小场景先做起来跑通一次之后后面加技能就非常快了。最后说一点个人体会本地部署这类 Agent 运行时最大的价值不在于“部署本身”而在于它能真正接入你的日常工作流。我建议跑通之后不要急着加一大堆技能先把它当成你常用的“查资料、整理信息、生成草稿”的入口用上一周你会发现哪些场景是高频的哪些技能是刚需然后有的放矢地去扩展。这样一步步调出来的助手才是真正“专属”的。 
长河君 · 2026/10/21 17:23:42 · 阅读 1.2k macOS本地部署OpenClaw接入飞书：完整实操与踩坑指南
1. 部署前先搞清楚 OpenClaw 的定位不是机器人框架是 Agent 运行时先说结论OpenClaw 不是那种“填个 token 就能跑”的聊天机器人框架它是一个把大模型、工具调用、记忆存储和 IM 入口统一管理起来的 Agent 运行时。你在飞书里发一句“帮我整理这周的会议纪要”它不只是把这句话转发给大模型而是会拆解任务、决定要不要查文档、按什么格式回复最后把结果发回飞书。这个“拆解—决策—执行—回复”的闭环才是它和普通 bot 最大的区别。我在 MacBook 上跑起来之后最直观的感受是它更像一个“住在飞书里的数字员工”而不是一个“聊天插件”。你可以在配置里给它挂技能比如查数据库、读 RSS、跑定时任务、调内部 API它会在多轮对话里自己决定用哪个工具。我第一次跑通时让它在飞书里帮我“查一下本周三下午有没有安排”它居然自己去翻日历服务然后回了一段带时间段的文字。那一刻我意识到这类项目真正值钱的地方不在“能聊天”而在“能办事”。所以如果你只是想做一个“自动回复机器人”OpenClaw 有点杀鸡用牛刀但如果你想要一个可以持续加技能、沉淀记忆、接多种消息入口的个人助手它确实是个好东西。macOS 本地部署的最大优势是数据完全在你自己手里改配置立刻生效调试的时候可以直接看终端日志不用走一遍“提交代码—构建—部署—看云平台日志”的漫长链路。坏处是电脑合盖或者断网它就歇了所以它更适合个人使用和团队小范围试用而不是生产级 7×24 小时服务。项目本身的代码和依赖不算重但它的运行依赖一个大模型 API。OpenClaw 支持 OpenAI 兼容接口所以你可以接任意一家提供这种格式的模型服务也可以接本地模型。我个人建议第一次部署时先用云端模型接口把链路跑通之后再折腾本地模型这样排查问题时会少一个变量。2. 环境准备macOS 上最容易拖延进度的三个前置项很多人部署失败不是 OpenClaw 难装而是环境没准备好。我在第一次部署时就是卡在 Python 版本上整整多花了半小时。下面这三个前置项提前检查好后面会非常顺。2.1 Python 版本macOS 自带的那个不一定够用macOS 系统自带的 Python 3 版本往往偏老而 OpenClaw 对 Python 版本有要求最好是 3.11 以上。如果你直接用系统自带的 Python 建虚拟环境很可能在安装依赖阶段遇到“编译某个包失败”或者“某个依赖版本冲突”的情况。我的建议是先装一个新版 Python再基于它创建虚拟环境。用你习惯的包管理器装就行装完确认一下python3 --version如果输出不是 3.11 或更高就别用这个解释器建环境。一个稳妥的办法是通过包管理器安装然后直接用它的绝对路径建虚拟环境。2.2 虚拟环境与依赖安装工具推荐用 uvOpenClaw 的依赖项不少而且对依赖解析比较敏感。我用 pip 装的时候遇到过“A 包要求某个版本B 包又要求另一个版本”的尴尬局面后来换成 uv 一次就通了。uv 是个用 Rust 写的 Python 包管理器速度比 pip 快一个数量级锁文件处理也靠谱。如果没有 uv先装它brew install uv后面安装 OpenClaw 依赖时uv sync会按照项目里的锁文件精确还原依赖版本能省掉大量手工解决依赖冲突的时间。如果你坚持用 pip 也可以但我强烈建议用 uv这一步能在“装依赖”环节帮你省下 5-10 分钟。2.3 目录结构规划别把所有文件堆在下载目录OpenClaw 运行后会生成数据文件、日志文件、配置文件。我第一次图省事直接放在“下载”目录里后来想改配置要翻半天还差点把下载目录里的文件当配置清了。建议在用户目录下建一个专门的工作目录mkdir -p ~/workspace/openclaw cd ~/workspace/openclaw后面的所有操作都在这一个目录里完成。这样做的好处是项目代码、虚拟环境、数据文件三者都在一起备份和迁移非常方便出问题时也能快速定位。还有一个容易被忽略的点OpenClaw 的项目名和目录名不要带空格和中文虽然 macOS 本身允许但某些依赖工具在解析路径时会出问题。我见过有人因为路径带中文导致 WebSocket 连接异常排查了半天才发现是路径问题。3. 飞书开放平台侧配置自建应用、权限与事件订阅的完整路径飞书侧的配置是整个部署里最“像做产品”的部分因为你要在开放平台上创建一个自建应用然后给这个应用开权限、配事件、发布版本。这里每一步都有讲究我按当时的操作顺序拆开讲。3.1 创建企业自建应用并开启机器人能力进入飞书开发者后台选择“企业自建应用”创建一个新应用。名字随意比如“本地助手”然后进入应用详情页。第一步不是写代码而是先给应用添加“机器人”能力。在“应用能力”页面里找到“机器人”开启它。这一步很关键因为如果没开机器人能力应用在后端能收到事件却没有身份在飞书里发消息——这个坑我后面会专门讲。接着进入“凭证与基础信息”页面把两个东西记下来配置项示例用途App IDcli_a1b2c3d4应用唯一标识OpenClaw 配置里的 app_idApp Secret一串很长的字符串应用密钥用于调用飞书 API这两个字段是后面 OpenClaw 连接飞书的“身份证”先存在一个安全的地方。注意 App Secret 不要泄露到公开文档或代码仓库里。3.2 开通权限只开需要的别全选在“权限管理”页面里按需开通权限。OpenClaw 要正常工作核心权限只有几个权限代码作用im:message读取和发送单聊、群组消息im:message:send_as_bot以机器人的身份发送消息im:chat:readonly可选读取群组基础信息用于群聊场景很多人会图省事把权限全选了我的建议是别这样。权限开太多一方面发布审核时管理员会多问几句另一方面如果应用被攻击攻击者能拿到的能力范围也会变大。只开够用的最小权限原则在任何时候都适用。权限申请通过后进入“版本发布”页面。这一步是很多人忽略的飞书自建应用创建后默认是“未发布”状态未发布的应用只有你自己能看到机器人也无法在真实会话里发消息。你需要创建一个版本填版本号、更新说明、可用范围然后提交发布。如果你自己是企业管理员直接在后台审批通过如果不是就得找管理员帮忙通过。这也是为什么我说“30 分钟”是在“管理员能立刻审批”的理想前提下如果卡在审批环节时间不可控。3.3 事件订阅本地部署选择长连接模式飞书的事件订阅有两种方式Webhook 和长连接。Webhook 模式需要你提供一个公网可访问的回调地址飞书服务器会把事件推送到这个地址上。本地部署没有公网固定地址走 Webhook 往往还要额外配置公网转发比较折腾。长连接模式则是飞书服务器和你的应用之间建立一个长期存活的 WebSocket 连接飞书主动把事件推过来。这对本地部署极其友好不需要公网地址不需要处理回调验签里的“URL 验证”环节只要你的电脑能访问飞书服务器就行。所以我的选择很明确长连接。在“事件订阅”页面订阅方式选“使用长连接接收事件”然后添加事件。OpenClaw 必须要监听的是“接收消息”事件对应的类型是im.message.receive_v1。把这个事件添加到订阅列表里。添加完事件后页面下方会出现一个“加密策略”区域。这里有两个东西Verification Token用于校验请求来源。Encrypt Key用于消息内容加密。在长连接模式下这两项不是必须的但飞书官方建议开启。我的建议是前期为了快速跑通可以都不填先把链路打通跑通之后再回头加上加密避免“一上来就一堆配置”导致不知道哪里错了。如果你开了加密后面 OpenClaw 配置文件里的encrypt_key必须和后台一致否则消息解密会失败。3.4 把飞书配置信息整理成一张表配置完后台后我习惯把所有关键信息汇总到一张表里后面写 OpenClaw 配置文件时直接抄配置字段从哪里获取备注app_id凭证与基础信息形如 cli_...app_secret凭证与基础信息注意保密verification_token事件订阅 - 加密策略如果不填配置里也可以留空encrypt_key事件订阅 - 加密策略如果不填配置里也可以留空订阅事件im.message.receive_v1必须添加到这里飞书侧的准备工作就绪。此时可以先在飞书里找到自己创建的应用打开“机器人”会话试着发一条消息你会看到“当前应用未发布仅开发者可见”之类的提示这很正常等后面 OpenClaw 跑起来连上长连接后这条消息就会被事件系统推送到本地。4. 本地部署实操拉代码、装依赖、写配置文件、跑起来这一节是纯动手环节步骤按顺序做基本不会出大问题。4.1 获取项目与安装依赖进入之前建好的工作目录拉取 OpenClaw 项目代码。仓库地址以你实际拉取到的为准我这里用一个示例路径cd ~/workspace/openclaw git clone https://github.com/openclaw/openclaw.git cd openclaw拉下来之后先看目录结构确认有配置文件模板和依赖清单。接下来创建虚拟环境并安装依赖uv sync如果项目里有pyproject.tomluv sync会自动创建一个.venv虚拟环境并安装所有依赖。装完之后可以检查一下虚拟环境里的 Python 版本source .venv/bin/activate python --version确认是 3.11 以上再继续。依赖安装是整个部署中最容易被网络或版本问题卡住的一环如果uv sync中途失败多半是网络问题换个网络环境再试一次往往就好了。4.2 编写 OpenClaw 的配置文件项目里通常有一个示例配置文件比如config.example.yaml。先复制一份cp config.example.yaml config.yaml然后编辑config.yaml。我当时的配置大概长这样model: provider: openai_compatible base_url: ${LLM_BASE_URL} api_key: ${LLM_API_KEY} model: ${LLM_MODEL} im: feishu: app_id: ${FEISHU_APP_ID} app_secret: ${FEISHU_APP_SECRET} verification_token: encrypt_key: mode: long_connection skills: - name: builtin_basic enabled: true storage: type: sqlite path: ./data/openclaw.db server: host: 127.0.0.1 port: 8080这里我用了环境变量引用好处是密钥不直接写在代码文件里。OpenClaw 支持从.env文件读取环境变量所以在项目根目录创建.env文件cat .env EOF LLM_BASE_URLhttps://你的模型接口地址/v1 LLM_API_KEY你的模型密钥 LLM_MODEL你的模型名 FEISHU_APP_IDcli_你的AppID FEISHU_APP_SECRET你的AppSecret EOF注意.env文件不要提交到 Git 仓库最好在项目的.gitignore里确认一下。模型接口地址必须是 OpenAI 兼容格式也就是说base_url后面要能直接拼接/chat/completions这种路径。如果你不想用环境变量直接写在config.yaml里也能跑但日常使用中很容易手滑把密钥分享出去所以我建议养成用.env的习惯。4.3 启动 OpenClaw 并完成飞书首次对话配置写完后启动服务source .venv/bin/activate openclaw run第一次启动时日志会输出一些初始化信息。关键要看这几行INFO Loading config from config.yaml INFO Connecting to Feishu long connection... INFO Feishu connection established. INFO Agent ready. Waiting for events...看到 “Feishu connection established” 就说明长连接已经建立了。此时去飞书里给机器人发一条消息比如“你好”终端里应该会出现类似这样的日志INFO Received event: im.message.receive_v1 INFO Processing message from [你的飞书昵称] INFO Reply sent to chat: oc_xxxxxxxx飞书会话里也会收到机器人的回复。到这一步整个部署就成功了。如果你发了消息但飞书里没有回复先别急下一节我把最常见的几个坑和完整的排查链路写出来。这些坑我基本都踩过排查思路比答案本身更有用。5. 踩坑实录验签失败、消息不回复、长连接断线的完整排查链路这一节写我在本地部署里真实遇到的三个问题以及我是怎么一步步定位的。排查链路比最终结论更有价值因为不同版本的 OpenClaw 和不同网络环境下同样的表象可能是不同原因。5.1 验签失败本地长连接模式为什么会遇到这个报错先说一个反直觉的现象即使我用的是长连接模式日志里还是出现过验签失败的报错。当时的第一反应是“长连接不是不需要验签吗怎么还会失败”后来才发现问题出在配置文件的verification_token字段和后台不一致。飞书的长连接模式本质上也要做身份校验只是实现方式和 Webhook 不同。如果你在后台开启加密策略后没有把对应的 verification token 填到 OpenClaw 配置里服务启动时连接会建立但第一条消息推过来时就被飞书侧判定为“身份不匹配”于是日志里出现验签失败消息被丢弃。排查链路是这样的确认后台“事件订阅”页面是否填了 Verification Token 或 Encrypt Key。如果填了检查config.yaml里verification_token和encrypt_key是不是和后台完全一致注意不要有空格。如果后台没填配置文件里也要留空字符串不要随便填个占位符。检查本地系统时间是否准确因为验签时飞书会校验时间戳。macOS 偶尔会出现时间偏差导致验签失败。我当时的根因很简单后台开了加密配置文件加密 key 复制的时候多了一个空格。把空格去掉就通了。这种问题用眼睛看不出来建议复制粘贴密钥后做个 trim 再保存。5.2 消息已收到但 Agent 不回复多半不是 Agent 的问题这个坑最迷惑人。日志里明明显示 “Received event: im.message.receive_v1”说明消息已经推送到本地了但飞书里就是没有回复。看起来像是 Agent 生成回复失败其实大概率是应用没有权限发送消息。我排查这个问题时的链路是看日志里有没有调用模型接口的记录。如果连模型请求日志都没有说明消息在更早的环节就被拦了。检查飞书后台“权限管理”确认im:message:send_as_bot权限是否已开通而不是只开通了im:message。检查应用是否已发布。未发布的应用即使收到了事件也无法以机器人身份在会话里发消息。在飞书“机器人”页面确认你用的是机器人身份发消息而不是应用身份。OpenClaw 接入的是机器人能力不是普通的“应用消息”能力。我当时卡在“未发布”状态整整十来分钟因为开发者后台的版本发布入口藏得比较深不仔细找容易漏掉。建议在接入 OpenClaw 之前先把应用发布流程走完并让管理员审批通过。还有一种情况模型接口调用失败但 Agent 没有显式报错。比如模型 API 返回了超时OpenClaw 默认会静默重试重试几次后放弃但不会在日志里打一个大红叉。如果你看到有模型请求日志却没有回复日志多半是模型侧的问题去验证一下模型接口本身是否可用。5.3 长连接断线MacBook 休眠和网络切换是主要元凶长连接模式好用归好用但它有个先天弱点依赖网络持续可用。我在实际使用中遇到过两类断线一类是 MacBook 合盖休眠后系统自动暂停网络活动长连接被服务端判定超时断开。OpenClaw 通常有自动重连机制但重连期间的消息会丢失。这个问题的缓解方案是在飞书后台的机器人设置里加上“事件重推”同时把本地节点的消息记录打开等重连后做一次补偿同步。不过 OpenClaw 对补偿同步的支持度取决于版本所以最稳妥的做法是如果对消息可靠性要求高别让电脑休眠或者用电源适配器时设置“合盖不睡眠”。另一类是网络切换比如从家里 Wi-Fi 切到手机热点出口 IP 变了飞书服务端的长连接可能被重置。这类断线通常会自动重连但重连需要几秒到几十秒。如果你在切网后立刻给机器人发消息很可能报“消息发送失败”或者长时间不回复。我在配置里加了这么一段来缩短重连时间im: feishu: mode: long_connection reconnect_interval: 3 heartbeat_interval: 30heartbeat_interval让连接在空闲时也保持活跃避免被服务端静默回收reconnect_interval控制断线后的重连频率。这两个参数不是每个版本都有具体看项目的配置文档。5.4 半小时时间线复盘到底哪里会超时很多人看到“30 分钟”会怀疑是不是标题党我实际跑下来的感受是如果环境没问题、审批能秒过30 分钟真的够。下面是时间线拆解阶段预计耗时关键动作最容易超时的点环境准备5 分钟检查 Python、安装 uv、建目录系统自带 Python 版本太老飞书配置10 分钟建应用、开权限、配事件、发布管理员审批时间长本地部署10 分钟拉代码、装依赖、写配置网络下载依赖不稳定启动验证5 分钟启动服务、发消息测试配置密钥不匹配这五个环节里真正不可控的是“发布审批”和“依赖下载网络”。如果你是企业管理员审批环节可以自己点通过如果你是普通成员第一次部署最好找管理员在旁边边做边让他审批这样能省掉等待时间。依赖下载如果慢可以考虑先配置镜像源或者换一个网络环境再跑uv sync。6. 让助手更“专属”技能扩展、数据存储与群聊场景跑通只是第一步真正让 OpenClaw 变得好用的是后续的定制。这一节说几个我在实际使用中体验比较深的扩展方向。6.1 技能机制给 Agent 添加“会做的事”OpenClaw 的技能机制简单说就是给 Agent 准备一批工具函数它会在对话中根据用户意图决定要不要调用。比如我给它加了一个查本地笔记数据库的技能它在飞书里收到“帮我找上周关于部署方案的笔记”时会自动调用这个工具而不是凭空编一个答案。配置技能的方式通常是这样的skills: - name: note_search enabled: true path: ./skills/note_search技能一般是一个包含描述文件和执行代码的目录。描述文件里告诉 Agent“这个技能是干什么的、什么时候应该调用、参数是什么”执行代码则是真正干活的函数。我给技能写的描述越具体Agent 调用它的准确率就越高。比如描述文件里写“当用户提到‘笔记’、‘备忘’、‘记录’时调用”比写成“搜索工具”要有效得多。6.2 数据存储与多会话记忆OpenClaw 默认把会话历史存储在本地 SQLite 里这个设计对本地部署很友好。你可以随时备份数据库文件整个会话记录就全带走了。数据库文件默认在配置的storage.path下比如./data/openclaw.db。多会话记忆这块有一个需要留意的点它默认是按会话维度区分的不是按用户区分。也就是说你和机器人在飞书里的私聊以及群里 它的对话会被当成不同会话。如果你希望机器人在不同会话之间共享某些长期记忆需要配置记忆持久化策略把特定信息存到记忆表里。这个功能我还在摸索中但方向是明确的给 Agent 建立一个“长期事实”的存储区域比如你的姓名、常用术语、偏好格式这样它在不同会话里都能保持一致性。6.3 群聊场景机器人 与权限控制本地部署的 OpenClaw 接飞书后完全可以拉到群里使用。群聊场景有一个核心配置是否允许在群里被 后回复。飞书事件订阅里im.message.receive_v1同样会推送群消息所以 OpenClaw 能收到群里的 消息。但群聊比单聊更容易出问题比如多个人同时 机器人OpenClaw 默认是串行处理的一个人问完才处理下一个。如果你希望它并发处理需要调整并发参数但要注意模型接口的速率限制。还有一个实际经验群里消息比较多时日志会比较吵建议在配置里开启“仅响应 机器人的消息”避免它对群里每条消息都做一次意图判断既费 token 又容易误触发。另外群聊里如果有人发了图片、文件、表情包OpenClaw 默认可能不处理这些媒体消息。如果你的场景需要解析图片就要给技能里加一个图像理解工具否则会在消息解析阶段直接把非文本内容丢掉。6.4 后续扩展方向从“能用”到“好用”跑通 OpenClaw 接飞书之后我给它逐步加了几个小能力目前已经变成一个挺顺手的私人助理定时任务每天早上九点把当天的日历摘要推到飞书群。信息聚合订阅几个 RSS 源让它在固定时间把摘要发给我。数据库查询让它读本地的一个轻量数据库按自然语言查询数据。这些能力的共同点是它们都不需要改动 OpenClaw 核心只需要写对应技能然后在配置里启用。如果你也想让助手“干活”而不是“聊天”可以从这几个方向里挑一个自己最需要的小场景先做起来跑通一次之后后面加技能就非常快了。最后说一点个人体会本地部署这类 Agent 运行时最大的价值不在于“部署本身”而在于它能真正接入你的日常工作流。我建议跑通之后不要急着加一大堆技能先把它当成你常用的“查资料、整理信息、生成草稿”的入口用上一周你会发现哪些场景是高频的哪些技能是刚需然后有的放矢地去扩展。这样一步步调出来的助手才是真正“专属”的。