Win11 下 Hermes Agent 安装、工具与 Skill 完全教程

前言：为什么你需要关注 Hermes Agent？

最近，开源社区一款名为 Hermes Agent（爱马仕 Agent）的 AI 智能体框架正在悄悄“炸场”——GitHub 星标数不断攀升，社区讨论热度居高不下。它不同于市面上某些“龙虾”类的 agent 框架，Hermes Agent 的核心理念是 自学习 与 轻量化部署，支持一行命令安装、六种执行后端、飞书/微信等 IM 集成，并且能够通过安装 Skill 实现能力自我进化。很多人第一反应是：“它能帮我自动写周报吗？”“能帮我管理文件吗？”——答案是能，而且比你想象的要强大。

对我而言，Hermes Agent 最吸引人的地方在于：它不只是一个聊天接口，而是一个真正可以执行本地任务、拥有记忆和工具调用能力的数字助手。在 Windows 11 上，借助 WSL2 的 Linux 内核，我们能完整发挥这套框架的强大功能。本教程将从零开始，带你一起在 Win11 环境中完成 Hermes Agent 的安装、常用工具链配置、模型对接，并深入讲解 Skill 的安装与自定义方法。文末还会附上飞书接入的避坑指南，以及我亲身踩坑后总结的 9 个核心技巧。

这篇文章将手拉手带你走完以下内容：

• Win11 + WSL2 环境准备
• Hermes Agent 一键安装与源码部署
• LLM 模型配置（本地模型 & 云端 API）
• 主题压缩、辅助模型等高级配置
• 常用工具（ripgrep、fd、jq 等）的安装与集成
• Skill 安装与编写入门
• 飞书机器人接入全流程
• 20+ 条实用避坑经验

不论你是想给自己的 Windows 加一个聪明的本地助手，还是准备把 Hermes Agent 接入团队协作，这篇教程都力求让你“小白进，大神出”。

一、Win11 环境配置：为 Hermes 准备的“地基”

Hermes Agent 是运行在 Linux 环境下的 Python 项目，因此在 Windows 上部署最优雅的方式就是 WSL2（Windows Subsystem for Linux 第二代）。如果你之前安装过 WSL，请确保版本为 2；如果从未接触，下面的步骤会让你轻松搞定。

1.1 启用 WSL2 并安装 Ubuntu

以管理员身份打开 PowerShell，执行以下命令：

wsl --install

这个命令会自动启用必需的组件，并安装默认的 Ubuntu 发行版。重启系统后，WSL2 将作为默认版本。如果已经安装过 WSL1，可以通过 wsl --set-version <distro> 2 升级。

安装完成后，在开始菜单找到 Ubuntu，首次启动会要求设置用户名和密码。请牢记这个密码，之后运行 sudo 命令时需要。

1.2 更新系统与必要依赖

进入 WSL2 终端后，先更新软件包列表并升级已安装的软件：

sudo apt update && sudo apt upgrade -y

接着安装一些基础依赖，Hermes Agent 后续安装脚本可能会用到：

sudo apt install -y curl git build-essential python3 python3-venv python3-pip

其中：

• curl 用于下载安装脚本；
• git 用于克隆代码仓库；
• build-essential 提供编译工具（某些 Python 包需要编译）；
• Python 3 环境是框架的基石。

1.3 （可选）配置 Windows Terminal 与系统代理

为了获得更好的体验，推荐在 Microsoft Store 安装 Windows Terminal，将 WSL 设为默认终端。如果你的网络环境访问 GitHub 缓慢，可以在 WSL 中配置代理。编辑 ~/.bashrc，添加：

export host_ip=$(cat /etc/resolv.conf |grep "nameserver" |cut -f 2 -d " ")
export http_proxy="http://$host_ip:7890"
export https_proxy="http://$host_ip:7890"

保存执行 source ~/.bashrc，其中 7890 请替换为你 Windows 主机上代理客户端的端口。注意，此操作要求 Windows 防火墙允许 WSL 访问主机端口。

环境地基已经打牢，接下来进入 Hermes Agent 的真正安装过程。

二、安装 Hermes Agent：两种主流方式

社区提供了两种安装路径：一键 curl 自动安装 和 手动克隆源码安装。一键脚本非常方便，适合想快速体验的朋友；手动安装则更灵活，便于二次开发和理解内部结构。

