1. 为什么非得本地部署一套龙虾再接飞书1.1 这个项目到底是干什么的先交代一下背景。同事搞了个开源的智能体框架项目代号 Openclaw社区里习惯叫它龙虾——因为这个项目最特色的工具调用模块做得很像龙虾钳子夹住哪个外部能力就往里拽。我们当时手头有一堆重复性工作比如内部知识问答、周报汇总正好拿它当试验田本地跑一份服务接上团队日常用的飞书让龙虾以一个机器人身份出现在工作群里。后面我统一用龙虾来代称它。它做的事情可以简单理解为一个能听懂自然语言指令、而且会调用各种工具的 AI 助手进程。跟打开网页版对话框不一样的是它可以自己写脚本、生成文件、调外部接口全流程自动化。这篇文章的主角不是某个大模型而是围绕怎么把这样一个本地 AI 助手稳妥地接到飞书里并且让它在群里把 PPT 好好展示出来这一整套链路。1.2 选本地部署而不是直接用云服务的三个理由很多人会问既然对接的是外部大模型 API为什么不在云端租个服务非要本地部署我当时的考虑非常实际数据不出内网。内部周报、项目方案里全是团队敏感信息走第三方云服务总觉得心里没底更何况还要长期跑。成本可控。智能体框架本身是开源的只有调用大模型接口时才按量付费本地部署只搭一台普通服务器。定制自由度。插件、提示词模板、文件生成路径这些全在本地改想怎么折腾怎么折腾不用受平台约束。当然本地部署的代价就是所有坑都得自己踩。部署、鉴权、网络、异常处理一个都跑不掉。这里先把话放前面后面讲到的每个问题几乎都不是照着文档做就能避免的而是要在真实环境里反复试错才会暴露出来。1.3 飞书在前、PPT在后真实使用场景是什么样的起因其实特别朴素每周五下午周会要有人把本周进展整理成 PPT十几页从数据到结论每次都是重复劳动。我们的想法是在飞书群里喊一声龙虾把本周周报做成 PPT机器人自己完成从大纲、内容组织到生成 .pptx 文件的整个流程再把成品直接在飞书里展示。注意这个展示才是关键。它不是发一个文件卡片让同事下载而是点开就能预览、能全屏放映。这一步卡了我整整两个晚上。当时第一个版本能发文件和能展示完全是两回事群里收到的就是一个下载入口手机端点开还会跳第三方 Office 应用团队直接炸锅。所以标题里那个PPT展示问题本质上是文件传输成功和内容可预览之间隔着一整层飞书的云文档导入逻辑。2. 从零部署环境、配置、命令行首跑2.1 环境要求与依赖安装我们的环境是一台 Ubuntu 22.04 的本地服务器8G 内存没有显卡纯 CPU 跑智能体框架绰绰有余真正吃算力的是外部大模型 API。部署前需要准备的东西如下Python 3.10 及以上Git服务器能正常访问外网因为大模型 API 和飞书开放接口都部署在公网安装步骤不复杂按顺序执行就行git clone 项目仓库地址 openclaw cd openclaw python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt cp .env.example .env这里有个细节我要专门提醒尽量不要图省事直接跑在系统 Python 环境里。后面调试飞书 SDK、python-pptx 这些依赖时虚拟环境能帮你省掉大量改了这个包影响那个包的麻烦。我们团队后来有一次升级依赖导致系统 Python 环境崩掉花了整整半天才清理干净从那以后所有项目一律强制走虚拟环境。2.2 配置文件里最容易翻车的地方第一次运行前需要把大模型 API 的 key 填进 .env大致长这样LLM_API_KEYsk-xxxx LLM_BASE_URLhttps://api.xxx.com/v1 LLM_MODELgpt-4o-mini MAX_TOKENS8192最容易翻车的是 LLM_BASE_URL 和模型名不对应。很多兼容接口的模型名跟官方文档不一样填错了启动时没有任何报错但是一问话就回model not found。建议先把这三个参数在终端里用官方 SDK 单独跑一个最小请求确认能通再继续别等接完飞书才发现是模型名写错了。另一个坑是临时文件目录。龙虾默认把生成的中间文件放到 ./tmp 下如果你的部署目录是个只读挂载后面生成 PPT 时就会出现莫名其妙的写入失败。我习惯显式指定一个独立数据目录mkdir -p /data/openclaw/tmp echo TMP_DIR/data/openclaw/tmp .env2.3 先把龙虾在终端里喂饱再谈接飞书配置完成后先启动 CLI 交互模式做冒烟测试。我强烈建议不要一上来就接飞书否则到时候你根本分不清到底是框架问题、网络问题还是飞书配置问题。终端里能正常对话、能调工具生成文件了再谈下一步。python main.py --cli 帮我生成一份测试用的 hello.pptx [工具调用] pptx_generator - /data/openclaw/tmp/hello.pptx看到这个输出说明龙虾的手已经能干活了。此时心理上也可以放轻松一点——框架本身没问题后面接飞书遇到的每个报错都是可以在日志里定位的。接下来才进入真正折磨人的接入阶段。3. 飞书机器人接入的真实链路应用、事件、长连接3.1 在开放平台建自建应用并开机器人的门接飞书的第一步是在飞书开放平台创建一个企业自建应用。这里有几个容易忽视的权限点我直接列出来机器人能力必须单独开启在应用能力里点开机器人。接收消息需要开通消息读取相关的权限比如im:message和im:message:readonly。后面要导入 PPT 到云文档还需要开通云盘文件读写权限具体是drive:drive这一组。如果希望机器人能发消息卡片还需要给im:message:send_as_bot权限。创建完成后你会拿到 App ID 和 App Secret这两个相当于账号和密码别写进代码仓库。我的习惯是放到 .env 里并且把 .env 的文件权限设为仅部署用户可读。权限这里还有个非常隐蔽的坑自建应用修改权限后很多权限需要创建版本并发布才真正生效。我第一次加完权限以为直接就能用结果调接口继续提示权限不足卡了半天才发现是版本没发布。如果你遇到配置明明是对的但接口说没权限先去后台看看应用版本状态。3.2 为什么本地部署必须用长连接而不是回调URL这是整篇文章里我觉得最值得展开的一个点。飞书机器人接收消息有两种模式一种是传统的事件回调 URL即飞书把用户消息 POST 到你提供的公网地址上另一种是长连接WebSocket由你的程序主动连上飞书的网关实时收事件。问题就出在第一种模式上你的本地服务器没有公网回调地址。有些方案会建议把本地服务暴露到公网但生产环境这么干特别不省心域名、证书、连接质量都要长期维护而且容易出现回调地址不稳定导致事件丢失。飞书官方后来主推的长连接模式就是为本地部署这种场景准备的——它不需要公网入口只要服务器能主动连上飞书网关就行。操作上在应用后台的事件与回调里选择使用长连接接收事件然后让龙虾用飞书官方 Python SDK 建立连接。SDK 内置了长连接支持启动后日志里能看到连接成功的状态。这一步走通后群里 机器人 的消息就能实时被本地程序收到整个过程不需要任何公网端口。这里我附带一个经验长连接模式下飞书 SDK 是有自动重连机制的但你要确保主进程没有异常退出。后面我把它注册成了 systemd 服务Restartalways这样进程挂了能自动拉起长连接也不会处于看似连着其实已经断的诡异状态。3.3 鉴权与事件签名最常见的两个报错即便用了长连接还是绕不开鉴权。飞书服务端调用你的逻辑时需要校验来源反过来你的程序调用飞书接口时也要出示身份。我们当时遇到的报错九成是下面这两个。第一个是tenant_access_token获取失败。这个 token 要用 App ID 加 App Secret 去换常见原因是 App Secret 填错或者应用状态是未启用。在开放平台把应用状态改成已启用之前很多接口调用都会被拒绝而且报错信息往往不太直白要翻日志才能看到根因。第二个是事件签名校验失败。长连接模式下 SDK 会自动做加密密钥校验但如果 .env 里没填 Encrypt Key或者填的跟开放平台后台不一致SDK 启动时就会报签名错误。排查方法很简单去后台事件与回调页面复制 Encrypt Key跟 .env 里逐字符比对一个字符都不能差。我那次就是因为复制的时候多带了一个空格排查了半个小时才找到。还有个小细节消息推送到本地后要确认代码里正确调用了消息处理器否则会出现机器人明明收到消息但没有任何反应的假象。建议在入口打一行调试日志把收到的消息内容和 event_id 都打出来后续排查会非常顺。4. PPT生成链路从一句话到一份.pptx4.1 让龙虾按大纲生成PPT的工作流设计机器人能收消息之后接下来的核心问题是怎么让它产出像样的 PPT。早期我把整个流程设计成一条链路分解成四步用户 机器人 发送指令比如把 /docs/本周周报.md 做成 PPT风格简洁每页不要超过 4 个要点。龙虾读取指定文件内容调用大模型生成结构化大纲。大纲是一个 JSON 数组每个元素对应一页包含标题、要点列表和备注。龙虾调用本地 PPT 生成工具把 JSON 逐页渲染成 .pptx 文件。工具返回文件路径龙虾再把文件上传到飞书并完成展示。这里最关键的是第 2 步的大纲质量。直接让大模型生成一个 PPT通常很空一定要在提示词里约束每页的信息密度。我们最终用的模板大致是你是PPT设计助手。请把下面的材料整理为PPT大纲。 要求 - 8到12页 - 首页为标题页最后一页为结论页 - 每页只有1个核心观点要点不超过4条 - 输出严格JSON不要markdown代码块标记对大模型输出做 JSON 解析时有个实战细节先剔除可能的围栏符号比如以 开头结尾的内容再调用 json.loads否则你会看到各种各样的解析崩溃。我们还加了一步校验解析后必须是一个列表列表里的每个元素必须包含 title 字段不合格就让模型重新生成一次。4.2 python-pptx生成文件字体、图片、体积三个坑生成 .pptx 我最终选了 python-pptx原因很简单它直接操作 XML不依赖本机安装 Office纯净服务器环境下也能跑。但实际用起来有三个坑非常典型提前排掉能省很多事。第一个是字体。服务器上如果没装中文字体生成的幻灯片里中文会全部变成方块或者被替换成难看的默认字体。解决办法是先装 Noto CJK 字体apt-get install -y fonts-noto-cjk fc-cache -f然后在 python-pptx 里显式给每个文本块设置中文字体名推荐用微软雅黑或Noto Sans CJK SC。这里不能指望默认主题帮你兜底逐段设置才可靠。我当时偷懒只设置了标题字体正文全部 fallback 成宋体预览效果惨不忍睹。第二个是图片。如果 PPT 里要放截图或配图图片路径必须用绝对路径不要在代码里写相对路径因为机器人当前工作目录跟预期经常不一致。另外大图会迅速撑爆文件体积建议在插入前统一把图片压缩到宽度 1024px 以内既保证清晰度又不至于让文件失控。第三个是体积。聊天场景下文件上传有体积上限PPT 太大就发不出去。我们当时的优化策略是所有底图压缩、不使用高分辨率位图当背景、能用矢量色块就用矢量。生成完成后脚本里加一行检查if os.path.getsize(pptx_path) 20 * 1024 * 1024: raise RuntimeError(PPT文件超过20MB请压缩图片后重试)留出一点余量是为了给后面导入云文档阶段的处理腾空间。5. PPT展示问题的根因排查从发不出去到没法预览5.1 现象一文件消息发出来了却只能下载不能预览第一个版本龙虾用飞书的消息接口把 .pptx 当文件发了出去。群里确实能看到一个文件卡片但点开是下载紧接着跳到本地 Office 应用手机上更麻烦直接弹第三方编辑器。团队的反馈非常直白我们要的是能直接点开看的。这就是标题里那个PPT展示问题的第一个核心矛盾。为什么会出现这种结果因为消息接口里的文件消息类型本质上是把一个二进制文件传给聊天窗口飞书只负责保存和分发不会去做格式解析和渲染。想要点开即预览必须绕过这一层把 PPT 导入为飞书的在线云文档再把这个云文档的卡片或链接发到群里。注意这一步不是把文件换个消息类型就能解决的。它涉及飞书开放平台另一组完全不同的接口——云文档导入能力。我从文档里看到这条路径的时候第一反应是终于有救了第二反应是又要啃一坨新 API 了。5.2 现象二导入云文档接口一直返回超时转向云文档导入后我按标准流程走了一遍总共三步用上传接口把本地 .pptx 作为媒体文件上传拿到文件标识。创建导入任务告诉飞书我要把这个 pptx 转成云端幻灯片。轮询任务状态直到拿到一个代表在线文档的标识。第一步就踩了大坑。导入云文档要用的上传接口是云盘域下的媒体上传而不是即时消息域下的文件上传。两个接口都能传文件但拿到的文件标识不通用。我第一次用错创建导入任务时直接报了文件类型不支持。轮询环节也容易翻车。导入一个十几页、带图片的 PPT 通常要几十秒甚至更久不能请求一次就放弃。我们的轮询逻辑是每 2 秒查一次最多等 120 秒import time resp client.drive.v1.import_task.create(...) ticket resp.data.ticket for _ in range(60): time.sleep(2) result client.drive.v1.import_task.get(ticketticket).data if result.job_status 0: doc_token result.token break else: raise TimeoutError(导入超时)真遇到超时先别慌看返回里的错误码。我们当时碰到过文件过大的报错也碰到过目标文件夹标识无效——导入任务要求挂载到云空间里一个真实存在的文件夹上随手填个字符串肯定不行。先建好一个专门放 AI 生成内容的文件夹把它的标识配置到 .env 里。还有一个细节老式的 .ppt 格式导入支持有限必须先转成 .pptx 再走流程。我在插件入口直接加了一道格式检查文件名后缀不是 .pptx 就拒绝进入导入阶段避免用户传个旧格式文件过来然后卡在导入超时。5.3 现象三在线预览出现乱码和排版崩坏导入成功、链接也发出去之后又冒出了第三层问题在线预览时的排版崩坏。具体表现是某些页面的文字挤在一起字体全变成了默认衬线体图片比例也不对。排查下来原因主要有两个。第一是源 PPT 里用了自定义特殊字体。飞书的在线渲染引擎只能识别它支持的那批字体其他字体要么被替换成默认要么造成字形错位。解决方法是回到生成环节全篇统一用微软雅黑和 Noto Sans CJK SC颜色、加粗这些用标准属性控制不要引入第三方字体文件。第二是幻灯片尺寸。我们最开始用的是 python-pptx 默认的 4:3 比例而飞书在线幻灯片默认按 16:9 处理两边不一致就会出现内容被裁切或留白过多。统一改成 13.333 x 7.5 英寸后大部分排版问题都消失了prs.slide_width Inches(13.333) prs.slide_height Inches(7.5)还有个更隐蔽的问题是形状的阴影效果。python-pptx 写出来的某些阴影在飞书渲染引擎里会被异常放大导致元素重叠。我在模板里干脆把所有形状的特效全部关掉用色块层次代替视觉层次效果反而更干净。这个现象在本地 Office 里完全看不出来只有在线预览才现形特别容易漏掉。5.4 最终方案落地上传-导入-发链接三步走把上面所有坑填平之后最终稳定运行的流程是这样龙虾生成 .pptx 到本地临时目录做文件体积和格式检查。调用飞书云盘媒体上传接口拿到文件标识。创建导入任务固定参数为.pptx格式挂载目录指向团队共享文件夹。轮询导入结果拿到在线文档标识。发送一条消息卡片把点击查看PPT做成按钮跳转链接指向上一步拿到的在线文档。还有一个体验层面的优化因为生成加导入整个流程可能要一分钟机器人必须先回复收到正在生成 PPT预计 1 分钟等真正成功后再发链接。这样用户不会对着一个半天不吭声的机器人反复 。我们最开始没做这步用户以为机器人挂了连续发了好几条结果任务队列里积压了三个生成请求整个服务差点被拖垮。6. 跑通后的可靠性优化和一点个人心得6.1 定时任务与消息风暴防护正式给团队用之前我做了三件可靠性优化。第一是把龙虾注册成 systemd 服务加上自动重启策略长连接断开后进程会自动拉起。第二是给机器人入口加任务队列PPT 生成属于重操作同一时刻只允许一个任务在跑其他请求排队并提示当前已有任务在处理。第三是消息发送合并群里一次性收到多条消息会被限流所以结果消息统一串成一条发出。[Unit] DescriptionOpenClaw Agent Service Afternetwork.target [Service] Typesimple WorkingDirectory/data/openclaw ExecStart/data/openclaw/.venv/bin/python main.py --feishu Restartalways RestartSec5 EnvironmentFile/data/openclaw/.env [Install] WantedBymulti-user.target日志也非常重要。龙虾的日志默认打到标准输出在 systemd 下可以用 journalctl 查看。我把日志级别调成 INFO并且在飞书消息处理入口加了结构化日志每一条消息都记录事件 ID、用户 ID、指令内容。后面不管谁出问题都能快速定位是哪个环节。6.2 把PPT大纲做进提示词模板跑了一段时间后我发现最有价值的改动不是代码而是把各团队的 PPT 风格沉淀成提示词模板。市场团队要看故事线技术团队要看数据对比不同团队的诉求完全不一样。我给龙虾配置了多套模板指令里带上风格技术周报就能走对应的大纲生成逻辑。比如技术周报模板会重点约束必须包含本周数据、风险项、下周计划三块数据对比页必须用统一表格结构结论页必须落到建议/行动项。这样生成的 PPT 至少骨架是对的人工只需要微调措辞不用再从头搭结构。6.3 踩完这些坑之后我更推荐的做法最后说点掏心窝的话。本地部署加飞书接入这套组合上限很高但运维成本也确实存在。如果你们团队只是偶尔要几个 PPT别学我这么折腾直接用现成的办公工具更划算。但如果你有批量生成、周期汇总、内部数据不能外传这类硬需求那这套东西的价值就非常明显。至少在我们这边每周的进展汇报已经稳定跑在群里喊一声、龙虾出 PPT、飞书在线预览这条链路上。而且这套上传-导入-发链接的展示思路不只是 PPT 能用换成导出 PDF、数据表格、甚至是长图报告逻辑都是通用的。下次再遇到类似需求我大概不会再被文件发出去不能预览这种表象带偏——先想清楚预览在目标平台上的真实形态再去翻对应的接口能省下整整一个晚上。