三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

手把手教你用 Hermes Agent 与 OpenClaw 搭建飞书 AI 助手

发布时间：2026/8/9 21:13:08 三亩地 编程学习日记
手把手教你用 Hermes Agent 与 OpenClaw 搭建飞书 AI 助手

1. 从零到一：为什么你需要 Hermes Agent 与 OpenClaw 的组合？

如果你正在寻找一个能帮你自动处理飞书消息、管理文档、甚至执行代码的“数字助理”，那么 Hermes Agent 和 OpenClaw 这对组合，可能就是你在找的答案。这听起来可能有点技术门槛，但别担心，这篇教程的目标就是“喂饭级”——我会把每一步都掰开揉碎，让你即使没有深厚的开发背景，也能亲手搭建起来。我们先来搞清楚，这两个东西到底是什么，以及它们组合起来能做什么。

Hermes Agent 是一个开源的、功能强大的 AI 代理框架。你可以把它理解为一个“大脑”或“指挥中心”。它本身不直接处理具体的任务，但它能理解你的指令（比如“帮我总结一下飞书群里今天的讨论”），然后去调用各种工具（Tool）来完成。这些工具可以是搜索网页、读写文件、执行命令等等。而 OpenClaw，就是这样一个专门为处理飞书（Lark）消息而生的“超级工具”。它不是一个简单的机器人，而是一个功能完备的 MCP（Model Context Protocol）服务器。MCP 你可以理解为一种标准协议，让像 Hermes Agent 这样的“大脑”能够安全、标准化地调用像 OpenClaw 这样的“手和眼睛”。

所以，整个工作流是这样的：你在 Hermes Agent 的界面上（可能是一个网页或命令行）输入指令。Hermes Agent 理解后，发现需要操作飞书，于是它通过 MCP 协议，把任务交给已经配置好的 OpenClaw 工具。OpenClaw 则利用飞书开放的 API，真正地去登录你的飞书账号、读取群消息、发送回复、上传文件等等。最后，OpenClaw 把结果返回给 Hermes Agent，再由 Hermes Agent 整理后呈现给你。这样一来，你就拥有了一个能 7x24 小时待命、精通飞书所有操作的 AI 助手。无论是自动同步会议纪要到知识库，还是根据群聊关键词触发特定工作流，都成为了可能。

2. 环境奠基：安装 Hermes Agent 的避坑指南

在开始激动人心的飞书集成之前，我们必须先把“大脑”——Hermes Agent 安装好。官方推荐了几种方式，但对于大多数想要快速上手和深度定制的用户，我强烈建议使用源码安装。这不仅让你对项目结构有最清晰的认识，也避免了 Docker 方式可能带来的权限和调试难题。别被“源码”吓到，整个过程其实非常 straightforward。

2.1 系统与依赖准备：绕开第一个大坑

首先，确保你的系统是Ubuntu 20.04/22.04 LTS 或 macOS。Windows 用户可以通过 WSL2（Windows Subsystem for Linux）获得一个完美的 Linux 环境，这是目前最稳定且与教程兼容的方案。在 WSL2 中安装一个 Ubuntu 发行版，接下来的操作就完全一致了。

接下来是依赖安装。这里有一个关键点：Node.js 的版本。Hermes Agent 对 Node.js 版本有要求，官方推荐使用nvm（Node Version Manager）来管理多个 Node.js 版本，这是最佳实践。打开你的终端（WSL 或 Linux/Mac 的终端），执行以下命令来安装 nvm 和正确的 Node.js：

# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash # 安装完成后，关闭并重新打开终端，或者运行： export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # 安装 Node.js 18（一个长期支持的稳定版本） nvm install 18 nvm use 18 # 验证安装 node --version # 应该输出 v18.x.x npm --version

另一个核心依赖是Python 3.10 或以上版本。很多系统自带 Python 3，但版本可能较低。请使用python3 --version检查。如果没有或版本低，在 Ubuntu 上可以用sudo apt update && sudo apt install python3 python3-pip安装。在 macOS 上，推荐使用 Homebrew:brew install python@3.10。

注意：请务必确认命令是python3和pip3。在后续的 OpenClaw 安装中，使用错误的 Python 版本是导致ModuleNotFoundError等问题的首要原因。

2.2 获取与构建 Hermes Agent：细节决定成败

环境准备好后，我们开始拉取 Hermes Agent 的代码并构建它。

