1. 从零到一为什么你需要 Hermes Agent 与 OpenClaw 的组合如果你正在寻找一个能帮你自动处理飞书消息、管理文档、甚至执行代码的“数字助理”那么 Hermes Agent 和 OpenClaw 这对组合可能就是你在找的答案。这听起来可能有点技术门槛但别担心这篇教程的目标就是“喂饭级”——我会把每一步都掰开揉碎让你即使没有深厚的开发背景也能亲手搭建起来。我们先来搞清楚这两个东西到底是什么以及它们组合起来能做什么。Hermes Agent 是一个开源的、功能强大的 AI 代理框架。你可以把它理解为一个“大脑”或“指挥中心”。它本身不直接处理具体的任务但它能理解你的指令比如“帮我总结一下飞书群里今天的讨论”然后去调用各种工具Tool来完成。这些工具可以是搜索网页、读写文件、执行命令等等。而 OpenClaw就是这样一个专门为处理飞书Lark消息而生的“超级工具”。它不是一个简单的机器人而是一个功能完备的 MCPModel 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 用户可以通过 WSL2Windows Subsystem for Linux获得一个完美的 Linux 环境这是目前最稳定且与教程兼容的方案。在 WSL2 中安装一个 Ubuntu 发行版接下来的操作就完全一致了。接下来是依赖安装。这里有一个关键点Node.js 的版本。Hermes Agent 对 Node.js 版本有要求官方推荐使用nvmNode 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 python3.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 buildbuild过程是编译 TypeScript 代码、打包前端资源的关键步骤。如果一切顺利你会看到成功的提示。但这里我遇到过两个典型问题内存不足在资源有限的虚拟机或 WSL 中构建前端部分时可能因内存不足而失败。解决方案是增加交换空间swap或者直接使用npm run build:light命令进行轻量构建它包含的功能对于入门和集成 OpenClaw 已经足够。权限问题如果在全局安装某些包时遇到权限错误不要使用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 的操作身份。这一步至关重要因为所有权限都在这里控制。登录 飞书开放平台 。点击“创建企业自建应用”给你的应用起个名字比如 “My-AI-Assistant”。进入应用后在“权限管理”页面为你的应用添加权限。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(日历)等。原则是你需要它做什么就勾选对应权限。然后点击“批量申请”。进入“事件订阅”页面这里暂时不需要配置除非你需要接收用户机器人的事件更高级的交互。对于 Hermes Agent 主动控制模式可以先跳过。进入“凭证与基础信息”页面这里有你需要的三个核心信息App IDApp SecretEncrypt 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“迁移”是部署中常被忽略但极其重要的环节。你可能需要在不同服务器间迁移或者将开发环境的配置同步到生产环境。迁移不仅仅是复制文件更要考虑环境一致性和数据连续性。场景一完整服务器迁移例如从旧虚拟机迁到新云主机环境复制在新服务器上重复 3.1 节的所有步骤确保 Python 版本、虚拟环境、pip 包版本完全一致。一个技巧是使用pip freeze requirements.txt在旧环境生成依赖列表然后在新环境用pip install -r requirements.txt安装。配置文件迁移直接复制~/.config/openclaw/config.yaml文件。这是核心。数据迁移如果有OpenClaw 默认可能使用本地 SQLite 数据库如果配置了缓存或会话。数据库文件通常位于~/.cache/openclaw/或项目目录下。你需要找到这个.db文件并复制到新环境的相同路径。在复制前务必停止旧服务器的 OpenClaw 服务以免数据损坏。服务状态与日志如果你使用 systemd 或 supervisor 管理 OpenClaw 进程也需要迁移相应的服务配置文件。场景二仅配置更新例如 App Secret 轮换这是更常见的情况。你只需要更新config.yaml中的app_secret字段然后重启 OpenClaw 服务即可。如果 OpenClaw 是以常驻进程运行你需要找到进程 ID 并发送重启信号或者使用进程管理工具。# 假设用 systemd 管理 sudo systemctl restart openclaw # 或者如果是在终端前台运行先 CtrlC 停止再重新运行 openclaw server迁移中的经典陷阱app secret复制不上去这个问题常在网页表单中出现。原因可能是复制的内容包含不可见字符如空格、换行。解决方案是先粘贴到纯文本编辑器如记事本、VS Code中检查并清除首尾空格再重新复制粘贴到飞书开放平台。端口冲突新环境 8000 端口可能已被占用。修改config.yaml中的port为其他值如 8001并确保 Hermes Agent 的配置也相应更改。文件权限迁移配置文件或数据库后确保运行 OpenClaw 的用户如你的登录用户有对这些文件的读写权限。4. 桥接大脑与双手在 Hermes Agent 中配置 OpenClaw MCPHermes Agent 和 OpenClaw 都已就位现在需要让它们认识并握手合作。这通过在 Hermes Agent 中添加 OpenClaw 作为一个 MCP 服务器来实现。4.1 理解 MCP 配置的核心理念Hermes Agent 的配置通常位于~/.hermes/config.jsonLinux/macOS或%APPDATA%\.hermes\config.jsonWindows中。我们需要在这个配置里声明一个 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 界面配置可能通过界面管理。但底层依然是文件配置。我们直接修改文件找到或创建配置文件。对于从源码运行的开发模式配置路径可能在项目目录下如hermes-agent/.hermes/config.json。你可以先检查~/.hermes/目录。编辑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 进行配置。通过 Web UI 配置推荐确保npm run dev正在运行浏览器打开http://localhost:3000。在 Hermes Agent 的 Web 界面中寻找设置或配置区域通常是一个齿轮图标。找到 “MCP Servers” 或 “Tools” 相关的配置项。添加一个新的 MCP 服务器。在连接类型中选择“TCP”或“Socket”。在地址栏填写127.0.0.1:8000如果你的 OpenClaw 运行在同一台机器上。给这个服务器起一个名字比如feishu。保存配置。重启 Hermes Agent 的开发服务器如果它正在运行让新配置生效。4.3 验证连接与权限测试配置完成后如何验证 Hermes Agent 已经成功连接到了 OpenClaw 并拥有了飞书权限呢在 Hermes Agent 的聊天界面或工具调用界面你应该能看到新添加的工具列表。这些工具的名字可能以feishu_或openclaw_开头例如feishu_send_message,feishu_list_chats等。进行一个简单的测试。尝试让 Hermes Agent 执行一个飞书操作。例如你可以输入指令“列出我所有的飞书群聊”。Hermes Agent 会解析指令调用 OpenClaw 的对应工具。观察 Hermes Agent 的日志和 OpenClaw 服务器的日志。如果连接成功你会看到 Hermes Agent 向127.0.0.1:8000发送了请求而 OpenClaw 服务器则收到了 MCP 请求并开始调用飞书 API。首次授权当你第一次执行一个需要较高权限的操作如读取所有群聊时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 构建自动化工作流一个完整案例让我们设计一个从触发到执行完毕的完整工作流感受一下这个组合的自动化威力。目标当飞书日历上的“项目评审会”结束时自动将会议纪要云文档链接、会上产生的待办事项从聊天记录中提取打包并发送给相关项目群的全体成员。步骤分解触发使用飞书开放平台的“事件订阅”功能订阅日历事件结束的推送。当事件触发时飞书会向一个你指定的、公网可访问的 URLWebhook发送 POST 请求。你需要一个接收器可以是一个简单的服务器如用 Python Flask 快速搭建。接收与解析这个接收器服务器收到事件后解析出会议主题、参与者、结束时间等信息。调用智能体接收器服务器通过 HTTP 请求调用 Hermes Agent 的 API如果暴露了的话或者直接将解析后的信息作为输入触发一个预定义在 Hermes Agent 中的“工作流”。智能体执行Hermes Agent 收到指令“处理刚结束的会议 ‘会议名’”。它首先调用feishu_search_messages在对应的项目群中查找会议开始时间后的所有消息。利用 LLM 分析这些消息识别出“待办事项”、“决策点”、“问题”等结构化信息。调用feishu_create_doc创建一个新的云文档将结构化信息写入生成一份简洁的会议纪要。调用feishu_get_chat_members获取项目群成员列表。调用feishu_send_message相关成员发送一条汇总消息“会议纪要已生成包含 X 个待办。详情请查收文档[链接]”。闭环整个流程无需人工干预从会议结束到通知发出可能在几分钟内自动完成。这个案例展示了如何将飞书的事件系统、OpenClaw 的 API 操作能力、以及 Hermes Agent 的逻辑编排与理解能力结合起来创造出强大的自动化场景。