基于OpenClaw与Whisper的自动化会议纪要生成系统实践

1. 项目概述：从录音到结构化会议纪要的自动化之旅

如果你和我一样，经常使用 Plaud 这类录音笔来记录会议、访谈或灵感迸发的瞬间，那你一定也经历过这样的场景：面对手机里一堆以日期命名的录音文件，需要花上半小时甚至更久，手动整理出谁说了什么、讨论了哪些要点、有哪些待办事项。这个过程不仅枯燥，还极易出错，尤其是当录音时长超过一小时时，整理工作简直是一场噩梦。

OpenPlawd 正是为了解决这个痛点而生的。它是一个运行在 OpenClaw 平台上的自动化技能（Skill），核心目标就一个：将你的 Plaud 录音文件，自动转化为结构清晰、可直接归档或分享的 HTML 会议纪要。想象一下，会议结束后一小时，你的邮箱里就躺着一份排版美观、包含讨论摘要、关键决策和行动项表格的会议记录，而你几乎什么都没做——这就是 OpenPlawd 带来的效率提升。

这个项目的技术栈非常务实：它通过 Plaud 的官方 API 拉取录音，利用开源的 Whisper 模型进行语音转写，再通过 OpenClaw 的智能体（Agent）能力，理解转录文本并生成结构化的笔记。整个流程涵盖了从数据获取、处理、智能分析到结果分发的完整链条，是一个典型的“AI 赋能日常工作流”的案例。虽然原作者已宣布不再主动维护，但项目的架构清晰、代码可用，为我们提供了一个绝佳的、可复现的自动化样板，无论是直接使用还是借鉴其设计思路，都极具价值。

2. 核心工作流与架构设计解析

OpenPlawd 不是一个单一脚本，而是一个设计精巧的自动化流水线。理解其架构，有助于我们后续的部署、调试乃至自定义开发。整个系统可以看作一个由事件驱动的数据处理管道。

2.1 端到端流程拆解

整个流程可以清晰地划分为九个阶段，环环相扣：

1. 轮询发现：系统以可配置的时间间隔（默认每小时）主动调用 Plaud API，查询是否有新的录音文件生成。这是一种“拉取”模式，相较于需要 Plaud 设备主动推送的“推送”模式，实现更简单，可靠性也足够高。
2. 文件下载：一旦检测到新录音，立即通过 API 将音频文件下载到本地服务器或 OpenClaw 的工作空间。这里通常下载的是压缩后的音频格式（如 M4A），以平衡文件大小和音质。
3. 音频预处理与分块：这是应对长录音的关键步骤。Whisper 等模型对单次处理的音频长度和文件大小有限制。OpenPlawd 使用ffmpeg工具，自动将超过特定大小（如24MB）的音频文件，按时间或大小切割成更小的“块”。这确保了后续转录步骤的稳定性。
4. 语音转录：核心环节。将每个音频块送入语音识别模型。项目采用了混合策略：对于短于90分钟的录音，优先使用 Groq 云服务提供的免费 Whisper API，性价比高；对于超长录音，则回退到 OpenAI 的 Whisper API，虽然收费但能力更强、限制更少。多个音频块可以并行转录，以加快整体速度。
5. 信息预览与交互确认：转录完成后，原始的文本是杂乱无章的。此时，OpenClaw 智能体会介入，初步分析文本，提取出可能的人名、公司名和会议类型（如“客户会议”、“团队周会”），并将这些信息呈现给用户进行确认或修正。这一步至关重要，它引入了“人在环路”的机制，确保了后续生成笔记的准确性，特别是专有名词的正确性。
6. 结构化内容生成：在用户确认信息后，OpenClaw 智能体开始真正的“理解”工作。它基于确认的上下文（如参会人、会议类型），分析完整的转录文本，识别讨论主题、总结要点、提炼决策，并特别提取出带有负责人和截止日期的“行动项”。
7. 结果分发：生成的最终产物是一份格式良好的 HTML 文档。OpenPlawd 提供了多种分发渠道：可以通过 Resend 等服务直接发送到指定邮箱；可以集成到 CRM 系统（如 Salesforce, HubSpot）中，为联系人创建笔记；也可以简单地保存到本地或网盘。
8. 云端清理：处理完成后，为了保持 Plaud App 内的整洁，脚本可以自动将原录音文件在云端重命名（例如，加上“已处理”前缀）或移动到回收站。这体现了流程的闭环性。
9. 本地归档：所有中间文件（原始音频、分块音频、原始转录文本）和最终生成的 HTML 笔记，都会按照日期、会议主题等规则，有序地保存在本地目录中，便于后续查阅。