# 1. 克隆仓库 git clone https://github.com/Hermes-AI-Project/hermes-agent.git cd hermes-agent # 2. 安装项目依赖 npm install

这一步的npm install可能会花费一些时间，因为它需要下载并编译所有前端和后端的依赖包。如果网络不畅，可以考虑配置 npm 镜像源。完成后，我们来进行构建：

# 3. 构建项目 npm run build

build过程是编译 TypeScript 代码、打包前端资源的关键步骤。如果一切顺利，你会看到成功的提示。但这里我遇到过两个典型问题：

  1. 内存不足：在资源有限的虚拟机或 WSL 中，构建前端部分时可能因内存不足而失败。解决方案是增加交换空间（swap），或者直接使用npm run build:light命令进行轻量构建，它包含的功能对于入门和集成 OpenClaw 已经足够。
  2. 权限问题：如果在全局安装某些包时遇到权限错误，不要使用sudo来运行npm install。这会导致后续文件所有权混乱。正确做法是修复 npm 的全局安装目录权限，或者更简单地，在项目目录下安装时，所有操作都在用户权限下完成。

构建成功后，你可以先试运行一下桌面应用（如果你安装的是完整版）：

# 运行桌面应用（如果构建了的话） npm run desktop

或者，更常用的方式是运行开发服务器，它同时提供前端界面和后端 API：

# 运行开发服务器 npm run dev

执行npm run dev后，终端会输出访问地址，通常是http://localhost:3000。用浏览器打开它，你应该能看到 Hermes Agent 的 Web 界面了。至此，你的“大脑”已经成功启动并运行。

3. 核心工具部署：OpenClaw 的安装、配置与深度迁移

现在，“大脑”有了，我们需要为它安装那双能操作飞书的“手”——OpenClaw。OpenClaw 本质上是一个 Python 包，它作为一个 MCP 服务器运行。我们将从最基础的安装开始，并深入探讨一个高级话题：从旧版本或不同环境“迁移” OpenClaw 配置。

3.1 基础安装与飞书应用创建

首先，我们通过 pip 安装 OpenClaw。强烈建议使用虚拟环境来隔离依赖，避免与系统其他 Python 项目冲突。

# 进入你的工作目录，可以放在 hermes-agent 同级 cd /path/to/your/workspace # 创建虚拟环境 python3 -m venv openclaw-env # 激活虚拟环境 # Linux/macOS/WSL: source openclaw-env/bin/activate # Windows PowerShell (如果在原生Windows下): # .\openclaw-env\Scripts\Activate.ps1 # 安装 OpenClaw pip install openclaw

安装完成后，你需要一个飞书开放平台的应用来作为 OpenClaw 的操作身份。这一步至关重要，因为所有权限都在这里控制。

  1. 登录 飞书开放平台 。
  2. 点击“创建企业自建应用”，给你的应用起个名字，比如 “My-AI-Assistant”。
  3. 进入应用后，在“权限管理”页面，为你的应用添加权限。OpenClaw 需要非常广泛的权限才能正常工作，至少需要添加：
    • contact:contact:readonly_as_app(读取部门与用户信息)
    • im:message(发送与接收单聊、群组消息)
    • im:message:readreceipt(消息已读权限)
    • im:message:send_as_bot(以机器人身份发送消息)
    • mail:mail:readonly(读取邮箱)
    • drive:drive:readonly(读取云文档)
    • 根据你的需求，可能还需要calendar:calendar:readonly(日历)等。原则是：你需要它做什么，就勾选对应权限。然后点击“批量申请”。
  4. 进入“事件订阅”页面，这里暂时不需要配置，除非你需要接收用户@机器人的事件（更高级的交互）。对于 Hermes Agent 主动控制模式，可以先跳过。
  5. 进入“凭证与基础信息”页面，这里有你需要的三个核心信息：
    • App ID
    • App Secret
    • Encrypt Key(如果启用了加密，在事件订阅里)请务必将它们妥善保存，下一步配置需要。

3.2 配置文件详解与首次运行

OpenClaw 通过一个 YAML 配置文件来管理所有设置。我们需要创建并编辑它。

# 创建一个配置目录和文件 mkdir -p ~/.config/openclaw nano ~/.config/openclaw/config.yaml

将以下内容粘贴进去，并替换<>中的内容为你飞书应用的信息：

