在腾讯云服务器上跑一个 OpenClaw然后让它直接挂在飞书上收发消息这个组合我前前后后折腾了整整两天。第一天全在踩飞书回调地址的坑第二天才算真正把流程跑通。现在回过头看整个部署链路其实并不复杂但涉及的东西不少云服务器的端口与安全组、容器服务的配置与日志、飞书开放平台的应用权限与事件订阅任何一环没对齐消息就会静悄悄地在某个环节断掉。这篇文章就把这条链路完整拆开讲一遍从腾讯云服务器的选型与开通到 OpenClaw 的安装配置再到飞书机器人的创建与事件订阅最后落地到系统服务和日志维护。适合手里有一台云服务器、想搞一个私有机器人来收消息、做提醒、执行定时任务的开发者参考。整个过程你跟着做大概需要一个小时其中一半时间花在飞书开放平台的各种权限按钮上。1. 方案设计为什么是腾讯云 OpenClaw 飞书1.1 选型逻辑服务器到底怎么选很多人第一步就问用轻量应用服务器还是云服务器 CVM实话讲部署一个 OpenClaw 这种常驻进程两者都能胜任关键看你的长期规划。轻量应用服务器的优势是门槛低买完就能用控制台把防火墙规则都简化了适合只想快速跑起来的场景。云服务器 CVM 的网络、磁盘、安全组控制更细适合后续要挂数据库、对象存储、更多微服务的部署。对个人项目来说2核4G的轻量应用服务器足够带宽选5M左右就行。OpenClaw 本体非常轻常驻内存占用通常不到200MB真正吃内存的是它要调用的大模型推理进程或者你额外挂载的插件服务。如果打算在服务器上本地跑推理模型那配置直接跳到4核16G别犹豫。系统镜像我推荐 Ubuntu 22.04 LTS主要原因是软件源更新及时遇到问题搜解决方案最容易命中。Debian 12 也可以本质没区别。不建议再选 CentOS上游停止维护之后很多源都不好使装个 Docker 都得折腾半天没必要给自己添堵。地域选择上离你的目标用户近就行。如果飞书机器人主要服务国内团队选广州、上海这些地域的可用区网络延迟差别不大。需要注意的一点是购买时把系统盘的容量选大一点比如80G左右。OpenClaw 的日志和插件数据日积月累磁盘满了再去扩容总归多一步操作。1.2 OpenClaw 能做什么不能做什么OpenClaw 是一个开源的智能助手框架核心思路是消息进动作出。它本身不是一个成品应用更像是一个躯壳接收来自各种渠道的消息解析意图调用插件或外部API完成任务然后把结果返回给用户。插件体系是它的灵魂你可以通过配置文件挂载不同的能力模块比如定时任务、HTTP请求、数据库查询等。我在实际使用中最看重的三点是第一渠道接入层是抽象好的接飞书、接其他IM都是同一套事件模型切换成本低第二插件之间可以通过消息互相触发能做出收到指令后自动查数据再推送这种复合流程第三它支持让大模型API参与意图判断也就是说用户用自然语言发指令就行不用记死命令。但它不是什么都能干。官方不会替你维护私有数据不会替你保证所有插件都兼容更不会负责飞书那边权限审核的进度。把期望摆正它是一个需要你投入配置、调试和持续维护的框架不是一个装完就自动智能的神仙软件。抱着装完就能用的心态来大概率会失望。1.3 飞书为什么选它作为交互入口飞书的开放平台在IM里算是做得比较完整的机器人能力是头等公民事件订阅支持长连接模式权限模型也清晰。更重要的是飞书机器人对内部小团队非常友好不需要走复杂的应用市场审核只要在企业自建应用里搭一个立刻就能用。选择飞书还有一个很实际的原因长连接模式。传统机器人接入IM通常需要一个公网HTTPS回调地址腾讯云给服务器分配的公网IP没有备案域名时配置HTTPS证书是一件很头疼的事情。飞书支持事件通过长连接主动推送给客户端相当于OpenClaw主动连上飞书服务器消息到达后直接通过这个长连接下发。你不需要在服务器上开任何入站端口也不需要域名和证书这对个人开发者来说省了一大半事。1.4 整体架构和数据流向整个链路画成文字大概是这样的用户在飞书App里打开机器人会话发送一条消息。飞书服务器收到后通过长连接把这条事件推送给运行在腾讯云服务器上的 OpenClaw 进程。OpenClaw 收到事件后经过插件匹配或大模型意图判断执行对应任务生成回复内容。最后OpenClaw 调用飞书开放API把回复消息发送到原会话中。可以看到数据流是双向的入站靠长连接推送出站靠API调用。这里有一个容易被忽视的点入站长连接是飞书主动连你出站API和模型调用是你主动连飞书或模型服务整台服务器在出站方向上的网络必须通畅443端口不能被防火墙封死。安全组里如果你把出站规则限制得很死一定要记得放行 HTTPS 出站。2. 环境准备从零开通一台可用的服务器2.1 购买与初始配置进入腾讯云控制台找到轻量应用服务器或CVM的购买入口。地域选离你主要用户近的镜像选 Ubuntu 22.04 LTS套餐选2核4G起步。安全组在购买页按需开放端口建议初始只放行22端口后续需要再加。服务器创建完成后第一件事不是急着装东西而是把系统基础配置弄好。我习惯先在控制台用网页终端登录一次执行这组基础命令apt update apt upgrade -y timedatectl set-timezone Asia/Shanghai timedatectl设置时区这件事特别容易被忽略但必须做。飞书在签发API调用凭证时会校验时间戳如果服务器系统时间和实际时间差得太多请求会直接返回类似invalid signature的错误查起来非常浪费时间。Docker容器默认用的时区也依赖宿主机的 /etc/localtime宿主机时区不对容器里日志时间也跟着歪。2.2 SSH登录与安全组后续操作不建议一直用网页终端效率太低。在本地机器生成SSH密钥并上传到服务器ssh-keygen -t ed25519 -C your_comment ssh-copy-id root你的服务器公网IP然后把SSH登录的密码认证关掉编辑 /etc/ssh/sshd_config确认 PasswordAuthentication no重启 sshd 服务。这一步不是必须的但对于长期运行的服务器来说等于把暴力猜密码这条路堵上了。安全组方面建议只保留22、80、443三个入站端口其他端口一律不对外开放。如果你用长连接模式接入飞书实际上80和443入站都可以不开留着只是为了以后要挂Web服务方便。2.3 安装Docker与ComposeOpenClaw 官方推荐用 Docker 方式部署理由很简单依赖都打包在镜像里升级回滚都干净。在 Ubuntu 上安装Docker最省事的方法是直接用官方源apt install -y docker.io docker-compose-plugin systemctl enable --now docker docker --version docker compose version国内服务器拉取镜像时可能会慢建议配置一下镜像加速地址具体地址在每个云厂商控制台都有提供照文档填到 /etc/docker/daemon.json 的 registry-mirrors 列表里然后重启 docker 服务。镜像加速配置好之后拉取 OpenClaw 镜像的时间能节省一大半尤其是第一次拉取的时候。3. 安装OpenClaw推荐Docker Compose方式3.1 Docker Compose编排我推荐使用 Docker Compose 来管理 OpenClaw而不是直接 docker run。原因很简单配置固化在文件里改动有记录其他人接手也能一眼看懂。以下是一个最简的 docker-compose.ymlservices: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: always environment: - TZAsia/Shanghai - OPENCLAW_APP_ID替换为飞书AppID - OPENCLAW_APP_SECRET替换为飞书AppSecret - OPENCLAW_CHANNELfeishu - OPENCLAW_LOG_LEVELinfo volumes: - ./config:/app/config - ./data:/app/data ports: - 8080:8080这个配置里有几个点要解释。restart: always 是必须的Docker 守护进程启动时会自动把容器拉起来服务器重启后不用手动干预。TZ 环境变量必须和宿主机保持一致否则日志时间会乱。config 和 data 两个目录挂载出来所有配置和数据都在宿主机上容器销毁重建也不会丢。8080 端口是OpenClaw 自带的 Web 管理接口如果你不需要可以把 ports 段整个删掉。3.2 源码方式运行如果你打算二次开发或者想调试插件那用源码方式跑更顺手。先把代码仓库 clone 到服务器安装依赖然后启动git clone https://example.com/openclaw.git cd openclaw cp .env.example .env # 编辑 .env填入飞书配置 ./bin/openclaw start源码方式的好处是断点调试方便改代码实时生效坏处是依赖管理需要自己维护Python 或 Node 的版本升级可能带崩环境。我个人建议先跑通 Docker 方式确认整个链路没问题之后再按需切到源码方式去开发插件。两条路都可以走但从稳定性的角度生产环境优先 Docker。3.3 配置文件核心参数逐项解析不管用哪种部署方式最终都要落到配置上。OpenClaw 的配置主要围绕以下几个维度渠道配置声明当前启用哪个消息渠道本场景是 feishu。渠道切换只需要改这一个参数这是框架抽象做得好的地方。应用凭证App ID 和 App Secret 是飞书识别你应用的凭据相当于账号密码务必通过环境变量注入不要写死在配置文件里并提交到版本库。插件开关插件目录下每个插件对应一个开关按需启用。刚开始跑通链路时建议只保留一个最简单的回显插件减少干扰变量。模型配置如果要用大模型做意图识别把API地址、密钥、模型名填到对应字段。注意模型API密钥同样走环境变量。配置的原则是最小化起步。我见过太多人第一次部署就把一堆插件全开结果日志刷屏根本分不清是哪一步出了问题。先把链路跑通再逐个加插件这是最省时间的路径。4. 飞书适配创建应用与打通消息链路4.1 飞书开放平台创建自建应用进入飞书开放平台登录后选择企业自建应用点击创建。名称写一个你认识的比如内部助手描述随意。创建完成后在应用凭证页面可以看到 App ID 和 App Secret。这里有一个必须养成的习惯App Secret 只在创建时完整显示一次之后随时可以重置但重置会让旧的配置全部失效。所以拿到 Secret 的第一时间就要保存到密码管理器或者环境变量文件里千万别随手截图往聊天工具里发。4.2 开启机器人能力与权限配置在应用的功能区域找到机器人点击启用。然后进入权限管理页面开通这两个核心权限im:message 读取接收消息im:message:send_as_bot 以机器人身份发送消息权限配置有个细节在飞书开放平台某些权限修改后不是立即生效的尤其是涉及消息读取的权限可能需要等一两分钟甚至重新发布应用版本后才生效。如果你改了权限后测试还是报权限不足别急着怀疑代码先去确认版本是否已发布、权限是否已生效。开发阶段如果用的是企业内部自建应用一般直接在测试企业里就能用如果套的是商店应用模板那权限审核流程会比较长建议一开始就选企业自建应用。4.3 事件订阅长连接模式优先进入事件订阅页面接收方式选择使用长连接接收事件。然后在事件列表里添加一个最关键的事件接收消息 im.message.receive_v1。这里我把 Webhook 与长连接再对比一下。Webhook 模式下飞书把事件通过 HTTP POST 推到你的回调地址要求这个地址必须公网可访问且是 HTTPS。这意味着你需要一个域名、一张证书还要处理回调签名验证。长连接模式下是运行在服务器上的 OpenClaw 主动建立一个出站连接飞书服务器往这个连接上推送事件。你的服务器不需要任何入站端口不需要域名也不需要证书。对腾讯云上大部分没有备案域名的个人服务器来说长连接是目前最省事的选择几乎不用额外折腾。4.4 与OpenClaw配置对接把第4.1步拿到的 App ID 和 App Secret填到 docker-compose.yml 的环境变量里然后启动服务docker compose up -d docker compose logs -f openclaw启动日志如果出现类似feishu connection established或长连接已建立的信息说明 OpenClaw 和飞书之间的链路已经通了一半。如果日志里一直在重复重连、报签名错误大概率是 App Secret 填错了或者服务器系统时间和实际时间偏差过大回到第2.1步检查。4.5 消息收发测试在飞书App里找到你创建的应用机器人发送一条消息比如你好。正常情况下的响应链路是飞书推送事件到OpenClawOpenClaw 调用回显插件再通过API回复你好。全程日志中会依次出现收到事件、插件命中、发送回复的记录。如果日志显示事件收到但没有回复大概率是发送消息这一步出了问题。这时候可以用飞书开放API手动测试一下发送能力直接在调试台调用发送消息接口填入你的用户ID和会话ID看能不能发出去。这一步能帮你快速定位问题出在OpenClaw侧还是飞书侧。5. 生产化进程守护、日志与稳定性5.1 systemd管理Docker Compose 模式下的进程守护已经由 restart: always 完成了不需要额外写 systemd。但如果你是源码方式运行或者想精细化控制启动顺序我给一个最小可用的 systemd unit[Unit] DescriptionOpenClaw Service Afterdocker.service Requiresdocker.service [Service] ExecStart/usr/bin/docker compose -f /opt/openclaw/docker-compose.yml up ExecStop/usr/bin/docker compose -f /opt/openclaw/docker-compose.yml down Restartalways RestartSec10 [Install] WantedBymulti-user.target真实项目中如果OpenClaw还依赖数据库、消息队列等上游服务After 和 Requires 列表要逐个加上否则启动顺序错了OpenClaw起来连不上依赖一直重启日志刷屏。这个坑我在别的项目里踩过印象很深。5.2 日志管理容器模式下查看日志很简单docker logs -f openclaw但长时间运行后容器日志默认是 JSON 文件格式只增不减磁盘早晚被撑爆。我建议在 daemon.json 里配置一下 log rotation{ log-driver: json-file, log-opts: { max-size: 50m, max-file: 5 } }配完后重启 docker 服务新日志就会按50MB一个文件滚动最多保留5个。如果是源码方式运行可以用 logrotate 来轮转日志文件配置一个 /etc/logrotate.d/openclaw 文件按天或按大小切分保留30天足够。5.3 备份与升级OpenClaw 的配置和数据都挂载在宿主机目录里备份方式就是把 config 和 data 两个目录打包带走tar czf openclaw-backup-$(date %F).tar.gz /opt/openclaw/config /opt/openclaw/data升级流程是标准的 Compose 流程拉新镜像、重建容器、检查日志、如有问题回滚到旧镜像。回滚的关键是提前记住当前镜像的版本号别用 latest 当作回滚点。用 latest 的坑在于你今天拉的是latest明天再拉就变成另一个镜像了回滚时想找回昨天那个镜像只能靠 tag。建议正式环境固定一个明确的版本号比如 openclaw/openclaw:1.x.x升级时手动改版本号再重建。6. 常见问题排查速查表6.1 高频问题与解决办法下面是我实际部署中遇到过的、以及帮别人排查过的问题整理成一张速查表现象可能原因解决办法启动日志反复重连App Secret 填错重置Secret后重新填入重启容器收到事件但无回复发送消息权限未生效检查权限管理重新发布应用版本消息延迟高服务器地域距离飞书服务较远选择靠近用户的服务器地域中文消息乱码容器字符集未配置环境变量加 LANGC.UTF-8定时任务不触发时区不一致确认宿主机、容器TZ统一为Asia/Shanghai磁盘空间告警容器日志未轮转配置daemon.json的log-opts并滚动旧日志6.2 排查思路与工具排查这类链路问题我有一个固定的顺序能省下大量试错时间。第一步看 OpenClaw 的实时日志确认消息事件是否到达。第二步如果事件没到检查长连接是否established检查飞书事件订阅页面的事件列表。第三步如果事件到了但没回复用飞书调试台手动调用发送消息API验证API本身是否可用。第四步如果API可用把 OpenClaw 日志级别调到 debug看插件执行过程具体卡在哪一步。排查过程中最忌讳的是没有依据地乱改配置每次只改一个变量改完看日志确认效果再决定下一步。我自己吃过亏的是同时改了模型配置和插件配置结果出了问题分不清是哪个改动引起的最后全部回滚重来反而耽误了更多时间。最后再分享一个小技巧把整个部署过程中的关键输出都存成一个文档包括App ID、Secret存放位置、服务器IP、镜像版本号、各配置文件路径。这台服务器可能半年后你才再动它一次到时候翻文档比翻聊天记录靠谱得多。
