Hermes 部署指南

Hermes 是什么

Hermes Agent 是由 Nous Research 开发的一款开源 AI 终端助手。你可以把它理解为一个运行在命令行里的"超级 AI 助手"，它能够：

在终端中与你对话，回答各种问题
执行终端命令（帮你操作电脑）
读写文件、搜索文件内容
浏览网页、搜索互联网信息
分析图片内容
编写和调试代码
设置定时任务（自动化）
连接 Telegram、Discord、微信等消息平台
拥有持久记忆，跨会话记住你的偏好
支持语音输入和语音回复

简单来说：它是一个能帮你干活的 AI，而且比普通聊天机器人强大得多。

Windows 部署指南

前置要求

安装 WSL2（Windows 子系统 Linux），开启系统更新

首次安装 WSL2

Hermes Agent 不支持原生 Windows，必须通过 WSL2 运行。WSL2 就是在 Windows 里装一个 Linux 系统，不影响你正常使用 Windows。

以管理员身份打开 PowerShell（右键开始菜单 → "终端(管理员)"）

wsl --install

如果WSL安装卡到了0%，试试换一种方式

wsl --install --web-download -d Ubuntu

2.等待安装完成，系统会提示你重启电脑

3.重启后，WSL 会自动打开，要求你设置 Linux 用户名和密码

4.设置完成后，你就有了一个 Ubuntu 终端。按下win键输入WSL会出现一个小企鹅的标志

5.验证安装成功：powershell管理员运行

wsl --version

如果显示版本号，说明安装成功。

安装 Git

在WSL2终端（Ubuntu）中运行

sudo apt update

sudo apt install git -y

git --version

看到版本号输出即可。

提示：后续所有命令都在 WSL2 终端中执行，不是在 Windows 的 CMD 或 PowerShell 中。

手动安装

如果一直安装失败，可以尝试手动安装：

第1步：安装 uv（Python 包管理器）

curl -LsSf https://astral.sh/uv/install.sh | sh

第2步：克隆仓库

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

第3步：创建虚拟环境：

uv venv venv --python 3.11

第4步：安装依赖：

export VIRTUAL_ENV="$(pwd)/venv"

uv pip install -e ".[all]"

第5步：安装 Node.js 依赖（可选，用于浏览器工具）

npm install

第6步：创建配置目录

mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}

cp cli-config.yaml.example ~/.hermes/config.yaml

touch ~/.hermes/.env

第7步：添加到系统路径

mkdir -p ~/.local/bin

ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

source ~/.bashrc

最后：验证安装

hermes version
hermes doctor

安装成功，参考如下：

Hermes 配置流程

安装完成之后，让你输入管理员密码。注意：密码输入以及API Key输入进去之后是看不到的

在你所依赖的环境中运行

hermes setup

选择快速配置

选择 More Provider

选择合适的协议后，填入 URL。比如：

填入URL:https://gpt-agent.cc/v1，或者https://gpt-agent.cc/

粘贴 API Key 并完成验证

粘贴 API Key 后终端通常不会显示内容，直接回车即可。如果一直验证失败，请检查 Key 是否已粘贴、尝试切换 URL，或重启当前运行环境后再试。

成功之后你将看到这些模型的名称，最后输入你对应模型的上下文大小之后配置你的聊天渠道，这里就不做演示了，我们这边选择跳过

聊天测试

在此输入Y，即可开始与Hermes聊天

如果能够正常回复你，那么就配置成功了

后续配置其他的东西，直接与你的Hermes说要求即可

聊天渠道无响应时的处理

hermes gateway

常见问题

Q1：`hermes: command not found`（找不到命令）

原因：安装后没有重新加载终端配置。

解决：

source ~/.bashrc

或者

source ~/.zshrc

如果还不行，检查 PATH：

echo $PATH | grep ".local/bin"

如果没有输出，手动添加

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Q2：上下文长度只有 16k / 2048，AI 回复经常断

原因：上下文窗口配置过小。

解决：在配置文件中手动设置上下文长度：

# ~/.hermes/config.yaml
model:
  default: "claude-sonnet-4-6"
  provider: "custom"
  base_url: ""
  context_length: 131072    # 设置为 128k

Q3：如何设置备用模型（自动故障转移）？

# ~/.hermes/config.yaml
fallback_model:
  provider: custom
  model: gpt-4o
  base_url: https://备用中转地址/v1
  api_key_env: FALLBACK_API_KEY    # 在 .env 中设置此变量

配置文件目录结构

~/.hermes/
├── config.yaml      # 主配置文件（模型、终端、压缩等设置）
├── .env             # API Key 和密钥
├── auth.json        # OAuth 认证凭据
├── SOUL.md          # AI 人格定义文件（可自定义）
├── memories/        # 持久记忆
├── skills/          # 技能文件
├── cron/            # 定时任务
├── sessions/        # 会话记录
└── logs/            # 日志文件

Q4：WSL2 中无法访问 Windows 上运行的本地模型

原因： WSL2 和 Windows 使用不同的网络。

解决方案一（推荐，Windows 11）：

在 Windows 中创建文件 C:\Users\你的用户名\.WSLconfig：

[wsl2]
networkingMode=mirrored

然后在 PowerShell 中重启 WSL：

wsl --shutdown

解决方案二（Windows 10）：*

在 WSL2 中获取 Windows 主机 IP：

ip route show | grep -i default | awk '{ print $3 }'

用这个 IP 替代 localhost。

Q5：更新后配置丢失

解决：

hermes config check     # 检查缺失的配置项
hermes config migrate   # 迁移配置到新版本格式

Hermes 部署指南

Hermes 是什么

Windows 部署指南

首次安装 WSL2

安装 Git

推荐一键安装（Linux / macOS / WSL2）

手动安装

第1步：安装 uv（Python 包管理器）

第2步：克隆仓库

第3步：创建虚拟环境：

第4步：安装依赖：

第5步：安装 Node.js 依赖（可选，用于浏览器工具）

第6步：创建配置目录

第7步：添加到系统路径

最后：验证安装

Hermes 配置流程

在你所依赖的环境中运行

选择快速配置

选择 More Provider

选择合适的协议后，填入 URL。比如：

粘贴 API Key 并完成验证

聊天测试

聊天渠道无响应时的处理

常见问题

Q1：`hermes: command not found`（找不到命令）

Q2：上下文长度只有 16k / 2048，AI 回复经常断

Q3：如何设置备用模型（自动故障转移）？

配置文件目录结构

Q4：WSL2 中无法访问 Windows 上运行的本地模型

Q5：更新后配置丢失