feishu: app_id: <你的 App ID> app_secret: <你的 App Secret> # 如果启用了事件订阅加密，需要填写 # encrypt_key: <你的 Encrypt Key> # verification_token: <你的 Verification Token> server: host: 0.0.0.0 # 监听所有网络接口，方便其他服务连接 port: 8000 # MCP 服务端口，记住这个端口号，后面 Hermes 要连接 # 日志级别，调试时可以设为 DEBUG logging: level: INFO

保存退出后，就可以启动 OpenClaw 服务器了：

# 确保在虚拟环境中 openclaw server

如果看到类似INFO: Started server process [12345]和INFO: Uvicorn running on http://0.0.0.0:8000的日志，恭喜你，OpenClaw 服务已经成功在 8000 端口运行了。这是 MCP 服务器的标准端口。

3.3 深度迁移：从旧环境“无损”搬迁 OpenClaw

“迁移”是部署中常被忽略但极其重要的环节。你可能需要在不同服务器间迁移，或者将开发环境的配置同步到生产环境。迁移不仅仅是复制文件，更要考虑环境一致性和数据连续性。

场景一：完整服务器迁移（例如从旧虚拟机迁到新云主机）

  1. 环境复制：在新服务器上重复 3.1 节的所有步骤，确保 Python 版本、虚拟环境、pip 包版本完全一致。一个技巧是使用pip freeze > requirements.txt在旧环境生成依赖列表，然后在新环境用pip install -r requirements.txt安装。
  2. 配置文件迁移：直接复制~/.config/openclaw/config.yaml文件。这是核心。
  3. 数据迁移（如果有）：OpenClaw 默认可能使用本地 SQLite 数据库（如果配置了缓存或会话）。数据库文件通常位于~/.cache/openclaw/或项目目录下。你需要找到这个.db文件并复制到新环境的相同路径。在复制前，务必停止旧服务器的 OpenClaw 服务，以免数据损坏。
  4. 服务状态与日志：如果你使用 systemd 或 supervisor 管理 OpenClaw 进程，也需要迁移相应的服务配置文件。

场景二：仅配置更新（例如 App Secret 轮换）

这是更常见的情况。你只需要更新config.yaml中的app_secret字段，然后重启 OpenClaw 服务即可。如果 OpenClaw 是以常驻进程运行，你需要找到进程 ID 并发送重启信号，或者使用进程管理工具。

# 假设用 systemd 管理 sudo systemctl restart openclaw # 或者如果是在终端前台运行，先 Ctrl+C 停止，再重新运行 `openclaw server`

迁移中的经典陷阱：

  • app secret复制不上去：这个问题常在网页表单中出现。原因可能是复制的内容包含不可见字符（如空格、换行）。解决方案是：先粘贴到纯文本编辑器（如记事本、VS Code）中，检查并清除首尾空格，再重新复制粘贴到飞书开放平台。
  • 端口冲突：新环境 8000 端口可能已被占用。修改config.yaml中的port为其他值（如 8001），并确保 Hermes Agent 的配置也相应更改。
  • 文件权限：迁移配置文件或数据库后，确保运行 OpenClaw 的用户（如你的登录用户）有对这些文件的读写权限。

4. 桥接大脑与双手：在 Hermes Agent 中配置 OpenClaw MCP

Hermes Agent 和 OpenClaw 都已就位，现在需要让它们认识并握手合作。这通过在 Hermes Agent 中添加 OpenClaw 作为一个 MCP 服务器来实现。

4.1 理解 MCP 配置的核心理念

Hermes Agent 的配置通常位于~/.hermes/config.json（Linux/macOS）或%APPDATA%\.hermes\config.json（Windows）中。我们需要在这个配置里声明一个 MCP 服务器。关键是要理解几个参数：

  • command: 这是启动 MCP 服务器的命令。对于本地运行的 OpenClaw，如果我们想由 Hermes Agent 来管理其生命周期（启动、停止），可以配置为openclaw server。但更常见的稳定做法是让 OpenClaw 作为独立服务运行（如我们在 3.2 节做的），然后这里配置一个stdio类型的连接。
  • args: 传递给 command 的参数。
  • env: 环境变量，对于 OpenClaw，可能需要指定配置文件路径，如OPENCLAW_CONFIG_PATH=~/.config/openclaw/config.yaml。

