Hermes Agent 是近期受到广泛关注的开源项目，由 Nous Research 发布，被社区称为“开源版 Claude Code”，能力上与 OpenClaw 相当。作为技术爱好者，亲自动手测试是必要的。需要提前说明的是，官方文档明确指出原生 Windows 环境不被支持，必须借助 WSL2。本文基于实际操作中的踩坑经历整理而成，希望能够帮助后来者节省时间。Mac 用户可以忽略此文，因为在该平台上的安装几

一、Hermes Agent 概述

Hermes Agent 是一个来自 Nous Research 的开源 AI Agent 框架，能够连接 Ollama 本地模型、OpenRouter、Anthropic 等多种后端。其核心能力包括：

• 文件系统操作（读取、写入、搜索、打补丁）

• 终端命令执行

• 浏览器自动化（点击、填写表单、截图）

• 代码生成与调试

• 任务委托与流程自动化

可以将其理解为一个运行在终端里的 AI 助手，接收自然语言指令并完成具体操作。

乎是一键完成的。

二、环境要求

项目	最低要求	推荐配置
操作系统	Windows 10 64-bit (2004+)	Windows 11
WSL2	必须安装	——
内存	8 GB	16 GB+
显卡显存	8 GB（用于 7B 模型）	16 GB+（用于 30B+ 模型）
磁盘空间	20 GB	50 GB+

再次强调：Hermes Agent 官方仅支持 WSL2 环境，请放弃在原生 Windows 上直接运行的尝试。

三、整体流程概览

text
Windows 端                               WSL2 内
   │                                        │
   ├─ 1. 安装 WSL2 ──────────────────────→ 已有 Ubuntu
   │                                        │
   ├─ 2. 安装 Ollama                        ├─ 3. 安装 Hermes Agent
   │    (监听 0.0.0.0)                      │
   │                                        │
   ├─ 4. 开放防火墙端口 11434 ←──────────────┤
   │                                        │
   └─ 5. 配置 Hermes 连接 Windows Ollama ──┘
                    │
                    ▼
              hermes chat 启动

图中的核心难点是 WSL2 与 Windows 之间的网络互通，根据社区反馈，大约 90% 的配置问题都出在这一步。

四、Step 1：安装 WSL2 并迁移到非 C 盘

4.1 安装 WSL2

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

powershell

wsl --install

该命令会默认安装 Ubuntu，重启后按提示设置用户名和密码。

4.2 迁移到非系统盘（强烈推荐）

WSL2 默认将虚拟磁盘存放在 C 盘的 %AppData% 下，随着模型体积增大，容易导致 C 盘空间不足。迁移方法如下（以 G 盘为例）：

powershell
# 查看当前状态
wsl --list --verbose

# 创建目标目录
New-Item -ItemType Directory -Path "G:\WSL\Ubuntu" -Force

# 导出备份
wsl --export Ubuntu G:\WSL\ubuntu-backup.tar

# 注销原有实例
wsl --unregister Ubuntu

# 重新导入到 G 盘
wsl --import Ubuntu G:\WSL\Ubuntu G:\WSL\ubuntu-backup.tar --version 2

⚠️ 常见问题：若导出时提示“系统找不到指定的文件”，说明虚拟磁盘已损坏。此时可直接重建：

powershell
wsl --unregister Ubuntu
# 下载 Ubuntu rootfs
Invoke-WebRequest -Uri "https://cloud-images.ubuntu.com/wsl/jammy/current/ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz" -OutFile "G:\WSL\ubuntu.tar.gz"
wsl --import Ubuntu G:\WSL\Ubuntu G:\WSL\ubuntu.tar.gz --version 2

4.3 修复默认用户

导入后默认使用 root 身份登录，需要创建普通用户：

bash
# 进入 WSL
wsl -d Ubuntu

# 创建用户（将 yourname 替换为实际用户名）
useradd -m -s /bin/bash yourname
passwd yourname
usermod -aG sudo yourname

# 设置默认用户
echo -e '[user]\ndefault=yourname' > /etc/wsl.conf

重启 WSL 使配置生效：

powershell
wsl --terminate Ubuntu
wsl -d Ubuntu

五、Step 2：在 WSL2 中安装 Hermes Agent

5.1 更新系统依赖

bash
sudo apt update && sudo apt install -y ripgrep ffmpeg

5.2 配置 Git 参数（预防克隆失败）

bash
git config --global http.postBuffer 524288000

若 GitHub 克隆出现 GnuTLS recv error，可能是代理设置干扰，建议清空代理：

bash
git config --global http.proxy ""
git config --global https.proxy ""

5.3 执行安装脚本

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

若脚本因 GitHub 网络问题失败，可以手动克隆：

bash
rm -rf ~/.hermes/hermes-agent
git clone --depth=1 https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent

5.4 安装 Python 依赖

