Hermes Agent 本地部署完整教程：从环境配置到飞书机器人接入-平芜编程栈

我最早接触 Hermes Agent，是在一个技术交流群里看到有人问“装是装好了，但模型连不上，飞书机器人也不回话”。当时我就意识到，很多人把它的定位搞错了——Hermes Agent 不是一个下载完就能聊天的对话框，而是一个需要按顺序配置的智能体框架。这篇教程就按我自己从零跑通的路径来写：先准备环境，再装 Hermes Agent，然后接入模型，最后把飞书机器人点对点打通。每一段命令都直接复制可用，尽量照顾纯新手，也解释每一步为什么要这么做。

1. 先搞清楚 Hermes Agent 的架构，再动手安装

1.1 它不是“聊天软件”，而是一套 Agent 运行框架

如果你把 Hermes Agent 理解成“另一个 ChatGPT 客户端”，后面大概率会卡在各种奇怪的配置上。它实际上是一个以命令行和配置文件为核心的 AI Agent 框架，负责把“模型调用”和“外部工具操作”编排成一条可执行的自动任务链。你输入一个任务，Hermes 会自己决定调用哪个模型、执行哪些工具、把工具返回的结果再反馈给模型，如此循环，直到任务完成。

打个比方：ChatGPT 这类产品是“你去店里点菜，厨师做好端给你”；Hermes Agent 更像“你雇了一个厨师团队，你给菜单，团队里的采购、切菜、炒菜、摆盘各司其职，最后由一个机器人服务员把菜端到客人面前，比如飞书机器人”。

1.2 Hermes Agent 的四个核心角色：引擎、模型、工具、配置

我第一次看 Hermes Agent 的目录结构时，也被一堆文件夹吓到。拆开看其实就四层：

角色	作用	对应你操作的东西
引擎（Hermes Core）	负责任务循环、决策、调度	安装包本身
模型后端（Backend）	屏蔽不同模型的差异	config.yaml 里的 model_backends 段
工具插件（Tools）	让 Agent 能做外部动作	飞书、HTTP、表格、文件生成等插件
配置层（Profiles）	决定“用哪个模型”“接哪些工具”	.hermes 目录下的 YAML 文件

这套设计的最大好处是解耦。你想从 DeepSeek 换成智谱 GLM，只要改配置里的 base_url 和 model 名，Agent 的逻辑代码完全不用动。你想从飞书换到钉钉，也只是换插件，不用重写业务流程。

1.3 为什么新手值得从 Hermes Agent 入手

市面上能做 Agent 的工具很多，Hermes Agent 对新手的友好之处在于“渐进式复杂”。第一周你只需要会用 hermes chat 和模型对话；第二周可以加一个工作流；第三周再接入飞书机器人。每一步都踩在相对标准化的命令和配置上，不会一上来就逼你写复杂代码。

另外它的资料相对集中，中文社区讨论也活跃。搜索“Hermes Agent 安装”“Hermes Agent Windows 本地安装”能刷出一堆经验帖，说明它不是一个小众到没人管的玩具项目，而是有人在持续维护和填坑的东西。对新手来说，“有人跟我踩过同样的坑”本身就是一种安全感。

2. 装之前要补的课：环境准备清单与常用命令

2.1 Python 和 Git 是两道硬门槛

Hermes Agent 本体是用 Python 写的，所以你的电脑上必须要有 Python 环境。很多新手安装失败，不是 Hermes 的问题，而是 Python 没装好，或者是版本不对。

建议装 Python 3.10、3.11 或 3.12，不建议用 3.13。原因很简单：Hermes 的部分依赖库对 3.13 的适配还不完善，装的时候可能报“找不到 wheel”或者编译失败。我见过有同学一上来装最新版 Python，结果 pip install 阶段直接红屏。Windows 用户在 python.org 下载安装包时，记得勾选 “Add Python to PATH”，否则后面输入 python 会提示“不是内部或外部命令”。

Git 用来下载源码仓库和后续升级，同样建议装。两个都装好之后，打开终端验证一下：

python --version git --version

能看到版本号输出，就说明基础环境没问题。如果 python 命令无效，试试 py --version，Windows 下多种 Python 共存时 py launcher 是更稳的入口。

2.2 用虚拟环境隔离依赖，避免污染系统 Python

新手最容易忽略虚拟环境，直接把东西装进系统 Python。短时间看没问题，但当你同时跑两三个项目，A 项目要求 requests 2.28，B 项目要求 requests 2.31，就知道什么叫“依赖地狱”了。