然而，对于已经独立运行的 OpenClaw 服务，我们更推荐使用stdio连接方式，但这需要 Hermes Agent 能通过某个命令“连接”到已存在的服务。更简单直接的方式是使用tcp连接，直接连接到 OpenClaw 服务的网络端口。

4.2 实战配置步骤

首先，确保你的 OpenClaw 服务正在运行（openclaw server命令在终端运行着，监听 8000 端口）。

然后，我们需要找到 Hermes Agent 的配置目录并编辑配置文件。如果你通过npm run dev启动了 Web 界面，配置可能通过界面管理。但底层依然是文件配置。我们直接修改文件：

  1. 找到或创建配置文件。对于从源码运行的开发模式，配置路径可能在项目目录下，如hermes-agent/.hermes/config.json。你可以先检查~/.hermes/目录。
  2. 编辑config.json文件。如果文件不存在，就创建它。内容如下：
{ "mcpServers": { "openclaw-feishu": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-openclaw" ], "env": { "OPENCLAW_CONFIG_PATH": "/absolute/path/to/your/.config/openclaw/config.yaml" } } } }

注意：上面的配置是一种方式，它假设存在一个名为@modelcontextprotocol/server-openclaw的 NPM 包来作为桥梁。但实际上，OpenClaw 官方更推荐的方式是让 Hermes Agent 直接通过 TCP 连接到已经运行的 OpenClaw 服务器。遗憾的是，Hermes Agent 的标准 MCP 配置可能不直接暴露 TCP 选项。因此，最可靠、经过验证的方法是通过 Hermes Agent 的 Web UI 进行配置。

  1. 通过 Web UI 配置（推荐）：

    • 确保npm run dev正在运行，浏览器打开http://localhost:3000。
    • 在 Hermes Agent 的 Web 界面中，寻找设置或配置区域（通常是一个齿轮图标）。
    • 找到 “MCP Servers” 或 “Tools” 相关的配置项。
    • 添加一个新的 MCP 服务器。在连接类型中，选择“TCP”或“Socket”。
    • 在地址栏填写：127.0.0.1:8000（如果你的 OpenClaw 运行在同一台机器上）。
    • 给这个服务器起一个名字，比如feishu。
    • 保存配置。

  2. 重启 Hermes Agent 的开发服务器（如果它正在运行），让新配置生效。

4.3 验证连接与权限测试

配置完成后，如何验证 Hermes Agent 已经成功连接到了 OpenClaw 并拥有了飞书权限呢？

  1. 在 Hermes Agent 的聊天界面或工具调用界面，你应该能看到新添加的工具列表。这些工具的名字可能以feishu_或openclaw_开头，例如feishu_send_message,feishu_list_chats等。
  2. 进行一个简单的测试。尝试让 Hermes Agent 执行一个飞书操作。例如，你可以输入指令：“列出我所有的飞书群聊”。Hermes Agent 会解析指令，调用 OpenClaw 的对应工具。
  3. 观察 Hermes Agent 的日志和 OpenClaw 服务器的日志。如果连接成功，你会看到 Hermes Agent 向127.0.0.1:8000发送了请求，而 OpenClaw 服务器则收到了 MCP 请求并开始调用飞书 API。
  4. 首次授权：当你第一次执行一个需要较高权限的操作（如读取所有群聊）时，OpenClaw 可能会在终端日志中输出一个飞书授权链接。这是因为你的飞书应用是“企业自建应用”，需要管理员在飞书后台审核通过你申请的权限，并且你自己也需要在飞书客户端中手动同意该应用获取相应的个人权限。你必须用浏览器打开这个链接，并用你的飞书账号登录、授权。这是安全必需的一步，否则所有 API 调用都会返回 403 权限错误。

关键心得：很多人在配置完成后卡在“工具调用无反应”或“返回权限错误”。请务必按顺序排查：a) OpenClaw 进程是否存活？curl http://127.0.0.1:8000试试。b) Hermes Agent 的 MCP 配置中，TCP 地址端口是否正确？c) 你是否点击了 OpenClaw 日志中输出的授权链接并完成了个人授权？d) 飞书开放平台的应用权限是否已经“申请通过”？（企业管理员审批）。这四步缺一不可。

5. 实战飞书集成：从消息处理到复杂工作流

连接成功后，你的 AI 助手就真正拥有了飞书能力。我们来探索几个核心应用场景，了解如何通过自然语言指挥它。

5.1 基础消息收发与信息查询

这是最直接的功能。你可以像使唤一个真人助理一样，让它处理飞书信息。

  • 场景：快速总结某个群昨天的讨论
    • 你对 Hermes Agent 说：“查看一下群名为‘项目周会’的群聊，把昨天（2023-10-27）的所有消息总结成一份会议纪要，列出关键决策和待办事项。”
    • 背后流程：Hermes Agent 会先调用feishu_list_chats工具找到该群的 ID。然后调用feishu_get_message_history获取指定日期的消息。最后，它利用自身的 LLM 能力（你需要为 Hermes Agent 配置一个 AI 模型，如 OpenAI GPT 或本地 Ollama 模型）来分析和总结这些消息，输出结构化的纪要。
  • 场景：自动发送每日报告
    • 你可以预设一个指令：“每个工作日上午 9 点，向‘团队日报’群发送一条消息，内容模板为：‘大家早！今日工作计划：[请根据我昨天的日程和邮件自动生成要点]’。”
    • 实现方式：这需要结合 Hermes Agent 的“计划任务”功能（如果支持）或外部的定时任务（如 cron job）来触发 Hermes Agent 执行指令。Agent 会调用feishu_send_message工具完成发送。

5.2 飞书云文档与知识库管理

OpenClaw 的强大之处在于它能深度操作飞书云文档（Docs）和知识库（Wiki）。

  • 场景：自动归档重要消息到知识库
    • 指令：“将‘技术分享’群里所有带‘#归档’标签的消息，自动整理并追加到知识库‘团队学习记录’的指定文档中。”
    • 实现拆解：这需要组合多个工具。首先定时轮询或监听群消息（feishu_get_message_history），过滤出带特定关键词的消息。然后，调用feishu_get_wiki_node和feishu_create_wiki_content等工具，将过滤后的内容按照格式写入知识库的指定位置。这体现了智能体（Agent）将复杂任务分解、串联多个工具的能力。
  • 场景：基于文档内容问答
    • 指令：“帮我从‘产品需求文档’这个云文档里，找出所有关于‘用户登录’的功能描述。”
    • 背后流程：Hermes Agent 调用feishu_get_doc_content获取文档全文。由于文档可能很长，它会利用 LLM 的上下文理解能力，或者先进行向量化存储和检索（如果集成了相关工具），来精准定位并提取相关信息。

5.3 构建自动化工作流：一个完整案例

让我们设计一个从触发到执行完毕的完整工作流，感受一下这个组合的自动化威力。

目标：当飞书日历上的“项目评审会”结束时，自动将会议纪要云文档链接、会上产生的待办事项（从聊天记录中提取）打包，并发送给相关项目群的全体成员。

步骤分解：

  1. 触发：使用飞书开放平台的“事件订阅”功能，订阅日历事件结束的推送。当事件触发时，飞书会向一个你指定的、公网可访问的 URL（Webhook）发送 POST 请求。你需要一个接收器，可以是一个简单的服务器（如用 Python Flask 快速搭建）。
  2. 接收与解析：这个接收器服务器收到事件后，解析出会议主题、参与者、结束时间等信息。
  3. 调用智能体：接收器服务器通过 HTTP 请求调用 Hermes Agent 的 API（如果暴露了的话），或者直接将解析后的信息作为输入，触发一个预定义在 Hermes Agent 中的“工作流”。
  4. 智能体执行：
    • Hermes Agent 收到指令：“处理刚结束的会议 ‘<会议名>’”。
    • 它首先调用feishu_search_messages，在对应的项目群中，查找会议开始时间后的所有消息。
    • 利用 LLM 分析这些消息，识别出“待办事项”、“决策点”、“问题”等结构化信息。
    • 调用feishu_create_doc创建一个新的云文档，将结构化信息写入，生成一份简洁的会议纪要。
    • 调用feishu_get_chat_members获取项目群成员列表。
    • 调用feishu_send_message，@相关成员，发送一条汇总消息：“会议纪要已生成，包含 X 个待办。详情请查收文档：[链接]”。
  5. 闭环：整个流程无需人工干预，从会议结束到通知发出，可能在几分钟内自动完成。

这个案例展示了如何将飞书的事件系统、OpenClaw 的 API 操作能力、以及 Hermes Agent 的逻辑编排与理解能力结合起来，创造出强大的自动化场景。

编程学习 学习日记 实战经验
← 返回列表