最近社区里OpenClaw这个名字是越来越多了。说白了它就是一个开源的AI Agent框架可以和你本地部署的大模型比如用Ollama跑的Qwen、DeepSeek无缝对接把模型变成真正能干活儿的“数字员工”再接上飞书机器人就能直接在聊天窗口里下发任务、查资料、跑流程。我自己折腾了一个周末把OpenClaw本地部署和飞书接入整体跑通踩了不少坑这篇就当成一份带注释的复盘笔记也想让后来的人少走点弯路。这篇适合谁看如果你手里有一张16G以上显存的显卡或者一台16G内存的Linux服务器想搞一个私有的AI助理同时日常又重度依赖飞书办公那这篇就是为你准备的。如果你是纯新手从没接触过Agent或Webhook也没关系我会把每一步的前因后果都说清楚照着做基本能跑通。1. OpenClaw本地部署的核心思路与选型1.1 为什么坚持本地部署而不是直接用云端API这个问题我琢磨了很久。OpenClaw本身是开源的它不自带模型能力而是通过运行时对接各种大模型接口。你可以选择接云端API也可以选择接本地推理服务。我选的是后者核心原因就三个字数据主权。先说数据隐私。飞书里聊的内容往往包含公司内部信息直接发给云端API等于把这些内容交给第三方。但用本地部署的大模型所有请求都走内网模型推理在本地显卡或服务器上完成数据不出机房。这一点对做企业内部工具来说几乎是刚需。第二是成本。云端API按token计费如果有几个同事高频使用一个月下来开销不小。本地部署买一张显卡是一次性投入之后随便跑不再额外花钱。我自己用的是RTX 4090跑32B以下量化模型的速度完全够用说实话比等待云端排队还快。第三是离线可用。本地部署之后不受外网波动影响万一断网飞书的外联功能用不了但OpenClaw自己还能跑内部消息处理不受影响。当然本地部署也有代价主要是硬件门槛和初始配置复杂度。如果你只是个人尝鲜、不在乎数据外流那直接用云端API配合OpenClaw会更省事。但既然标题是“本地部署”那下面所有操作都以本地推理为基础来讲。1.2 部署方案怎么选Docker容器还是裸机安装OpenClaw官方给了两种部署方式Docker Compose和裸机源码运行。这两条路我都试过各有各的适用场景。如果你只是想在测试环境快速跑通我强烈建议用Docker。它把Python运行时、依赖库、Redis等中间件都封装好了一条docker compose up -d就能把服务拉起来升级和卸载都干净。缺点是调试定制不太灵活想改源码逻辑就得进容器里操作不太方便。裸机源码运行则适合想二次开发的人。你可以直接在宿主机上装Python环境、克隆仓库、装依赖、改配置文件起服务后直接在代码里打日志调试体验好很多。我就是用裸机跑的生产环境因为后面要挂自定义技能改起来顺手。我自己整理了一张对照表方便你判断对比维度Docker容器裸机源码运行部署速度快一条命令慢要装依赖定制灵活性低需进容器高随便改资源占用稍高多一层虚拟化低直连宿主机日志排查需要docker logs直接看终端输出适合场景快速验证、生产环境稳定发布二次开发、调试新技能如果你选择Docker记得把本地的Ollama服务也映射到容器内可访问的地址比如http://192.168.1.10:11434不要用http://localhost,因为容器内的localhost是容器自己。2. 环境准备与依赖安装2.1 硬件和系统的最低要求别被“AI Agent框架”这种词吓到OpenClaw本身不吃资源真正吃资源的是底层大模型。我实测下来的最低门槛是CPU四核起步内存16G以上模型量化后也要占用内存加载中间缓存显卡最好是N卡并有10G以上显存这样跑7B~14B的量化模型才流畅。如果你只有CPU没显卡也可以跑就是速度慢到让人崩溃一句话可能要等五六秒。系统方面Ubuntu 22.04和Windows 11我都跑过。Ubuntu上的兼容性最好很多依赖在Linux上编译顺畅Windows上需要装WSL2或者直接用CMD偶尔会遇到本地依赖编译失败的问题。如果你手头是MacM系列芯片也能跑但有些固件库不支持建议还是先装个Linux虚拟机。还有一点要说清楚OpenClaw本来就有机器人相关的能力如果你以后再想接ROS2之类的机器人控制建议直接上Ubuntu再装ROS2 Humble后面的扩展会顺畅很多。热搜词里总有人把OpenClaw和ROSClaw放在一起问其实就是这个原因底层通信方式有些是相通的。2.2 安装Ollama并拉取合适的模型Ollama是目前最简单好用的本地推理服务它把模型下载、加载、API调用全都封装好了。安装它之前先确认一下你的显卡驱动和CUDA已就绪不然Ollama会用CPU跑。安装命令我直接贴在下面curl -fsSL https://ollama.com/install.sh | sh systemctl status ollama装好后默认服务监听在0.0.0.0:11434可以在浏览器里访问http://你的服务器IP:11434看到说明页面。然后拉取模型。我个人建议从qwen2.5:14b这个量化版本开始它质量和速度比较平衡。如果你显存只有8G那就退一步用qwen2.5:7b如果显存16G以上可以试试qwen2.5:32b的q4量化版回答质量会明显上一个档次。ollama run qwen2.5:14b首次运行会下载模型大概8~10G耐心等一会儿。拉取完成后可以用下面的命令测试API是否正常curl http://localhost:11434/api/generate -d {model:qwen2.5:14b,prompt:你好}能看到一段JSON返回说明Ollama这边已经就绪了。这时候OpenClaw还没装上但大模型这块已经算保底了。2.3 OpenClaw安装与初始化OpenClaw本身没有专门的一键安装包但官方文档给的源码安装方式很稳定。先准备一个干净的Python 3.10以上环境建议用venv隔离别污染系统环境。git clone https://github.com/openclaw-open-source/openclaw.git cd openclaw python3 -m venv venv source venv/bin/activate pip install -r requirements.txt依赖装好后复制一份默认配置cp config.example.yaml config.yaml这里需要修改的关键项就是模型接口地址。打开config.yaml找到llm字段把base_url改成Ollama的地址比如llm: base_url: http://localhost:11434 model: qwen2.5:14b api_key: ollama # Ollama不校验key随便填一个占位符然后启动python main.py看到日志里有Server started at相关的输出就说明OpenClaw已经起来了。默认端口一般是8080可以用curl http://localhost:8080/health确认状态。这一步走完你已经有了一台能调用本地大模型的Agent服务只不过它现在还是个“哑巴”没法让外部世界找到它。下一步就是通过飞书来赋予它一张“嘴”。3. 飞书接入的完整配置流程3.1 在飞书开放平台创建应用和机器人飞书接入方式其实还是走开放平台的机器人能力本质就是给OpenClaw配一个Webhook入口。先在 飞书开放平台 登录点“创建企业自建应用”名称就叫“OpenClaw助手”之类的创建之后会自动拿到一个App ID和App Secret这两个字段后面要用到。然后进入“添加应用能力”选择“机器人”。这一步会在应用里生成一个机器人你可以在飞书里搜索这个应用并给机器人发消息。但光有机器人还不够要让OpenClaw接收到消息需要把消息事件推送到你的服务上。3.2 配置事件订阅和回调地址回到应用的“事件订阅”页面订阅范围选“接收消息”也就是用户给机器人发消息时飞书会向你的服务器发一个POST请求。这里的关键是回调地址。回调地址的格式是https://你的域名:端口/webhook/feishu注意OpenClaw默认不启用SSL如果你没有现成的HTTPS域名可以先用HTTP在内网测试飞书要求回调地址必须是公网可访问的但如果是纯内网测试你可以通过修改飞书应用的“IP白名单”来绕过公网要求具体看你的网络环境。为了稳妥我建议你先用curl手动模拟一下飞书发来的回调确认OpenClaw的Webhook能收到消息。实际上OpenClaw对飞书回调解析已经封装好了你只需要确保请求能到达8080端口的/webhook/feishu路径即可。这里有一个容易踩的坑飞书的事件订阅签名验证需要“加密策略”默认是“加密”。你必须把前面拿到的App Secret填到OpenClaw的配置里否则签名校验会失败飞书那边会一直提示“url验证失败”。我一开始就是没填Secret卡了快一小时。3.3 在OpenClaw里配置飞书绑定回到OpenClaw的config.yaml找到飞书相关的配置段feishu: app_id: cli_xxxxxxxx app_secret: xxxxxxxxxxxxxxxx encrypt_key: 你的Encrypt Key verification_token: 你的Verification Token webhook_path: /webhook/feishuEncrypt Key和Verification Token可以在飞书开放平台的“事件订阅”页面看到。全部填好后重启服务python main.py然后在飞书里给“OpenClaw助手”发一条消息比如“你好”。如果配置成功聊天窗口会在几秒内收到OpenClaw返回的回复。这个回复其实是本地模型实时生成的不是关键词匹配。这里要注意一个细节飞书应用的“权限管理”里需要开启“读取用户发给机器人的消息”和“给用户发送消息”两项权限并且在“版本发布”里创建版本并发布上线否则机器人只能自己看到消息没法主动回话。4. 实操过程与关键踩坑记录4.1 一次完整的从零部署实录我挑一个典型环境说一台刚装好Ubuntu 22.04的服务器显卡是RTX 309024G显存。先装驱动和CUDA这个比较慢但很重要没装好的话Ollama会用CPU推理速度差好几倍。用nvidia-smi确认驱动能识别显卡后装Ollama、拉模型一键完成。然后是OpenClaw源码那一通操作中途遇到一个问题requirements.txt里有个叫tokenizers的包需要版本在0.19以上但pip默认装了个旧版导致启动时报cannot import name Tokenizer。解决方法是手动强制升级pip install --upgrade tokenizers启动后我习惯用screen -S openclaw在后台跑避免SSH断开就停服。接着是飞书开放平台那一套我把App ID和Secret手动填进去后还专门登录飞书后台确认了“事件订阅”里回调地址的路径和端口一致。折腾好久发现是因为我填回调地址时写成了/webhook而OpenClaw配置里定义的是/webhook/feishu马上改掉验证通过。最后我们通过飞书机器人给OpenClaw发送“帮我总结一下今天销售日报的关键数据。”你需要提前在OpenClaw里挂一个读取表格的技能否则它只会用大模型的常识回答。不过这是我后面加技能的事了先确认它能收到消息并调用模型即可。4.2 五个典型的翻车现场部署过程中我遇到的坑不止一个这里挑五个最常见的分享排查思路。问题现象可能原因解决办法飞书一直提示“url验证失败”回调地址路径不对或Encrypt Key配置错检查config.yaml里的webhook_path确保和开放平台填写的路径完全一致本地模型返回空白Ollama模型未加载或服务未监听用curl http://localhost:11434/api/version测试确认nvidia-smi里显存是否占满服务能接收消息但不回话缺少“发送消息”权限在飞书应用的权限管理里开启“给用户发送消息”然后重新发布版本部署在国外服务器后国内访问延迟高网络链路问题这是正常的物理距离造成的延迟建议部署在国内或内网如果只是个人使用就用内网穿透的方式回调Agent回复速度慢模型太大或推理线程被占用换更小的量化模型或限制并发请求数量第五个“内网穿透”我多说一句如果你只有一台本地机器没有公网IP又想测试飞书回调可以用支持内网映射的工具把本地8080端口暴露到一个公网域名上然后在飞书后台填那个域名。这属于正常的技术方案不涉及网络代理问题。5. 常见问题速查表与优化技巧5.1 性能调优显存不够怎么办很多朋友私信问我只有8G显存能不能跑OpenClaw加飞书。我的结论是能跑但要用聪明的模型选择。8G显存跑7B模型的最好量化版本比如qwen2.5:7b-q3是没问题的但并发很差只能串行处理请求。如果你要几个人同时用建议用两个方案之一一是租一张共享显卡二是把模型规模降成3B。另一个办法是给Ollama配置“并发限制”.在环境变量里设置OLLAMA_NUM_PARALLEL1让模型一次只处理一个请求避免炸显存。我自己用的命令是OLLAMA_NUM_PARALLEL1 OLLAMA_KEEP_ALIVE600 ollama serve这样模型在内存里驻留10分钟不会每来一个请求就重新加载一次响应速度能快不少。还可以用ollama ps监控当前加载的模型和缓存情况。5.2 安全与权限配置注意事项本地部署最大的风险就是API暴露在网络上。Ollama默认监听在0.0.0.0:11434这个端口如果在公网上任何人都可以直接请求你的模型相当于给别人免费用算力。所以一定要只绑定内网IP比如OLLAMA_HOST127.0.0.1:11434或者用防火墙规则限制访问来源。飞书这边也有两个安全建议第一在飞书应用的“权限管理”里限制机器人只能对特定用户群回复防止内部同事乱调第二OpenClaw的日志里不要打印完整的消息原文因为可能有敏感词改一下日志级别或者做脱敏处理。还有如果你开启了不加密的HTTP回调飞书事件里的内容在传输过程中是明文。对于企业使用我建议在OpenClaw前面加一层Nginx反向代理配置SSL证书用HTTPS回调地址多一层保障。我在实际跑的时候还遇到过一个问题飞书机器人回复消息时OpenClaw默认会把整个模型输出原样返回如果模型输出特别长飞书又会截断。解决办法是在config.yaml里设置回复长度上限比如max_reply_length: 500超出的部分自动截断。结尾最后分享一个我自己的体会别一上来就想把全赛道都跑通。先把一个最简单的问答闭环走完比如“飞书里发一句你好OpenClaw回一句欢迎”确认链路通顺后再往OpenClaw上挂技能。飞书接入的核心其实是回调地址别配错还有App Secret和Encrypt Key一定要填对。我现在这套已经稳定跑了两周公司内部几个人都在用接下来打算把定时任务也接进来让机器人每天早上主动播报待办事项。如果你也在折腾OpenClaw欢迎一起交流踩坑经验。