我习惯在项目目录里建一个纯隔离的虚拟环境：

mkdir hermes-project cd hermes-project python -m venv venv

激活方式根据系统不同有区别：

# Windows PowerShell .\venv\Scripts\activate # macOS / Linux source venv/bin/activate

激活成功之后，终端行首会出现 (venv) 字样。以后安装 Hermes 和插件，全部在这个环境里操作。想退出环境，输入 deactivate 即可。

2.3 给 pip 配一个速度快一点的镜像源

Hermes Agent 的依赖不少，直接走默认源下载，在国内经常几十 KB/s 地爬，装一个包能等十分钟。这不是命令的问题，是网络链路的问题。提前换一个镜像源，能省很多时间。

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

阿里云源也可以：

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

配完之后，pip install 的下载速度会明显提升。这个操作是给包管理工具换下载地址，也是社区里常见做法，可以放心用。

2.4 Windows 用户需要额外留意的两个点

第一，部分依赖需要 C++ 编译。有些 Python 包在 Windows 上没有预编译版本，安装时要现场编译，这时候系统里得有 Microsoft C++ Build Tools。用 winget 可以快速安装：

winget install Microsoft.VisualStudio.2022.BuildTools

安装过程中记得勾选“使用 C++ 的桌面开发”工作负载。如果电脑上已经装了 Visual Studio 2022 并且勾选了这一项，可以跳过。

第二，控制台中文乱码。Windows 默认终端在跑部分 Python 程序时可能乱码，尤其是打印日志时。提前执行下面两行，能减少很多视觉上的迷惑：

chcp 65001 set PYTHONIOENCODING=utf-8

chcp 65001 是把控制台代码页切成 UTF-8，第二个命令告诉 Python 用 UTF-8 输出。这个组合在配飞书时尤其有用，不然中文消息日志全变成“锟斤拷”，你根本不知道发生了什么。

3. 正式安装 Hermes Agent：pip、源码、桌面版三条路

3.1 方式一：pip 安装，新手首选

在虚拟环境激活的前提下，直接安装：

pip install -U hermes-agent

安装完成后，验证一下：

hermes --version

如果提示找不到 hermes，多半是虚拟环境没激活，或者 Python Scripts 目录没在 PATH 里。Windows 下可以手动把 venv\Scripts 路径加进去，但最省事的还是重新激活环境后再试。

pip 安装的好处是省事，坏处是拿到的不是最新开发版。对于绝大多数人来说，稳定版完全够用，别为了“追新”去折腾源码。

3.2 方式二：源码安装，适合想改代码的进阶者

源码安装的原理是从官方仓库把代码拉下来，然后以“可编辑模式”安装，代码改了之后立即生效，适合想给 Hermes 提交 PR 或者自己加插件的人。

git clone <Hermes Agent 官方仓库地址> cd hermes-agent pip install -e .

注意尖括号里的地址需要替换成仓库实际地址，最好去官网或 GitHub 页面复制，不要凭记忆敲。源码安装后，动态库路径偶尔会被系统 Python 干扰，所以一定要在虚拟环境里执行这组命令。

3.3 方式三：桌面版 / Windows 本地安装包

如果你不想碰命令行，Hermes Agent 也有桌面版安装包，Windows 下通常是 .exe 或 .msi 文件。去官网或发布页下载后，双击安装，一路 Next 即可。

桌面版本质上是把 Python 解释器和 Hermes 核心打成一个独立程序，自带依赖，不用你自己配环境。对纯小白来说，这确实是最省心的方式。不过后续接模型、配飞书时，还是需要打开终端输入 hermes 命令，所以终端的基础操作依然要会。

安装包版的另一个好处是升级简单，覆盖安装新版即可。缺点是自定义能力弱一些，比如你想换一个没有被内置的模型供应商，可能需要去改配置文件，而桌面版不一定把配置目录暴露得很直观。

3.4 初始化配置项与验证安装是否成功

安装完成后的第一件事是初始化：

hermes init

它会生成一个 .hermes 目录，里面至少包含：

config.yaml：核心配置，模型后端、飞书、插件开关都在这里。
profiles.yaml：不同场景下的参数组合。
tools/：工具插件的目录。
logs/：运行日志位置，排错时最重要。

初始化完成后用 hermes doctor 做一次自检：

hermes doctor

它会检查 Python 版本、依赖是否完整、模型后端能否连通、配置文件语法有没有问题。我强烈建议新手第一次跑通后，先把 hermes doctor 的输出保存一份，之后再改什么配置出了问题，至少知道哪一项是原本正常的。