如果系统提示 uv: command not found，需要先安装 uv：

bash
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

然后安装项目依赖：

bash
cd ~/.hermes/hermes-agent
export PATH="$HOME/.local/bin:$PATH"
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"
UV_HTTP_TIMEOUT=300 uv pip install -e ".[messaging,cron,cli,mcp,pty]"

设置 UV_HTTP_TIMEOUT=300 是因为部分大包（如 elevenlabs）下载速度慢，默认 30 秒容易超时。

5.5 创建全局命令软链接

bash
ln -sf ~/.hermes/hermes-agent/hermes ~/.local/bin/hermes
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
hermes version   # 应显示 v0.8.0 或更高版本

六、Step 3：安装 Ollama（Windows 端）

1. 访问 ollama.com 下载 Windows 安装包并完成安装。

2. 安装完成后，系统托盘中会出现 Ollama 图标。

3. 下载所需的模型（请使用实际存在的模型标签，避免使用不存在的名称）：

powershell
ollama pull qwen2.5:7b          # 需要约 6 GB 显存，适合入门
ollama pull qwen2.5:32b         # 需要约 20 GB 显存
ollama pull deepseek-r1:32b     # 需要约 20 GB 显存
ollama pull qwen2.5-coder:7b    # 面向代码任务

如果需要扩展现有模型的上下文长度（Ollama 默认值较小），可以按以下方式创建自定义模型：

powershell
# 使用反引号 ` 作为换行符
"FROM qwen2.5:32b`nPARAMETER num_ctx 32768" | Out-File -FilePath "Modelfile" -Encoding utf8
# 或者使用 [Environment]::NewLine
"FROM qwen2.5:32b" + [Environment]::NewLine + "PARAMETER num_ctx 32768" | Out-File -FilePath "Modelfile" -Encoding utf8
ollama create qwen2.5-32b-32k -f "Modelfile"

七、Step 4：打通 WSL2 到 Windows Ollama 的网络（关键难点）

核心问题：WSL2 运行在虚拟网络中，其 localhost 并不指向 Windows 宿主机。

7.1 让 Ollama 监听所有网络接口

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

powershell
[System.Environment]::SetEnvironmentVariable("OLLAMA_HOST", "0.0.0.0", "User")

然后彻底重启 Ollama（在系统托盘中右键退出，再重新启动）。验证监听状态：

powershell
netstat -an | findstr 11434
# 预期输出：TCP    0.0.0.0:11434    0.0.0.0:0    LISTENING

7.2 添加防火墙放行规则

管理员 PowerShell：

powershell
New-NetFirewallRule -DisplayName "Ollama WSL" -Direction Inbound -Protocol TCP -LocalPort 11434 -Action Allow

7.3 检查并删除可能存在的阻止规则（非常重要）

powershell
Get-NetFirewallRule -DisplayName "*Ollama*" | Format-Table DisplayName, Enabled, Direction, Action

实践中发现，Windows 防火墙有时会为 ollama.exe 自动创建 阻止 规则，而阻止规则的优先级高于允许规则，导致即使添加了允许规则也无法连通。若发现阻止规则，请删除：

powershell
Get-NetFirewallRule -DisplayName "ollama.exe" | Where-Object {$_.Action -eq "Block"} | Remove-NetFirewallRule

7.4 在 WSL 中测试连接

bash
# 获取 Windows 宿主机的 IP 地址
HOST_IP=$(ip route | grep default | awk '{print $3}')
echo $HOST_IP

# 测试连接
curl http://$HOST_IP:11434/api/tags

• 若能返回模型列表，说明网络已通。

• 如果出现 Connection refused，通常是 Ollama 没有监听 0.0.0.0，请返回 7.1 检查环境变量并重启。

• 如果出现 Connection timed out，一般是防火墙拦截，请检查并删除阻止规则。

八、Step 5：配置 Hermes 连接本地模型

方法一：交互式配置

bash
hermes model

选择 More providers... → Custom endpoint，然后填入以下信息：

• API base URL：http://你的宿主机IP:11434/v1（示例：http://172.27.112.1:11434/v1）

• API key：留空

• Model name：qwen2.5-32b-32k:latest（使用你创建的模型名称）

• Context length：32768

方法二：直接编辑配置文件（更可靠）

bash
HOST_IP=$(ip route | grep default | awk '{print $3}')
# 确保 URL 中包含 /v1 路径
sed -i "s|http://[^/]*:11434|http://$HOST_IP:11434/v1|g" ~/.hermes/config.yaml

修改后可以检查配置是否生效：

bash
grep -E "base_url|model" ~/.hermes/config.yaml

九、Step 6：修复上下文窗口限制（必须执行）

Hermes Agent 要求最低 64K 的上下文窗口，而大多数本地模型的默认上下文为 32K，若不修改配置将会报错。解决方法是通过修改配置文件绕过检查：