2.2 关键技术选型背后的逻辑

为什么是这些技术？每个选择都有其深意：

• OpenClaw 作为执行平台：OpenClaw 提供了一个统一的、可编程的智能体环境。OpenPlawd 作为其一个“技能”，可以天然地利用 OpenClaw 的调度能力（如定时任务）、交互能力（如通过 Telegram 通知用户确认信息）以及智能体内核（用于理解和生成笔记）。这避免了从零搭建一个带交互逻辑的后端服务。
• Whisper 作为转录引擎：OpenAI 开源的 Whisper 模型在语音识别，尤其是多语言和带口音语音的识别上，表现出了业界领先的鲁棒性。选择它而非其他商用服务，保证了转录质量的下限，且开源模型可以通过 Groq 等平台低成本使用。
• Groq + OpenAI 的混合云策略：这是一个成本与性能平衡的典范。Groq 为 Whisper 提供免费的 API 额度，非常适合日常高频的短会议处理。但当遇到超长录音（如全天工作坊），免费额度可能不够或超时，此时切换到更稳定、配额独立的 OpenAI API，保证了流程不中断。这种“降级”策略在构建可靠系统时很常见。
• FFmpeg 进行音频处理：FFmpeg 是音视频处理领域的“瑞士军刀”，几乎无所不能。用它来执行音频分块、格式转换等操作，稳定性和效率都有保障，避免了引入不成熟的专用库。

注意：这个架构体现了“胶水代码”的哲学。它没有重复造轮子去实现语音识别或大语言模型，而是巧妙地用 Python 脚本将几个优秀的现有服务（Plaud API, Whisper API, OpenClaw）粘合在一起，形成了一个价值大于各部分之和的自动化解决方案。

3. 环境准备与详细部署指南

要让这条自动化流水线跑起来，我们需要准备好所有的“原材料”和“工具”。下面是一步一步的实操指南，我会补充许多原文档未提及的细节和避坑点。

3.1 前置条件清单

在开始安装代码之前，请确保你已拥有以下账户和软件：

1. Plaud 设备与账户：你至少需要有一个 Plaud 录音笔，并在手机 App 上登录账户，且里面有录音文件。这是数据源头。
2. OpenClaw 网关：你需要在你的服务器（可以是家里的树莓派、NAS，或云服务器）上安装并运行 OpenClaw。这是整个自动化流程的“大脑”和调度中心。请确保 OpenClaw 的主服务 (openclawd) 正常运行。
3. Groq Cloud 账户：访问 Groq 控制台 ，注册并创建一个 API 密钥。他们的 Whisper API 在免费额度内确实非常慷慨，是项目的首选。
4. （可选）OpenAI 账户：如果你预计会处理大量超长录音，建议准备一个 OpenAI API 密钥。在项目设置中绑定付费方式。
5. （可选）Resend 账户：如果你希望最终笔记通过邮件发送，需要注册 Resend 并创建 API 密钥。它比直接配置 SMTP 服务器更简单、可靠。
6. FFmpeg：在运行 OpenClaw 的服务器上安装 FFmpeg。对于 Ubuntu/Debian 系统：sudo apt update && sudo apt install ffmpeg -y。对于 macOS：brew install ffmpeg。安装后，在终端输入ffmpeg -version确认安装成功。

3.2 逐步安装与配置流程

假设你的 OpenClaw 工作目录在~/.openclaw/workspace。

# 1. 克隆项目代码 cd ~/.openclaw/workspace git clone https://github.com/nicolasglg/openplawd.git cd openplawd

第一步的注意事项：确保你有git命令，并且当前用户对~/.openclaw/workspace目录有写权限。如果克隆失败，检查网络或目录权限。

# 2. 安装 Python 依赖 # 项目依赖非常简单，主要是 requests 库用于网络请求 pip install requests