2.1 方式一：官方 curl 一行安装（推荐新手）

Hermes Agent 官方仓库中维护了一个安装脚本，可以直接通过 curl 执行，自动完成克隆仓库、创建虚拟环境、安装依赖等操作。

在 WSL 终端中执行：

curl -fsSL https://raw.githubusercontent.com/HermesAgent/hermes-agent/main/install.sh | bash

脚本开始后，会逐步输出安装进度，包括：

• 克隆 Hermes Agent 主仓库到 ~/hermes-agent；
• 在仓库内创建 Python 虚拟环境；
• 安装所有必需的 Python 依赖；
• 下载默认的辅助模型文件（如用于主题压缩的小模型）；
• 生成初始配置文件。

首次运行耗时取决于网络与机器性能，通常在 3~8 分钟左右。安装成功后，终端会提示你进入目录并激活环境：

cd ~/hermes-agent && source .venv/bin/activate

2.2 方式二：手动克隆安装（推荐进阶用户）

如果你想对安装过程有更多控制权，或者网络环境导致脚本运行失败，可以手动操作。

首先克隆仓库并进入：

git clone https://github.com/HermesAgent/hermes-agent.git ~/hermes-agent
cd ~/hermes-agent

创建并激活虚拟环境：

python3 -m venv .venv
source .venv/bin/activate

安装依赖：

pip install -r requirements.txt

如果遇到某个包安装失败，多半是缺少编译工具或系统库。例如安装 sentencepiece 可能缺少 cmake，可以通过 sudo apt install cmake 解决。建议保持 pip 版本最新：pip install --upgrade pip。

安装完成后，同样需要配置模型和运行环境。

2.3 安装脚本背后的秘密：工具依赖补充

主安装脚本默认会安装一些高效的命令行工具来增强 Agent 的能力，如：

• ripgrep (rg)：快速全文搜索工具；
• fd-find (fdfind)：现代化的 find 替代品；
• jq：命令行 JSON 处理器；
• pandoc：文档格式转换工具（用于处理各种文件）。

如果一键脚本遗漏了某些工具（例如在 Ubuntu 22.04 上 fd-find 的命令名可能是 fd-find 而不是 fd），你可以手动补充：

sudo apt install ripgrep fd-find jq pandoc
ln -s $(which fdfind) ~/.local/bin/fd   # 创建一个 fd 命令链接

这些工具赋予了 Agent 搜索文件系统、处理结构化数据的能力，后续章节会展开讲解它们的用法。

2.4 首次运行：Hello Hermes

在 hermes-agent 目录下且虚拟环境激活时，输入：

python -m hermes

如果不报错且出现交互提示，说明核心框架已经跑通。不过此时还没有对接 LLM 模型，它无法给出聪明回复，我们需要继续配置“大脑”。

三、对接 LLM 模型：赋予 Agent 灵魂

Hermes Agent 支持多种模型后端，包括 Ollama、OpenAI API、LM Studio、Groq 等。每种后端都有其适用场景，下面分别介绍配置方法，你可以根据自己的硬件和需求选择一种或多种。

3.1 使用 Ollama 部署本地开源模型

Ollama 是目前最流行的本地模型运行工具，简化了部署和推理过程。首先要确保 WSL2 中已安装 Ollama。如果尚未安装，执行：

curl -fsSL https://ollama.com/install.sh | sh

安装完成后，启动 Ollama 服务（或者让它后台运行）：

ollama serve

然后拉取一个你喜欢的模型，例如 llama3.1:8b 或 qwen2:7b。对于硬件资源有限的朋友，建议使用 phi3:mini 或 gemma2:2b 这类轻量级模型。

ollama pull llama3.1:8b

等待模型下载完毕，运行 ollama list 确认模型就位。

在 Hermes Agent 中配置 Ollama 非常简单。首次执行 python -m hermes 时，会在 ~/.hermes/config.yaml 生成默认配置文件。编辑该文件，找到 LLM 配置段，修改为：

llm:
  backend: ollama
  model: llama3.1:8b
  ollama_base_url: http://localhost:11434
  temperature: 0.7

保存后重新运行 Agent，它就会使用本地的 Ollama 服务进行推理。如果 Ollama 没有正确运行，Agent 会报连接错误，此时请检查 ollama serve 是否在运行。