如果 pip 安装过程报 ModuleNotFoundError，别慌。先把 Hermes 升级到最新：

pip install -U hermes-agent

再装一下它声明的全部依赖。如果是源码安装的：

pip install -r requirements.txt

还不行，就回头看 2.4 节，把 C++ Build Tools 装上，很多编译类报错都是缺少这个引起的。

4. 让 Hermes Agent 开口说话：模型接入与本地部署速度调优

4.1 模型接入的两种方式：本地模型和云 API

Hermes Agent 自己不带模型，它只负责调度。所以安装完成后，你还要给它接一个“大脑”。从易用性角度，我建议新手优先走云 API，等跑通了再玩本地模型。两者对比如下：

对比项	本地模型	云 API
硬件要求	需要一定显存/内存	只需要能联网
速度	受硬件限制，可能较慢	通常更快更稳定
费用	电费而已	按 token 计费
隐私性	数据不出本机	数据经过第三方服务
适合人群	有 GPU、重隐私需求	新手、快速验证、生产级稳定性要求高

4.2 本地模型路线：用 Ollama 把模型跑起来

本地模型方案里，我推荐用 Ollama 做运行时，它对配置要求低，安装也简单。Windows 下可以用：

winget install Ollama.Ollama

macOS 和 Linux 用户直接去官网下载安装包或按官方脚本安装。装好后先启动服务：

ollama serve

正常会看到监听在 11434 端口的日志。再开一个新终端，拉取一个适合入门的中小规模模型，比如阿里的 Qwen2.5 7B：

ollama pull qwen2.5:7b

这一步会下载几个 GB 的文件，取决于你的网络速度。拉取完成之后，在 Hermes 的 config.yaml 里增加一个本地模型后端：

model_backends: - name: "local" provider: "openai_compatible" base_url: "http://localhost:11434/v1" api_key: "ollama" model: "qwen2.5:7b"

Ollama 对外提供了兼容 OpenAI 格式的接口，所以 Hermes 只需要把它当成一个本地 API 服务来连。api_key 随便填一个非空字符串就行，本地服务多数不校验。

4.3 云 API 路线：用 DeepSeek、智谱、通义快速跑通

云 API 的接法跟本地模型非常像，只是把 base_url 和 api_key 换掉。以 DeepSeek 为例，去它的开放平台注册账号、创建 API Key，然后在文件里配置：

model_backends: - name: "deepseek" provider: "openai_compatible" base_url: "https://api.deepseek.com/v1" api_key: "sk-你的Key" model: "deepseek-chat"

智谱和通义也是同样的结构，只有 base_url 和 model 名不同。按对应平台最新文档替换即可。

一个经验：不要为了“支持国产”或“便宜”盲目选模型，先看你日常跑的任务是什么类型。代码生成类任务，DeepSeek 系列表现不错；通用对话和总结类，Qwen 和 GLM 系列都能打。新手可以把两三个模型都配上，然后在 profiles.yaml 里切换，感受一下实际差异。

4.4 为什么本地部署模型会卡：显存、量化、上下文长度都要管

热搜词里有“Hermes Agent 跑本地部署模型速度慢”，这几乎是所有本地部署新手都会碰到的问题。慢的根源通常不是 Hermes 本身，而是模型推理环节。

模型参数量。7B 模型如果用 FP16 精度加载，光权重就占约 14GB 内存；4-bit 量化后可以压到 4~6GB。显存不够时，系统会偷偷把参数放在内存里跑，速度会断崖式下降。
内存带宽。生成 token 的速度约等于内存带宽除以模型体积。DDR5 内存带宽大约 50GB/s，一个 4GB 的量化模型理论速度也就 12 token/s 左右，实际打六折很正常。
上下文长度。上下文越长，推理时占用的显存越多，计算量也越大。很多人把上下文设成 32K，跑起来当然卡。对飞书机器人对话这种场景，4096 完全够用。

在 Ollama 启动时，可以限制上下文长度来提速：

ollama run qwen2.5:7b --num-ctx 4096

或者直接设置环境变量，告诉 Ollama 优先用 GPU：

set OLLAMA_NUM_GPU=999

意思是能放 GPU 就放 GPU。如果你用的是 NVIDIA 显卡，还可以通过 ollama ps 查看当前模型的显存占用，确认到底有没有走 GPU。

4.5 模型连通性自检清单

配好模型后，先跑一个最直接的自检：

hermes chat -m qwen2.5:7b --prompt "你好，请回复收到"

如果通了，说明 Hermes 到模型这部分没问题。常见的报错就三类：

