💡 导语：
谁说强大的 AI Agent 只能在 Linux 上运行？虽然 Hermes Agent 官方原生支持 Linux 和 macOS，但通过 Windows Subsystem for Linux (WSL2)，我们完全可以在 Windows 11/10 上获得丝滑、原生般的体验！

本指南将手把手带你完成从 零配置 WSL2 到 成功部署 Hermes Agent，再到 接入飞书机器人 的全过程。我们将直面并解决所有可能遇到的“坑”，让你在 Windows 上也能拥有一个会自我进化的 AI 伙伴！

⚠️ 重要前提：为什么必须用 WSL2？

根据官方文档和社区实践，Hermes Agent 是一个基于 Python 的复杂系统，重度依赖 Linux 环境下的工具链（如 uv、特定的系统库等）。直接在 Windows 原生命令行（CMD/PowerShell）或 Git Bash 中安装几乎肯定会失败。

WSL2 在 Windows 内核上运行一个完整的 Linux 内核，为你提供了一个与 Ubuntu 等发行版几乎无异的开发环境，是目前在 Windows 上运行 Hermes Agent 唯一可靠且官方推荐的方式。

文末有超值福利！如果你觉得本文对你有启发，请务必点赞、收藏、评论“666”并转发给你的朋友。你的每一个互动，都是对我持续创作深度内容的最大支持！关注我，获取更多关于Java并发、NIO源码、云原生架构与AI系统底层原理的独家干货。

🛠 第一部分：在 Windows 上安装并配置 WSL2

步骤 1：启用 WSL 功能

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

# 启用必要的 Windows 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

执行完毕后，重启你的电脑。

步骤 2：设置 WSL2 为默认版本

重启后，再次打开 PowerShell（普通用户即可），运行：

# 将 WSL2 设置为默认版本
wsl --set-default-version 2

步骤 3：安装 Linux 发行版（推荐 Ubuntu）

  1. 打开 Microsoft Store (微软应用商店)。
  2. 搜索 “Ubuntu”。
  3. 选择 “Ubuntu 22.04 LTS” (或最新 LTS 版本)，点击 “获取” 进行安装。

步骤 4：初始化 Ubuntu

  1. 安装完成后，在开始菜单中启动 “Ubuntu”。
  2. 首次启动会要求你创建一个 Linux 用户名和密码（这与你的 Windows 账户无关，请牢记）。
  3. 初始化完成后，你就拥有了一个功能完备的 Linux 终端！
💡 避坑提示：如果你在中国大陆，可能会遇到网络问题导致安装缓慢或失败。可以尝试在 PowerShell 中使用 wsl --install -d Ubuntu-22.04 --web-download 命令，并配合系统代理（如果有的话）。

🚀 第二部分：在 WSL2 中安装 Hermes Agent

现在，我们的操作环境已经切换到了 WSL2 的 Ubuntu 终端。

步骤 1：更新系统包（可选但推荐）

sudo apt update && sudo apt upgrade -y

步骤 2：执行官方一键安装脚本

这是最简单、最不容易出错的方式。在 Ubuntu 终端中粘贴并运行：

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

这个脚本会自动完成以下工作：

  • 安装 uv (超快的 Python 包安装器和虚拟环境管理器)
  • 安装 Python 3.11+
  • 克隆 Hermes Agent 仓库
  • 创建并激活虚拟环境
  • 安装所有依赖
  • 将 hermes 命令添加到你的 PATH

步骤 3：重载 Shell 并验证安装

安装完成后，为了让 hermes 命令生效，需要重载你的 Shell 配置：

# 对于 Bash 用户
source ~/.bashrc

# 对于 Zsh 用户（如果你已切换）
source ~/.zshrc

然后，验证是否安装成功：

hermes --version

你应该能看到类似 hermes x.x.x 的输出。

步骤 4：配置模型提供商

运行设置向导，连接你的大模型 API：

hermes setup

在交互式界面中：

  1. 选择你的模型提供商（如 OpenAI, Anthropic, OpenRouter, 或国内的大模型）。
  2. 输入对应的 API Key。
  3. 选择一个默认模型（如 gpt-4o, claude-3-5-sonnet-20241022）。

配置完成后，你可以通过 hermes 命令直接与 Agent 对话，测试其基本功能。

💡 避坑提示：
* 网络问题：如果 curl 命令卡住或失败，很可能是网络问题。请确保你的 WSL2 能正常访问 GitHub。必要时可配置 Git 代理。
* 权限问题：不要在 WSL2 中使用 sudo 来运行 hermes 命令，这可能导致权限混乱。始终以普通用户身份运行。

💬 第三部分：接入飞书机器人

Hermes Agent 通过其内置的 gateway 模块支持多平台消息接入。下面是如何将其连接到飞书。

步骤 1：在飞书开放平台创建应用

  1. 访问 飞书开放平台。
  2. 点击 “创建企业自建应用”。
  3. 填写应用名称（如 My Hermes），点击 “创建”。

步骤 2：配置应用权限

  1. 在应用详情页，进入 “应用功能” -> “机器人”，确保已启用。
  2. 进入 “权限管理”，申请以下权限：
    • im:message:send_as_bot
    • im:message:read
    • contact:user:readonly
  3. 保存并 发布 权限。

步骤 3：获取凭证

在 “凭证与基础信息” 页面，记下：

  • App ID
  • App Secret

步骤 4：在 WSL2 中配置 Hermes Gateway

回到你的 WSL2 Ubuntu 终端，运行 gateway 配置命令：

hermes gateway setup

在交互式向导中：

  1. 选择 feishu。
  2. 输入你刚刚获取的 App ID 和 App Secret。
  3. User IDs: 如果你想让所有用户都能使用，可以留空。如果只想给自己用，可以输入你的飞书用户ID（可在飞书个人资料中找到）。
  4. Domain: 保持默认 feishu。
  5. Connection mode: 选择 websocket (推荐)。

步骤 5：配置飞书事件订阅（关键！）

回到飞书开放平台：

  1. 进入 “事件与回调”。
  2. 订阅方式 选择 “长连接”。
  3. 在 “需要订阅的事件” 中，勾选 im.message.receive_v1。
  4. 保存。

步骤 6：在飞书中测试！

现在，打开你的飞书，搜索你创建的应用（或在群聊中添加它），向它发送一条消息，比如 “你好！”。如果一切顺利，你的 Hermes Agent 就会回复你了！

💡 避坑提示：
* 公网 IP 问题：飞书的长连接模式不需要你的服务器有公网 IP，Hermes Gateway 会主动建立到飞书的 WebSocket 连接，因此在家用网络下也能正常工作。
* 防火墙：确保你的 Windows 防火墙没有阻止 WSL2 的网络连接。

💎 总结

通过 WSL2 这座桥梁，我们在 Windows 上成功搭建了一个功能完整、能够自我进化的 Hermes Agent，并将其无缝接入了飞书工作流。

核心流程回顾：

  1. 启用并安装 WSL2 (Ubuntu)。
  2. 在 WSL2 终端中运行官方一键安装脚本。
  3. 通过 hermes setup 配置模型 API。
  4. 在飞书开放平台创建应用并获取凭证。
  5. 通过 hermes gateway setup 完成飞书接入。

现在，无论你是在 Windows 上办公，还是在飞书里沟通，你的 AI 分身都已就位，随时准备与你一同成长！

再次呼吁：如果你被本文的深度和洞见所打动，请不要吝啬你的点赞、收藏、评论和转发！你的支持是我继续创作万字源码解析的最大动力。关注我，让我们一起在技术的深海中，探索更多宝藏！