最近被好几个朋友问到同一件事怎么把 OpenClaw 这个开源智能体框架部署起来还要能接到飞书里用。我自己在 1Panel 上完整跑通了这套流程从装面板到飞书机器人回复第一条消息大概花了一个多小时中间踩了几个不小的坑。这篇文章就把整个链路拆开讲透——为什么选 1Panel OpenClaw 飞书这个组合、每一步具体怎么操作、以及网上搜不到的那些报错到底怎么解决。先给结论这套方案适合手头有云服务器或者家里常开的机器、团队日常用飞书、想给群里加一个能自主执行任务的 AI 助手的人。OpenClaw 负责智能体本身1Panel 负责把容器环境和日志管理得明明白白飞书则是最贴近日常工作的交互入口。文章里所有操作步骤、配置参数、坑点排查都是我实际跑过的不是抄文档。1. 方案拆解为什么是这三个东西凑在一起1.1 OpenClaw 到底是个什么玩意OpenClaw 是一个开源、可自托管的 AI 智能体框架。你可以把它理解成一个“数字员工”它连上大模型以后不只能跟你聊天还能调用工具、读写文件、执行命令、管理长期会话。跟普通聊天机器人最大的区别是它有“记忆”——同一个会话里它能记住上下文跨多次交互累积任务状态甚至在被唤醒后自主完成一整条任务链路。“自托管”这三个字才是选它的核心理由。数据在自己的服务器上token 消耗自己可控规则自己定不依赖某个封闭的云平台。网上常拿它跟 workbuddy 之类的商业智能体比但那些工具要么收费、要么数据在别人手里对很多团队来说这两条就劝退了。OpenClaw 当然也有学习成本但一旦跑通它就是完全属于你的东西。1.2 1Panel 解决的是运维层面的问题如果纯用命令行 docker run 来部署其实也能跑但后续维护很痛苦端口冲突排查、环境变量写错导致容器反复重启、日志找不到、忘了容器挂载了哪个目录……这些问题在 1Panel 里全都变成了网页上的可视化操作。1Panel 是一个开源的 Linux 服务器管理面板内置 Docker 环境管理、容器编排、实时日志、资源监控、反向代理等功能。尤其是“编排”功能把 docker-compose 的 YAML 配置做成图形化落地入口对想用容器又不想背命令的开发者非常友好。我选它的原因很简单容器状态、日志、重启策略、磁盘占用全部一眼可见排查问题能省一半时间。1.3 飞书不只是聊天窗口是工作流的入口很多人以为接飞书就是把机器人消息转发一下实际上飞书开放平台的机器人能力远不止这些可以发富文本卡片、可以发表格、可以接收群里 的消息、可以读写多维表格。这意味着智能体能真正嵌入团队的工作流里而不是一个孤立的聊天窗口。对国内团队来说飞书本身就是沟通和协作的主阵地。把智能体接进飞书等于让团队每个人都能用最熟悉的工具去调用 AI 能力不需要额外装客户端、学新系统。这也是为什么“飞书 agent 搭建”这类词条搜索热度一直很高——需求是真实的缺的只是一份能落地的教程。2. 动手前先把这几件事准备好2.1 服务器配置与 1Panel 安装OpenClaw 本身的资源占用不算夸张我用的是一台 2C4G 的云服务器实际跑起来内存占用稳定在 1.5G 左右。如果你要同时跑多个智能体或者接入大量群聊建议上 4G 内存这钱别省后面 OOM 排查更折腾。如果你暂时没有 Linux 服务器想在 Windows 11 上先做验证也不是不行——通过 WSL 或者虚拟机装 1Panel 都能跑通。但我不建议长期这么干智能体这玩意儿要 7x24 在线才有价值放在常开的云服务器上才是正解。1Panel 官方提供了一键安装脚本装完会在终端输出面板访问地址和随机生成的初始账号密码。默认端口是 8443首次访问会提示自签名证书不受信任选择“继续访问”就好。这里提醒一句装完第一件事就是改掉初始密码并开启两步验证面板暴露在公网上被扫到可不是闹着玩的。2.2 飞书开放平台先建应用再想别的接入飞书的凭证要在飞书开放平台open.feishu.cn里创建。流程是这样的用管理员账号登录选择“创建企业自建应用”名称随意比如“团队智能助手”。创建完成后进入应用详情页在“凭证与基础信息”里找到 App ID 和 App Secret。App ID 一般是cli_开头的一串字符App Secret 是一长串密文这两串后面要填到 OpenClaw 的配置里。在“添加应用能力”里勾选“机器人”让应用具备机器人身份。如果你是个人开发测试可以用飞书提供的“测试企业”环境创建应用不需要真实企业的管理员审批。但要正式给团队用就得走企业管理员审核流程并且发布应用版本后机器人才对所有人可见。这个审核流程建议提前走因为可能耗时几个小时到一天不等。2.3 端口、目录、数据卷规划部署前花两分钟把下面这几个东西定下来能避免后期返工1Panel 面板端口默认 8443安装时可改。OpenClaw 服务端口我用的 8080在容器编排里映射只要不跟已有服务冲突即可。数据持久化目录/opt/openclaw挂载进容器放配置、会话文件、日志。目录规划是最容易被忽略但又最关键的一步。OpenClaw 的会话是文件型持久化的如果数据卷没挂好容器一重建所有会话和配置全丢相当于白部署。记住一个原则一切有状态的数据都要进数据卷容器本身要随时可以删了重建。3. 在 1Panel 中部署 OpenClaw 的完整操作3.1 用编排功能创建容器1Panel 的“编排”功能就是 Docker Compose 的图形化入口。在“容器 - 编排 - 创建编排”里把下面的配置填进去services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - 8080:8080 volumes: - /opt/openclaw/data:/app/data - /opt/openclaw/logs:/app/logs environment: - TZAsia/Shanghai - OPENCLAW_CHANNELfeishu - FEISHU_APP_IDcli_xxxxxxxxxxxxxxxx - FEISHU_APP_SECRETxxxxxxxxxxxxxxxxxxxxxxxx - LLM_PROVIDERanthropic - LLM_API_KEYsk-ant-xxxxxxxxxxxxxxxx - LLM_MODELclaude-sonnet-4-xxx logging: driver: json-file options: max-size: 50m这里先说明一下OpenClaw 迭代很快不同版本的镜像名和环境变量命名可能有差异。上面的配置是当前社区主流的写法我建议提交前先去官方仓库确认一下最新文档里的变量名避免因为版本差异白折腾。填完配置后点击提交1Panel 会自动拉取镜像并创建容器。第一次拉镜像会比较慢取决于服务器跟镜像仓库之间的网络状况几分钟到十几分钟都正常。容器状态可以从“启动中”变成“运行中”这一步就算过了。3.2 LLM 模型后端的选型与参数OpenClaw 本身不含大模型它需要连接一个 LLM 后端才能干活。主流选择是 Anthropic Claude 系列、OpenAI GPT 系列以及各类兼容 OpenAI 协议的服务商。我个人用的是 Claude 的 API理由很直接Agent 类任务对长上下文理解和工具调用稳定性要求极高Claude 在这块的表现确实更稳。如果你已经买了其他家的 API也没问题把 provider 和 api key 换成对应的值就行。比较懒人的做法是选兼容 OpenAI 协议的接口因为这类接口在大部分框架里的兼容性都是最好的。参数上有一条建议max_tokens别设太小。Agent 执行任务时经常要处理工具返回的长文本、再二次推理生成最终结果输出空间留够能避免生成到一半被截断的尴尬。如果你跑的是代码生成类任务这个参数往大了设基本没错。3.3 启动后的三个检查动作容器起来后别急着去飞书发消息先花一分钟看日志。在 1Panel 的容器列表里点击“日志”重点观察三件事渠道配置是否成功加载有没有跟飞书相关的初始化日志。是否成功连接到 LLM 后端API key 有没有被拒绝。消息监听是否启动端口是否正常监听。正常情况下日志末尾会出现类似feishu channel started的信息。如果看到 ERROR先别慌逐个核对环境变量——尤其是 App Secret复制的时候很容易漏掉末尾的字符这种低级错误我犯过不止一次。4. 快速接入飞书两边对暗号4.1 飞书后台的事件订阅与权限容器跑起来只是第一步飞书这边还得把事件推送配好两边才算真正“对上暗号”。回到飞书开放平台的应用管理页做三件事在“事件与回调”里配置订阅方式。推荐用长连接模式OpenClaw 支持的话就优先用它好处是不需要把回调地址暴露到公网对服务器没有公网 IP 或者不想配反向代理的场景特别友好。如果只能用“请求地址”模式那就要在 1Panel 里配置反向代理把公网 HTTPS 请求转发到 OpenClaw 的 8080 端口。添加事件im.message.receive_v1接收消息。这个事件负责把用户发给机器人的消息、群里 机器人的消息推送给 OpenClaw。在“权限管理”里确保开通以下权限读取单聊消息、读取群组消息、以机器人身份发送消息。对应的 scope 在飞书后台可以直接搜索添加常见的是im:message和im:message:send_as_bot这两个。提示飞书权限改完后应用必须重新发布版本才会真正生效。这个坑我踩过一次——后台加了权限OpenClaw 那边调用接口还是提示无权限折腾半天才发现是没点发布。4.2 OpenClaw 侧的飞书凭证OpenClaw 要连接飞书需要知道应用的 App ID 和 App Secret。把这两个值填到第 3 章的 compose 环境变量里FEISHU_APP_ID和FEISHU_APP_SECRET然后重新部署容器。如果你改了环境变量后想更新容器不用删了重建直接编辑容器配置里的环境变量保存后 1Panel 会基于新配置重建容器。重建后同样去日志里确认飞书长连接是否建立成功。看到连接成功的日志说明 OpenClaw 已经在“听”飞书的动静了。4.3 首条消息验证与进群在飞书里找到这个应用机器人发起单聊随便发一句“你好”。如果配置没问题几秒内会收到机器人回复。这里多说一句如果你刚创建应用还没发布版本只有应用管理者也就是你自己能搜到并跟机器人对话这是测试阶段的正常现象。单聊验证通过后把机器人拉进一个测试群然后 机器人下一个具体任务比如“帮我整理一下这段文字里的重点”。注意一个细节很多企业默认机器人进群后群成员 它是没反应的需要在飞书后台把机器人的可用范围改成全员或者把机器人设为群管理员。这个条件不满足群里 怎么都不回非常容易让人误判。5. 实测让智能体在飞书里真正干活5.1 从问答到知识检索接入飞书后我第一个接的场景是知识库问答。OpenClaw 支持连接外部知识源比如你本地的笔记库这也是“openclaw obsidian”这个词有热度的原因。我的做法是在服务器上放一份团队共享的 Markdown 笔记目录把它挂载给 OpenClaw然后在飞书群里直接问“我们上周的会议纪要在哪”“线上环境的部署文档里有几步”它就能去对应目录检索并返回摘要。实测下来的感受是笔记格式规整、层级清晰的情况下准确率相当能打。但如果笔记本身很乱它也会一本正经地胡说八道。所以知识库场景的正确姿势是先定好目录规范别一股脑把所有文档都丢给它。5.2 让机器人给群里发表格飞书机器人发纯文本结构化数据一多就看花眼。OpenClaw 处理表格类输出的思路是转成 Markdown 表格发出去飞书客户端会自动渲染成类似卡片样式的表格观感比纯文本强太多。如果你需要的是真正的表格文件比如 Excel两条路可以走一是让 OpenClaw 先生成 CSV 或 XLSX 文件再通过飞书上传文件接口发出来二是封装飞书消息接口的 post 消息类型用富文本结构实现表格效果。网上搜“飞书机器人发送表格”会有大量代码片段但其实让 agent 自己生成文件再推送才是最省事的路径——你只需要在提示词里说清楚格式要求。5.3 多维表格联动把智能体做成数据入口飞书多维表格是很多人没意识到的宝藏。理论上OpenClaw 可以通过飞书开放 API 读写多维表格的数据定时把监控脚本的输出写入一张表或者直接在群里说“把这条加到待办表格里”agent 自动完成新增记录。要实现这个场景核心是给 OpenClaw 封装“工具调用”——把多维表格的增删改查封装成函数注册到它的工具列表里。这样它就能理解“新增记录”“查询记录”“更新状态”这些操作。这个方向我还在完善中但架构思路是确定的OpenClaw 提供工具调用机制飞书提供数据存储和展示中间用 API 打通即可。6. 常见问题与避坑手册6.1 session file locked (timeout 60000ms) 怎么解这个报错我必须放在第一位因为它折磨了我快一个晚上。完整报错长这样agent failed before reply: session file locked (timeout 60000ms)。原因说起来并不复杂OpenClaw 用文件型持久化会话来保存对话状态每个会话对应一个 session 文件。当两个进程同时尝试读写同一个会话文件时后到的进程会等锁释放等超过 60 秒就抛这个错。最常见的触发场景有两种容器被启动了多个实例。比如在 1Panel 里创建编排后又手滑用命令行docker run了一个两个容器共享同一份数据卷就会疯狂抢锁。上次容器被强制杀掉锁文件没清理干净。服务器断电、docker 重启都可能导致遗留的 .lock 文件一直占着锁。我的排查和修复步骤执行docker ps -a | grep openclaw看是不是有多个容器实例。如果有多个全部停掉只保留一个删除多余容器。进入数据目录删除名字里带.lock的遗留锁文件。重启容器再测一次。注意生产环境务必保持单一实例同一个数据卷绝对不要同时挂给多个容器。这是这类报错的根本解药。6.2 飞书机器人没反应日志也不报错这类问题最让人抓狂因为两边看起来都是正常的。我遇到过一种典型情况飞书后台事件订阅配好了OpenClaw 日志也显示连接成功但发消息就是不回。当时怀疑过网络、怀疑过版本最后发现是应用根本没发布。排查顺序建议照这个来看 OpenClaw 日志里有没有收到消息的记录类似message received。有的话问题出在 agent 侧没有就继续往下查。确认应用是否发布了版本。测试企业的应用默认只有创建者自己可用其他人拉机器人进群事件根本不会推送过来。检查飞书后台“机器人”能力里的可用范围设置把它改成全员可用。确认事件订阅模式没问题。长连接模式下如果网络有波动连接可能断开而不会自动重连需要看日志里的心跳。6.3 “飞书没有 CLI 权限”到底是什么意思“飞书没有 CLI 权限”这类词条的热度很高背后其实是一类问题OpenClaw 或者你写的脚本在调用飞书接口时收到了权限不足的报错。绝大多数情况下是两个原因应用没申请对应的 scope 权限。每个飞书 API 接口都有对应的权限点调用前必须先在后台申请。权限申请了但没重新发布应用版本权限根本没生效。还有一个容易踩的地方部分接口要求“应用商店应用”或“企业自建应用”的不同权限等级。比如读取用户手机号这种敏感信息自建应用需要管理员额外审核普通 scope 申请了也没用。遇到权限报错先回后台查 scope再确认版本状态别急着去改代码。6.4 容器反复重启和中文乱码容器无限重启是部署 agent 类应用最常见的坑。先看日志是不是有 OOM内存不足的记录如果是加内存或者减少同时打开的会话数。如果日志没问题再用docker inspect看容器的健康检查配置是不是写坏了。中文乱码的坑也很经典compose 环境变量里加上TZAsia/Shanghai一般就能解决同时确保基础镜像里带了对应语言编码。最后说说我这个组合用下来的真实感受。最有价值的不是“AI 多智能”这种抽象体验而是它把一堆原本要手动拼装的活变成了一句对话的事——现在我在飞书群里让它整理当天摘要、汇总表格、查文档它都能直接交付结果。如果你也想搭一套我的建议是别一上来就追求复杂功能先把单聊跑通再拉群、再接工具、再上多维表格联动每一步都验证没问题了再往前走。过程中遇到报错不用慌先看日志、再查版本、最后才怀疑配置——按这个顺序排查绝大多数坑都能绕过去。希望这篇记录能让你少走几个我走过的弯路。