第二步的实操心得：建议在 OpenClaw 使用的 Python 虚拟环境中执行此命令，避免污染系统环境。如果你不确定 OpenClaw 用的哪个环境，可以尝试~/.openclaw/venv/bin/pip install requests。

# 3. 复制技能定义文件 # 这个 SKILL.md 文件告诉 OpenClaw 如何与这个项目交互 cp SKILL.md ~/.openclaw/workspace/skills/openplawd/SKILL.md

第三步的关键点：skills目录是 OpenClaw 加载技能的地方。复制完成后，你可能需要重启 OpenClaw 服务，或者在 OpenClaw 的管理界面刷新技能列表，才能让它识别到新的openplawd技能。

# 4. 配置环境变量 cp .env.example .env # 使用你喜欢的编辑器编辑 .env 文件，例如 nano 或 vim nano .env

现在打开.env文件，填入你的密钥。这是最核心也最容易出错的一步。

如何获取PLAUD_TOKEN？这是整个流程启动的钥匙。原文档的方法（从浏览器 LocalStorage 获取）是有效的，但这里提供一个更稳定、更详细的步骤：

1. 在电脑上打开 Chrome 或 Edge 浏览器。
2. 访问 https://web.plaud.ai 并登录你的 Plaud 账户。
3. 按F12打开开发者工具。
4. 切换到“应用程序”标签页（Application）。
5. 在左侧存储菜单中，找到“本地存储”->https://web.plaud.ai。
6. 在右侧的键值对列表中，寻找一个名为tokenstr的键。
7. 其值应该是以bearer eyJ...开头的一长串字符。完整地复制这个值，包括开头的bearer。
8. 将它粘贴到.env文件的PLAUD_TOKEN=后面。

重要警告：这个令牌（Token）相当于你的账户密码，务必妥善保管，不要泄露。它通常有有效期，如果后续脚本报错“API 不可用”或“未授权”，很可能就是这个令牌过期了，需要重新按上述步骤获取一个新的。

获取GROQ_API_KEY：登录 Groq Cloud 控制台，在 API Keys 页面创建一个新的密钥，复制以gsk_开头的字符串，填入.env。

其他可选配置：

• OPENAI_API_KEY：填入你的 OpenAI 密钥（以sk-开头）。
• RESEND_API_KEY,EMAIL_FROM,EMAIL_TO：如果你配置了邮件发送，这里填 Resend 的密钥、发件人邮箱（需在 Resend 中验证过）和收件人邮箱。
• OPENPLAWD_BASE_DIR：除非你想改变音频和笔记的存储位置，否则保持默认即可。

一个完整的.env文件示例：

PLAUD_TOKEN=bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... GROQ_API_KEY=gsk_abc123... OPENAI_API_KEY=sk-proj-xyz456... RESEND_API_KEY=re_789... EMAIL_FROM=notes@yourdomain.com EMAIL_TO=youremail@gmail.com

3.3 设置定时任务（Cron）

为了让流程完全自动化，我们需要设置定时任务，让系统每小时自动检查新录音。

你需要编辑 OpenClaw 的 cron 配置文件。这个文件的位置通常是~/.openclaw/config/cron.json或类似路径。用编辑器打开它。

