去年冬天我把一副常用的小型开源框架折腾成了“本地常驻服务”让它既能处理日常消息又能联动内部的文档和审批流程。最初原因很简单云端方案每个月都要为 API 调用量付费数据还得在别人服务器上过一圈实在不放心。反复比较之后我选定了 OpenClaw 作为本地部署的主体框架然后把飞书作为前端交互入口。这套方案在 Mac 上跑通之后我的日常工作方式发生了不小的变化。下面这篇就是我完整记录下来的本地部署过程从环境检查、安装启动到飞书应用注册、事件订阅、回调调试每一步都附上了当时踩过的坑和最终的解决办法。如果你也有一台 Mac想在自己的电脑上部署一个可长期运行的自动化消息处理服务并且希望它直接和企业协作工具打通那么这篇文章适合你。我们不谈晦涩的底层原理只讲能落地、可复现、稳定运行三个月的实用操作。1. 为什么我选择在 Mac 上做本地部署而不是直接租一台服务器先交代一下背景。我之前用过几款在线消息机器人服务最让我难受的点有两个一个是数据链路不透明消息内容要在第三方平台解析后再回传敏感信息我不敢直接放上去另一个是功能扩展受限平台不开放插件机制想做点定制逻辑就得靠逆向或者 hack维护成本极高。OpenClaw 出现在我视野里之后我注意到它的设计思路和那些封闭平台完全不同它把“接收消息—处理逻辑—发送响应”的整个链路都留给你自己控制所有配置都是本地文件核心服务只负责调度和路由。换句话说OpenClaw 更像一个“消息处理器”而不是一个“AI 机器人平台”。你可以按照自己的意图组合任意处理节点它只负责把事件从入口拉到出口。在 Mac 上部署还有一个现实原因我日常的代码和脚本都已经在这台电脑上本地集成开发环境、定时任务、数据文件全都现成。把 OpenClaw 跑在 Mac 上它可以直接访问我本地已有的资源不需要额外搭建一套文件同步机制。而且 Mac 的电源管理比较稳定合盖后通过配置 caffeinate 可以让服务保持运行这一点在会议室展示和远程调用场景下特别有用。本地部署的另一个好处是迭代速度。云端服务每次改动都要重新打包、重新上传中间还要经历环境不一致造成的诡异 bug。本地部署完全绕开这些问题改完配置马上生效逻辑出错直接看日志调试体验和开发普通脚本没有任何差别。当然本地部署也有它的代价。最明显的就是“可用性”问题电脑关机、睡眠或者断网服务就不可用了。我的做法是把 OpenClaw 做成一个 launchd 服务开机自启配合电源设置让它在关键时段保持唤醒。下面我会专门讲这个配置。2. 环境盘点在动手安装之前先检查这些项目我不太喜欢“拿到项目就开始跑安装命令”的操作方式那通常会浪费更多时间在排查环境问题上。这次部署前我先花十分钟确认了三类基础条件硬件资源、系统版本、运行语言。2.1 Mac 硬件与系统要求官方文档对硬件的要求写得很宽松但我实测下来有两项指标会直接影响使用体验。内存OpenClaw 本身占用不高跑一个基础示例大约需要 300MB 内存。但如果你的处理链路里包含本地模型推理比如接入了本地的大语言模型那么内存占用会直线上升。我的建议是至少 16GB 内存8GB 也能跑但别同时开浏览器和大型 IDE。磁盘项目安装后大约占 1.5GB 空间其中大部分是依赖包和示例模型配置。如果你还打算下载嵌入模型或者语音模型预留 10GB 比较稳妥。系统版本macOS 12.0Monterey及以上我都测试过包括 Intel 和 Apple Silicon 两种架构。Apple Silicon 上有些依赖需要走 Rosetta 2后面我会提具体解决办法。2.2 安装 Homebrew 与基础命令行工具OpenClaw 的依赖安装我统一走 Homebrew 管理这比手动下载安装包要省心得多。如果你的 Mac 上还没有 Homebrew用下面这行命令装/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)装完之后把 Homebrew 的 bin 目录加到 PATH 里Apple Silicon 用户尤其要注意echo eval $(/opt/homebrew/bin/brew shellenv) ~/.zprofile eval $(/opt/homebrew/bin/brew shellenv)Apple Silicon 的 Mac 会把 Homebrew 默认安装到/opt/homebrew而 Intel Mac 是/usr/local。如果你在终端里执行brew --version报错多半就是 PATH 没配对。2.3 运行时版本Node.js 与 Python 的坑OpenClaw 的核心运行时依赖 Node.js部分扩展脚本用 Python 编写。版本要求其实不算苛刻但有两点需要注意Node.js 必须是 18 及以上我用的 20.11 LTS 版本全程没有遇到兼容性问题。Python 3.10 或以上版本并且需要能正常调用 pip 安装依赖。如果你的 Mac 自带的是 Python 3.8请务必升级。brew install node20 python3.11 git这里要特别提醒一点不要直接用系统自带的 Python也不要从 python.org 下载安装包后天真地以为python3指向的就是新版本。用 Homebrew 管理的好处是版本清晰、升级方便、不会污染系统环境。2.4 网络环境与镜像源配置这一步极其关键。OpenClaw 的依赖包一部分托管的境外仓库如果你直接拉取大概率会遇到超时或者校验失败。我当时等了二十分钟才发现问题不在代码而在网络链路上。解决方案是把 npm 和 pip 的 registry 都切到国内镜像npm config set registry https://registry.npmmirror.com pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple提示如果你所在的公司/团队有内部镜像源优先用内部的速度和稳定性都更好。3. 安装 OpenClaw源码获取、依赖安装与首次启动环境准备完毕之后就进入真正的安装环节。我采用的方式是从 GitHub 拉取源码然后本地编译这样后续修改代码和自定义插件都比较方便。3.1 拉取源码与安装依赖git clone https://github.com/openclaw/openclaw.git cd openclaw npm install第一执行npm install通常会花 5 到 10 分钟。如果你发现某一项依赖一直卡住可以单独重试npm config set fetch-retries 3 npm config set fetch-timeout 120000 npm install安装完成之后项目里会生成一个openclaw可执行文件。你可以先看看帮助文档./openclaw --help我执行时的输出显示它支持start、stop、status、config和plugin五个子命令这版本还支持热加载配置排查问题的时候特别方便。3.2 初始化配置文件OpenClaw 的配置默认放在~/.openclaw/config.js第一次启动前需要手动初始化./openclaw config init生成之后不要急着启动打开配置文件看一眼cat ~/.openclaw/config.js里面有几个关键字段需要按需修改server.port本地服务监听端口默认 18080。server.host监听地址默认 127.0.0.1如果需要局域网内访问改成 0.0.0.0。plugins需要激活的插件列表。channels消息渠道配置后面飞书集成时要在这里填信息。3.3 首次启动跑通默认管道我建议第一次启动只保留默认配置不加载任何外部插件先确保服务能正常运行./openclaw start正常情况下日志里会出现类似这样的输出OpenClaw has been initialized. Local server listening on http://127.0.0.1:18080看到这两行说明基础服务已经跑起来了。接着用健康检查接口验证一下curl -X POST http://127.0.0.1:18080/api/health如果返回{status:ok}说明项目安装没有问题可以进入下一步飞书集成了。3.4 让 OpenClaw 后台常驻./openclaw start默认在前台运行关掉终端服务就停了。我的目标是让它在后台长期运行即使电脑重启之后也能自动恢复所以最好做成 launchd 服务。在~/Library/LaunchAgents/下创建一个 plist 文件比如com.openclaw.daemon.plist?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringcom.openclaw.daemon/string keyProgramArguments/key array string/usr/local/bin/openclaw/string stringstart/string /array keyRunAtLoad/key true/ keyKeepAlive/key true/ keyStandardOutPath/key string/tmp/openclaw.log/string keyStandardErrorPath/key string/tmp/openclaw.err/string /dict /plist然后加载并启动launchctl load ~/Library/LaunchAgents/com.openclaw.daemon.plist launchctl start com.openclaw.daemon注意ProgramArguments里的路径要填 openclaw 可执行文件的绝对路径。你可以用which openclaw查看。不要填成相对路径。4. 飞书应用注册打通外部入口的前置工作OpenClaw 本身只是一个本地服务要想让它接收飞书里发来的消息需要在飞书开放平台创建一个应用然后把事件回调地址指向本机的 OpenClaw 服务。这个链路就是整个集成的核心。4.1 在飞书开放平台创建应用打开飞书开放平台进入开发者后台选择“创建企业自建应用”填写应用名称和描述创建完成后你会得到一个 App ID 和 App Secret。这两个信息是后续配置的基础。需要特别注意的是App Secret 不要泄露给任何人也不要提交到公开的代码仓库。飞书开放平台会对这个密钥做权限校验一旦泄露别人就可以伪造你的应用身份收发消息。4.2 启用机器人能力在应用功能的“机器人”页面点击启用机器人。这一步做完之后这个应用就有了一个对应的机器人账号用户可以通过搜索应用名称找到机器人并给它发消息。启用机器人之后飞书后台会生成一个机器人专属的 Webhook 地址这个地址是“发消息”用的。而我们要接的“收消息”能力需要靠事件订阅来完成两者要区分开。4.3 配置事件订阅在事件订阅页面选择“订阅方式”为“使用 Webhook”回调地址暂时先写你自己的服务器地址后面我们再通过内网穿透工具映射到本机端口。这里的事件类型我选择的是message.receive_v1接收用户发给机器人的消息message.read_v1消息已读事件bot.menu_v1机器人菜单点击事件这三个事件基本覆盖了日常交互场景。另外如果你需要机器人主动推送消息还需要申请相应权限。4.4 权限配置的完整清单飞书的权限体系比较繁杂很容易漏配置。我整理了一份当时用到的权限清单权限点用途申请方式im:message读取用户消息内容企业自建应用默认可选im:message.group_at_msg接收群内 机器人的消息需单独申请im:chat读取群列表和群信息按需申请contact:user.base读取用户基本信息一般不需要contact:department.base读取部门信息按需申请大部分权限在“权限管理”页面搜索关键词就能找到。审批速度取决于企业管理员的配置个人开发环境用管理员账号可以直接通过。5. 接线把飞书事件流导进本地 OpenClaw应用创建好了事件订阅也配了接下来要做的是把飞书服务器发来的 HTTPS 请求转发到本地 18080 端口上。飞书不支持 HTTP 回调而且要求回调地址必须是公网可访问的 HTTPS 地址这就需要在本地和公网之间搭一座桥。5.1 为什么需要本地隧道飞书的事件订阅机制是这样的当有人给机器人发消息飞书服务器会向你的回调地址发送一串 JSON 格式的加密数据。你的服务必须在几秒内响应否则飞书会认为回调失败然后重试若干次。本地开发的 Mac 通常没有公网 IP防火墙也挡着外网请求。最简单可靠的办法是用隧道工具把本地的 18080 端口映射到一个临时的公网 HTTPS 地址然后把这个地址填到飞书的回调配置里。我当时用的是 cloudflared因为它在 Mac 上安装方便、无需注册、免费额度足够个人开发用brew install cloudflared cloudflared tunnel --url http://127.0.0.1:18080执行之后终端会分配一个https://xxxx.trycloudflare.com的临时地址。把这个地址复制到飞书事件订阅的回调地址栏里注意路径要指向 OpenClaw 的 webhook 接口。默认的路径是https://xxxx.trycloudflare.com/webhook/feishu这时候先不要急着保存飞书会立刻向这个地址发送一条“URL 验证”请求OpenClaw 收到之后会原样返回一个加密的 challenge 字符串飞书校验通过后事件订阅才算配置成功。5.2 OpenClaw 里配置飞书应用参数回到 OpenClaw 的配置文件~/.openclaw/config.js在channels.feishu部分填入应用信息channels: { feishu: { enable: true, appId: cli_xxxxxxxxxxxx, appSecret: xxxxxxxxxxxxxxxxxxxxxxxx, eventMode: webhook, webhookPath: /webhook/feishu, encryptKey: , verificationToken: } }注意encryptKey和verificationToken是从飞书“事件订阅”页面拿到的不是应用凭据。如果你不打算用加密模式encryptKey 留空也行但 verificationToken 一定要填对否则飞书会拒绝推送。5.3 重启 OpenClaw 并测试连通性配置保存后重启服务launchctl stop com.openclaw.daemon launchctl start com.openclaw.daemon或者如果你用的是后台常驻方式也可以输入./openclaw restart。然后打开日志文件tail -f /tmp/openclaw.log日志里如果出现registration completed字样说明飞书已经成功订阅了事件并且验证回调通过了。5.4 内网穿透的一个坑临时域名会失效cloudflared分配的临时域名只在隧道进程存活期间有效。进程一停域名就失效飞书的回调会马上报错。所以我把 cloudflared 也做成了 launchd 服务让它在后台持久运行。如果你有固定公网 IP 或者云服务器也可以把 OpenClaw 直接部署在云上省去隧道这一层。但本地部署的核心价值就是数据不出本机所以我更倾向于把“本地服务 隧道”这套组合一直保留着。6. 跑通第一个飞书消息的完整流程配置完成后进入验证环节。我给机器人发了一条测试消息完整链路大概是这样我在飞书里找到机器人发送“你好”飞书服务器向 cloudflared 隧道地址推送事件cloudflared 把请求转发到本地 18080 端口OpenClaw 的飞书插件收到事件解析出消息内容和发送者信息OpenClaw 把消息交给默认处理管道生成回应回应通过飞书机器人 API 发送回会话窗口最终我在飞书里看到了机器人的回复往返时间大约 800 毫秒。这个延迟在局域网环境下相当理想。6.1 如何处理飞书消息中的加密内容飞书会在事件回调头里附带一个X-Lark-Request-Timestamp和X-Lark-Request-Nonce消息体里的encrypt字段是密文。OpenClaw 的飞书插件已经把解密逻辑内置了前提是你的配置正确。我当时遇到的坑是encryptKey填错了日志里一直报 “invalid encrypt key”。后来我回到飞书后台重新生成了 Encrypt Key同步更新到配置文件问题才解决。所以如果你在测试时发现回调验证一直失败优先检查 Encrypt Key 和 Verification Token 是否和后台一致。6.2 写一个最简单的自动回复逻辑OpenClaw 的默认处理管道是直接把用户消息转到本地大模型服务。如果你还没有本地模型也可以先用一个最简单的“回声”模式把用户消息原样返回先验证链路通不通。在~/.openclaw/config.js里找到pipelines.default部分pipelines: { default: { steps: [ { module: echo, params: {} } ] } }配置说明echo模块会把收到的消息内容直接作为响应发送。测试通过之后再把这个模块换成真正的大模型推理模块。6.3 接入本地模型推理的配置参考如果你想用本地运行的模型来做语义回复OpenClaw 也支持通过 OpenAI 兼容接口接入。比如你在局域网内跑了一个本地推理服务地址是http://127.0.0.1:12345/v1那么在配置里这样写pipelines: { default: { steps: [ { module: llm, params: { baseUrl: http://127.0.0.1:12345/v1, model: qwen2.5-7b-instruct, apiKey: local-dummy-key } } ] } }apiKey填任意字符串即可因为本地服务不做鉴权。这段配置的意思是OpenClaw 接收飞书消息后把消息文本发给本地 LLM 服务拿到生成结果后再通过飞书 API 发回聊天窗口。7. 长期稳定运行日志、守护与常见故障排查部署完成不是终点能稳定跑三个月才是终点。这一阶段我把重点放在了日志监控、进程守护和日常故障排查上。7.1 日志文件与日志轮转OpenClaw 默认把日志输出到 stdout用 launchd 方式启动的话就写到/tmp/openclaw.log。这个文件会无限增长所以我配置了系统自带的日志轮转。在/etc/newsyslog.d/openclaw.conf里加一行/tmp/openclaw.log root:wheel 640 5 100 * 86400意思是当文件大小达到 100KB 时自动轮转保留最近 5 份旧日志每天至少检查一次。这样日志文件不会撑爆磁盘。7.2 让 Mac 合盖后服务不中断Mac 默认合盖后进入睡眠所有网络服务都会挂起。如果你的任务是让 OpenClaw 随时在线可以通过caffeinate阻止睡眠caffeinate -s 这条命令让系统在插电状态下不进入睡眠。你也可以配合 Mac 的“低功耗模式”来平衡能耗。我用这种方式连续运行了两周没有出现服务掉线的情况。7.3 常见问题排查表以下是这段时间内我遇到最多的问题和对应解决办法。现象可能原因排查/解决飞书回调验证失败Encrypt Key 或 Verification Token 配置错误重新复制后台参数并重启事件订阅页面一直显示“待验证”回调地址没有正确穿透到本地确认 cloudflared 进程是否存活机器人收不到消息权限未开通或事件类型未订阅检查im:message权限和事件订阅列表OpenClaw 日志有错误但服务正常某条事件派发失败用./openclaw debug开启详细日志启动报端口被占用之前有残留进程lsof -i :18080找到进程并 kill本地模型推理有时无响应显存不足或模型并发太高降低模型并发数或换小尺寸模型这些排查步骤不需要复杂的工具一个终端加一个日志文件基本就能覆盖大多数问题。7.4 升级与备份OpenClaw 迭代速度比较快我每个月会拉一次最新代码然后执行增量更新cd ~/openclaw git pull npm install ./openclaw restart更新前请务必备份配置文件cp ~/.openclaw/config.js ~/.openclaw/config.js.bak配置文件的格式是 JavaScript没有严格的语法校验改错一个逗号都可能导致启动失败。备份能让你在升级翻车时快速回滚省去重新配置的麻烦。8. 从消息机器人到自动化工作流进阶扩展心得当飞书消息链路稳定之后OpenClaw 就不再只是个“聊天机器人”了。我开始在它上面挂了一些小的自动化任务包括每日定时推送提醒、关键词触发告警、内部接口查询等。这里分享两个可以复用的扩展思路。8.1 定时任务扩展在 OpenClaw 的plugins目录里新建一个定时任务插件可以看到它会在每天固定时间向飞书群推送一条文本消息。这里的核心逻辑很简单定时器触发 → 生成消息内容 → 调用飞书机器人 API 发送。如果你对消息推送的实时性要求不高这类定时任务足够覆盖绝大多数场景。8.2 关键词路由扩展另一个有用的模式是关键词路由。比如收到包含“日报”的消息OpenClaw 就触发日报生成脚本收到“提醒我”的消息就登记一条时间提醒。这个模式我整理出了一个通用的路由表关键词操作示例日报触发日报汇总脚本“生成日报”检查触发系统健康检查“检查所有服务状态”提醒写入提醒队列“提醒我下午三点开会”实现方式也不复杂在pipelines.default.steps里加一个router模块根据消息内容匹配不同的分支模块。8.3 注意这些扩展不会自动处理复杂业务需要明确一点OpenClaw 是调度框架不是业务系统本身。如果你要对接真正的业务数据库或者复杂审批流建议通过它提供的http模块调用内部接口而不是把所有逻辑都写在 OpenClaw 的插件里。这样做的好处是职责单一OpenClaw 只做消息路由和调度业务逻辑留在业务系统内部。9. 写在最后我对这套方案的直接体验从最初只是想省云服务费用到现在把 OpenClaw 作为飞书消息处理的固定入口这套本地部署方案已经稳定运行了三个多月。我最满意的点依然是数据的可控性消息内容在本机处理加密逻辑自己掌握不依赖任何外部解析服务。如果你准备照着这篇文章操作我的建议是先老老实实走通“安装 隧道 飞书回调”这条完整链路第一次测试只跑一个 echo 模块确认链路没有断点之后再上本地模型或者自动化任务。这条路我走过一遍最大的教训就是别跳步每一步都有它存在的意义。遇到问题的时候先看日志日志里通常写着真正的答案——它比任何猜测都可靠。
去年冬天我把一副常用的小型开源框架折腾成了“本地常驻服务”让它既能处理日常消息又能联动内部的文档和审批流程。最初原因很简单云端方案每个月都要为 API 调用量付费数据还得在别人服务器上过一圈实在不放心。反复比较之后我选定了 OpenClaw 作为本地部署的主体框架然后把飞书作为前端交互入口。这套方案在 Mac 上跑通之后我的日常工作方式发生了不小的变化。下面这篇就是我完整记录下来的本地部署过程从环境检查、安装启动到飞书应用注册、事件订阅、回调调试每一步都附上了当时踩过的坑和最终的解决办法。如果你也有一台 Mac想在自己的电脑上部署一个可长期运行的自动化消息处理服务并且希望它直接和企业协作工具打通那么这篇文章适合你。我们不谈晦涩的底层原理只讲能落地、可复现、稳定运行三个月的实用操作。1. 为什么我选择在 Mac 上做本地部署而不是直接租一台服务器先交代一下背景。我之前用过几款在线消息机器人服务最让我难受的点有两个一个是数据链路不透明消息内容要在第三方平台解析后再回传敏感信息我不敢直接放上去另一个是功能扩展受限平台不开放插件机制想做点定制逻辑就得靠逆向或者 hack维护成本极高。OpenClaw 出现在我视野里之后我注意到它的设计思路和那些封闭平台完全不同它把“接收消息—处理逻辑—发送响应”的整个链路都留给你自己控制所有配置都是本地文件核心服务只负责调度和路由。换句话说OpenClaw 更像一个“消息处理器”而不是一个“AI 机器人平台”。你可以按照自己的意图组合任意处理节点它只负责把事件从入口拉到出口。在 Mac 上部署还有一个现实原因我日常的代码和脚本都已经在这台电脑上本地集成开发环境、定时任务、数据文件全都现成。把 OpenClaw 跑在 Mac 上它可以直接访问我本地已有的资源不需要额外搭建一套文件同步机制。而且 Mac 的电源管理比较稳定合盖后通过配置 caffeinate 可以让服务保持运行这一点在会议室展示和远程调用场景下特别有用。本地部署的另一个好处是迭代速度。云端服务每次改动都要重新打包、重新上传中间还要经历环境不一致造成的诡异 bug。本地部署完全绕开这些问题改完配置马上生效逻辑出错直接看日志调试体验和开发普通脚本没有任何差别。当然本地部署也有它的代价。最明显的就是“可用性”问题电脑关机、睡眠或者断网服务就不可用了。我的做法是把 OpenClaw 做成一个 launchd 服务开机自启配合电源设置让它在关键时段保持唤醒。下面我会专门讲这个配置。2. 环境盘点在动手安装之前先检查这些项目我不太喜欢“拿到项目就开始跑安装命令”的操作方式那通常会浪费更多时间在排查环境问题上。这次部署前我先花十分钟确认了三类基础条件硬件资源、系统版本、运行语言。2.1 Mac 硬件与系统要求官方文档对硬件的要求写得很宽松但我实测下来有两项指标会直接影响使用体验。内存OpenClaw 本身占用不高跑一个基础示例大约需要 300MB 内存。但如果你的处理链路里包含本地模型推理比如接入了本地的大语言模型那么内存占用会直线上升。我的建议是至少 16GB 内存8GB 也能跑但别同时开浏览器和大型 IDE。磁盘项目安装后大约占 1.5GB 空间其中大部分是依赖包和示例模型配置。如果你还打算下载嵌入模型或者语音模型预留 10GB 比较稳妥。系统版本macOS 12.0Monterey及以上我都测试过包括 Intel 和 Apple Silicon 两种架构。Apple Silicon 上有些依赖需要走 Rosetta 2后面我会提具体解决办法。2.2 安装 Homebrew 与基础命令行工具OpenClaw 的依赖安装我统一走 Homebrew 管理这比手动下载安装包要省心得多。如果你的 Mac 上还没有 Homebrew用下面这行命令装/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)装完之后把 Homebrew 的 bin 目录加到 PATH 里Apple Silicon 用户尤其要注意echo eval $(/opt/homebrew/bin/brew shellenv) ~/.zprofile eval $(/opt/homebrew/bin/brew shellenv)Apple Silicon 的 Mac 会把 Homebrew 默认安装到/opt/homebrew而 Intel Mac 是/usr/local。如果你在终端里执行brew --version报错多半就是 PATH 没配对。2.3 运行时版本Node.js 与 Python 的坑OpenClaw 的核心运行时依赖 Node.js部分扩展脚本用 Python 编写。版本要求其实不算苛刻但有两点需要注意Node.js 必须是 18 及以上我用的 20.11 LTS 版本全程没有遇到兼容性问题。Python 3.10 或以上版本并且需要能正常调用 pip 安装依赖。如果你的 Mac 自带的是 Python 3.8请务必升级。brew install node20 python3.11 git这里要特别提醒一点不要直接用系统自带的 Python也不要从 python.org 下载安装包后天真地以为python3指向的就是新版本。用 Homebrew 管理的好处是版本清晰、升级方便、不会污染系统环境。2.4 网络环境与镜像源配置这一步极其关键。OpenClaw 的依赖包一部分托管的境外仓库如果你直接拉取大概率会遇到超时或者校验失败。我当时等了二十分钟才发现问题不在代码而在网络链路上。解决方案是把 npm 和 pip 的 registry 都切到国内镜像npm config set registry https://registry.npmmirror.com pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple提示如果你所在的公司/团队有内部镜像源优先用内部的速度和稳定性都更好。3. 安装 OpenClaw源码获取、依赖安装与首次启动环境准备完毕之后就进入真正的安装环节。我采用的方式是从 GitHub 拉取源码然后本地编译这样后续修改代码和自定义插件都比较方便。3.1 拉取源码与安装依赖git clone https://github.com/openclaw/openclaw.git cd openclaw npm install第一执行npm install通常会花 5 到 10 分钟。如果你发现某一项依赖一直卡住可以单独重试npm config set fetch-retries 3 npm config set fetch-timeout 120000 npm install安装完成之后项目里会生成一个openclaw可执行文件。你可以先看看帮助文档./openclaw --help我执行时的输出显示它支持start、stop、status、config和plugin五个子命令这版本还支持热加载配置排查问题的时候特别方便。3.2 初始化配置文件OpenClaw 的配置默认放在~/.openclaw/config.js第一次启动前需要手动初始化./openclaw config init生成之后不要急着启动打开配置文件看一眼cat ~/.openclaw/config.js里面有几个关键字段需要按需修改server.port本地服务监听端口默认 18080。server.host监听地址默认 127.0.0.1如果需要局域网内访问改成 0.0.0.0。plugins需要激活的插件列表。channels消息渠道配置后面飞书集成时要在这里填信息。3.3 首次启动跑通默认管道我建议第一次启动只保留默认配置不加载任何外部插件先确保服务能正常运行./openclaw start正常情况下日志里会出现类似这样的输出OpenClaw has been initialized. Local server listening on http://127.0.0.1:18080看到这两行说明基础服务已经跑起来了。接着用健康检查接口验证一下curl -X POST http://127.0.0.1:18080/api/health如果返回{status:ok}说明项目安装没有问题可以进入下一步飞书集成了。3.4 让 OpenClaw 后台常驻./openclaw start默认在前台运行关掉终端服务就停了。我的目标是让它在后台长期运行即使电脑重启之后也能自动恢复所以最好做成 launchd 服务。在~/Library/LaunchAgents/下创建一个 plist 文件比如com.openclaw.daemon.plist?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringcom.openclaw.daemon/string keyProgramArguments/key array string/usr/local/bin/openclaw/string stringstart/string /array keyRunAtLoad/key true/ keyKeepAlive/key true/ keyStandardOutPath/key string/tmp/openclaw.log/string keyStandardErrorPath/key string/tmp/openclaw.err/string /dict /plist然后加载并启动launchctl load ~/Library/LaunchAgents/com.openclaw.daemon.plist launchctl start com.openclaw.daemon注意ProgramArguments里的路径要填 openclaw 可执行文件的绝对路径。你可以用which openclaw查看。不要填成相对路径。4. 飞书应用注册打通外部入口的前置工作OpenClaw 本身只是一个本地服务要想让它接收飞书里发来的消息需要在飞书开放平台创建一个应用然后把事件回调地址指向本机的 OpenClaw 服务。这个链路就是整个集成的核心。4.1 在飞书开放平台创建应用打开飞书开放平台进入开发者后台选择“创建企业自建应用”填写应用名称和描述创建完成后你会得到一个 App ID 和 App Secret。这两个信息是后续配置的基础。需要特别注意的是App Secret 不要泄露给任何人也不要提交到公开的代码仓库。飞书开放平台会对这个密钥做权限校验一旦泄露别人就可以伪造你的应用身份收发消息。4.2 启用机器人能力在应用功能的“机器人”页面点击启用机器人。这一步做完之后这个应用就有了一个对应的机器人账号用户可以通过搜索应用名称找到机器人并给它发消息。启用机器人之后飞书后台会生成一个机器人专属的 Webhook 地址这个地址是“发消息”用的。而我们要接的“收消息”能力需要靠事件订阅来完成两者要区分开。4.3 配置事件订阅在事件订阅页面选择“订阅方式”为“使用 Webhook”回调地址暂时先写你自己的服务器地址后面我们再通过内网穿透工具映射到本机端口。这里的事件类型我选择的是message.receive_v1接收用户发给机器人的消息message.read_v1消息已读事件bot.menu_v1机器人菜单点击事件这三个事件基本覆盖了日常交互场景。另外如果你需要机器人主动推送消息还需要申请相应权限。4.4 权限配置的完整清单飞书的权限体系比较繁杂很容易漏配置。我整理了一份当时用到的权限清单权限点用途申请方式im:message读取用户消息内容企业自建应用默认可选im:message.group_at_msg接收群内 机器人的消息需单独申请im:chat读取群列表和群信息按需申请contact:user.base读取用户基本信息一般不需要contact:department.base读取部门信息按需申请大部分权限在“权限管理”页面搜索关键词就能找到。审批速度取决于企业管理员的配置个人开发环境用管理员账号可以直接通过。5. 接线把飞书事件流导进本地 OpenClaw应用创建好了事件订阅也配了接下来要做的是把飞书服务器发来的 HTTPS 请求转发到本地 18080 端口上。飞书不支持 HTTP 回调而且要求回调地址必须是公网可访问的 HTTPS 地址这就需要在本地和公网之间搭一座桥。5.1 为什么需要本地隧道飞书的事件订阅机制是这样的当有人给机器人发消息飞书服务器会向你的回调地址发送一串 JSON 格式的加密数据。你的服务必须在几秒内响应否则飞书会认为回调失败然后重试若干次。本地开发的 Mac 通常没有公网 IP防火墙也挡着外网请求。最简单可靠的办法是用隧道工具把本地的 18080 端口映射到一个临时的公网 HTTPS 地址然后把这个地址填到飞书的回调配置里。我当时用的是 cloudflared因为它在 Mac 上安装方便、无需注册、免费额度足够个人开发用brew install cloudflared cloudflared tunnel --url http://127.0.0.1:18080执行之后终端会分配一个https://xxxx.trycloudflare.com的临时地址。把这个地址复制到飞书事件订阅的回调地址栏里注意路径要指向 OpenClaw 的 webhook 接口。默认的路径是https://xxxx.trycloudflare.com/webhook/feishu这时候先不要急着保存飞书会立刻向这个地址发送一条“URL 验证”请求OpenClaw 收到之后会原样返回一个加密的 challenge 字符串飞书校验通过后事件订阅才算配置成功。5.2 OpenClaw 里配置飞书应用参数回到 OpenClaw 的配置文件~/.openclaw/config.js在channels.feishu部分填入应用信息channels: { feishu: { enable: true, appId: cli_xxxxxxxxxxxx, appSecret: xxxxxxxxxxxxxxxxxxxxxxxx, eventMode: webhook, webhookPath: /webhook/feishu, encryptKey: , verificationToken: } }注意encryptKey和verificationToken是从飞书“事件订阅”页面拿到的不是应用凭据。如果你不打算用加密模式encryptKey 留空也行但 verificationToken 一定要填对否则飞书会拒绝推送。5.3 重启 OpenClaw 并测试连通性配置保存后重启服务launchctl stop com.openclaw.daemon launchctl start com.openclaw.daemon或者如果你用的是后台常驻方式也可以输入./openclaw restart。然后打开日志文件tail -f /tmp/openclaw.log日志里如果出现registration completed字样说明飞书已经成功订阅了事件并且验证回调通过了。5.4 内网穿透的一个坑临时域名会失效cloudflared分配的临时域名只在隧道进程存活期间有效。进程一停域名就失效飞书的回调会马上报错。所以我把 cloudflared 也做成了 launchd 服务让它在后台持久运行。如果你有固定公网 IP 或者云服务器也可以把 OpenClaw 直接部署在云上省去隧道这一层。但本地部署的核心价值就是数据不出本机所以我更倾向于把“本地服务 隧道”这套组合一直保留着。6. 跑通第一个飞书消息的完整流程配置完成后进入验证环节。我给机器人发了一条测试消息完整链路大概是这样我在飞书里找到机器人发送“你好”飞书服务器向 cloudflared 隧道地址推送事件cloudflared 把请求转发到本地 18080 端口OpenClaw 的飞书插件收到事件解析出消息内容和发送者信息OpenClaw 把消息交给默认处理管道生成回应回应通过飞书机器人 API 发送回会话窗口最终我在飞书里看到了机器人的回复往返时间大约 800 毫秒。这个延迟在局域网环境下相当理想。6.1 如何处理飞书消息中的加密内容飞书会在事件回调头里附带一个X-Lark-Request-Timestamp和X-Lark-Request-Nonce消息体里的encrypt字段是密文。OpenClaw 的飞书插件已经把解密逻辑内置了前提是你的配置正确。我当时遇到的坑是encryptKey填错了日志里一直报 “invalid encrypt key”。后来我回到飞书后台重新生成了 Encrypt Key同步更新到配置文件问题才解决。所以如果你在测试时发现回调验证一直失败优先检查 Encrypt Key 和 Verification Token 是否和后台一致。6.2 写一个最简单的自动回复逻辑OpenClaw 的默认处理管道是直接把用户消息转到本地大模型服务。如果你还没有本地模型也可以先用一个最简单的“回声”模式把用户消息原样返回先验证链路通不通。在~/.openclaw/config.js里找到pipelines.default部分pipelines: { default: { steps: [ { module: echo, params: {} } ] } }配置说明echo模块会把收到的消息内容直接作为响应发送。测试通过之后再把这个模块换成真正的大模型推理模块。6.3 接入本地模型推理的配置参考如果你想用本地运行的模型来做语义回复OpenClaw 也支持通过 OpenAI 兼容接口接入。比如你在局域网内跑了一个本地推理服务地址是http://127.0.0.1:12345/v1那么在配置里这样写pipelines: { default: { steps: [ { module: llm, params: { baseUrl: http://127.0.0.1:12345/v1, model: qwen2.5-7b-instruct, apiKey: local-dummy-key } } ] } }apiKey填任意字符串即可因为本地服务不做鉴权。这段配置的意思是OpenClaw 接收飞书消息后把消息文本发给本地 LLM 服务拿到生成结果后再通过飞书 API 发回聊天窗口。7. 长期稳定运行日志、守护与常见故障排查部署完成不是终点能稳定跑三个月才是终点。这一阶段我把重点放在了日志监控、进程守护和日常故障排查上。7.1 日志文件与日志轮转OpenClaw 默认把日志输出到 stdout用 launchd 方式启动的话就写到/tmp/openclaw.log。这个文件会无限增长所以我配置了系统自带的日志轮转。在/etc/newsyslog.d/openclaw.conf里加一行/tmp/openclaw.log root:wheel 640 5 100 * 86400意思是当文件大小达到 100KB 时自动轮转保留最近 5 份旧日志每天至少检查一次。这样日志文件不会撑爆磁盘。7.2 让 Mac 合盖后服务不中断Mac 默认合盖后进入睡眠所有网络服务都会挂起。如果你的任务是让 OpenClaw 随时在线可以通过caffeinate阻止睡眠caffeinate -s 这条命令让系统在插电状态下不进入睡眠。你也可以配合 Mac 的“低功耗模式”来平衡能耗。我用这种方式连续运行了两周没有出现服务掉线的情况。7.3 常见问题排查表以下是这段时间内我遇到最多的问题和对应解决办法。现象可能原因排查/解决飞书回调验证失败Encrypt Key 或 Verification Token 配置错误重新复制后台参数并重启事件订阅页面一直显示“待验证”回调地址没有正确穿透到本地确认 cloudflared 进程是否存活机器人收不到消息权限未开通或事件类型未订阅检查im:message权限和事件订阅列表OpenClaw 日志有错误但服务正常某条事件派发失败用./openclaw debug开启详细日志启动报端口被占用之前有残留进程lsof -i :18080找到进程并 kill本地模型推理有时无响应显存不足或模型并发太高降低模型并发数或换小尺寸模型这些排查步骤不需要复杂的工具一个终端加一个日志文件基本就能覆盖大多数问题。7.4 升级与备份OpenClaw 迭代速度比较快我每个月会拉一次最新代码然后执行增量更新cd ~/openclaw git pull npm install ./openclaw restart更新前请务必备份配置文件cp ~/.openclaw/config.js ~/.openclaw/config.js.bak配置文件的格式是 JavaScript没有严格的语法校验改错一个逗号都可能导致启动失败。备份能让你在升级翻车时快速回滚省去重新配置的麻烦。8. 从消息机器人到自动化工作流进阶扩展心得当飞书消息链路稳定之后OpenClaw 就不再只是个“聊天机器人”了。我开始在它上面挂了一些小的自动化任务包括每日定时推送提醒、关键词触发告警、内部接口查询等。这里分享两个可以复用的扩展思路。8.1 定时任务扩展在 OpenClaw 的plugins目录里新建一个定时任务插件可以看到它会在每天固定时间向飞书群推送一条文本消息。这里的核心逻辑很简单定时器触发 → 生成消息内容 → 调用飞书机器人 API 发送。如果你对消息推送的实时性要求不高这类定时任务足够覆盖绝大多数场景。8.2 关键词路由扩展另一个有用的模式是关键词路由。比如收到包含“日报”的消息OpenClaw 就触发日报生成脚本收到“提醒我”的消息就登记一条时间提醒。这个模式我整理出了一个通用的路由表关键词操作示例日报触发日报汇总脚本“生成日报”检查触发系统健康检查“检查所有服务状态”提醒写入提醒队列“提醒我下午三点开会”实现方式也不复杂在pipelines.default.steps里加一个router模块根据消息内容匹配不同的分支模块。8.3 注意这些扩展不会自动处理复杂业务需要明确一点OpenClaw 是调度框架不是业务系统本身。如果你要对接真正的业务数据库或者复杂审批流建议通过它提供的http模块调用内部接口而不是把所有逻辑都写在 OpenClaw 的插件里。这样做的好处是职责单一OpenClaw 只做消息路由和调度业务逻辑留在业务系统内部。9. 写在最后我对这套方案的直接体验从最初只是想省云服务费用到现在把 OpenClaw 作为飞书消息处理的固定入口这套本地部署方案已经稳定运行了三个多月。我最满意的点依然是数据的可控性消息内容在本机处理加密逻辑自己掌握不依赖任何外部解析服务。如果你准备照着这篇文章操作我的建议是先老老实实走通“安装 隧道 飞书回调”这条完整链路第一次测试只跑一个 echo 模块确认链路没有断点之后再上本地模型或者自动化任务。这条路我走过一遍最大的教训就是别跳步每一步都有它存在的意义。遇到问题的时候先看日志日志里通常写着真正的答案——它比任何猜测都可靠。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