避坑提示：

• WSL2 的内存占用问题：Ollama 加载大模型（如 8B）可能会消耗大量内存，建议在 .wslconfig 中设置内存上限，防止系统卡死。
• 模型首次加载时会比较慢，耐心等待即可。

3.2 接入 OpenAI 或兼容接口

如果你有 OpenAI 的 API Key，或使用第三方代理（如 ChatAnywhere、API2D 等），可以配置为：

llm:
  backend: openai
  model: gpt-4o-mini
  api_key: sk-your-api-key
  api_base: https://api.openai.com/v1   # 或自定义代理地址
  temperature: 0.7

对于没有国际信用卡的用户，可以使用国内的一些中转服务，将 api_base替换为相应的地址即可。

注意：配置文件中的 api_key 是明文的，请确保该文件的读取权限仅限于自己。你可以用 chmod 600 ~/.hermes/config.yaml 来保护它。

3.3 辅助模型与主题压缩配置

Hermes Agent 的一大特色是 对话主题压缩。在长对话中，Agent 会定期将历史内容压缩为摘要，以节省上下文窗口。此功能需要一个小型摘要模型。官方默认使用 Ollama 上的 tinyllama 或 phi3:mini。如果你的主模型已经足够小，也可以指定它兼任摘要模型，但推荐使用专门的小模型以降低延迟。

配置文件中添加：

summary_llm:
  backend: ollama
  model: phi3:mini            # 或者其他 1~2B 的模型
  temperature: 0.2

如果本地没有资源运行第二个模型，可以将摘要模型设置为和主模型一样，或者使用更低成本的云端 API（如 gpt-3.5-turbo）。

此外，你可以调整压缩触发的长度阈值：

compact_after_tokens: 4000
keep_memory_tokens: 2000

这里数值根据你使用的模型上下文长度灵活设置。8B 模型一般可设为 6000~8000。

四、常用工具集成与实践技巧

Hermes Agent 的一个强大之处在于它能够调用系统工具来完成复杂任务。这些工具不仅仅是内部代码，很多是你系统中已经安装的命令行利器。Agent 通过自主判断，选择合适的工具来解决问题。因此，工具链的完善程度，直接影响 Agent 的“生产力”。

4.1 ripgrep：秒速搜索文件内容

ripgrep (rg) 是 Agent 发现信息的重要触手。假设你要求 Agent：“找出所有包含 TODO 的 Python 文件”，它会自动构造类似 rg "TODO" --glob "*.py" 的命令并执行。确保 Agent 环境中 rg 可用。安装前面已有介绍。测试命令：

rg "hermes" ~/hermes-agent/README.md

如果返回高亮结果，说明正常工作。

4.2 fd：快速定位文件与目录

fd 是一个超快的查找工具。Agent 用它来定位特定名称的文件。例如“把下载目录下所有 PDF 文件列出来”，Agent 就会用 fd -e pdf ~/Downloads。安装后请确保命令 fd 能直接使用，如果不能，可创建别名。在 WSL 中手动编译符号链接：sudo ln -s $(which fdfind) /usr/local/bin/fd。

4.3 jq：处理 JSON 数据的好帮手

很多 API 返回 JSON 格式数据，Agent 调用后需要解析，jq 应运而生。它能让 Agent 以声明式的方式取出想要的字段。例如执行 curl 某个API | jq '.data.name'。确保 jq 已安装：sudo apt install jq。

4.4 pandoc：打通文档格式墙

当 Agent 需要将 Markdown 转为 PDF、或提取 Word 文档内容时，pandoc 就是幕后英雄。安装：sudo apt install pandoc texlive-latex-base（后者是生成 PDF 的引擎）。随后 Agent 便可以执行类似 pandoc input.md -o output.pdf 的命令。

4.5 其他小工具：构建 Agent 的瑞士军刀

• entr：文件变化自动执行命令，可用于 Agent 监控文件修改。
• fzf：模糊查找工具，增强交互式选择。
• docker：如果 Agent 需要管理容器，可以安装 Docker Engine。

建议尽量多地在 WSL 中安装这些工具，Hermes Agent 会通过自然语言调用它们，你的日常任务自动化程度会大幅提升。

