上个月我在 Ubuntu 服务器上折腾完一件事把开源 Agent 框架 OpenClaw 跑起来推理后端接到本地 Ollama再通过飞书机器人跟它对话。目的很简单——团队已经习惯用飞书协作我不希望每次想问点事情还要切到终端敲命令行更不想把内部资料交给云服务商。折腾完回头看整条链路的难度其实不高但涉及环境、模型、通道三块每一块都有几个容易忽略的坑。这篇文章就把我的完整部署过程、配置参数和踩坑记录整理出来给同样想在 Ubuntu 本地部署 OpenClaw、接入 Ollama 和飞书的人一份可以直接照着做的参考。1. 这套组合解决什么问题OpenClaw、Ollama 与飞书的各自角色1.1 OpenClaw 到底是个什么东西OpenClaw 是一个开源的 Agent 运行时框架核心思路是模型无关 通道插件化。模型无关意味着它不绑定某一家推理服务既可以接云端 Claude API也可以接本地部署的 Ollama、vLLM 这类推理服务通道插件化意味着它和人对话的入口可以灵活配置飞书、Teams、终端、Web 控制台都可以作为交互渠道。我当时选择它的理由主要是两点第一配置是文件化的整个 Agent 的行为、模型、通道都能用配置文件管理方便版本控制第二它本身提供了会话管理、工具调用、上下文维护这些 Agent 基础设施不需要我从零写一套状态机。如果你之前在纠结 OpenClaw 和 WorkBuddy 这类产品怎么选我的观点是如果你要的是可控部署、自定义通道、接本地模型OpenClaw 这类开源运行时更合适如果你要的是开箱即用、图形化管理那商业产品体验会好很多。1.2 为什么推理后端要选 OllamaOllama 是目前本地部署大模型最省事的引擎之一一条ollama pull就能把模型权重拉下来ollama serve就把推理服务跑起来了。它帮我解决了几个实际问题模型文件放在本地磁盘对话数据不出服务器适合处理内部文档、敏感数据推理成本按电费和硬件折旧算长期跑比按 token 付费便宜第三Ollama 自带 OpenAI 兼容的 API 接口OpenClaw 接它只需要配一个 base_url不需要写专门的适配层。当然本地推理也有代价模型能力上限取决于服务器显存和内存。我的实践是16GB 显存的卡可以稳定跑 14B 量级的量化模型日常问答、文档总结够用如果只有 CPU建议选 7B/8B 或者更小的量化版本并接受响应速度下降的现实。1.3 飞书通道的价值和外挂方式飞书作为通道本质上解决的是人如何方便地跟 Agent 对话的问题。终端里跑 Agent 适合开发者但团队里的人不可能都配好命令行环境。飞书机器人接入后私聊、群聊里 一下就能触发 Agent对话记录也顺带留在飞书里团队协作链路是完整的。接入方式上飞书开放平台提供机器人能力和事件订阅机制。OpenClaw 通过飞书 API 接收消息、调用会话逻辑再把结果通过机器人身份发回聊天窗口。消息的接收方式有两种一种是用 HTTPS 回调地址需要公网可达另一种是飞书支持的长连接模式OpenClaw 主动建立一个 WebSocket 连接去收事件这样本地服务器也能用不需要额外申请公网域名。2. Ubuntu 环境准备系统版本、运行时安装与最容易翻车的三个细节2.1 系统版本和基础软件我这次部署用的是 Ubuntu 22.04 LTS内核和软件源都比较成熟。如果你还在用 20.04问题也不大但要注意 OpenClaw 如果是最新版本可能依赖较新的 glibc 和 Node 运行时越老的系统越容易出现装不上、启动报错这类问题。建议直接用 22.04 或 24.04 LTS省去后续折腾。开始之前先确认下面几项依赖项版本要求检查命令Ubuntu 系统22.04 LTS 或更新lsb_release -aNode.js18.x 或以上node -vPython3.10 或以上python3 --versionGit任意较新版本git --version磁盘空间建议剩余 30GB 以上df -h如果系统里没有 Node.js我推荐用 nvm 安装避免直接改系统级目录后面升级也方便curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 18 nvm use 18这里有个实际经验安装完 nvm 之后一定要source ~/.bashrc或者重新打开终端否则node命令找不到。第一次踩这个坑时我还以为是安装没成功实际上只是环境变量没刷新。2.2 磁盘规划模型比你想象中更占空间Ollama 拉下来的模型动辄 4GB 到 10GB如果同时跑好几个模型磁盘占用会轻松超过 50GB。很多人的服务器根分区只分了 30GB装完系统和依赖就剩不到一半再拉模型必然爆盘。我的做法是单独给模型数据挂一块数据盘然后把 Ollama 的模型目录指到数据盘上。具体操作是修改 Ollama 服务的环境变量编辑服务文件或 override 配置sudo systemctl edit ollama在打开的编辑器中填入[Service] EnvironmentOLLAMA_MODELS/data/ollama/models保存后重载服务sudo systemctl daemon-reload sudo systemctl restart ollama这样模型文件全部落到独立数据盘系统盘只需要装软件本身压力小很多。这个细节在官方文档里不算醒目但实际部署中非常关键。2.3 安装 OpenClaw 的两种途径OpenClaw 的安装方式我当时看到的是源码安装和预编译包两种主流方案。源码安装的好处是跟随最新代码能第一时间体验到新功能预编译包的好处是稳定不需要本地编译工具链。如果你走源码安装先把代码 clone 下来git clone https://github.com/openclaw/openclaw.git cd openclaw npm install npm run build然后把命令行入口放到全局路径或者干脆做成一个 systemd 服务。注意源码安装过程对网络依赖比较大npm install如果中途失败可以多试几次大部分情况是网络抖动导致的。预编译包方式更简单把压缩包解压后将可执行文件软链到/usr/local/bin/openclaw即可。安装完成后务必跑一下openclaw version确认命令可以用同时也能快速发现 glibc 版本兼容问题。2.4 环境变量和 PATH 的坑Ubuntu 环境变量配置错误导致的命令找不到问题我见得太多了。如果你把 OpenClaw 装在自定义目录记得把它的路径加进~/.bashrcexport PATH$HOME/openclaw/bin:$PATH export OPENCLAW_HOME$HOME/.openclawOPENCLAW_HOME这个变量可以控制 OpenClaw 的配置和数据目录默认位置。默认情况下它会把数据放在用户家目录下如果你用 root 用户跑就放在/root/.openclaw用普通用户跑就在/home/xxx/.openclaw。我建议显式指定这样多用户共用一台服务器时不会出现数据目录混乱的问题。配置完之后执行source ~/.bashrc再打开一个终端窗口验证。不要在一个终端里反复 source这样容易掩盖环境变量没有写入配置文件的问题。3. Ollama 推理链路安装服务、拉取模型、验证接口、接入 OpenClaw3.1 安装 Ollama 并确认服务状态Ollama 的安装本身就一条命令curl -fsSL https://ollama.com/install.sh | sh安装完成后服务会以 systemd 方式托管手动启动和管理可以用sudo systemctl start ollama sudo systemctl enable ollama sudo systemctl status ollamaOllama 默认监听本机的 11434 端口如果你之后有远程调用需求可以设置OLLAMA_HOST0.0.0.0:11434但要先想好访问控制策略。我这边因为 OpenClaw 和 Ollama 都在同一台机器上保持 127.0.0.1 监听就足够了减少了暴露风险。3.2 模型选择和拉取模型选择是整个链路里最影响体验的一环。我的经验是先想清楚用途再选模型而不是一上来就拉最大的参数版本。做代码辅助、结构化输出7B/8B 模型就能应付做长文总结、深度分析、多轮对话14B 或更大的模型明显更稳。参数越大显存占用和响应延迟都在涨飞书聊天的体验和终端里完全不同——超过 10 秒没响应人就会开始怀疑机器人是不是挂了。我当时先拉了一个 qwen2.5 的 7B 版本验证链路ollama pull qwen2.5:7b模型拉到本地后查看当前有哪些模型ollama list拉取过程中如果网速不稳定Ollama 本身支持断点续传进度中断后重新执行ollama pull会继续下载。这一步在本地化部署场景里很实用不用因为一次网络中断就重新开始。3.3 手动验证推理接口在把模型接入 OpenClaw 之前最好先手动验证一次推理接口避免后面报错时分不清是模型问题还是 Agent 的问题。我一般用 curl 直接请求 Ollama 的 APIcurl http://127.0.0.1:11434/api/chat \ -d {model: qwen2.5:7b, messages: [{role: user, content: 用一句话介绍你自己}], stream: false}顺利的话返回 JSON 里会出现response字段和模型生成的文本。这一步通过后再去配置 OpenClaw就能确认推理链路是通的。如果 curl 卡住很久不响应去看/var/log/ollama.log或者journalctl -u ollama -f常见的坑是显存不足导致 OOM或者模型还在首次加载中。3.4 OpenClaw 侧配置模型 providerOpenClaw 的模型配置我是放在~/.openclaw/config.yaml里的核心思路是把 provider 指到 Ollama 的地址。配置内容大致是这样具体字段名以你下载版本的文档为准agent: default_model: qwen2.5:7b model_provider: type: ollama base_url: http://127.0.0.1:11434 context_window: 8192 temperature: 0.7context_window这个参数值得多说一句。Ollama 默认的上下文长度由模型决定但 OpenClaw 在组织对话、调用工具、注入系统提示词时会把整个请求拼到一起如果上下文窗口设得太小长对话会报 token 超限。如果你发现聊着聊着突然不响应了先查是不是上下文窗口不够不要急着怀疑模型本身。还有一点OpenClaw 会在每次请求时带上系统提示词和工具定义这部分的 token 也要算进上下文里。所以配置窗口时给模型默认能力留出余量比如模型本身支持 32K但 OpenClaw 里设 24K 或 16K稳定性和首响应速度都会更好。4. 飞书通道打通从开放平台创建应用到长连接接收事件4.1 创建飞书应用并开启机器人能力飞书这边的准备工作需要在飞书开放平台后台完成。登录后进入开发者后台创建一个企业自建应用名字随便起比如本地助手。创建完应用后在应用能力里添加机器人能力这一步会让这个应用获得一个机器人身份之后所有消息都以这个机器人名义收发。创建应用这一步本身不难但很关键的是下一步的权限配置。飞书的权限模型是细粒度的机器人要能收消息、发消息必须显式申请对应权限点。我当时申请的是im:message—— 读取用户发给机器人的消息im:message:send_as_bot—— 以机器人身份发送消息权限申请后需要发布应用版本管理员审核通过后权限才生效。如果你是在自己的团队内部用审核一般很快。这里有个容易漏的点权限版本发布之后应用要重新上线否则测试时一直提示无权限。4.2 获取密钥和配置参数在开放平台后台的凭证与基础信息页面可以拿到两个关键参数App ID 和 App Secret。这两个参数就是 OpenClaw 连飞书时要用的身份凭证。把它们复制下来后续配置里会用到。注意 App Secret 类似密码别直接提交到公开仓库建议用环境变量或配置文件权限控制来管理。另外要确认机器人的名称和头像因为飞书的消息流里会展示这些信息。我当时把机器人名称改成和内部项目一致头像也换成了团队 LOGO这样在群聊里不会和别的 bot 混淆。4.3 事件订阅用长连接模式绕开公网回调飞书接收消息核心在事件订阅。后台有两种模式可选一种是回调地址模式需要提供一个公网可访问的 HTTPS 地址飞书服务器会把事件 POST 到那个地址另一种是长连接模式应用主动建立 WebSocket 连接飞书推送事件过来。我必须得说长连接模式对本地部署来说太友好了。不需要公网 IP不需要配域名证书不用在 Nginx 里写转发规则OpenClaw 启动后往飞书开放平台一连消息就收得到。我当时选的就是这个模式在事件订阅页面选择使用长连接接收事件然后在开放平台后台添加事件im.message.receive_v1—— 接收消息事件添加事件后页面会提示订阅成功。很多教程默认让你准备公网回调你要是和我一样在本地或内网服务器上跑直接选长连接能省下一整个下午的时间。4.4 OpenClaw 里的飞书通道配置回到 OpenClaw飞书通道的配置文件可以这么写字段名以你实际版本为准channels: feishu: app_id: cli_xxxxxxxxxxxx app_secret: xxxxxxxxxxxxxxxxxxxxxxxx event_mode: websocket配置里有几个容易踩的点app_id和app_secret可以通过环境变量注入OpenClaw 通常会支持OPENCLAW_FEISHU_APP_ID这种形式的环境变量比直接写死在配置文件里更安全。事件订阅如果配置的是长连接模式OpenClaw 启动时会自动建立连接不需要额外设置回调路由。如果飞书后台配置的是回调模式OpenClaw 这边就要配置回调路径和端口还要保证网络可达。这属于另一种部署方式复杂度明显高于长连接。配置完成后重启 OpenClaw日志里如果出现feishu channel connected之类的信息基本就是连上了。然后你在飞书里私聊机器人发一句你好机器人应该会在几秒内回你。5. 实测中的典型报错agent failed before reply: session file locked 的完整排查链路5.1 报错现场链路全部打通后的第二天群里有人反馈机器人有时候不回消息OpenClaw 的日志里出现一行刺眼的报错agent failed before reply: session file locked (timeout 60000ms)这个报错表面意思是会话文件被锁住了等了 60 秒还没拿到锁Agent 直接在响应前就失败了。当时我的第一反应是锁冲突但到底是谁在持锁、为什么持有这么久需要一层层往下查。5.2 理解 session 和锁的机制OpenClaw 的会话管理实际操作中会为每个会话维护一个本地状态文件里面保存对话历史、上下文状态、任务进度。为了保证同一个会话不会被多个进程同时写坏它会用文件锁来控制访问——这个机制本身是合理的问题在于锁的粒度和持锁时间。timeout 60000ms说明 OpenClaw 给拿锁设置了一个 60 秒的上限。如果上一个请求持有锁超过 60 秒没释放后面所有针对同一会话的请求都会直接失败。也就是说报错不一定是因为锁代码有 bug很可能是持锁的那一侧跑得太慢或卡死了。5.3 逐步排查进程、锁文件、推理耗时我先看了进程状态ps -ef | grep openclaw确认只有一个 OpenClaw 主进程在跑排除多进程冲突的问题。然后又用lsof查了会话目录下的锁文件被谁占用lsof ~/.openclaw/sessions/结果发现持锁进程确实是 OpenClaw 自己说明是同一个进程在处理并发请求时前一个任务还没结束后一个任务就来抢同一会话的锁。这时候再翻对应时间段的日志看到前一个请求在等 Ollama 返回而 Ollama 那边模型加载和推理耗时超过了 60 秒于是锁就一直在那个请求手里后续请求全部排队超时。换句话说根因是一跳本地推理太慢锁等待超时设得太短二跳多个请求撞到了同一个会话。5.4 修复方案与验证定位之后我做了三件事第一把 OpenClaw 的锁超时时间调大。不同版本的配置字段不一样我的做法是在配置文件里找到类似session_lock_timeout的字段从 60000 毫秒调到 180000 毫秒。这一步是为了让慢推理也能在锁等待窗口内完成。第二给 Ollama 侧减压。确认推理慢是因为模型被频繁冷启动于是把 Ollama 的 keep_alive 参数调长让模型常驻显存避免每次请求都重新加载curl http://127.0.0.1:11434/api/generate \ -d {model: qwen2.5:7b, keep_alive: 30m}第三也是最重要的在飞书侧和 OpenClaw 侧尽量避免同会话并发。飞书群聊里如果多人同时 机器人OpenClaw 可能会把多个消息路由到同一个会话自然触发锁竞争。我的方案是在群聊配置里让不同用户走不同会话或者干脆减少群内高频调用重要操作移到私聊里执行。修改配置后我复测了三种场景连续私聊三条消息、群聊里两个人同时 、以及一个长任务进行中再发一条新消息。前两种都稳定通过了第三种仍有概率出现排队等待但已经不会直接报错失败而是在前一个任务完成后正常处理。这个结果说明锁机制本身没坏是业务场景中并发和耗时的匹配问题。5.5 同类报错举一反三session file locked只是会话文件锁这一类问题的表象。和它同族的还有 session file not found、session directory permission denied、session file is occupied 等等。遇到这类问题我习惯按下面的顺序排查先确认进程是否异常残留ps和lsof能解决大部分持有锁的疑问。再看锁文件的最后修改时间和持有时间如果是几个小时前的残留锁且没有活跃进程可以删除锁文件但要谨慎操作。然后检查推理耗时如果模型加载要 30 秒同时锁超时只有 10 秒调参是必然的。最后回到业务侧是不是入口处允许多个请求打到了同一个会话 ID。这套方法论不仅适用于 OpenClaw任何有会话管理的 Agent 框架都通用。6. 直接复现的完整操作清单与两个值得尝试的扩展6.1 复现操作顺序一览为了方便你照着操作我把整条链路的核心顺序整理成一个清单准备 Ubuntu 22.04 或更新的系统安装 Node.js 18 和 Python 3.10。规划磁盘把 Ollama 模型目录指向数据盘。安装 OpenClaw确认openclaw version正常。安装 Ollamaollama pull拉取目标模型。用 curl 手动验证/api/chat接口。在 OpenClaw 配置文件中接入 Ollama 作为 model provider。在飞书开放平台创建应用开启机器人能力申请权限。配置事件订阅选择长连接模式添加消息接收事件。在 OpenClaw 配置飞书通道的 app_id、app_secret。启动 OpenClaw在飞书里私聊机器人验证全链路。这个顺序是我多次部署后觉得最顺的一条路径每一步都验证通过再进下一步出问题时定位范围会小很多。6.2 扩展方向飞书多维表格回写和多模型路由链路跑通之后你可以继续往两个方向扩展。第一个是飞书多维表格回写。OpenClaw 这类 Agent 框架通常支持工具调用你可以把多维表格的 API 封装成一个工具让 Agent 把总结、归档、任务跟踪结果直接写入飞书多维表格。比如我后来做了一个简单的日志归档功能Agent 每完成一次长任务就会在表格里新增一条记录包含任务内容、耗时、结果摘要和触发人。这个功能团队反馈非常好用等于 Agent 从能聊升级到了能干活。第二个值得尝试的是多模型路由。Ollama 可以同时管理多个模型不同任务分给不同模型的策略在 Agent 场景下很实用。简单问答走 7B 小模型省资源复杂代码或长文总结走 14B 大模型保质量。OpenClaw 如果支持按规则切换模型就把这个配置做成路由表飞书消息里的关键词可以触发模型切换比如消息里出现总结分析就走大模型。这个思路的收益很大但也会带来一点延迟增加适合对响应速度要求不极致、但对质量有要求的场景。6.3 一点更现实的优化建议最后说一个我在实际使用中的体会这套部署完成后最影响体验的不是模型能力而是模型常驻和并发控制。Ollama 的 keep_alive 一定要调否则每隔一段时间没人对话模型就被释放下一个人触发请求时又要等几十秒加载。OpenClaw 侧的并发限制和锁超时也要提前规划好宁可排队也别直接失败飞书用户是不会去看你日志的他们只会觉得这个机器人又坏了。如果你打算长期跑建议把 OpenClaw 和 Ollama 都注册成 systemd 服务设置开机自启和崩溃自动重启。日志用journalctl -u openclaw -u ollama -f统一查看排查问题时能少走很多弯路。整个项目做到这个程度就已经具备了在团队内稳定使用的基础。剩下的优化空间就看你想让它聊得更聪明还是干更多的活了。