bash
sed -i 's/context_length: 32768/context_length: 65536/' ~/.hermes/config.yaml
grep context_length ~/.hermes/config.yaml   # 应显示 65536

注意：这只是让 Hermes Agent 不再拒绝启动，实际模型仍然只有 32K 上下文能力。当对话长度超过 32K 时，模型可能会遗忘早期内容。如果显存充足，可以在创建 Modelfile 时将 num_ctx 设为 65536，生成真正的 64K 版本模型。

十、Step 7：启动并使用

在正式启动之前，建议先运行健康检查：

bash
hermes doctor

确认没有错误后，启动交互界面：

bash
hermes chat

启动成功后，终端会显示 ASCII 艺术标题以及可用工具列表。在提示符后直接输入自然语言指令即可。

常用命令速查

命令	说明
hermes chat	进入交互式对话模式
hermes "写一个Python爬虫"	执行单次任务
hermes doctor	运行全面健康检查
hermes model	切换模型（交互式）
hermes model qwen2.5:7b	快速切换到指定模型

状态栏含义示例

text
qwen2.5-32b-32k:latest | 16.7K/65.5K | [###.......] 26% | 5m

从左到右依次表示：当前模型名称 / 已使用的 token 数 / 总上下文 token 数 / 上下文占用比例 / 会话持续时长。

十一、常见问题与解决方法（基于实际踩坑汇总）

Q1：安装脚本克隆 GitHub 失败
错误信息包含 GnuTLS recv error 或 HTTP/2 stream not closed cleanly。
解决方法：

bash
git config --global http.proxy ""
git config --global https.proxy ""
git config --global http.postBuffer 524288000
rm -rf ~/.hermes/hermes-agent
git clone --depth=1 https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent

Q2：WSL 中 curl 访问 Ollama 超时
错误信息为 Connection timed out。原因通常是 Windows 防火墙中存在 ollama.exe 的阻止规则，请按 7.3 节的步骤删除。

Q3：WSL 中 curl 访问 Ollama 拒绝连接
错误信息为 Connection refused。原因是 Ollama 未监听 0.0.0.0，请检查 7.1 节的环境变量设置并重启 Ollama。

Q4：hermes 命令找不到
执行以下命令创建软链接并更新 PATH：

bash
ln -sf ~/.hermes/hermes-agent/hermes ~/.local/bin/hermes
export PATH="$HOME/.local/bin:$PATH"

Q5：Python 依赖安装超时
增加下载超时时间：

bash
UV_HTTP_TIMEOUT=300 uv pip install -e ".[messaging,cron,cli,mcp,pty]"

Q6：未找到 uv 命令
请参照 5.4 节先安装 uv。

Q7：上下文窗口过小导致拒绝启动
按第九步修改配置文件即可。

Q8：WSL 导出备份时找不到 ext4.vhdx
说明虚拟磁盘损坏，可直接按 4.2 节的重建方法处理。

Q9：使用 ollama pull qwen3.5:35b 失败
因为该模型标签在官方库中不存在，请改用 qwen2.5:32b 或其他实际存在的模型名称。

十二、模型选型参考（仅列出 Ollama 官方库中实际存在的模型）

模型	显存需求	中文能力	代码能力	推理能力	拉取命令
qwen2.5:7b	~6 GB	★★★	★★	★★	ollama pull qwen2.5:7b
qwen2.5:32b	~20 GB	★★★★	★★★	★★★★	ollama pull qwen2.5:32b
deepseek-r1:32b	~20 GB	★★★	★★★	★★★★★	ollama pull deepseek-r1:32b
qwen2.5-coder:7b	~6 GB	★★★	★★★★	★★★	ollama pull qwen2.5-coder:7b
llama3.3:70b	~48 GB	★★	★★★★	★★★★	ollama pull llama3.3:70b（需大显存）

需要说明的是，即使是 32B 的本地模型，在 Agent 任务上的综合表现仍与 Claude Sonnet/Opus 存在差距。Hermes Agent 的效果高度依赖于底层大模型的能力。若希望体验完整功能，建议同时配置 OpenRouter 的 API Key。

总结

完成上述全部步骤后，你将获得：

• 一个完全运行在本地的 AI Agent，数据无需离开本机

• 完全免费，无需支付任何 API 费用

• 支持离线使用，不依赖外部网络服务

• 内置 74 项技能和 28 种工具（覆盖文件、代码、浏览器、任务委派等）

简而言之，Hermes Agent 相当于一个在终端中值守的 AI 执行者——你下达指令，它完成操作。至于执行效果如何，取决于你为其配备的基础模型能力。

如果你不想在本地环境花费过多时间，也可以直接使用星海智算提供的预配置镜像，跳过所有配置环节，快速开始体验。