这段时间折腾了一台云服务器把 OpenClaw 装进 1Panel再把机器人接入飞书整套流程走完我觉得这是目前把 AI Agent 真正落地到办公场景里比较顺的一条路。尤其当你本来就习惯用飞书协作又不想天天开着一堆网页端聊天窗口的时候这套组合的价值就很明显。简单交代一下背景1Panel 是一款开源的 Linux 服务器管理面板自带 Docker、容器编排、网站反向代理、数据库管理这些能力相当于帮我们把服务器运维里 80% 的重复操作图形化了。OpenClaw 是当前很受关注的开源 Agent 框架它自己不生产大模型而是负责把模型能力拆成工具调用、会话管理、多平台接入这类基础设施级的事情。飞书则是大量团队每天都在用的办公 IM机器人、多维表格、审批流这些能力都开放了 API天然适合做 Agent 的交互界面。这篇文章适合三类人第一已经用 1Panel 在管服务器但还没想清楚怎么把 AI 服务跑起来的朋友第二飞书管理员或运营同学想给团队加一个能自动查数据、发表格、定时汇报的机器人第三纯粹好奇的程序员想用一个周末把消息通道跑通顺便踩一踩那些文档里不会写的坑。1. 项目概述与需求拆解1.1 先想清楚你缺的不是模型是一个能长期跑起来的 Agent 载体现在大模型 API 已经非常便宜大家缺的反而是“怎么把模型可靠地接到具体工作流里”。你可以直接在终端里和 Claude、GPT 对话但终端不是办公场景你也可以在网页里开着对话框但网页不会主动翻你的多维表格不会在早上九点把日报整理好发到群里。OpenClaw 这类 Agent 框架补的正是这一层。它的核心职责是“会话管理”和“工具调度”收到一条消息判断该调用哪个工具保持上下文对话处理多轮任务拆分最后把结果以一种对用户友好的方式返回。拿一个生活化的类比来说大模型像一个很聪明但刚入职的实习生OpenClaw 就是给这个实习生配的工位、电脑、企业 IM 账号和工作流程手册让它真正开始营业。用 1Panel 来承载 OpenClaw则解决的是“怎么让它稳定跑在路上”的问题。Agent 服务不是一次跑完就结束的命令行脚本它需要常驻、需要日志、需要重启策略、需要反向代理、需要证书管理。这些恰好是 1Panel 的强项。1.2 为什么把 IM 通道选在飞书而不是先做网页或命令行很多人做 Agent Demo 时会先写个网页对话框但我个人经验是网页对话框试用完就扔IM 机器人反而能沉淀下来。原因很简单办公 IM 是每天打开次数最多的应用机器人被拉进群、被 一下就能触发任务。飞书相对其他 IM 有几个明显的优势开放平台成熟创建机器人应用是全图形化操作不需要过审资质。机器人消息支持富文本卡片和文件发送能让 Agent 输出表格、图片、交互按钮而不只是干巴巴的文字。多维表格的 API 表现很好Agent 可以直接把结果写入多维表格或者反过来从多维表格读取数据再加工。国内服务器直连飞书回调地址网络延迟低后端部署在北京或华东的云服务器上非常稳。当然如果你们团队用的是钉钉或企业微信逻辑一样只是配置字段不同。OpenClaw 的通道设计就是为多平台准备的飞书只是其中一个适配器。1.3 项目整体的技术链路和关键决策整个方案的技术链路可以概括成一条线飞书消息 → 飞书开放平台事件回调 → 1Panel 反向代理 → OpenClaw 容器 → 大模型 API → 工具调用 → 结果返回飞书。这条链路里有三个关键决策影响后续是否稳定用 Docker Compose 而不是直接在宿主机上装 Python 环境。OpenClaw 依赖一堆运行时组件直接装有依赖冲突风险放进容器里隔离干净升级也简单。用 1Panel 的网站功能做反向代理而不是手动写 Nginx 配置。飞书回调要求 HTTPS申请证书、续期、绑定域名的操作在面板里点几下就完成省去很多细节。飞书机器人走事件订阅模式而不是长连接模式。事件订阅配合 HTTPS 回调运维视角更清晰出问题可以直接看 Webhook 日志。2. 基础环境准备1Panel 安装与运行配置2.1 一台什么样的服务器才能跑得动 OpenClaw先别急着上高配。OpenClaw 本身是一个 Agent 运行时内存和 CPU 消耗主要取决于三块大模型 API 的请求并发、工具调用产生的临时数据量、是否还在本地跑了向量检索之类的组件。我的建议是最低 2 核 4G 内存、5M 带宽起步。这样的配置跑 OpenClaw 接飞书日常问答绰绰有余如果你打算同时跑本地 Ollama 做模型推理那至少得 4 核 16G再配一块支持 CUDA 或 Apple Metal 的卡。如果只是调用云端 API2 核 4G 足够磁盘 20G 也就够了因为 OpenClaw 的会话数据本质上是文本文件占不了多少空间。操作系统推荐 Ubuntu 22.04 或 Debian 12。这两者的内核版本对 Docker 支持比较好1Panel 的安装脚本也覆盖了绝大多数云厂商的镜像。不建议用 CentOS 7 之类的老系统依赖太旧后面装 Docker 和证书组件容易踩坑。2.2 1Panel 安装与初始化要点1Panel 的安装本身很友好官方给了一行命令照着执行就可以。安装完成后面板默认端口是 8090 之类的随机端口账号密码也是随机生成的会显示在安装成功的输出里。这里我提醒三个容易忽略的点安装完成后立刻到云厂商的安全组里限制面板访问端口只允许你自己的办公网 IP 访问否则面板暴露在公网上就是一个攻击面。1Panel 默认会帮你安装 Docker、Docker Compose、Nginx 等组件装的时候会提示选择镜像加速。国内机器建议选择一个可用的镜像加速后面拉取 OpenClaw 镜像会快很多。面板登录后第一件事设置好强制两步验证。1Panel 的后台能操作服务器上的所有容器和文件账号安全性值得认真对待。等面板起来之后你会发现界面里有“容器”、“编排”、“网站”、“数据库”几个模块我们主要用到的是“编排”和“网站”这两个。2.3 为 OpenClaw 规划数据目录与权限在 1Panel 里可视化操作之前我习惯先在服务器上把目录结构搭好避免后面数据权限混乱。mkdir -p /opt/openclaw/{data,config,logs} cd /opt/openclaw这三个目录的用途dataOpenClaw 的会话文件、知识库索引、定时任务记录。configOpenClaw 的配置文件和通道配置。logs独立日志目录虽然容器日志也能看但独立目录更适合长期归档。这里有一个我自己吃过亏的点容器的数据卷权限如果挂在宿主机上经常因为 UID 不一致导致容器内无法写文件。最省事的做法是把 /opt/openclaw 这个目录的属主改成容器内运行用户的 UID。通常在配置里指定以 1000:1000 运行宿主机上对应执行chown -R 1000:1000 /opt/openclaw如果不知道 OpenClaw 容器默认用什么用户跑可以先启动一个空容器看下或者直接在 Compose 配置里通过 user 参数指定避免权限纠结。3. OpenClaw 部署与初始化配置3.1 通过 1Panel 的编排功能创建 Compose 项目1Panel 的“编排”模块其实就是可视化编辑 Docker Compose 文件我个人非常推荐用这个方式而不是直接在服务器上敲 docker-compose up。原因很简单Compose 文件存在面板里以后改配置、重启、看日志都有统一入口。打开 1Panel → 容器 → 编排 → 新建编排填入以下内容services: openclaw: image: ghcr.io/你的命名空间/openclaw:stable container_name: openclaw restart: unless-stopped ports: - 18080:8080 volumes: - /opt/openclaw/data:/app/data - /opt/openclaw/config:/app/config - /opt/openclaw/logs:/app/logs environment: - TZAsia/Shanghai - OPENCLAW_MODEL_PROVIDERopenai - OPENCLAW_MODELgpt-4o-mini extra_hosts: - host.docker.internal:host-gateway这里解释几个关键点镜像名以你实际拉取到的为准我写 ghcr.io 只是示意。OpenClaw 的发行渠道可能在不同时间有变化大家到官方仓库看一下最新的镜像地址。端口映射 18080:8080 的意思是宿主机的 18080 端口转发到容器的 8080。这个 18080 只是内部回调端口不需要对公网开放后面会由 Nginx 反向代理到 443。extra_hosts 这一段是给容器里访问宿主机用的。如果你以后要接 Ollama、本地数据库就会用到 host.docker.internal 这个地址。保存并启动之后在 1Panel 的容器列表里就能看到 openclaw 容器。如果启动失败点击容器的“日志”按钮看到的输出信息比命令行更直观。3.2 配置大模型 API 接入OpenClaw 本身不绑定某个特定厂商它抽象出一个模型访问层。我的建议是先用兼容 OpenAI 格式的官方或中转 API把链路跑通后面再慢慢优化到本地模型或专属模型。在 Compose 环境变量里你需要关注的三个核心配置环境变量说明示例值OPENCLAW_MODEL_PROVIDER模型供应商类型openai / ollama / anthropicOPENCLAW_MODEL默认模型名gpt-4o-mini / deepseek-chatOPENCLAW_API_KEYAPI 访问密钥sk-xxxx如果你使用某个兼容 OpenAI 格式的国内模型服务可以额外配置 API 地址格式类似- OPENCLAW_API_BASEhttps://api.example.com/v1这里有一个非常重要的经验不要在生产环境用“反向代理大模型 API”这类不稳定的方式。我用过一段时间的非官方中转服务最后最大感受就是高负载时延迟飘忽、时不时 401出了问题排查很麻烦。如果预算允许优先选择官方 API 或大厂的合规服务稳定性完全不一样。在 1Panel 中修改环境变量后切记要点“重建容器”而不是“重启容器”。因为环境变量是在容器创建时写入进程环境的单纯 restart 不会让新的变量生效。这个细节我踩过不止一次。3.3 启动后的自检与基础验证容器创建完成后先看日志。第一次启动一般会看到模型连接初始化、通道注册、监听端口这些信息。如果日志停留在某个错误状态最常见的原因就两个API Key 不对或者某个目录没有写权限。我的自检流程# 确认容器状态 docker ps | grep openclaw # 查看最近日志 docker logs -f openclaw # 验证健康检查端口 curl -I http://localhost:18080/health如果 /health 返回了正常响应说明 OpenClaw 的 Web 服务已经起来。这时候还没接飞书之前你可以先用 OpenClaw 自带的命令行聊天功能测一下模型链路是否通顺。在容器里执行docker exec -it openclaw openclaw chat输入一句“你好介绍一下你自己”如果模型能正常返回说明中间最大的变量——模型连接——已经解决了。接下来把精力花在飞书通道上。4. 飞书机器人接入实操从开放平台到 OpenClaw 通道4.1 在飞书开放平台创建企业自建应用飞书机器人接入 OpenClaw第一步是在飞书开放平台控制台创建一个应用。登录管理员账号进入开发者后台选择“企业自建应用”填写名称和描述。注意如果你不是管理员需要找飞书管理员开通开发者权限否则看到的功能入口不全。创建完成后进入应用详情页按下面的顺序操作在“应用能力”里添加“机器人”能力一个按钮就能开。在“凭证与基础信息”页面拿到 App ID 和 App Secret后面要填到 OpenClaw 配置里。在“权限管理”里开通机器人需要的权限。权限这块是踩坑重灾区给一个比较完整的参考清单权限名称用途建议im:message接收用户发给机器人的消息必开im:message.send以机器人身份发送消息必开im:message.group_at_msg接收群里 机器人的消息群聊场景必开im:chat读取群列表和群成员信息处理群任务时建议开docs:document读取和写入云文档、多维表格如果你的 Agent 要处理表格必须开权限开通之后需要创建应用版本并发布发布后权限才会真正生效。公司内部应用一般审批很快甚至管理员直接点通过。很多同学遇到“机器人不回复消息”的问题八成就是权限还没生效或者应用版本没有发布。4.2 在 OpenClaw 配置飞书 ChannelOpenClaw 各个版本的配置文件位置略有差异但思路是一致的应用启动时会读取 config 目录下的通道配置文件把飞书 App ID 和 App Secret 填进去通道就会自动注册。我这次用的是 YAML 配置整体结构类似这样channels: lark: app_id: cli_xxxxx app_secret: 填写你的AppSecret verification_token: 填写事件订阅里的验证令牌 encrypt_key: 字段名在不同版本有可能调整以自己的配置模板为基准。这里重点解释两个概念verification_token 是飞书开放平台用来验证回调消息来源的防止伪造请求。在事件订阅配置页面可以生成。encrypt_key 是事件加密的密钥如果你在飞书后台勾选了“启用加密”就需要填没启用的话留空即可。我个人建议启用加密安全级别高一层OpenClaw 也能自动处理解密并不会增加太多配置负担。改完配置后回到 1Panel 重建容器。打开日志如果看到类似“lark channel registered”这样的输出说明飞书通道注册成功。4.3 回调地址发布与 HTTPS 配置飞书事件订阅要求回调地址必须是公网可访问的 HTTPS URL不能是 IP 直连也不能是 HTTP。这一步在 1Panel 里操作非常顺手不需要手动导 Nginx 配置。我的操作路径是1Panel → 网站 → 创建站点 → 反向代理 → 填入域名 → 后端地址指到 http://127.0.0.1:18080。创建站点之后别忘了申请 SSL 证书。1Panel 支持内建 Lets Encrypt 申请和自动续期绑定域名后几分钟就能生效。如果你已经有证书文件也可以直接上传。然后回到飞书开放平台的事件订阅页面订阅方式选择“将事件发送至开发者服务器”。请求地址填 https://你的域名/feishu/event 这样的路径。点击“保存”飞书会向这个地址发送一个 URL 验证请求。OpenClaw 收到后会正确响应。保存成功后再添加事件推荐先加这两个接收消息im.message.receive_v1接收群聊中 机器人消息im.message.receive_v1 里的群聊场景一般也绑定了具体按飞书后台提示选择。事件订阅配置完成后回到飞书应用里点击“启用机器人”再到飞书里搜索一下这个应用就能找到自家机器人。给它发一句消息OpenClaw 容器日志里会同步看到消息事件说明整条链路已经通了。4.4 能力落地发消息、发表格、写多维表格、定时任务机器人通了之后距离“能用”还差一步配置具体的能力。OpenClaw 支持通过提示词和工具让模型自主决定调用什么我的实际使用场景有三个供你参考。第一个场景是日常问答。飞书群里 机器人问一些只读类信息比如查某个项目的状态、生成一段周报文案。这时候 OpenClaw 直接调模型回答不需要额外工具几分钟就配好。第二个场景是发送表格。这是很多人需要的功能让机器人把某次任务的结果生成 Excel 或 CSV 文件发送到聊天里。OpenClaw 的工具调用里包含文件生成能力模型会把结构化数据写成表格文件再通过飞书消息接口发出去。我实际测试时让它把过去一个月的线上故障记录整理成表格生成速度令人满意而且能直接下载打开。第三个场景是多维表格读写。飞书多维表格本质上就是一个轻量数据库非常适合做 Agent 的记忆存储或业务数据管理。你可以在 OpenClaw 里配置一个“基础数据表”的写入工具然后让机器人接收自然语言指令比如“把今天运维组报上来的问题记录到多维表格”模型会自动解析字段并写入。定时任务是我比较看好的方向。在 OpenClaw 配置里加一个 cron 任务比如“每个工作日早上九点半从多维表格读取昨天未关闭工单汇总成表格发到群”。到点后容器会自动触发任务不完全依赖用户快来消息。4.5 会遇到的飞书机器人文件与消息类型坑飞书机器人发送文件走的是上传文件接口拿到 file_key 之后才能发送文件消息。市面上不少接入方案只处理了文本消息文件消息经常发不出去OpenClaw 这层已经封装好了你不需要自己拼接 API。真正要注意的是过期时效。飞书对临时素材文件有一个有效期Agent 生成文件后如果迟迟不发送等文件 key 失效就会发失败。解决方案很简单拿到文件后立刻发送不要中间搁置等待。我见过有人配置里写了很长的中间步骤结果文件在生成后 5 分钟才发刚好过期。另外飞书消息里的 markdown 格式和网页端不完全一致。在文本卡片里想换行必须显式写 \n不能靠模型自动生成“两个空格换行”这种习惯。这个细节如果不在提示词里约束机器人发出来的内容就会挤在一团。5. 常见问题与排查技巧实录5.1 报错 “agent failed before reply: session file locked” 的解决过程这个报错从网络搜索热度来看已经成为 OpenClaw 接入飞书的高频问题我自己也遇到过而且第一次遇到时一度以为是飞书配置错了。先描述一下现象机器人接收消息后模型在处理请求时失败飞书端收到一条错误回复OpenClaw 日志里出现类似 “agent failed before reply: session file locked (timeout 60000ms)” 的提示。先解释底层原因。OpenClaw 的会话体系是一个用户或一个群对应一个独立的会话文件这个文件负责保存上下文历史。为了保证数据一致性同一时间只允许一个写操作。当一个事件还没处理完另一个事件又试图写同一个会话文件时就会产生锁等待。如果等待超过默认的 60000ms框架就直接放弃输出 session file locked。为什么会出现并发写同一个会话我排查下来主要有三个来源飞书的事件重试机制。飞书在没收到成功响应时会隔一段时间重新推送同一个事件。如果第一次还没处理完第二次就来了就会撞锁。用户同时从多个设备给机器人发消息。比如手机和电脑同时打开同一个群两边各发了一条消息。定时任务和用户消息同时命中同一个会话。比如每秒跑一次的定时任务正在写会话用户刚好发来消息。定位方式其实很简单在 OpenClaw 日志里找到 session locked 前后的 request_id 和会话 ID再对照飞书后台的事件投递记录。如果时间戳上第二次请求几乎和第一次相差几秒那就是重试或并发挤兑。解决办法有三个层面在飞书开放平台的事件订阅里把事件重试间隔调长或确认回调已正确返回 200避免每次都触发重试。在 OpenClaw 配置里把会话锁超时从 60000ms 调整到业务可接受的范围比如 120000ms。但这只是缓解不能解决真正的并发问题。对不同会话使用独立配置让定时任务和手动消息分到不同会话目录从根源上减少锁冲突。我没有直接改代码去绕过文件锁而是用“任务规划”的方式规避定时任务只负责读取数据并写入另一个话题不占用主会话。实测下来效果好很多。5.2 飞书后台提示“回调地址验证失败”这个问题的出现频率也非常高而且有相当一部分情况是 OpenClaw 本身没起问题就是网络链路没通。我总结了一个排查顺序照着做基本可以快速定位先确认域名解析是否生效。在本机或服务器上执行dig 你的域名确认解析到了这台机器的公网 IP。确认 1Panel 防火墙有没有放行 443 端口。如果之前手动设置过 iptables 或 firewalld很可能 80 和 443 没有放行。在服务器上直接请求回调地址curl -k https://你的域名/feishu/event。返回一个 404 或者 405 都是正常的因为飞书校验请求会带 challenge 参数裸 GET 请求一定是错误响应。如果连接超时说明 Nginx 端口都没通。查看 OpenClaw 容器日志确认有没有收到这个验证请求。如果日志里完全没有任何记录说明请求根本没有到容器。如果是请求到了但响应格式不对检查 verification_token 和 encrypt_key 是否和飞书后台一致。这里我想专门强调一下路径问题。有些同学在 1Panel 反向代理时配置了子路径转发比如把 / 转发到 18080又在飞书后台填了 https://域名/feishu/event。这时 OpenClaw 实际收到的路径可能被改写了导致路由不匹配。所以我建议统一用根路径或统一的 /webhook 路径不要搞多层重写。5.3 模型 API 连接失败导致机器人无响应机器人能收到消息但迟迟没有回复OpenClaw 日志里出现模型调用失败这属于另一个高频问题。常见表现有connect timeout、401 unauthorized、rate limit exceeded。先说连接超时。如果你用的是境外模型服务国内服务器直连经常超时。解决方式不是绕道而是选择国内可用且合规的模型服务。这一点预算换稳定非常值。再说 401。这类错误多半是环境变量里的 API Key 不对或者填了别人的 key。在 1Panel 里进入容器的环境变量页面逐项核对。注意 Key 里可能不会有任何星号遮罩复制粘贴时千万别多空格。最后说 rate limit。OpenClaw 的会话可能因为配了“每隔几秒自动检查任务”而频繁调用模型很容易把 API 限额打爆。我的建议是把定时任务的触发频率设置到 30 分钟以上日常对话场景一般不会触发限流。另一个容易忽略的问题模型上下文过长导致超时。OpenClaw 默认会把整个会话历史带给模型如果群里闲聊内容很多输入 token 会膨胀。可以给会话加一个历史裁剪规则超过多少轮就把早期消息清理掉既省 token 又减少超时概率。5.4 1Panel 环境下排查容器和网络的小技巧在 1Panel 里排查容器的难度比纯命令行低很多但有几个技巧是面板上看不到的写在这里进入容器内部执行命令1Panel 的容器列表里有“终端”入口但有时因为 shell 路径问题打不开。用命令行进入更稳docker exec -it openclaw bash。查看容器启动参数和端口映射docker inspect openclaw | grep -A 20 ExposedPorts。查看容器内进程状态docker top openclaw如果 java 或 node 进程一直不见可能是初始化卡住了。另外容器内的时区问题。Compose 里已经设置了TZAsia/Shanghai但如果忘记设置OpenClaw 生成的定时任务可能全部按 UTC 时间跑。这就是为什么定时任务老是差 8 小时。碰到定时任务不准先检查容器时区再看飞书时区设置。6. 运维建议与后续扩展6.1 让 OpenClaw 长期稳定运行的几个小习惯这套方案跑起来之后运维压力其实不大但养成几个好习惯能让它更稳定。第一是定时备份。OpenClaw 的会话数据都在 /opt/openclaw/data 目录本质上就是文本文件备份成本极低。我用 1Panel 自带的计划备份功能每天把 /opt/openclaw 整个目录压缩传到对象存储或另一台备份机。出问题时恢复到前一天状态、重新拉容器几分钟就能回来。第二是升级策略。OpenClaw 更新迭代速度不慢每次升级前先看 release note升级之前手动备份数据目录。不要在生产环境用 latest 标签最好锁定一个具体的版本号确认稳定后再批量升级。第三是资源限制。Compose 里可以给容器设置 CPU 和内存上限防止某个异常进程把整台服务器拖垮deploy: resources: limits: cpus: 1.5 memory: 2G这个配置在 1Panel 编排界面里也能可视化设置。如果是 2 核 4G 的小机器我给 OpenClaw 限制 1.5 核、2G 内存给面板、数据库、Nginx 留出余量。6.2 从飞书扩展到更多工作场景OpenClaw 接入飞书只是起点通道层设计决定了它天然支持横向扩展。我后续计划比较明确一是把群里常见的“FAQ 问答”接到一个知识库索引上。用向量存储把历史文档切片用户提问后 Agent 先检索再回答准确率会高很多。二是把定时任务做得更细。比如每天定时把各渠道数据收集起来写入多维表格生成报表再把汇总图表发到对应群。这个过程完全不需要人干预。三是对接更多 IM。如果有些重要告警要发到其他平台同一套 Agent 内核可以再接一个额外的通道不同通道指向不同场景互不干扰。6.3 最后分享一个小技巧我在实际使用中发现OpenClaw 的会话策略对飞书机器人体验影响很大。把群里所有消息都灌进同一个上下文聊久了模型会“变笨”因为无关信息太多了。比较好的做法是按照群、按人、按主题拆分会话让每个会话保持短小精悍。具体操作方式就是在配置里限制“单会话消息最长保留 N 轮”超过后自动归档。这样既保留了上下文连续性又不会让模型负担过重。还有一点是关于体验细节飞书卡片的交互能力很强但第一次调试时别急着做复杂按钮。先把文本消息和文件消息跑通让用户觉得“这个机器人确实能帮我干活”再逐步加上审批按钮、任务确认、报告导出这些交互节点。毕竟Agent 真正被团队接受不是看它有几十个工具调用能力而是看它能不能在日常工作里减少十分钟以上的重复劳动。