401 Unauthorized：API Key 不对，或者本地 Ollama 的 api_key 为空导致请求被拒。
404 / model not found：模型名写错，或者本地模型没拉取成功。
timeout：网络不通。如果你连的是境外模型服务，超时非常正常；建议优先用国内可访问的模型平台。

日志是排错最好的朋友。Hermes 的日志默认写到 .hermes/logs/ 下，用 hermes logs -f 可以实时跟踪。看到哪个环节红字，就去修哪一块，别盲目重装。

5. 接飞书机器人：从创建应用到推送表格全流程

5.1 飞书机器人的运行逻辑，先说清楚

飞书机器人不是一个“钉在群里的按钮”，它本质上是两个程序通过飞书开放平台的中转通道在对话。Hermes 启动一个服务，飞书开放平台把群里用户发给机器人的消息，通过 Webhook 或长连接方式推给 Hermes；Hermes 把文本作为问题交给 Agent，Agent 调用模型生成回答；最终 Hermes 调用飞书消息 API，把回答发回聊天窗口。

理解了这个链路，你就知道配置阶段的三个关键点：应用身份（App ID/App Secret）、事件接收方式（Webhook 或长连接）、消息发送权限（权限管理里开通）。这三样齐了，机器人才能真正干活。

5.2 在飞书开放平台创建企业自建应用

操作路径是飞书开放平台 → 开发者后台 → 创建企业自建应用。如果是第一次创建，需要企业管理员账号扫码登录。

创建后按下面顺序配置：

在“应用能力”里添加“机器人”能力，这是机器人出现在群里的前提。
进入“事件订阅”，添加事件im.message.receive_v1，表示“当用户给机器人发消息时通知 Hermes”。
接收方式选择“使用长连接接收事件”。这是新手最容易忽略的一步。很多教程默认让你填回调地址，但回调地址需要一台有公网 IP 的服务器，普通家用电脑和云服务器之间还要额外处理端口映射。长连接模式是 Hermes 主动连飞书服务器，你的电脑不需要公网地址，配置难度下降一大截。
在“权限管理”里开通机器人发消息和读取消息的权限，具体权限项以飞书开放平台实际列表为准，常见的包括im:message、im:message:send_as_bot等。
最后点“创建版本”并发布，等待应用状态变为“已发布”。

很多人卡在最后一步：应用没发布，只有创建者本人能看到测试机器人，群里其他成员根本不显示机器人。所以发布这一步不能省。

5.3 Hermes 端安装飞书插件并配置

飞书应用创建好后，你会拿到 App ID 和 App Secret。这两个字符串相当于机器人的账号密码，要妥善保管。

在 Hermes 里安装飞书插件：

hermes plugin install feishu

然后在 config.yaml 里增加一个 feishu 段：

feishu: app_id: "cli_xxxxx" app_secret: "你的AppSecret" event_mode: "websocket"

这里的 event_mode websocket 就是前面说的长连接模式。配置完成后，启动 Hermes 服务：

hermes server start

启动日志里如果出现类似 feishu websocket connected 的信息，说明机器人和飞书开放平台已经连上了。这时候去飞书群里私聊或 @机器人发一句“你好”，它应该会回你。

如果没反应，先别急着检查代码，先看日志。我见过至少三个案例，都是配置文件里的 app_secret 复制时多了一个空格，导致鉴权失败。日志里一般会显示invalid signature或auth failed，一眼就知道问题方向。

5.4 如果必须用 Webhook 回调模式，需要注意什么

长连接模式不是万能的。有些场景下，你还在第二台服务器上部署了其它服务，希望飞书事件直接打到 Hermes 暴露的 HTTP 接口上，那就得用 Webhook 方式。这时候需要一台有公网 IP 的机器，并在事件订阅里填一个回调地址，格式大致是：

https://your-domain.com/feishu/event

第一次配置 Webhook 时，飞书开放平台会向这个地址发送一个验证请求。Hermes 收到后会自动响应验证，但前提是你把 encrypt_key 和 verification_token 也填进了配置。这个“验证不通过”的坑，我踩过一次，原因是把 encrypt_key 和 verification_token 填反了。一旦填反，平台返回的是验证失败，而日志里只提示 verification failed，不会告诉你具体哪个字段不对。解决办法就是逐个对着平台后台确认。

对新手来说，我真的建议先走长连接，等所有流程都理解了，再按需切换到 Webhook。

5.5 让机器人把数据生成表格发到群里

“飞书机器人发送表格”是很多人搜索的目标。在实际使用里，分两种典型情况：