{ "jobs": [ // ... 可能已有其他任务 ... { "id": "plaud-poll-hourly", "schedule": "0 * * * *", // 每小时的0分执行（即每小时一次） "command": "cd /home/yourusername/.openclaw/workspace/openplawd && /usr/bin/python3 scripts/plaud-poll.py", "agent": "main", // 指定由哪个OpenClaw智能体来接收通知和交互 "enabled": true } ] }

配置详解与避坑：

• "schedule": "0 * * * *"是 cron 表达式，代表“每小时的第0分钟”。你可以根据需要调整，比如"30 * * * *"代表每小时的30分。
• command中的路径必须是绝对路径。cd到项目目录是为了让脚本能正确找到.env文件。Python 解释器的路径也最好用绝对路径（which python3命令可查看）。
• agent字段指定了当脚本发现有新录音、需要用户确认信息时，通知哪个 OpenClaw 智能体。这通常是你常用的那个智能体名称。
• 修改保存后，必须重启 OpenClaw 的 cron 服务或整个 OpenClaw 服务，才能使新配置生效。命令可能是sudo systemctl restart openclawd或参考 OpenClaw 的文档。

3.4 手动测试验证

在交给 cron 自动运行前，强烈建议先手动测试一遍，确保所有环节畅通。

# 进入项目目录，并手动运行轮询脚本 cd ~/.openclaw/workspace/openplawd python3 scripts/plaud-poll.py

观察终端输出。理想情况下，它会：

1. 打印“正在检查 Plaud 录音...”。
2. 如果找到未处理的新录音，会输出录音 ID 和文件名。
3. 开始下载音频文件。
4. 调用 Whisper 进行转录（这步可能需要一些时间，取决于录音长度和网络）。
5. 最后，OpenClaw 智能体应该会通过你配置的通知渠道（如 Telegram）给你发送一条消息，内容类似于：“发现新录音：关于XX项目的讨论。识别到参会人：[张三， 李四]。会议类型：客户会议。请确认信息是否正确？”
6. 你回复确认后，智能体会开始生成笔记，并最终将 HTML 文件保存到本地，或按配置发送邮件。

如果测试成功，恭喜你，自动化流水线已经搭建完成！如果失败，请根据终端报错信息，结合下一章的“问题排查”部分进行诊断。

4. 核心脚本功能与自定义修改指南

OpenPlawd 的核心逻辑集中在几个 Python 脚本中。理解它们，你就能根据自己的需求进行定制。

4.1plaud-poll.py：主轮询与处理引擎

这是项目的心脏。它不仅仅是一个轮询脚本，更是一个状态机，管理着从发现到归档的完整生命周期。

主要函数与流程：

• poll_new_recordings(): 调用 Plaud API，获取录音列表，并过滤出未处理的（通过检查本地是否存在对应文件）。
• download_recording(rec_id, filename): 下载音频文件到本地downloads/目录。
• transcribe_audio(filepath): orchestration 函数。负责判断文件大小，决定是否分块，以及选择 Groq 还是 OpenAI 的 Whisper API。
  • 内部会调用split_audio_with_ffmpeg()进行分块。
  • 实现了一个简单的“断点续传”逻辑：如果某个分块之前转录失败，下次运行时不会重复转录已成功的分块。
• interact_with_agent(transcript, metadata): 将原始转录文本和元数据（如文件名中的时间）发送给 OpenClaw 智能体，触发交互流程。
• cleanup_on_plaud(rec_id, new_name): 处理完成后，调用 Plaud API 重命名或删除云端原文件。

自定义点：

• 轮询频率：除了在 cron 中修改，你也可以在脚本里硬编码一个不同的等待时间，但更推荐用 cron 管理。
• 音频分块策略：split_audio_with_ffmpeg函数中决定了分块大小（如24MB）和分块时长。如果你的录音质量特别高或特别低，可能需要调整ffmpeg的-b:a（音频比特率）参数来控制输出文件大小。
• 转录后处理：在transcribe_audio返回最终文本后，你可以插入自己的文本清洗逻辑，比如用正则表达式批量替换某些行业术语。

4.2SKILL.md：OpenClaw 技能定义与提示工程

这个文件定义了 OpenClaw 智能体在“会议笔记生成”这个任务上的行为模式，是提示工程（Prompt Engineering）的体现。

核心结构：

1. 技能描述：告诉智能体这个技能是干什么的。
2. 触发命令：用户说什么会激活这个技能（如“检查 plaud”、“生成会议笔记”）。
3. 处理逻辑：当技能被触发后，智能体应该执行哪些步骤（调用哪个 Python 函数、如何处理返回结果）。
4. 提示模板：这是最关键的部分。它定义了智能体在生成会议笔记时，应该遵循的格式、包含哪些章节（如会议主题、参会人、日期、摘要、讨论要点、行动项）、行动项表格的样式等。

自定义点（这里大有可为）：

• 修正表：原文件里有一个corrections表格，用于纠正 Whisper 常见的语音转文字错误。你必须根据你的同事、客户、合作伙伴的名字和公司名来定制这个表！这是提升笔记准确率最有效的手段。例如，Whisper 可能总是把“子航”听成“紫航”，你就在这里添加一条修正。

  | Whisper Output | Correction | Context | |---------------|------------|---------| | 紫航 | 子航 | 同事张三 | | 腾迅 | 腾讯 | 合作公司 | | next action | 行动项 | 会议术语 |

• 笔记模板：你可以修改提示模板，让生成的 HTML 笔记更符合你公司的品牌规范。比如，加入公司的 Logo、特定的颜色代码、或者增加“保密等级”、“会议编号”等字段。
• 分发逻辑：你可以在技能定义中，增加判断逻辑。例如，如果会议类型是“客户会议”，则除了生成 HTML，还额外调用一个函数将行动项同步到 CRM；如果是“内部团队会议”，则只保存到共享网盘。

4.3 其他工具脚本

• rename/trash功能：plaud-poll.py支持命令行参数，让你可以手动管理云端的录音文件。例如python3 scripts/plaud-poll.py rename rec_123 "已处理-项目复盘"。这在自动化出错需要手动干预时非常有用。
• 日志与调试：脚本的日志输出相对简单。对于生产环境，建议你增加更详细的日志记录（如使用 Python 的logging模块），将不同级别的日志（INFO, ERROR, DEBUG）输出到文件，方便日后排查问题。

5. 实战问题排查与优化经验分享

即使按照指南一步步操作，也难免会遇到问题。下面是我在部署和使用过程中遇到的一些典型问题及解决方案，这可能是比官方文档更有价值的部分。

5.1 常见错误与解决方法速查表

5.2 性能优化与稳定性提升技巧

1. 设置处理超时与重试：网络请求和 AI 接口调用可能失败。在生产环境中，你应该在requests调用和调用 OpenClaw/Whisper API 的地方添加try-except块，并实现简单的重试机制（例如，最多重试3次，每次间隔递增）。这能显著提高流程的鲁棒性。
2. 管理本地存储：音频和转录文本会占用磁盘空间。可以在plaud-poll.py的最终归档步骤后，增加一个清理逻辑，比如只保留最近30天的原始音频文件，或者定期将处理完成的文件压缩备份到其他存储。
3. 敏感信息处理：会议录音可能涉及商业机密。确保运行 OpenClaw 的服务器安全，.env文件权限设置为仅当前用户可读 (chmod 600 .env)。如果使用云服务，考虑对转录文本和最终笔记进行加密存储。
4. 扩展通知渠道：除了 OpenClaw 内置的 Telegram，你还可以修改脚本，在处理完成或失败时，通过 Server 酱、钉钉机器人、企业微信等方式发送通知，实现多端提醒。
5. 备份与监控：对于关键的业务会议，不要完全依赖自动化。可以设置一个“备份”机制，例如，所有原始录音文件在处理后，自动同步一份到你的个人云盘。同时，监控 cron 任务的日志，确保它每天都在正常运行。

5.3 从“能用”到“好用”的进阶改造

OpenPlawd 提供了一个优秀的起点，但你可以基于它打造更贴合自己需求的系统：

• 集成知识库：将生成的会议笔记，除了保存为 HTML，还可以自动提取关键内容，存入 Notion、Obsidian 或你的本地知识库，并打上标签（如项目名、参会人），方便未来搜索。
• 多语言支持：虽然 Whisper 本身支持多语言，但 OpenClaw 智能体生成笔记的提示词是英文的。你可以修改SKILL.md中的提示模板，让智能体用中文总结和输出，更适合中文会议场景。
• 说话人分离：目前笔记无法区分“谁说了哪句话”。你可以探索集成像 PyAnnote 这样的说话人分离工具，先区分不同说话人的语音段落，再分别转录，最后让 AI 总结出“张三的观点是...”、“李四的建议是...”，这样生成的笔记会更有价值。
• 自定义摘要：对于不同的会议类型（如头脑风暴、项目复盘、客户谈判），你可能需要不同结构的笔记。可以在交互阶段，让用户选择会议模板，从而应用不同的提示词来生成摘要。

这个项目最宝贵的价值在于它展示了一种思路：用轻量级的自动化脚本，将消费级硬件（Plaud）、强大的云端 AI 能力（Whisper, LLM）和可扩展的自动化平台（OpenClaw）连接起来，解决一个具体的、高频的痛点。即使未来 Plaud 官方提供了笔记功能，或者你换了其他录音设备，这套以 API 和 AI 为核心的处理流水线，其设计模式依然可以快速迁移和复用。