1. 先搞清楚这套组合到底在解决什么问题先说个我自己的场景本地攒了一台带显卡的工作站装了 Ollama 跑开源模型平时自己一个人在终端里聊得挺开心。但问题在于这东西只有我能用。同事问我能不能给咱们群也接一个家里人想用一下我总不能教每个人去敲命令行。后来我把 OpenClaw 接上飞书机器人又把模型后端指向本地 Ollama整个事情就完全不一样了群里 一下机器人它就能回答问题、执行任务数据还全程不出内网。这篇是实战系列的第一篇就把这条链路从零到一完整拆开。OpenClaw 是个开源的个人 AI 助手框架。你可以把它理解成一个中间调度层它负责连接各种消息平台收到消息后交给大模型驱动的 Agent 主循环去处理Agent 还能调用一堆工具——读写文件、执行 shell 命令、浏览网页、查日历——然后把最终结果发回对话。它不只是个聊天机器人而是一个真正能干活的 AI 代理。飞书则承担了遥控器的角色你平时上班就在飞书里不用开任何额外界面群聊就是和 AI 交互的入口。Ollama 在这里负责提供本地大模型推理能力好处是私密、免费、无 API 限流焦虑敏感数据完全留在自己的服务器上。所以这套组合的完整链路是飞书用户群聊里 机器人 │ ▼ 飞书开放平台事件订阅 / 长连接推送 │ ▼ OpenClaw Agent 主循环 ──► Ollama本地大模型推理 │ │ │ 需要时调用文件/命令/网页等工具 └─ qwen2.5 或 llama3.1 等 ▼ 飞书消息 API把回复发回群聊 │ ▼ 用户收到机器人的回答这篇文章适合两类人一是想在公司或团队里搭一个私有 AI 助手的开发者、运维二是单纯想把本地大模型从终端玩物变成全家可用工具的折腾型玩家。你有 Docker 基础、懂一点 YAML 配置就能完整跑通。2. 开工前的物料清单服务器、飞书权限和模型选型2.1 服务器与运行环境的最低要求别一上来就追新追大先看你的硬件能撑住什么模型。OpenClaw 本身对资源要求不高大头全在本地推理上。如果你的机器只有 CPU那 7B 级别的量化模型勉强能跑但一条消息可能要等几十秒体验会很差。如果你有 NVIDIA 显卡16GB 显存起步是黄金配置能舒服地跑 14B 模型24GB 以上可以考虑 32B如果是 Mac 的统一内存架构32GB 内存跑 14B 也没问题。操作系统方面Linux 服务器是最省心的选择Docker 布署也最顺Windows 上我建议用 WSL2 或者干脆全程容器化避免各种路径和环境变量问题。另外提醒一句飞书开放平台的 API 需要你的服务器能正常访问外网如果你的机器在 NAT 后面、没有公网 IP也没关系因为咱们会用飞书的长连接模式这个后面细说。2.2 飞书侧关键的隐形成本管理员审批很多人以为接飞书机器人就是建个应用那么简单结果卡在审批上。企业自建应用创建之后所有权限变更都要走创建版本 - 提审 - 管理员审批这个流程。也就是说你需要有一个飞书管理员帮你点通过或者你自己就是管理员。如果你在一个大型组织里建议提前跟管理员打好招呼把申请发布应用这个事列入流程否则配置到一半卡住很尴尬。Subscriptions 还有一个容易忽略的点你创建的应用是企业自建应用而不是商店应用所以审批一般走内部流程不会太久但一定要留出这个时间。我在第一次搭的时候权限配置花了十分钟审批等了大半天所以把这事排在物料清单里提前准备。2.3 本地模型选型Agent 任务不能只看能聊给 OpenClaw 选模型和普通聊天选模型是两回事。普通聊天模型答得差一点最多是废话多但 Agent 场景里模型必须稳定输出工具调用指令——它得能判断这个问题需要调用什么工具、传什么参数并在工具返回结果后正确组织最终回复。工具调用能力不达标的模型会表现得很怪要么明明该查文件却硬编一个答案要么反复调用同一个工具不结束。模型显存/内存建议工具调用表现适用定位qwen2.5:7b约 6GB良低配机器跑通链路qwen2.5:14b约 12GB优综合推荐中文好llama3.1:8b约 8GB良英文任务更占优deepseek-r1:8b约 8GB中推理强但工具调用需实测基于我的实测qwen2.5:14b是目前这个场景里性价比最高的选择中文指令理解好、工具调用协议支持得完整、在 16GB 显存上速度也还凑合。如果你机器配置低先用qwen2.5:7b把链路跑通再换大模型。3. 飞书侧完整配置自建应用、事件订阅与长连接模式3.1 创建企业自建应用并开启机器人能力登录飞书开放平台开发者后台选择创建企业自建应用填好名称、图标和描述这一步不用纠结后面随时能改。创建完进入应用详情页左侧导航找到应用能力把机器人能力打开。机器人能力不打开后面一切都是空谈。最容易被忽略的是权限管理。飞书把权限设计得非常细碎命名还经常调整。我的建议是在权限管理页面里把和消息、群组、机器人相关的权限逐条过一遍按最小权限原则勾选。实际需要的大概是这几类接收用户发给机器人的消息、以机器人身份发送消息、读取群基本信息。不同版本界面里选项名可能不一样认准中文功能描述别死背权限代码。这里我有个经验宁可先多勾一两个等跑通了再收紧也不要一开始就卡在只有收发没有发这种权限空缺上。3.2 事件订阅强烈建议用长连接而不是公网 Webhook这是整篇教程里最影响成败的一个选择。飞书事件订阅有两种接收方式一种是你提供一个公网 HTTPS 回调地址飞书把事件推送过去另一种是长连接模式由飞书的内置长连接机制主动向你的服务器建立 WebSocket 连接事件通过这条连接直接推给你。我的建议非常明确用长连接。原因有三第一不需要公网域名和 HTTPS 证书省掉一层运维第二服务器在 NAT 后面、没有固定公网 IP 也能用家里部署特别合适第三OpenClaw 的飞书连接器本身就是为这种模式设计的事件进来后直接在本地处理延迟更低。在事件订阅页面你需要添加至少一个事件im.message.receive_v1中文名大概叫接收消息。这就是用户 机器人时触发的事件。同时页面里会有Verification Token校验Token和Encrypt Key加密密钥两个字段。这里有个大坑如果开放平台上开启了加密回调的 payload 会是一坨密文接收方必须先解密才能拿到真实事件内容。所以要么你别开加密纯内网场景问题不大要么把密钥正确配置到 OpenClaw 侧两边一致才能跑通。3.3 发布版本、把机器人拉进群、定位 chat_id权限和事件配好之后去版本管理与发布里创建一个版本填好版本说明提交审批。管理员审批通过后你的应用才算真正生效。这一步很多人会漏光在开发者后台改了配置不重新发布版本线上应用跑的还是老配置。每次改了权限或事件订阅都要重新发版。应用发布后到飞书群里添加机器人群设置 - 群机器人 - 添加机器人 - 找到你刚创建的应用。添加成功后你可以在群里 它试一下此时如果事件订阅通了OpenClaw 那边就能看到事件日志。还有一个关键数据chat_id。它一般长这样oc_xxxxxxxxxxxxxxxxxxxx。获取方式有两个一是从事件推送的 payload 里拿消息事件里一定带chat_id字段二是调用开放平台的群信息接口。chat_id后面配置白名单和手动发送消息时都要用建议先记住它。4. Ollama 本地模型接入细节OpenAI 兼容接口是枢纽4.1 安装、常驻启动与对外开放监听Ollama 的安装很简单Linux 一条脚本命令macOS 和 Windows 有现成安装包。装完先拉模型比如ollama pull qwen2.5:14b这一步会花一些时间取决于网速和模型体积。这里提醒一下模型文件大提前规划磁盘空间14B 量化模型大概要 9GB 左右。然后是最容易踩的坑。默认情况下 Ollama 只监听127.0.0.1:11434这意味着只有本机进程能访问。如果你的 OpenClaw 跑在 Docker 容器里那容器里的进程是访问不到宿主机 Ollama 的。解决办法是让 Ollama 监听所有网卡OLLAMA_HOST0.0.0.0:11434 ollama serve注意监听0.0.0.0意味着局域网里所有机器都能访问你 Ollama 的接口如果服务器在内网环境里别人也能白嫖你的推理能力。建议通过防火墙或 Docker 网络隔离来限制别裸奔。4.2 用 OpenAI 兼容层做连通性测试Ollama 自带一个 OpenAI 兼容接口地址是http://localhost:11434/v1。这意味着任何配置了 OpenAI Base URL 就能用的框架都可以直接指向 Ollama。先手动验证一下# 查看当前有哪些模型 curl http://localhost:11434/v1/models# 模拟一次对话请求 curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5:14b, messages: [{role: user, content: 用一句话介绍你自己}] }如果这两条命令都正常返回说明 Ollama 的兼容层没问题可以把它当作一个本地版 OpenAI API来对接。有一点要明确Ollama 的 /v1 接口默认不需要鉴权但 OpenClaw 这类框架通常要求填一个 API Key 字段这里随便填一个非空字符串比如ollama就能通过。4.3 function calling 能力实测别等接完才发现模型不行在正式接入 OpenClaw 之前我强烈建议你先单独验证一下模型的工具调用能力。Ollama 的 /v1 接口也支持tools参数你可以手工构造一次带工具定义的请求看模型是正确返回tool_calls还是无视工具直接给了一个文本回答。后者说明这个模型在工具调用模式下表现不行建议换一个再继续。实测下来qwen2.5系列的界面比较规整工具调用格式正确率高deepseek-r1这种强推理模型会把思维链内容混进输出有时工具调用的格式会漂移需要花时间调 prompt。Agent 场景里我更看重协议稳定性而不是推理天花板所以这一步值得在动手接 OpenClaw 之前花十分钟测清楚。5. OpenClaw 安装、初始化与飞书连接器配置5.1 安装与启动方式OpenClaw 是开源项目迭代速度很快。我写这篇时安装方式以官方仓库 README 为准。大致流程是拉代码、装依赖、构建、初始化配置git clone https://github.com/openclaw/openclaw.git cd openclaw # 安装依赖并构建具体命令以仓库 README 为准 pnpm install pnpm build # 初始化配置文件 openclaw init # 启动 Agent 主进程 openclaw start如果你不想折腾本地环境也可以直接把 OpenClaw 容器化运行。但不管哪种方式都建议先跑一遍openclaw init它会生成一个包含默认配置的文件你要做的就是在它基础上改。我个人的习惯是先在终端里跑通openclaw chat和本地模型对话确认 Agent 基本功能没问题再去连飞书。这样排查问题时能干净地切分OpenClaw 自身问题和飞书接入问题。5.2 飞书连接器配置字段逐个解读打开生成的配置文件找到连接器相关段落把飞书信息填进去。下面是我手头版本的配置示意不同版本字段名可能有出入但含义是稳定的你照着这个思路去对应自己版本的配置格式就行connectors: feishu: appId: cli_xxxxxxxxxxxxxxxx appSecret: 你的应用密钥 eventMode: websocket replyMode: api allowedChatIds: - oc_xxxxxxxxxxxxxxxxxxxx几个关键字段说清楚appId和appSecret在飞书开发者后台应用详情页的凭证与基础信息里拿。appSecret是敏感信息别提交进 Git 仓库建议用环境变量注入。eventMode: websocket这就是前面说的长连接模式。设为这个值后OpenClaw 会主动连上飞书的长连接服务不需要你部署公网回调。replyMode: api回复方式。用飞书消息 API 精确地把回复发到对应会话而不是简单粗暴地往群里发。allowedChatIds白名单。只允许列出的群或会话触发机器人。这个字段务必配置否则任何能把你的应用拉进去的群都能驱使你的 Agent。这里插一句OpenClaw 这类框架配置字段更新很快如果你查文档发现字段名不一样不要慌重点是找到应用凭证、事件模式、回复模式、白名单这四个语义对应的配置位。5.3 对接 OllamaLLM 参数配置与宿主机地址问题模型这块的配置在配置文件的 LLM 段落里。核心思路就是把 Ollama 的 OpenAI 兼容接口伪装成一个 OpenAI 服务。配置示意如下llm: provider: openai baseUrl: http://host.docker.internal:11434/v1 apiKey: ollama model: qwen2.5:14b temperature: 0.3如果你直接用环境变量等价的是这三项OPENAI_BASE_URLhttp://host.docker.internal:11434/v1、OPENAI_MODELqwen2.5:14b、OPENAI_API_KEYollama。注意host.docker.internal这个地址。当 OpenClaw 跑在 Docker 容器里、Ollama 跑在宿主机上时容器内访问宿主机要用这个特殊域名。Linux 上 Docker 默认不一定支持host.docker.internal需要在启动容器时加参数--add-hosthost.docker.internal:host-gateway。如果你直接让 OpenClaw 跑在宿主机上那baseUrl直接写http://localhost:11434/v1就行。temperature我建议调低比如 0.3。原因后面故障章节会讲Agent 场景里模型太自由会导致工具调用逻辑发散。5.4 首次联调在群里发出第一句对话配置都填好之后启动 OpenClaw 主进程然后在飞书测试群里 你的机器人发一句你好介绍一下你自己。这时候盯紧 OpenClaw 的日志按三层去确认第一层事件是否进来。日志里应该能看到飞书消息事件被接收的记录。没有的话问题在飞书侧应用没发布、权限没生效、长连接没建立。第二层Agent 是否真的调了模型。日志里应该有 LLM 请求的痕迹包括模型名和耗时。第三层回复是否通过飞书 API 发出。如果事件进来了、模型也响应了但群里没看到回复重点检查appSecret是否配错、发送权限是否到位。我第一次联调就出现了日志显示回复发送成功但群里没消息的怪象最后发现是应用版本没重新发布线上应用的权限还是旧的。这类问题太容易出现了所以我把联调顺序固定成先查事件、再查模型、最后查发送。6. 实测中的典型故障与排查路径6.1 排错方法论给故障分层接飞书机器人这件事链路长任何一层出问题表现都很相似群里没反应。所以我的排查方法论永远是分层的飞书事件层 - OpenClaw Agent 层 - Ollama 模型层 - 飞书消息发送层。每一层都有对应的日志先判断卡在哪一层再深入那一层。很多人在群里发现问题后第一反应是去翻模型配置结果折腾半天发现是事件订阅没通。按层排查能省大量时间。6.2 高频故障对照速查表故障现象可能原因处理方向群里 机器人完全没反应事件订阅没通 / 应用版本未发布eventMode检查长连接确认发版状态事件日志里有消息但回复极慢本地模型推理慢 / 模型过大换小模型加 GPU或降量化等级报权限不足错误缺少发送消息的权限去开放平台补权限并重新发版消息内容是密文开放平台开了加密OpenClaw 侧没配密钥配置 Encrypt Key 或关闭加密Docker 内连不上 Ollama监听地址不对 / 容器和宿主机网络不通设OLLAMA_HOST0.0.0.0加host.docker.internal映射同一条消息被处理很多次事件重试机制 / 超时重复推送检查是否有幂等控制逻辑6.3 我踩得最狠的三个坑第一个坑是事件订阅的加密配置不一致。我当时在飞书开放平台把Encrypt Key开了但 OpenClaw 侧没填对应的密钥结果事件虽然推进来了内容却是密文Agent 完全读不懂。这个问题的排查路径是看到日志中有事件记录但内容是乱码立刻想到加密没有对齐。解决方案是两边配置统一要么都开、要么都关。第二个坑是工具调用死循环。某次模型反复调用同一个查询工具一直不进入生成最终回复的环节导致群里迟迟收不到结果。根因有两个方面这个具体任务的工具参数设计得太模糊模型不知道什么时候该停以及temperature调得偏高模型在工具调用叙事里发散了。后来我把工具描述写得更明确并把temperature降到 0.3问题基本消失。第三个坑是长连接断线。飞书长连接模式偶尔会断如果不自动重连机器人就静默失联了。新版 OpenClaw 对断线重连做了处理但如果你用的版本偏旧建议写一个简单的守护脚本定时检查连接状态断了就重启进程。别问我怎么知道的都是凌晨被同事机器人怎么又死了的消息炸醒换来的经验。7. 上线前的安全收尾与这个系列后续还能玩什么7.1 安全收尾清单别让 Agent 裸奔接入跑通之后第一件事不是庆祝而是收紧权限。这里我列一份自己的上线前检查单第一allowedChatIds白名单必须配只允许你信任的群或会话与 Agent 交互第二appSecret绝对不要出现在代码仓库和日志里用环境变量或密钥管理工具注入第三审视 OpenClaw 的工具权限如果只是做问答和文本处理就别给它裸 shell 权限或者至少限制工作目录第四如果遇到任务积压给 Agent 设置单轮任务超时避免一个死循环任务占住推理资源。还有一个很容易忽略的点飞书的事件机制有重试。如果 Agent 处理时间太长飞书侧会认为超时并重推事件可能导致同一任务被重复执行。上线前应对这类重复做幂等保护比如记录已处理消息的消息 ID重复事件直接丢弃。7.2 从能聊到能用下一步扩展方向链路跑通只是起点。飞书消息类型丰富你可以让 Agent 解析富文本、卡片消息、图片和语音可以给它加定时任务每天早上自动汇总日报推送到群里可以用 Playbook 技能脚本把高频工作流固化成可复用的技能比如查排班生成周报整理会议纪要还可以做多模型路由简单闲聊走本地小模型复杂任务切更大模型。这个系列后续我会重点写两件事一是 Playbook 技能脚本的落地经验包括脚本怎么写、Agent 如何自主决定调用二是多模型路由和飞书消息卡片的高级玩法。这篇先到这里把基础链路和排错经验交代清楚是你自己动手折腾的地基。最后分享一点我的个人体会整套系统跑通并不难难的是让身边的人愿意用。我一开始图省事用 7B 模型回复慢不说还经常理解偏同事试了两次就放弃了。后来换了 14B 模型并加了 GPU回复速度上来工具调用也稳定了群里才真正有人每天都用。所以我的建议是第一版先用小模型把链路跑通验收之后再根据实际使用情况换大模型。别一上来就追求最强模型稳定可用比什么都重要。