4.6 技巧总结：让工具发挥最大价值

• 明确指定工具：在对话中告诉 Agent “使用 fd 找到所有 .log 文件，然后用 rg 搜索 Error”，这样它会精准调用。
• 提供工具说明：如果你自己安装了特殊脚本，可以将使用说明写入 Hermes 的“tool registry”中（后面 Skill 部分会提到）。
• 测试工具可用性：在首次使用前，在 WSL 终端独立运行这些工具，排除环境变量问题。

五、Skill 安装与编写：让 Agent 自我进化

Hermes Agent 区别于普通聊天机器人的核心特性之一就是 Skill（技能）系统。Skill 是预定义的任务执行逻辑，可以看成一种“小程序”，让 Agent 具备处理特定领域问题的能力。官方和社区维护了大量 Skill，从文件管理到飞书消息处理，甚至是代码审阅。

5.1 Skill 的概念与作用

一个 Skill 通常包含：

• 元信息：名称、描述、触发条件；
• 执行逻辑：可以是 Shell 脚本、Python 函数，或一个 LLM 提示词；
• 参数定义：Skill 需要的输入参数。

Agent 接收到用户指令后，会判断是否需要调用 Skill，如果需要，则匹配最合适的 Skill，并填充参数执行，最后将结果返回给用户。例如，安装一个“生成周报”的 Skill，用户只需说“生成本周工作周报”，Agent 就会收集 git 提交记录、邮件摘要等信息，自动生成周报。

5.2 安装官方 Skill 市场中的 Skill

Hermes Agent 官方提供了 Skill 市场，通过命令即可浏览和安装。在激活的虚拟环境中，运行：

hermes skill list   # 列出可用的 Skill

比如看到名为 weekly-report 的 Skill，可以安装：

hermes skill install weekly-report

安装过程中脚本会自动下载 Skill 文件，并注册到 Agent 中。部分 Skill 可能依赖额外 Python 包或系统工具，安装脚本会提示补充。

5.3 手动安装第三方 Skill

很多社区开发者在 GitHub 上分享自己的 Skill，通常是一个文件夹或压缩包。你可以手动将其放入 Hermes 的 Skill 目录。默认 Skill 存放路径为 ~/.hermes/skills/。例如从某仓库下载一个名为 file-organizer 的 Skill：

cd ~/.hermes/skills
git clone://github.com/someone/hermes-skill-file-organizer file-organizer

之后 Hermes Agent 重启时，会自动扫描该目录并加载新的 Skill。你也可以通过 hermes skill reload 动态加载。

5.4 编写一个简单的自定义 Skill

假设我们创建一个名为 “hello_world” 的 Skill，功能是回显用户的名字并问好。

