最近帮一个做SaaS的团队把OpenClaw部署到了他们的Ubuntu云服务器上顺手把飞书机器人也接上了。这事听起来简单实际做起来环节不少云服务器初始化、Docker runtime、OpenClaw配置、飞书开放平台应用创建、channel对接、消息联调每一步都有各自的坑。前后折腾了两天我把完整的部署过程和排查经验写成这篇东西给准备在Ubuntu云服务器上跑OpenClaw、并且打算接飞书机器人当团队助手的同学做个参考。这篇内容适合有一定Linux基础、用过Docker、但对OpenClaw和飞书开放平台不大熟悉的人如果你是从零开始照着每一步来做也能把服务跑起来。1. 部署前先把架构和需求理清楚1.1 OpenClaw到底是个什么东西直接用大白话说OpenClaw是一个开源的AI Agent运行时框架。它做的事情可以理解成“消息渠道的中枢”你可以把飞书群、微信、Discord这些IM渠道接到同一个Agent上用户在各个群里发消息OpenClaw收到之后调用大模型进行处理再把结果回复到对应的会话里。它还能挂工具、定时任务、工作流这些能力不过这次部署我们主要用它的IM接入和Agent对话部分。选OpenClaw而不是自己从零写机器人最大的原因是省事。飞书机器人看着简单真正要自己处理消息回调、会话状态、消息分段、重试机制、多轮上下文工作量不小。OpenClaw把这些做了抽象配置层面只需要指定channel类型和对应的凭证剩下的事框架内部消化。另一个好处是它支持多种大模型后端不同团队用的模型不一样今天用千问明天想换DeepSeek改配置就能切换不需要改代码。1.2 为什么选Ubuntu云服务器而不是本机跑这个选择其实经历过纠结。最初考虑过直接在团队成员的本机跑Docker省一台服务器钱但很快放弃了。本机跑有几个现实问题一是机器关机或休眠服务就断了飞书机器人变成“时灵时不灵”状态体验很差二是IP不固定飞书如果配的是Webhook回调一旦家里网络变化就可能收不到事件三是日志、数据散落在个人电脑上后面想迁移或者多人协作很麻烦。Ubuntu云服务器这边一台2核4G的小规格实例就能跑得很稳。Ubuntu 22.04 LTS系统在服务器领域用得最多软件源、Docker兼容性、各种运维脚本的适配都最成熟文档和遇到问题时能找到的参考也最多。另外一个很重要的点是云服务器可以设置开机自启、进程守护配合Docker的restart策略基本上做到“配置一次长期跑”。1.3 整体信息流与组件关系整个系统拆开看其实就四个角色用户、飞书、OpenClaw、大模型。用户在飞书群里机器人发消息飞书通过长连接或者Webhook把消息事件推给OpenClawOpenClaw带着上下文请求大模型接口拿到生成结果后进行格式化处理再由飞书channel调API把消息发回会话。OpenClaw在这条链路里相当于一个调度中枢它自己不产生内容但负责“把对的消息送到对的地方”。理解这条信息流很重要后面排查问题全靠它。比如“用户在飞书发了消息但机器人没反应”问题可能出在飞书事件订阅配置、OpenClaw的channel鉴权、大模型接口调用失败这三个环节中任意一个。有了这条链路图排查时就能按顺序一步步验证而不是瞎猜。2. 前置环境准备与飞书应用配置2.1 云服务器初始化我这次用的是腾讯云和阿里云都测试过的通用流程选Ubuntu 22.04 LTS镜像。创建实例时有个容易被忽略的点数据盘。OpenClaw运行会产生会话数据、日志、配置如果全放到系统盘后续系统盘满了会很被动。我一般建议系统盘40G起步单独挂一块20G数据盘挂载到 /opt 或者直接作为OpenClaw的数据目录。服务器创建完成后第一件事是更新系统包并装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git ufw接着配置防火墙。OpenClaw的管理控制台默认监听一个本地端口常见是18693具体看版本这个端口建议限制来源IP不要直接对全公网放行。如果公司出口IP固定就在安全组里只放行这个IPsudo ufw allow 22/tcp sudo ufw allow 18693/tcp from 你的公司出口IP sudo ufw enable提示生产环境千万不要把OpenClaw控制台的端口暴露到0.0.0.0并且不加认证否则别人扫到端口就能访问你的管理界面轻则被改配置重则泄露对话记录。然后创建运行用户和数据目录。不建议直接用root跑容器虽然方便但权限范围太宽后面万一容器被攻破影响面会很大sudo useradd -r -m -s /bin/bash openclaw sudo mkdir -p /opt/openclaw sudo chown -R openclaw:openclaw /opt/openclaw2.2 安装Docker运行时建议装Docker Engine而不是桌面版Docker Desktop因为服务器上没有图形界面Docker Desktop没有意义还占资源。官方安装脚本一行搞定curl -fsSL https://get.docker.com | sudo sh sudo systemctl enable --now docker装完后把openclaw用户加进docker组这样后面操作容器不用每次sudosudo usermod -aG docker openclaw如果你的服务器在国内拉取官方镜像可能比较慢可以给Docker配置镜像加速。编辑 /etc/docker/daemon.json把 registry-mirrors 配置成可用的镜像源改完重启Docker。这一步属于常规优化如果你的网络本身没问题可以跳过。2.3 在飞书开放平台创建机器人应用飞书这边流程比较繁琐但也最不能出错。先访问飞书开放平台创建一个企业自建应用应用名称比如“团队助手”。创建后进入应用配置页面需要做四件事第一在“添加应用能力”里找到“机器人”开启机器人能力。开启后应用会获得一个机器人之后在飞书里搜索应用名就能找到它。第二配置权限。在权限管理里搜索下面这些权限并开通im:message读取消息im:message.p2p_msg:readonly接收单聊消息im:message.group_msg接收群消息im:chat获取群信息im:message:send_as_bot以机器人身份发消息这些权限是OpenClaw这类机器人跑起来的最低要求。权限多了其实无所谓但少了肯定不行缺一个就可能导致某个消息场景收不到或者发不出。第三配置事件订阅。这里强烈建议选“长连接模式”也就是WebSocket方式而不是Webhook。Webhook需要公网可访问的回调地址还要配置URL验证调试起来麻烦长连接只要服务器能主动连上飞书就行不需要暴露额外端口。选长连接后把需要订阅的事件勾上至少勾选 im.message.receive_v1接收消息事件。第四在“凭证与基础信息”里拿到App ID和App Secret在“事件订阅”里拿到Verification Token。这三个值是后面OpenClaw配置飞书channel时必须要用的。注意App Secret要当成密码对待不要提交到Git仓库也不要贴在飞书群里。建议写进OpenClaw的环境变量或者config文件里文件权限设为600。飞书这边配完之后还要“创建版本并发布”等管理员审核通过。这个步骤经常有人漏掉结果配置全是对的但机器人死活不工作原因就是应用没有发布到企业。3. OpenClaw部署与飞书channel接入实操3.1 获取镜像并启动容器OpenClaw的部署形式有好几种官方文档推荐Docker Compose方式因为它可以一次性把核心服务和依赖启动好。如果只是简单跑一个实例单容器也够用。我这次是先用单容器跑通后面再补systemd守护。先写一个docker-compose.yml文件version: 3 services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - 18693:18693 volumes: - /opt/openclaw:/data environment: - TZAsia/Shanghai启动cd /opt/openclaw docker compose up -d启动后OpenClaw会在 /data 目录下生成默认配置文件和初始数据。如果希望在启动前就把配置写好也可以先手动创建配置目录把config.yaml放进去再启动容器。实操心得使用固定版本标签而不是latest。我见过几次latest更新后配置格式不兼容导致服务起不来而且每次image pull的镜像内容可能不一样出问题后很难复现。固定到具体版本号比如openclaw/openclaw:0.6.x生产环境更稳。3.2 大模型接入配置OpenClaw本身不带模型它需要对接一个大模型API。模型选择会直接决定回复质量和成本我这次先接的是通义千问主要是内网环境访问稳定。config.yaml里LLM部分大概长这样llm: provider: openai-compatible base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key: sk-你的密钥 model: qwen-plus如果你用的是DeepSeek把base_url和model换成对应的就可以。OpenClaw支持多种provider的原因是它用了统一的OpenAI兼容协议很多国内模型服务商都提供这个协议这样不同模型之间切换的成本就很低。提示不要把API Key硬编码在config.yaml里提交到仓库。可以用环境变量注入比如在docker-compose.yml里写 ${DASHSCOPE_API_KEY}然后在宿主机上用env文件管理。3.3 飞书channel的核心配置项飞书channel的配置是这次部署的重头戏。在config.yaml的channels部分新增feishu配置channels: feishu: app_id: cli_xxxxxxxx app_secret: 你的AppSecret verification_token: 你的VerificationToken lark_host: https://open.feishu.cn receive_id_type: chat_id有几个字段需要解释。lark_host默认就是这个地址一般不用改。receive_id_type这个字段决定消息发到群里还是单聊里用什么ID类型大多数场景保持chat_id即可。app_id和app_secret就是前面从飞书开放平台拿到的值。配置完成后重启容器让配置生效docker compose restart openclaw查看启动日志看飞书channel是否初始化成功docker logs -f openclaw日志里如果出现类似“feishu channel connected”的信息说明长连接建立成功。如果一直在报鉴权失败优先检查App Secret是否复制完整、有没有多余空格、应用是否已发布。3.4 消息联通性验证配置完成不等于能用一定要做完整链路验证。我的验证步骤很固定五步走第一在飞书里搜索应用名找到机器人先给机器人发一条单聊消息“你好”。如果能在日志里看到收到事件说明事件接收链路是通的。第二等OpenClaw回复。正常情况几秒到十几秒会有回复具体取决于大模型响应速度。如果日志显示调用了LLM没有报错但飞书没有消息大概率是发送消息权限或者receive_id_type配置问题。第三把机器人拉进一个测试群在群里机器人发消息验证群聊场景。这一步容易踩坑机器人拉进群之后群里消息事件不一定默认推送需要在飞书后台事件订阅里确认是否勾选了群消息相关事件。第四测试连续对话。连续发几条消息确认上下文是否连贯。OpenClaw会根据会话保存上下文如果每次回复都是“失忆”状态检查会话文件目录是否有写入权限。第五测试异常输入比如发一段很长的文字让它总结或者问一个它不该回答的问题。这一步主要是看崩溃恢复能力以及长文本处理效果。4. 运行期坑点与排查实录4.1 session file locked并发锁冲突这个报错是我这次部署遇到最头疼的问题。日志里反复出现agent failed before reply: session file locked (timeout 60000ms)意思是有个会话文件被锁住了60秒内没拿到锁OpenClaw放弃了这次回复。出现这个问题的原因通常是同一份数据目录被多个OpenClaw进程同时使用常见于两个场景一是docker compose restart时旧容器还没完全退出新容器就启动二是在宿主机上同时手动跑了另一个OpenClaw实例两边用同一个 /data 目录。解决办法是先确认进程数量docker ps | grep openclaw ps aux | grep openclaw | grep -v grep确保只有一个OpenClaw实例在跑。如果确认只有一个实例但仍然出现锁报错可能是上次异常退出留下了残留锁文件。找到会话目录下的.lock文件在确认没有进程占用后删掉然后重启服务。实操心得这个锁机制本身是为了防止同一个会话被并发写坏设计上没问题但排查时要先怀疑“是不是有第二个进程”再怀疑“残留锁文件”。直接删锁文件前一定要确认没有活跃进程否则可能造成会话数据损坏。4.2 飞书长回复被截断OpenClaw在飞书里输出长内容时容易被截断这个现象在群里特别明显。原因是飞书对单条消息长度有限制超长的回复会被截断或者发送失败。我在群里问技术方案OpenClaw一口气输出一大段Markdown结果开头还在“整体架构”结尾突然变成“内容被截断”。解决思路有两个方向。一个是让模型控制输出长度在OpenClaw的prompt里加一句“回答尽量精简单次回复不超过500字”简单粗暴但有效。另一个是配置消息分段发送OpenClaw如果支持把长回复按段拆分发送到会话里体验会好很多但要确认你用的版本是否支持。提示如果团队经常需要OpenClaw输出长文档与其让它直接发到飞书不如让它生成一个链接或者把内容写到知识库/文档里再发个链接这样既解决截断问题也方便沉淀。4.3 机器人能发消息但收不到用户消息这个问题的现象是OpenClaw主动发消息比如定时任务能正常发送但用户在飞书里给机器人发消息机器人完全没反应。日志里也看不到收到事件的记录。这种情况十有八九是事件订阅没配好。检查三处一是飞书后台事件订阅里是否勾选了 im.message.receive_v1二是长连接是否成功建立日志里应该有connected相关输出三是应用是否已经发布版本并审核通过。还有一个小坑如果团队成员同时用飞书的国内版和海外版事件推送的域名不同配置文件里lark_host如果默认指向国内飞书海外版的事件就到不了。这种情况需要根据实际使用的飞书版本调整lark_host。4.4 日志、重启与日常维护OpenClaw跑起来之后日常维护主要围绕日志和数据备份。日志查看是排查问题的第一手段docker logs -f openclaw日志量大的时候建议加上时间过滤或者用docker logs的--since参数查看最近一段时间的日志。Docker默认的json-file日志驱动会无限增长建议在daemon.json里配置日志轮转{ log-driver: json-file, log-opts: { max-size: 20m, max-file: 3 } }数据备份方面OpenClaw的配置、会话数据都在/opt/openclaw下定期打包备份这个目录即可tar czf openclaw-backup-$(date %Y%m%d).tar.gz /opt/openclaw恢复时先停掉容器解压覆盖数据目录再启动容器so easy。如果配合云服务器的快照功能定期做整机快照抗风险能力还会更强。关于自动重启docker compose文件里已经有了restart: unless-stopped这意味着宿主机重启后容器会自动拉起来。但有个细节如果容器内部因为某种原因不断崩溃Docker的restart策略会不断尝试重启这种场景下要看日志而不是一昧重启否则会陷入“起不来-重启-又挂”的循环里。最后再分享几个我跑这套环境的心得。第一飞书后台的权限和事件订阅配置是整个接入过程最容易出错的地方出问题先回到飞书后台检查这三项应用有没有发布、权限有没有开通、事件订阅有没有勾对。第二OpenClaw的日志就是最好的老师遇到任何诡异问题第一步都是开日志用时间线把事件推进和日志输出对起来比东猜西猜高效得多。第三不要把生产环境的配置改得太花哨能简则简一个干净的config文件、一个固定的镜像版本、一个完整的数据备份这三样东西能让这套系统稳定跑很久。我这个实例上线到现在已经连续运行了两周中间只因为云服务器升级重启过一次Docker自动拉起来后一切照旧。如果你也在折腾OpenClaw和飞书机器人遇到问题欢迎留言交流我看到都会回复。