第一种，把 Agent 生成的结果导出成 CSV 文件，再作为附件发到群里。Hermes 的飞书插件通常提供文件发送入口，类似：

hermes feishu send-file --chat_id "oc_xxxxxxx" --file "./report.csv"

chat_id 是群聊的唯一 ID，在飞书群的设置里可以找到。如果你的 Agent 有数据分析功能，可以先让它生成 CSV，再通过这条命令发出去。

第二种，调用飞书多维表格 API，把数据写入一张在线工作表，然后把链接推送到群里。这种方式适合需要多人协同编辑的报表。配置上需要额外开 bitable 相关权限，然后让 Hermes 通过插件调用多维表格的写入接口。

我比较常用的组合是：让 Hermes 定时跑一个任务，统计日志里的错误数量，生成一张 CSV，再往群里发一句“今日错误汇总已完成”，附上文件。整个链路跑通后，基本可以替代一部分人工巡检的活。

5.6 飞书机器人不回消息的排查顺序

如果机器人毫无反应，按下面顺序排查：

打开hermes logs -f，看有没有收到消息事件。如果日志里完全没有事件，说明飞书开放平台到 Hermes 的连接有问题。
检查应用是否已经发布。未发布的应用只有你一个人能看到机器人。
检查权限是否开通，以及发布版本是否包含最新权限。
检查事件订阅里是否添加了im.message.receive_v1，并且消息接收方式选的是长连接。
检查配置里的 app_id、app_secret 是否有隐藏空格或换行符。
确认群里 @机器人的格式。有些配置要求消息前缀必须包含关键词，你没触发它自然不响应。

这条线排完，90% 的问题都能定位。

6. 新手最容易踩的五个坑，我按踩中频率排序

6.1 安装时卡在依赖下载或编译

症状是 pip install 执行到某个包时报红色错误，常见的像 pydantic、tokenizers 这类含 C 扩展的包。原因要么是网络下载慢，要么是缺少编译工具。解决方法是先用 2.3 节换镜像源，再装 2.4 节的 C++ Build Tools。如果还不行，直接换 Python 3.11 再试一次。实践下来，Python 3.11 在兼容性上最稳。

6.2 模型接入后报 401 或 timeout

绝大部分是配置问题。401 检查 API Key 是否正确、api_key 字段有没有被误删。timeout 优先检查网络。如果你用的是境外模型服务，超时大概率是网络链路问题，建议换成国内平台或者本地模型，而不是反复提高超时时间，那只是治标不治本。

6.3 本地模型回答一句话要想半天

先跑ollama ps看模型是否真正加载到 GPU。如果显示 CPU 也在跑，检查 4.4 节的 OLLAMA_NUM_GPU 环境变量。再换一个量化版本更低的模型，比如把 qwen2.5:7b 换成 qwen2.5:3b 甚至 1.5b。硬件不够的时候，参数更小的模型带来的体验提升，远大于任何花哨配置。

6.4 飞书机器人能看到，但始终不回复

多数情况是权限和发布状态问题。自查顺序：应用是否发布、权限是否包含发消息、事件订阅是否开启长连接、配置是否填错。还有一个隐藏坑：飞书平台把“机器人”和“应用”分成两个能力，只创建应用不添加机器人能力，群里是拉不进机器人的。

6.5 控制台中文乱码、命令窗口闪退

中文乱码用chcp 65001配合set PYTHONIOENCODING=utf-8。命令窗口闪退多半是运行 hermes 时缺少交互终端，不要直接双击运行桌面版的控制台入口，从现有终端里敲命令更稳。另外，Hermes 的日志和缓存默认存放在用户目录的 .hermes 文件夹下，跑了一段时间后体积可能很大。清理缓存的命令很简单：

hermes cache clean

Windows 下如果想彻底一点，可以手动删除%USERPROFILE%\.hermes\cache和%USERPROFILE%\.ollama\models里不再使用的旧模型文件。C 盘空间紧张时，这个目录是很容易忽略的“大户”。

最后分享一个我自己的使用习惯：配置阶段全程开着hermes logs -f看日志，改一步看一步，不要一次改完再启动。我遇到过太多人一次性填了模型、飞书、插件一堆配置，结果报错后根本不知道先查哪里。日志会直接告诉你哪个环节红了，跟着日志走比对着网上的截图猜要快很多。先小步跑通，再逐步加复杂功能，这才是 Hermes Agent 最舒服的上手方式。

Hermes Agent 本地部署完整教程：从环境配置到飞书机器人接入