1. 在 ~/.hermes/skills/ 下创建一个新目录 hello_world。
2. 在该目录中创建 `skill.yaml，内容：

name: hello_world
description: 向用户问好
triggers: ["问好", "hello", "hi"]
parameters:
  - name: name
    type: string
    required: true
    prompt: "请输入你的名字"
executor:
  type: command
  command: "echo Hello, ${name}!"

3. 重启或重载 Skill：hermes skill。
4. 测试：在对话中输入“向我问好”，Agent 会识别为 hello_world Skill，然后请求你提供名字参数，最后输出 Hello, 张三!。

当然，这只是一个玩具示例。真实的 Skill 可以调用外部 API、读写文件、生成报表等。将常用操作封装为 Skill，可以极大提升 Agent 的实用性和个性化程度。

5.5 卡帕西 LLM Wiki 集成 Skill 实例

网络上有一个很受欢迎的 Skill，是集成了 Andrej Karpathy 的 LLM Wiki，允许 Agent 查阅 LLM 相关知识。安装该 Skill 后，你可以直接问 Agent “请解释 RoPE 位置编码”，Agent 会调用内置的搜索脚本，从 wiki 仓库中获取信息并组织语言回答。安装方法类似上面的手动安装，克隆仓库到 skills 目录。该 Skill 依赖本地有 wiki 的 markdown 文件，所以首次会提示下载知识库，耐心等待即可。

Skill 生态是 Hermes Agent 发展的发动机，如果你有想法，不妨动手写一个，分享给社区，让 Agent 越来越聪明。

六、飞书接入：让你的 Agent 进驻企业协作

将 Hermes Agent 接入飞书，可以实现通过飞书机器人直接与 Agent 交互，或者在群里 @机器人处理任务。这对于团队来说尤其有价值——你可以在群里让 Agent 帮忙查数据、发通知、执行脚本。下面一步步来。

6.1 创建飞书机器人并获取凭证

登录 飞书开放平台 ，创建一个企业自建应用。

• 点击“创建企业自建应用”，填写名称（如“Hermes 助手”），上传图标。
• 在“应用功能”中，启用“机器人”。
• 在“权限管理”中，搜索并添加以下权限：
  • im:message
  • im:message.group_at_msg
  • im:message.p2p_msg
  • im:message.group_msg（如果需要群聊）
  • im:resource（下载文件资源）
• 保存后，点击“发布版本”，由管理员审核通过。

然后在“凭证与基础信息”页面，获取 App ID 和 App Secret。这是 Agent 连接飞书的钥匙。

6.2 配置 Hermes Agent 飞书集成

Hermes Agent 官方深度集成了飞书，配置起来十分方便。找到 ~/.hermes/config.yaml，添加飞书配置段：

lark:
  app_id: "cli_aXXXXXXXXXXX"
  app_secret: "YOUR_APP_SECRET"
  encrypt_key: ""     # 如果消息加密了才填
  verification_token: ""     # 可空
  bot_name: "Hermes"

保存后，在飞书开放平台的事件订阅中，配置请求地址 URL。Agent 启动时会自动运行一个 HTTP 服务，默认端口 5858。因此你需要一个公网可达的地址。可以使用内网穿透工具（如 frp、ngrok），或者部署在云服务器上。如果只是本地测试，用 ngrok 快速生成一个临时域名：

ngrok http 5858

将生成的 https://xxxx.ngrok.io 作为事件回调地址填入飞书后台，并设置 Token（可选）。

6.3 启动 Agent 并测试

确保配置无误后，在 hermes-agent 目录下执行：

python -m hermes --serve

这会以服务模式启动，监听 5858 端口。Agent 控制台会打印 Lark server is running...。

在飞书客户端找到你的机器人，发送“你好”，机器人应该会回复。如果遇到问题，检查以下常见错误：

• 回调地址验证失败：确认 ngrok 隧道正确，且防火墙没有阻止端口。
• 机器人无响应：查看 Agent 日志，确认 App ID / Secret 是否有效。
• 群聊中无法 @机器人：检查权限是否添加 im:message.group_at_msg。

飞书接入成功后，你可以创建群聊，将机器人拉入，之后所有群成员都可以通过 @机器人 来调用 Agent 的能力。例如 @Hermes 帮我搜索项目中的定义，Agent 会调用 ripgrep 执行，并将结果发回群里。这就是真正的团队 AI 助手！

6.4 微信接入可能性

虽然官方主要宣扬飞书集成，但社区也有人在探索微信接入。通过个人微信的 itchat 协议或企业微信机器人，可以实现类似效果。因为政策风险，本文不做展开。可以参考飞书模式，找到对应的 webhook 接口进行适配。

七、核心避坑指南与优化建议

在已经带领数十位朋友成功部署 Hermes Agent 后，我总结出以下高频问题和解决技巧，希望帮你少走弯路。

7.1 WSL2 与模型内存相关

• 问题：Ollama 启动后，WSL2 内存持续飙升甚至 OOM。
• 解决：在 Windows 用户目录下创建 .wslconfig 文件，设置：
  text

  [wsl2]
  memory=8GB
  swap=0
  

  限制 WSL2 最多使用 8GB 内存，避免抢占过多系统资源。
• 还可以通过设置 Ollama 的环境变量 OLLAMA_NUM_PARALLEL=1 限制并行请求数。

7.2 Python 环境与依赖冲突

• 现象：pip install 时报错 error: externally-managed-environment。
• 这通常是因为 Ubuntu 23.04+ 的 Python 提示避免在系统环境安装。解决方法就是使用虚拟环境（我们之前已经创建了 .venv），确保在执行任何 pip 命令前已经 source .venv/bin/activate。
• 如果安装 pytorch 等大包过于缓慢，可以配置 pip 国内镜像：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple torch。

7.3 配置文件路径与权限

• Agent 启动时可能会提示找不到配置文件。第一次运行 Agent 后，配置会自动生成在 ~/.hermes/config.yaml。如果没生成，可以手动复制仓库模板 config.template.yaml 过去。
• 建议将配置文件权限设为 600：chmod 600 ~/.hermes/config.yaml，尤其是包含 API Key 时。

7.4 模型输出质量不佳

• 考虑更换模型或调整 temperature。对于严谨的任务（如代码生成），temperature 可以设为 0.1~0.3。
• 主题压缩如果太激进会丢失细节，可以适当增大 keep_memory_tokens。
• 确保辅助模型可用：如果没有额外资源，建议摘要模型和主模型设为同一个。

7.5 飞书回调地址连通性

• 如果使用 ngrok，免费隧道域名会随机变化，且稳定连接时间有限。可以考虑使用稳定的 frp 服务，或租用一台轻量云服务器部署 Agent。
• 确保飞书后台的“事件订阅”配置中，请求地址后不要额外路径，默认就是 http(s)://your-domain:5858/。

7.6 Skill 安装后无效果

• 确认 Skill 目录结构正确，包含有效的 skill.yaml 文件。
• 重启 Agent 后应该自动加载；如果仍无效，运行 hermes skill reload 或查看日志是否有加载错误。
• Skill 内命令可能依赖某些系统工具，先手动执行一下命令看看是否成功。

7.7 其他零散建议

• 定期更新 Hermes Agent 源码，社区迭代很快。cd ~/hermes-agent && git pull 后重新安装依赖。
• 利用 journalctl 或 tmux 让 Agent 长期后台运行：nohup python -m hermes --serve &，并配合日志重定向。
• 备份你的配置和 Skill 文件夹，重装系统时可快速恢复。

八、进阶玩法：Agent 的多后端模式与自我进化

8.1 多后端切换策略

有些任务更适合本地隐私保护，有些则需要更强的云端模型。Hermes Agent 允许在对话中临时切换模型，例如你可以说：“切换到 OpenAI 模型回答这个问题”。前提是在配置文件中同时定义多个后端，并且给它们别名：

llm_backends:
  local:
    backend: ollama
    model: llama3.1:8b
  cloud:
    backend: openai
    model: gpt-4o

然后通过特殊指令或 Skill 触发切换。这需要一定自定义开发，但社区已有示例，可以搜索 “hermes multi-backend” 了解。

8.2 使用 Skill 打造工作流自动化

结合多个 Skill 可以组合出复杂的工作流。例如：

1. “file-monitor” Skill：监控指定文件夹，当有新文件加入时触发；
2. “file-organizer” Skill：按类型移动文件到对应目录；
3. “report” Skill：每日生成文件处理报告发送到飞书。

这些 Skill 之间通过消息或文件事件串联，让 Agent 从一个被动聊天程序，进化为自动化数字管家。

8.3 与 Windows 本地应用打通

虽然 Agent 运行在 WSL，但它可以通过 wsl.exe 命令调用 Windows 程序。例如在 Skill 中写：wsl.exe cmd.exe /C start notepad 就能打开 Windows 的记事本。更高级的可以调用 PowerShell 脚本，让 Agent 管理 Windows 系统服务。这为跨平台集成打开了大门。

##结语

经过本篇教程，你已经在 Windows 11 上完成了 Hermes Agent 从零到一的搭建，并且学会了配置多种模型、集成强力命令行工具、安装自定义 Skill，以及接入飞书实现团队协作。这只是一个开始，随着你对 Agent 的理解加深，它会越来越像一个贴心且全能的伙伴，帮你从重复劳动中解放出来。

或许有人会问，AIGC 发展如此迅速，今天学 Hermes Agent 会不会过两天就被淘汰？我的观点是：开源自建 Agent 代表了一种“数据主权”和“定制自由”，这是闭源产品难以替代的。况且动手搭建的过程本身就是一种宝贵的学习。希望你能在 Hermes Agent 的生态里玩出花儿来，创造出独一无二的数字助手。

如果本文帮助到了你，欢迎分享给更多朋友。也欢迎你关注后续的 Skill 开发专题，我们会手把手教你编写实用的职场 Skill，让爱马仕 Agent 成为你办公桌上的隐形同事。