企业官网建设流程全解析

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_KEY=sk-xxxx LLM_BASE_URL=https://api.xxx.com/v1 LLM_MODEL=gpt-4o-mini MAX_TOKENS=8192

最容易翻车的是 LLM_BASE_URL 和模型名不对应。很多兼容接口的模型名跟官方文档不一样，填错了启动时没有任何报错，但是一问话就回"model not found"。建议先把这三个参数在终端里用官方 SDK 单独跑一个最小请求，确认能通再继续，别等接完飞书才发现是模型名写错了。

另一个坑是临时文件目录。龙虾默认把生成的中间文件放到 ./tmp 下，如果你的部署目录是个只读挂载，后面生成 PPT 时就会出现莫名其妙的写入失败。我习惯显式指定一个独立数据目录：

mkdir -p /data/openclaw/tmp echo "TMP_DIR=/data/openclaw/tmp" >> .env

2.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 服务，Restart=always，这样进程挂了能自动拉起，长连接也不会处于"看似连着其实已经断"的诡异状态。

3.3 鉴权与事件签名：最常见的两个报错

即便用了长连接，还是绕不开鉴权。飞书服务端调用你的逻辑时需要校验来源，反过来，你的程序调用飞书接口时也要出示身份。我们当时遇到的报错，九成是下面这两个。

第一个是tenant_access_token获取失败。这个 token 要用 App ID 加 App Secret 去换，常见原因是 App Secret 填错，或者应用状态是"未启用"。在开放平台把应用状态改成"已启用"之前，很多接口调用都会被拒绝，而且报错信息往往不太直白，要翻日志才能看到根因。

第二个是事件签名校验失败。长连接模式下 SDK 会自动做加密密钥校验，但如果 .env 里没填 Encrypt Key，或者填的跟开放平台后台不一致，SDK 启动时就会报签名错误。排查方法很简单：去后台"事件与回调"页面复制 Encrypt Key，跟 .env 里逐字符比对，一个字符都不能差。我那次就是因为复制的时候多带了一个空格，排查了半个小时才找到。

还有个小细节：消息推送到本地后，要确认代码里正确调用了消息处理器，否则会出现"机器人明明收到消息但没有任何反应"的假象。建议在入口打一行调试日志，把收到的消息内容和 event_id 都打出来，后续排查会非常顺。

4. PPT生成链路：从一句话到一份.pptx

4.1 让"龙虾"按大纲生成PPT的工作流设计

机器人能收消息之后，接下来的核心问题是怎么让它产出像样的 PPT。早期我把整个流程设计成一条链路，分解成四步：

1. 用户 @机器人 发送指令，比如"把 /docs/本周周报.md 做成 PPT，风格简洁，每页不要超过 4 个要点。"
2. 龙虾读取指定文件内容，调用大模型生成结构化大纲。大纲是一个 JSON 数组，每个元素对应一页，包含标题、要点列表和备注。
3. 龙虾调用本地 PPT 生成工具，把 JSON 逐页渲染成 .pptx 文件。
4. 工具返回文件路径，龙虾再把文件上传到飞书并完成展示。

这里最关键的是第 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 现象二：导入云文档接口一直返回超时

转向云文档导入后，我按标准流程走了一遍，总共三步：

1. 用上传接口把本地 .pptx 作为媒体文件上传，拿到文件标识。
2. 创建导入任务，告诉飞书"我要把这个 pptx 转成云端幻灯片"。
3. 轮询任务状态，直到拿到一个代表在线文档的标识。

第一步就踩了大坑。导入云文档要用的上传接口是云盘域下的媒体上传，而不是即时消息域下的文件上传。两个接口都能传文件，但拿到的文件标识不通用。我第一次用错，创建导入任务时直接报了"文件类型不支持"。

轮询环节也容易翻车。导入一个十几页、带图片的 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(ticket=ticket).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 最终方案落地：上传-导入-发链接三步走

把上面所有坑填平之后，最终稳定运行的流程是这样：

1. 龙虾生成 .pptx 到本地临时目录，做文件体积和格式检查。
2. 调用飞书云盘媒体上传接口，拿到文件标识。
3. 创建导入任务，固定参数为.pptx格式，挂载目录指向团队共享文件夹。
4. 轮询导入结果，拿到在线文档标识。
5. 发送一条消息卡片，把"点击查看PPT"做成按钮，跳转链接指向上一步拿到的在线文档。

还有一个体验层面的优化：因为生成加导入整个流程可能要一分钟，机器人必须先回复"收到，正在生成 PPT，预计 1 分钟"，等真正成功后再发链接。这样用户不会对着一个半天不吭声的机器人反复 @。我们最开始没做这步，用户以为机器人挂了，连续发了好几条，结果任务队列里积压了三个生成请求，整个服务差点被拖垮。

6. 跑通后的可靠性优化和一点个人心得

6.1 定时任务与消息风暴防护

正式给团队用之前，我做了三件可靠性优化。第一是把龙虾注册成 systemd 服务，加上自动重启策略，长连接断开后进程会自动拉起。第二是给机器人入口加任务队列，PPT 生成属于重操作，同一时刻只允许一个任务在跑，其他请求排队并提示"当前已有任务在处理"。第三是消息发送合并，群里一次性收到多条消息会被限流，所以结果消息统一串成一条发出。

[Unit] Description=OpenClaw Agent Service After=network.target [Service] Type=simple WorkingDirectory=/data/openclaw ExecStart=/data/openclaw/.venv/bin/python main.py --feishu Restart=always RestartSec=5 EnvironmentFile=/data/openclaw/.env [Install] WantedBy=multi-user.target

日志也非常重要。龙虾的日志默认打到标准输出，在 systemd 下可以用 journalctl 查看。我把日志级别调成 INFO，并且在飞书消息处理入口加了结构化日志，每一条消息都记录事件 ID、用户 ID、指令内容。后面不管谁出问题，都能快速定位是哪个环节。

6.2 把PPT大纲做进提示词模板

跑了一段时间后，我发现最有价值的改动不是代码，而是把各团队的 PPT 风格沉淀成提示词模板。市场团队要看故事线，技术团队要看数据对比，不同团队的诉求完全不一样。我给龙虾配置了多套模板，指令里带上"风格=技术周报"就能走对应的大纲生成逻辑。

比如技术周报模板会重点约束：必须包含本周数据、风险项、下周计划三块；数据对比页必须用统一表格结构；结论页必须落到"建议/行动项"。这样生成的 PPT 至少骨架是对的，人工只需要微调措辞，不用再从头搭结构。

6.3 踩完这些坑之后我更推荐的做法

最后说点掏心窝的话。本地部署加飞书接入这套组合，上限很高，但运维成本也确实存在。如果你们团队只是偶尔要几个 PPT，别学我这么折腾，直接用现成的办公工具更划算。但如果你有批量生成、周期汇总、内部数据不能外传这类硬需求，那这套东西的价值就非常明显。

至少在我们这边，每周的进展汇报已经稳定跑在"群里喊一声、龙虾出 PPT、飞书在线预览"这条链路上。而且这套"上传-导入-发链接"的展示思路，不只是 PPT 能用，换成导出 PDF、数据表格、甚至是长图报告，逻辑都是通用的。下次再遇到类似需求，我大概不会再被"文件发出去不能预览"这种表象带偏——先想清楚"预览"在目标平台上的真实形态，再去翻对应的接口，能省下整整一个晚上。