1. 项目概述为什么需要OpenClaw与飞书机器人的组合如果你在一个团队里工作大概率用过飞书。飞书的消息、文档、多维表格确实让协作效率提升了不少。但很多时候我们希望能让一些重复、繁琐的工作自动化。比如每天定时从数据库拉取数据生成报表发到群里或者当用户在群里问“今天谁值班”时机器人能自动查询排班表并回复再或者把飞书当成一个智能助理的入口让它帮你查天气、订会议室、甚至基于知识库回答专业问题。这就是OpenClaw这类工具的价值所在。简单来说OpenClaw是一个开源的、功能强大的机器人框架它就像一个“万能插座”可以轻松连接飞书、钉钉、微信等主流办公平台并赋予机器人处理消息、调用API、执行自动化流程的能力。它内置了丰富的插件和事件处理机制开发者无需从零开始造轮子就能快速搭建一个功能复杂的聊天机器人。而Docker则是解决“环境依赖”这个老大难问题的利器。你有没有遇到过这种情况在自己电脑上跑得好好的程序放到服务器上就各种报错不是Python版本不对就是某个依赖库装不上。Docker通过容器技术把应用和它需要的所有环境比如操作系统、运行时、库文件打包成一个独立的“集装箱”。这个集装箱在任何支持Docker的机器上都能以完全相同的方式运行真正做到“一次构建处处运行”。所以“OpenClaw多飞书机器人完整配置教程Docker部署版”这个标题瞄准的就是一个非常具体的痛点如何用最稳定、最可复制的方式在服务器上部署一个能同时服务多个飞书团队或应用的机器人后台。这比在本地电脑上跑一个测试版要复杂得多涉及到网络、持久化、配置管理、安全等一系列生产环境才需要考虑的问题。接下来我会以一个实际部署过多个生产级机器人的经验带你一步步走通整个流程并分享那些官方文档里可能不会写的“坑”和技巧。2. 核心需求与方案设计解析在动手之前我们必须先想清楚要做什么。一个“多飞书机器人”系统通常意味着以下几种场景为多个不同的飞书企业或同一个企业内的多个自建应用提供服务。比如你作为开发者可能同时为A公司和B公司开发了不同的机器人应用它们需要运行在同一台服务器上但逻辑和数据完全隔离。同一个机器人应用需要处理来自多个不同群聊或用户的消息。这虽然通常由一个机器人实例处理但也涉及到配置和管理。高可用和负载均衡。当用户量增大时可能需要部署多个机器人实例来分担压力。我们的教程主要聚焦于第一种场景这也是最复杂、最具通用性的。要实现它方案设计上必须考虑以下几个核心点2.1 环境隔离与配置分离这是“多机器人”的前提。每个机器人都有自己独立的飞书应用凭证App ID, App Secret, Verification Token, Encryption Key以及可能不同的数据库、缓存、第三方API密钥等。在Docker环境下最优雅的方式是为每个机器人创建一个独立的容器并通过环境变量或配置文件将各自的密钥注入进去。这样容器之间是相互隔离的一个机器人的故障不会影响另一个。2.2 数据持久化机器人运行时产生的数据如用户会话状态、缓存、日志不能随着容器销毁而丢失。我们需要使用Docker的卷Volume功能将容器内的特定目录如/app/data,/app/logs映射到宿主机的硬盘上。这样即使容器重启或重建数据依然存在。2.3 网络与通信飞书的服务器需要能访问到我们部署的机器人。这意味着我们的服务器必须有一个公网IP并且开放相应的端口通常是80或443。在容器内部OpenClaw服务默认监听某个端口如8080我们需要通过Docker的端口映射-p 80:8080将其暴露给外部。如果部署多个机器人监听同一端口则需要使用反向代理如Nginx根据域名或路径进行分发。2.4 日志与监控生产环境没有日志等于“盲人摸象”。我们需要配置OpenClaw输出结构化的日志并确保日志文件被持久化到卷中方便日后排查问题。更进阶的做法是接入ELKElasticsearch, Logstash, Kibana或Graylog等日志系统。基于以上考量我推荐的部署架构如下一个Docker镜像基于官方或社区维护的OpenClaw Docker镜像或者自己构建一个包含所有依赖的定制镜像。多个Docker容器每个飞书机器人对应一个容器实例。Docker Compose编排使用docker-compose.yml文件来定义和运行这多个容器。它可以方便地管理容器间的依赖关系、网络、卷和配置。对于单个机器人直接docker run也行但多容器时Compose是更佳选择。外部反向代理可选但推荐使用Nginx作为入口统一管理SSL证书、域名和到不同机器人容器的路由。这个方案清晰、易于维护也方便后续扩展。下面我们就进入具体的实操环节。3. 前期准备环境与飞书应用配置兵马未动粮草先行。在服务器上开搞之前有些准备工作必须在本地或飞书开发者后台完成。3.1 服务器环境准备你需要一台Linux服务器Ubuntu 20.04/22.04或CentOS 7/8是常见选择并确保安装Docker与Docker Compose这是基础中的基础。以Ubuntu为例安装命令如下# 更新软件包索引 sudo apt-get update # 安装依赖 sudo apt-get install ca-certificates curl gnupg lsb-release # 添加Docker官方GPG密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 设置稳定版仓库 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker引擎 sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin # 验证安装 sudo docker run hello-world注意如果遇到“Docker Desktop failed to start because virtualization support wasn‘t detected”这类错误那是桌面版的问题。在Linux服务器上我们安装的是Docker Engine需要确保服务器CPU支持虚拟化一般云服务器都支持并且没有其他冲突的虚拟化软件。配置防火墙开放需要用到的端口例如80HTTP、443HTTPS以及你计划映射的OpenClaw服务端口如8080、3000等。使用ufw或firewalld进行配置。sudo ufw allow 22/tcp # SSH端口务必保留 sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable域名与SSL证书生产环境必备飞书机器人配置的回调地址必须是HTTPS。你需要一个域名并为其申请SSL证书可以使用Let‘s Encrypt的免费证书。证书文件如fullchain.pem和privkey.pem需要放在服务器上后续配置Nginx时会用到。3.2 飞书应用创建与配置这是最关键的一步配置错了后面全白搭。假设我们要部署两个机器人一个用于内部团队通知Bot A一个用于客户服务Bot B。创建企业自建应用分别登录两个不同的飞书开发者账号或同一账号下创建两个应用。进入 开发者后台 点击“创建企业自建应用”。为应用起名例如“内部助手-Bot A”和“客户服务-Bot B”。获取凭证在应用详情页的“凭证与基础信息”部分找到并记录以下四项它们相当于机器人的“身份证”和“钥匙”App IDApp SecretVerification Token在“事件订阅”页面Encryption Key在“事件订阅”页面如果启用了加密配置权限在“权限管理”页面根据机器人需要的功能添加对应的权限。例如接收消息im:message接收用户发送的消息、im:message.group_at_msg接收群聊中机器人的消息等。发送消息im:message.p2p_msg:send发送单聊消息、im:message:send_as_bot发送群消息等。访问通讯录contact:user.id:readonly读取用户信息等。添加权限后记得在页面底部“版本管理与发布”中创建新版本并申请发布。只有审核通过或企业内自建应用在可用范围内的权限才会生效。配置事件订阅核心在“事件订阅”页面开启订阅。请求地址 URL填写你的服务器公网地址。例如https://bot-a.yourdomain.com/feishu/event和https://bot-b.yourdomain.com/feishu/event。这里/feishu/event是OpenClaw默认处理飞书事件的路由你也可以自定义。验证Token和加密Key填入之前记录的Verification Token和Encryption Key。添加事件点击“添加事件”根据需求选择。最基础的是接收消息v2.0im.message.receive_v1。选择后需要订阅相关的消息类型如text、image等。保存点击保存后飞书会向你的请求地址发送一个带有challenge参数的GET请求进行验证。此时你的后端服务OpenClaw必须已经启动并能正确响应这个挑战验证才能通过。我们可以在部署完服务后再回来点“重新保存”来触发验证。至此前期的配置工作就完成了。我们把两个机器人的四组密钥分别记好接下来就要在服务器上让它们“活”起来。4. Docker部署实战从镜像到多容器运行现在我们登录到准备好的Linux服务器开始实际的部署工作。4.1 获取或构建OpenClaw Docker镜像OpenClaw项目通常会在Docker Hub或GitHub Packages上提供官方镜像。我们需要先拉取镜像。假设官方镜像名为openclaw/openclaw:latest。sudo docker pull openclaw/openclaw:latest如果官方没有提供或者你需要一个包含特定插件、依赖的定制镜像就需要自己编写Dockerfile来构建。这里假设我们使用官方镜像。4.2 规划项目目录结构清晰的目录结构是管理多容器的关键。我在服务器上通常会这样组织/opt/openclaw-deploy/ ├── docker-compose.yml # 总编排文件 ├── nginx/ │ ├── nginx.conf # Nginx主配置 │ ├── conf.d/ │ │ ├── bot-a.conf # 机器人A的Nginx配置 │ │ └── bot-b.conf # 机器人B的Nginx配置 │ └── ssl/ # 存放SSL证书 │ ├── bot-a.yourdomain.com/ │ │ ├── fullchain.pem │ │ └── privkey.pem │ └── bot-b.yourdomain.com/ │ ├── fullchain.pem │ └── privkey.pem ├── bot-a/ # 机器人A的配置和数据 │ ├── config/ │ │ └── config.yaml # OpenClaw配置文件 │ └── data/ # 映射的数据卷目录 └── bot-b/ # 机器人B的配置和数据 ├── config/ │ └── config.yaml └── data/你可以使用mkdir -p命令依次创建这些目录。4.3 编写OpenClaw配置文件每个机器人容器都需要自己的配置文件。以bot-a/config/config.yaml为例# OpenClaw 基础配置 server: host: 0.0.0.0 # 监听所有网络接口 port: 8080 # 容器内服务端口与docker-compose中映射的端口一致 # 飞书平台配置 feishu: app_id: cli_xxxxxxxxxxxxxxx # 替换为Bot A的App ID app_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 替换为Bot A的App Secret verification_token: xxxxxxxxxxxxxxxxxxxxxxxx # 替换为Bot A的Verification Token encrypt_key: xxxxxxxxxxxxxxxx # 替换为Bot A的Encryption Key如果未加密则留空或删除 # 事件回调路径需要与飞书后台配置的“请求地址”路径后缀一致 event_callback_path: /feishu/event # 插件配置示例 plugins: enabled: - weather # 天气查询插件 - schedule # 定时任务插件 weather: api_key: your_weather_api_keybot-b的配置文件同理内容替换为Bot B的凭证。务必注意app_id等敏感信息不要提交到公开的代码仓库。4.4 编写Docker Compose编排文件这是核心中的核心/opt/openclaw-deploy/docker-compose.ymlversion: 3.8 services: # 机器人A服务 openclaw-bot-a: image: openclaw/openclaw:latest container_name: openclaw-bot-a restart: unless-stopped # 自动重启策略确保服务高可用 ports: - 8081:8080 # 宿主机的8081端口映射到容器的8080端口 volumes: # 挂载配置文件使容器内能读取到宿主机的配置 - ./bot-a/config/config.yaml:/app/config.yaml:ro # 挂载数据目录实现数据持久化 - ./bot-a/data:/app/data environment: # 也可以通过环境变量覆盖配置优先级高于配置文件 - TZAsia/Shanghai networks: - openclaw-network # 加入自定义网络方便容器间通信如果需要 # 机器人B服务 openclaw-bot-b: image: openclaw/openclaw:latest container_name: openclaw-bot-b restart: unless-stopped ports: - 8082:8080 # 注意端口不能冲突这里用8082 volumes: - ./bot-b/config/config.yaml:/app/config.yaml:ro - ./bot-b/data:/app/data environment: - TZAsia/Shanghai networks: - openclaw-network # Nginx反向代理可选但推荐 nginx-proxy: image: nginx:alpine container_name: nginx-proxy restart: unless-stopped ports: - 80:80 - 443:443 volumes: # 挂载Nginx配置目录 - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro - ./nginx/conf.d:/etc/nginx/conf.d:ro # 挂载SSL证书目录 - ./nginx/ssl:/etc/nginx/ssl:ro depends_on: - openclaw-bot-a - openclaw-bot-b networks: - openclaw-network # 定义自定义网络 networks: openclaw-network: driver: bridge这个配置定义了两个OpenClaw服务和一个Nginx服务。它们通过openclaw-network网络互联。Nginx容器对外暴露80和443端口负责将来自不同域名的请求转发到对应的OpenClaw容器。4.5 配置Nginx反向代理首先配置主配置文件nginx/nginx.conf保持简洁主要配置通过include引入user nginx; worker_processes auto; error_log /var/log/nginx/error.log warn; pid /var/run/nginx.pid; events { worker_connections 1024; } http { include /etc/nginx/mime.types; default_type application/octet-stream; sendfile on; keepalive_timeout 65; # 包含各个机器人的独立配置 include /etc/nginx/conf.d/*.conf; }然后为每个机器人编写独立的服务器配置。以nginx/conf.d/bot-a.conf为例server { listen 80; server_name bot-a.yourdomain.com; # 将HTTP请求重定向到HTTPS return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name bot-a.yourdomain.com; # SSL证书配置 ssl_certificate /etc/nginx/ssl/bot-a.yourdomain.com/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/bot-a.yourdomain.com/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; # 反向代理到OpenClaw容器 location / { proxy_pass http://openclaw-bot-a:8080; # 使用Docker服务名网络自动解析 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 以下两行对飞书事件回调很重要确保超时设置合理 proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; } # 可选静态文件服务或健康检查端点 location /health { proxy_pass http://openclaw-bot-a:8080/health; access_log off; } }bot-b.conf的配置类似只需修改server_name、ssl_certificate路径和proxy_pass的目标服务名openclaw-bot-b。4.6 启动所有服务进入项目目录运行一条命令即可启动所有定义的服务cd /opt/openclaw-deploy sudo docker-compose up -d-d参数表示在后台运行。使用以下命令查看服务状态和日志# 查看所有容器状态 sudo docker-compose ps # 查看某个容器的日志如Bot A sudo docker-compose logs -f openclaw-bot-a如果一切顺利你应该能看到OpenClaw容器成功启动的日志。现在你的两个机器人服务已经在http://openclaw-bot-a:8080和http://openclaw-bot-b:8080容器网络内运行并且通过Nginx在https://bot-a.yourdomain.com和https://bot-b.yourdomain.com对外提供服务。5. 飞书应用验证与功能测试服务跑起来了但还需要和飞书平台“握手”确认。5.1 完成事件订阅验证回到飞书开发者后台分别进入Bot A和Bot B的应用的“事件订阅”页面。确保“请求地址”填写的是你配置的HTTPS地址如https://bot-a.yourdomain.com/feishu/event。点击页面上的“保存”或“重新保存”按钮。此时飞书会向该地址发送一个GET请求进行验证。你的OpenClaw服务需要正确响应这个挑战。一个正常的OpenClaw框架会自动处理这个验证。你可以在Nginx和OpenClaw的日志中观察验证请求# 查看Nginx访问日志 sudo docker-compose logs nginx-proxy | grep GET /feishu/event # 查看OpenClaw应用日志 sudo docker-compose logs openclaw-bot-a | grep -i challenge如果验证成功飞书后台页面会显示“验证成功”。如果失败请检查网络连通性服务器防火墙是否开放80/443端口域名解析是否正确配置一致性飞书后台的Verification Token和Encryption Key是否与config.yaml中的完全一致包括空格路径是否正确飞书请求的路径是否与OpenClaw配置的event_callback_path匹配日志错误仔细查看OpenClaw容器的错误日志寻找线索。5.2 权限申请与启用事件订阅验证通过后在“权限管理”页面确保所有需要的权限都已添加并且已经发布版本。对于企业自建应用需要企业管理员在“审核中心”同意申请。只有权限生效后机器人才能正常接收和发送消息。5.3 基础功能测试验证通过后就可以进行真实场景测试了。添加到群聊将机器人应用添加到某个飞书群。接收消息在群里机器人或与机器人发起单聊发送一条消息。观察OpenClaw容器的日志应该能看到接收消息的事件日志。发送消息编写一个简单的OpenClaw插件或脚本实现“收到什么就回复什么”的echo功能。在群里测试看机器人是否能成功回复。检查消息权限如果发送消息失败提示无权限请回到开发者后台检查im:message:send_as_bot等发送消息的权限是否已申请并生效。6. 高级配置、运维与故障排查部署完成只是第一步要让机器人稳定可靠地运行还需要考虑更多。6.1 配置热更新与多环境我们目前将配置写在config.yaml里并挂载为只读卷。如果想更新配置需要修改宿主机文件后重启容器sudo docker-compose restart openclaw-bot-a对于更复杂的配置可以考虑使用环境变量、或者专门的配置中心如Apollo, Nacos。在docker-compose.yml中可以用environment部分覆盖配置environment: - FEISHU_APP_IDcli_xxxx - FEISHU_APP_SECRETxxxx - LOG_LEVELDEBUGOpenClaw需要支持从环境变量读取这些配置。6.2 数据持久化与备份我们通过volumes将/app/data目录映射到了宿主机。你需要定期备份这些目录。可以使用cron定时任务配合tar或rsync命令将/opt/openclaw-deploy/bot-a/data等目录备份到其他存储位置。6.3 日志管理默认日志可能输出到容器内的标准输出stdout通过docker-compose logs查看。对于生产环境建议将日志持久化并集中管理在docker-compose.yml中配置日志驱动和大小限制防止日志撑爆磁盘。logging: driver: json-file options: max-size: 10m max-file: 3或者将日志文件挂载到宿主机然后使用Filebeat等工具采集到ELK。6.4 监控与健康检查可以给Docker服务添加健康检查指令让Docker引擎自动判断容器是否健康。healthcheck: test: [CMD, curl, -f, http://localhost:8080/health] # 假设OpenClaw有/health端点 interval: 30s timeout: 10s retries: 3 start_period: 40s同时可以配置Prometheus Grafana来监控服务器的CPU、内存、磁盘使用率以及容器的运行状态。6.5 常见问题与排查实录在实际部署中我踩过不少坑这里分享几个典型的问题一飞书事件回调一直失败返回400或500错误。排查首先看Nginx访问日志确认请求是否到达。再看OpenClaw应用日志。可能原因1Verification Token或Encryption Key配置错误。一字不差地核对注意开头结尾是否有隐藏空格。可能原因2OpenClaw服务启动失败或插件加载错误。检查应用日志开头是否有异常堆栈信息。常见于依赖缺失或配置文件格式错误YAML对缩进非常敏感。可能原因3网络超时。飞书服务器可能在海外到国内服务器的网络不稳定。适当调大Nginx的proxy_read_timeout和OpenClaw自身的超时设置。问题二机器人能收到消息但无法回复提示“无权限”。排查这是最典型的问题。去飞书开发者后台“权限管理”页面。解决确认所需权限尤其是发送消息的权限已添加并且已经创建了新版本并发布。企业自建应用需要管理员审核通过。权限生效可能有几分钟延迟。问题三Docker容器启动后立即退出。排查使用sudo docker-compose logs [service-name]查看退出前的日志。可能原因配置文件路径错误导致挂载失败或者config.yaml格式错误导致应用启动时解析崩溃。检查docker-compose.yml中volumes映射的宿主机路径是否存在以及YAML文件的语法推荐使用在线YAML校验工具。问题四Nginx报错502 Bad Gateway。排查这意味着Nginx无法连接到后端的OpenClaw服务。解决确认OpenClaw容器是否在运行sudo docker-compose ps。确认Nginx配置中proxy_pass的地址是否正确。在docker-compose网络中应使用服务名如http://openclaw-bot-a:8080而不是localhost或127.0.0.1。进入Nginx容器内部尝试用curl命令直接访问后端地址看是否通sudo docker-compose exec nginx-proxy curl http://openclaw-bot-a:8080/health。问题五如何更新OpenClaw版本步骤拉取新镜像sudo docker-compose pull openclaw-bot-a openclaw-bot-b。重启服务sudo docker-compose up -d。Compose会使用新镜像重新创建容器。重要在更新前最好先在一个测试环境验证新版本与现有插件、配置的兼容性。部署和运维是一个持续的过程。建议将整个/opt/openclaw-deploy目录纳入版本控制如Git但切记不要提交包含真实密钥的配置文件。可以使用.env文件或配置模板的方式来管理敏感信息。通过这套Docker Compose方案你获得了一个可移植、易扩展、便于管理的多飞书机器人部署环境可以在此基础上安心地开发更强大的机器人功能了。 基于Docker部署OpenClaw实现多飞书机器人自动化配置与运维
1. 项目概述为什么需要OpenClaw与飞书机器人的组合如果你在一个团队里工作大概率用过飞书。飞书的消息、文档、多维表格确实让协作效率提升了不少。但很多时候我们希望能让一些重复、繁琐的工作自动化。比如每天定时从数据库拉取数据生成报表发到群里或者当用户在群里问“今天谁值班”时机器人能自动查询排班表并回复再或者把飞书当成一个智能助理的入口让它帮你查天气、订会议室、甚至基于知识库回答专业问题。这就是OpenClaw这类工具的价值所在。简单来说OpenClaw是一个开源的、功能强大的机器人框架它就像一个“万能插座”可以轻松连接飞书、钉钉、微信等主流办公平台并赋予机器人处理消息、调用API、执行自动化流程的能力。它内置了丰富的插件和事件处理机制开发者无需从零开始造轮子就能快速搭建一个功能复杂的聊天机器人。而Docker则是解决“环境依赖”这个老大难问题的利器。你有没有遇到过这种情况在自己电脑上跑得好好的程序放到服务器上就各种报错不是Python版本不对就是某个依赖库装不上。Docker通过容器技术把应用和它需要的所有环境比如操作系统、运行时、库文件打包成一个独立的“集装箱”。这个集装箱在任何支持Docker的机器上都能以完全相同的方式运行真正做到“一次构建处处运行”。所以“OpenClaw多飞书机器人完整配置教程Docker部署版”这个标题瞄准的就是一个非常具体的痛点如何用最稳定、最可复制的方式在服务器上部署一个能同时服务多个飞书团队或应用的机器人后台。这比在本地电脑上跑一个测试版要复杂得多涉及到网络、持久化、配置管理、安全等一系列生产环境才需要考虑的问题。接下来我会以一个实际部署过多个生产级机器人的经验带你一步步走通整个流程并分享那些官方文档里可能不会写的“坑”和技巧。2. 核心需求与方案设计解析在动手之前我们必须先想清楚要做什么。一个“多飞书机器人”系统通常意味着以下几种场景为多个不同的飞书企业或同一个企业内的多个自建应用提供服务。比如你作为开发者可能同时为A公司和B公司开发了不同的机器人应用它们需要运行在同一台服务器上但逻辑和数据完全隔离。同一个机器人应用需要处理来自多个不同群聊或用户的消息。这虽然通常由一个机器人实例处理但也涉及到配置和管理。高可用和负载均衡。当用户量增大时可能需要部署多个机器人实例来分担压力。我们的教程主要聚焦于第一种场景这也是最复杂、最具通用性的。要实现它方案设计上必须考虑以下几个核心点2.1 环境隔离与配置分离这是“多机器人”的前提。每个机器人都有自己独立的飞书应用凭证App ID, App Secret, Verification Token, Encryption Key以及可能不同的数据库、缓存、第三方API密钥等。在Docker环境下最优雅的方式是为每个机器人创建一个独立的容器并通过环境变量或配置文件将各自的密钥注入进去。这样容器之间是相互隔离的一个机器人的故障不会影响另一个。2.2 数据持久化机器人运行时产生的数据如用户会话状态、缓存、日志不能随着容器销毁而丢失。我们需要使用Docker的卷Volume功能将容器内的特定目录如/app/data,/app/logs映射到宿主机的硬盘上。这样即使容器重启或重建数据依然存在。2.3 网络与通信飞书的服务器需要能访问到我们部署的机器人。这意味着我们的服务器必须有一个公网IP并且开放相应的端口通常是80或443。在容器内部OpenClaw服务默认监听某个端口如8080我们需要通过Docker的端口映射-p 80:8080将其暴露给外部。如果部署多个机器人监听同一端口则需要使用反向代理如Nginx根据域名或路径进行分发。2.4 日志与监控生产环境没有日志等于“盲人摸象”。我们需要配置OpenClaw输出结构化的日志并确保日志文件被持久化到卷中方便日后排查问题。更进阶的做法是接入ELKElasticsearch, Logstash, Kibana或Graylog等日志系统。基于以上考量我推荐的部署架构如下一个Docker镜像基于官方或社区维护的OpenClaw Docker镜像或者自己构建一个包含所有依赖的定制镜像。多个Docker容器每个飞书机器人对应一个容器实例。Docker Compose编排使用docker-compose.yml文件来定义和运行这多个容器。它可以方便地管理容器间的依赖关系、网络、卷和配置。对于单个机器人直接docker run也行但多容器时Compose是更佳选择。外部反向代理可选但推荐使用Nginx作为入口统一管理SSL证书、域名和到不同机器人容器的路由。这个方案清晰、易于维护也方便后续扩展。下面我们就进入具体的实操环节。3. 前期准备环境与飞书应用配置兵马未动粮草先行。在服务器上开搞之前有些准备工作必须在本地或飞书开发者后台完成。3.1 服务器环境准备你需要一台Linux服务器Ubuntu 20.04/22.04或CentOS 7/8是常见选择并确保安装Docker与Docker Compose这是基础中的基础。以Ubuntu为例安装命令如下# 更新软件包索引 sudo apt-get update # 安装依赖 sudo apt-get install ca-certificates curl gnupg lsb-release # 添加Docker官方GPG密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 设置稳定版仓库 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker引擎 sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin # 验证安装 sudo docker run hello-world注意如果遇到“Docker Desktop failed to start because virtualization support wasn‘t detected”这类错误那是桌面版的问题。在Linux服务器上我们安装的是Docker Engine需要确保服务器CPU支持虚拟化一般云服务器都支持并且没有其他冲突的虚拟化软件。配置防火墙开放需要用到的端口例如80HTTP、443HTTPS以及你计划映射的OpenClaw服务端口如8080、3000等。使用ufw或firewalld进行配置。sudo ufw allow 22/tcp # SSH端口务必保留 sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable域名与SSL证书生产环境必备飞书机器人配置的回调地址必须是HTTPS。你需要一个域名并为其申请SSL证书可以使用Let‘s Encrypt的免费证书。证书文件如fullchain.pem和privkey.pem需要放在服务器上后续配置Nginx时会用到。3.2 飞书应用创建与配置这是最关键的一步配置错了后面全白搭。假设我们要部署两个机器人一个用于内部团队通知Bot A一个用于客户服务Bot B。创建企业自建应用分别登录两个不同的飞书开发者账号或同一账号下创建两个应用。进入 开发者后台 点击“创建企业自建应用”。为应用起名例如“内部助手-Bot A”和“客户服务-Bot B”。获取凭证在应用详情页的“凭证与基础信息”部分找到并记录以下四项它们相当于机器人的“身份证”和“钥匙”App IDApp SecretVerification Token在“事件订阅”页面Encryption Key在“事件订阅”页面如果启用了加密配置权限在“权限管理”页面根据机器人需要的功能添加对应的权限。例如接收消息im:message接收用户发送的消息、im:message.group_at_msg接收群聊中机器人的消息等。发送消息im:message.p2p_msg:send发送单聊消息、im:message:send_as_bot发送群消息等。访问通讯录contact:user.id:readonly读取用户信息等。添加权限后记得在页面底部“版本管理与发布”中创建新版本并申请发布。只有审核通过或企业内自建应用在可用范围内的权限才会生效。配置事件订阅核心在“事件订阅”页面开启订阅。请求地址 URL填写你的服务器公网地址。例如https://bot-a.yourdomain.com/feishu/event和https://bot-b.yourdomain.com/feishu/event。这里/feishu/event是OpenClaw默认处理飞书事件的路由你也可以自定义。验证Token和加密Key填入之前记录的Verification Token和Encryption Key。添加事件点击“添加事件”根据需求选择。最基础的是接收消息v2.0im.message.receive_v1。选择后需要订阅相关的消息类型如text、image等。保存点击保存后飞书会向你的请求地址发送一个带有challenge参数的GET请求进行验证。此时你的后端服务OpenClaw必须已经启动并能正确响应这个挑战验证才能通过。我们可以在部署完服务后再回来点“重新保存”来触发验证。至此前期的配置工作就完成了。我们把两个机器人的四组密钥分别记好接下来就要在服务器上让它们“活”起来。4. Docker部署实战从镜像到多容器运行现在我们登录到准备好的Linux服务器开始实际的部署工作。4.1 获取或构建OpenClaw Docker镜像OpenClaw项目通常会在Docker Hub或GitHub Packages上提供官方镜像。我们需要先拉取镜像。假设官方镜像名为openclaw/openclaw:latest。sudo docker pull openclaw/openclaw:latest如果官方没有提供或者你需要一个包含特定插件、依赖的定制镜像就需要自己编写Dockerfile来构建。这里假设我们使用官方镜像。4.2 规划项目目录结构清晰的目录结构是管理多容器的关键。我在服务器上通常会这样组织/opt/openclaw-deploy/ ├── docker-compose.yml # 总编排文件 ├── nginx/ │ ├── nginx.conf # Nginx主配置 │ ├── conf.d/ │ │ ├── bot-a.conf # 机器人A的Nginx配置 │ │ └── bot-b.conf # 机器人B的Nginx配置 │ └── ssl/ # 存放SSL证书 │ ├── bot-a.yourdomain.com/ │ │ ├── fullchain.pem │ │ └── privkey.pem │ └── bot-b.yourdomain.com/ │ ├── fullchain.pem │ └── privkey.pem ├── bot-a/ # 机器人A的配置和数据 │ ├── config/ │ │ └── config.yaml # OpenClaw配置文件 │ └── data/ # 映射的数据卷目录 └── bot-b/ # 机器人B的配置和数据 ├── config/ │ └── config.yaml └── data/你可以使用mkdir -p命令依次创建这些目录。4.3 编写OpenClaw配置文件每个机器人容器都需要自己的配置文件。以bot-a/config/config.yaml为例# OpenClaw 基础配置 server: host: 0.0.0.0 # 监听所有网络接口 port: 8080 # 容器内服务端口与docker-compose中映射的端口一致 # 飞书平台配置 feishu: app_id: cli_xxxxxxxxxxxxxxx # 替换为Bot A的App ID app_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 替换为Bot A的App Secret verification_token: xxxxxxxxxxxxxxxxxxxxxxxx # 替换为Bot A的Verification Token encrypt_key: xxxxxxxxxxxxxxxx # 替换为Bot A的Encryption Key如果未加密则留空或删除 # 事件回调路径需要与飞书后台配置的“请求地址”路径后缀一致 event_callback_path: /feishu/event # 插件配置示例 plugins: enabled: - weather # 天气查询插件 - schedule # 定时任务插件 weather: api_key: your_weather_api_keybot-b的配置文件同理内容替换为Bot B的凭证。务必注意app_id等敏感信息不要提交到公开的代码仓库。4.4 编写Docker Compose编排文件这是核心中的核心/opt/openclaw-deploy/docker-compose.ymlversion: 3.8 services: # 机器人A服务 openclaw-bot-a: image: openclaw/openclaw:latest container_name: openclaw-bot-a restart: unless-stopped # 自动重启策略确保服务高可用 ports: - 8081:8080 # 宿主机的8081端口映射到容器的8080端口 volumes: # 挂载配置文件使容器内能读取到宿主机的配置 - ./bot-a/config/config.yaml:/app/config.yaml:ro # 挂载数据目录实现数据持久化 - ./bot-a/data:/app/data environment: # 也可以通过环境变量覆盖配置优先级高于配置文件 - TZAsia/Shanghai networks: - openclaw-network # 加入自定义网络方便容器间通信如果需要 # 机器人B服务 openclaw-bot-b: image: openclaw/openclaw:latest container_name: openclaw-bot-b restart: unless-stopped ports: - 8082:8080 # 注意端口不能冲突这里用8082 volumes: - ./bot-b/config/config.yaml:/app/config.yaml:ro - ./bot-b/data:/app/data environment: - TZAsia/Shanghai networks: - openclaw-network # Nginx反向代理可选但推荐 nginx-proxy: image: nginx:alpine container_name: nginx-proxy restart: unless-stopped ports: - 80:80 - 443:443 volumes: # 挂载Nginx配置目录 - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro - ./nginx/conf.d:/etc/nginx/conf.d:ro # 挂载SSL证书目录 - ./nginx/ssl:/etc/nginx/ssl:ro depends_on: - openclaw-bot-a - openclaw-bot-b networks: - openclaw-network # 定义自定义网络 networks: openclaw-network: driver: bridge这个配置定义了两个OpenClaw服务和一个Nginx服务。它们通过openclaw-network网络互联。Nginx容器对外暴露80和443端口负责将来自不同域名的请求转发到对应的OpenClaw容器。4.5 配置Nginx反向代理首先配置主配置文件nginx/nginx.conf保持简洁主要配置通过include引入user nginx; worker_processes auto; error_log /var/log/nginx/error.log warn; pid /var/run/nginx.pid; events { worker_connections 1024; } http { include /etc/nginx/mime.types; default_type application/octet-stream; sendfile on; keepalive_timeout 65; # 包含各个机器人的独立配置 include /etc/nginx/conf.d/*.conf; }然后为每个机器人编写独立的服务器配置。以nginx/conf.d/bot-a.conf为例server { listen 80; server_name bot-a.yourdomain.com; # 将HTTP请求重定向到HTTPS return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name bot-a.yourdomain.com; # SSL证书配置 ssl_certificate /etc/nginx/ssl/bot-a.yourdomain.com/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/bot-a.yourdomain.com/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; # 反向代理到OpenClaw容器 location / { proxy_pass http://openclaw-bot-a:8080; # 使用Docker服务名网络自动解析 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 以下两行对飞书事件回调很重要确保超时设置合理 proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; } # 可选静态文件服务或健康检查端点 location /health { proxy_pass http://openclaw-bot-a:8080/health; access_log off; } }bot-b.conf的配置类似只需修改server_name、ssl_certificate路径和proxy_pass的目标服务名openclaw-bot-b。4.6 启动所有服务进入项目目录运行一条命令即可启动所有定义的服务cd /opt/openclaw-deploy sudo docker-compose up -d-d参数表示在后台运行。使用以下命令查看服务状态和日志# 查看所有容器状态 sudo docker-compose ps # 查看某个容器的日志如Bot A sudo docker-compose logs -f openclaw-bot-a如果一切顺利你应该能看到OpenClaw容器成功启动的日志。现在你的两个机器人服务已经在http://openclaw-bot-a:8080和http://openclaw-bot-b:8080容器网络内运行并且通过Nginx在https://bot-a.yourdomain.com和https://bot-b.yourdomain.com对外提供服务。5. 飞书应用验证与功能测试服务跑起来了但还需要和飞书平台“握手”确认。5.1 完成事件订阅验证回到飞书开发者后台分别进入Bot A和Bot B的应用的“事件订阅”页面。确保“请求地址”填写的是你配置的HTTPS地址如https://bot-a.yourdomain.com/feishu/event。点击页面上的“保存”或“重新保存”按钮。此时飞书会向该地址发送一个GET请求进行验证。你的OpenClaw服务需要正确响应这个挑战。一个正常的OpenClaw框架会自动处理这个验证。你可以在Nginx和OpenClaw的日志中观察验证请求# 查看Nginx访问日志 sudo docker-compose logs nginx-proxy | grep GET /feishu/event # 查看OpenClaw应用日志 sudo docker-compose logs openclaw-bot-a | grep -i challenge如果验证成功飞书后台页面会显示“验证成功”。如果失败请检查网络连通性服务器防火墙是否开放80/443端口域名解析是否正确配置一致性飞书后台的Verification Token和Encryption Key是否与config.yaml中的完全一致包括空格路径是否正确飞书请求的路径是否与OpenClaw配置的event_callback_path匹配日志错误仔细查看OpenClaw容器的错误日志寻找线索。5.2 权限申请与启用事件订阅验证通过后在“权限管理”页面确保所有需要的权限都已添加并且已经发布版本。对于企业自建应用需要企业管理员在“审核中心”同意申请。只有权限生效后机器人才能正常接收和发送消息。5.3 基础功能测试验证通过后就可以进行真实场景测试了。添加到群聊将机器人应用添加到某个飞书群。接收消息在群里机器人或与机器人发起单聊发送一条消息。观察OpenClaw容器的日志应该能看到接收消息的事件日志。发送消息编写一个简单的OpenClaw插件或脚本实现“收到什么就回复什么”的echo功能。在群里测试看机器人是否能成功回复。检查消息权限如果发送消息失败提示无权限请回到开发者后台检查im:message:send_as_bot等发送消息的权限是否已申请并生效。6. 高级配置、运维与故障排查部署完成只是第一步要让机器人稳定可靠地运行还需要考虑更多。6.1 配置热更新与多环境我们目前将配置写在config.yaml里并挂载为只读卷。如果想更新配置需要修改宿主机文件后重启容器sudo docker-compose restart openclaw-bot-a对于更复杂的配置可以考虑使用环境变量、或者专门的配置中心如Apollo, Nacos。在docker-compose.yml中可以用environment部分覆盖配置environment: - FEISHU_APP_IDcli_xxxx - FEISHU_APP_SECRETxxxx - LOG_LEVELDEBUGOpenClaw需要支持从环境变量读取这些配置。6.2 数据持久化与备份我们通过volumes将/app/data目录映射到了宿主机。你需要定期备份这些目录。可以使用cron定时任务配合tar或rsync命令将/opt/openclaw-deploy/bot-a/data等目录备份到其他存储位置。6.3 日志管理默认日志可能输出到容器内的标准输出stdout通过docker-compose logs查看。对于生产环境建议将日志持久化并集中管理在docker-compose.yml中配置日志驱动和大小限制防止日志撑爆磁盘。logging: driver: json-file options: max-size: 10m max-file: 3或者将日志文件挂载到宿主机然后使用Filebeat等工具采集到ELK。6.4 监控与健康检查可以给Docker服务添加健康检查指令让Docker引擎自动判断容器是否健康。healthcheck: test: [CMD, curl, -f, http://localhost:8080/health] # 假设OpenClaw有/health端点 interval: 30s timeout: 10s retries: 3 start_period: 40s同时可以配置Prometheus Grafana来监控服务器的CPU、内存、磁盘使用率以及容器的运行状态。6.5 常见问题与排查实录在实际部署中我踩过不少坑这里分享几个典型的问题一飞书事件回调一直失败返回400或500错误。排查首先看Nginx访问日志确认请求是否到达。再看OpenClaw应用日志。可能原因1Verification Token或Encryption Key配置错误。一字不差地核对注意开头结尾是否有隐藏空格。可能原因2OpenClaw服务启动失败或插件加载错误。检查应用日志开头是否有异常堆栈信息。常见于依赖缺失或配置文件格式错误YAML对缩进非常敏感。可能原因3网络超时。飞书服务器可能在海外到国内服务器的网络不稳定。适当调大Nginx的proxy_read_timeout和OpenClaw自身的超时设置。问题二机器人能收到消息但无法回复提示“无权限”。排查这是最典型的问题。去飞书开发者后台“权限管理”页面。解决确认所需权限尤其是发送消息的权限已添加并且已经创建了新版本并发布。企业自建应用需要管理员审核通过。权限生效可能有几分钟延迟。问题三Docker容器启动后立即退出。排查使用sudo docker-compose logs [service-name]查看退出前的日志。可能原因配置文件路径错误导致挂载失败或者config.yaml格式错误导致应用启动时解析崩溃。检查docker-compose.yml中volumes映射的宿主机路径是否存在以及YAML文件的语法推荐使用在线YAML校验工具。问题四Nginx报错502 Bad Gateway。排查这意味着Nginx无法连接到后端的OpenClaw服务。解决确认OpenClaw容器是否在运行sudo docker-compose ps。确认Nginx配置中proxy_pass的地址是否正确。在docker-compose网络中应使用服务名如http://openclaw-bot-a:8080而不是localhost或127.0.0.1。进入Nginx容器内部尝试用curl命令直接访问后端地址看是否通sudo docker-compose exec nginx-proxy curl http://openclaw-bot-a:8080/health。问题五如何更新OpenClaw版本步骤拉取新镜像sudo docker-compose pull openclaw-bot-a openclaw-bot-b。重启服务sudo docker-compose up -d。Compose会使用新镜像重新创建容器。重要在更新前最好先在一个测试环境验证新版本与现有插件、配置的兼容性。部署和运维是一个持续的过程。建议将整个/opt/openclaw-deploy目录纳入版本控制如Git但切记不要提交包含真实密钥的配置文件。可以使用.env文件或配置模板的方式来管理敏感信息。通过这套Docker Compose方案你获得了一个可移植、易扩展、便于管理的多飞书机器人部署环境可以在此基础上安心地开发更强大的机器人功能了。