Hermes Agent

核心能力

学完本教程后，你将能够：

• 在 macOS、Windows、Linux 上部署并运行 Hermes Agent
• 使用自然语言指令让代理自动执行跨平台任务（如文件操作、系统命令、API 调用）
• 通过配置文件自定义代理的行为与权限边界
• 排查常见的部署与运行故障

前置条件

安装步骤

1. 克隆仓库

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

2. 创建虚拟环境

python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# 或
venv\Scripts\activate     # Windows

3. 安装依赖

pip install --upgrade pip
pip install -r requirements.txt

注意：若遇到 torch 安装失败，请先根据 PyTorch 官网 选择与你的 CUDA 版本匹配的安装命令。

4. 配置 API 密钥

创建 .env 文件并填入以下内容：

NOUS_API_KEY=你的API密钥
# 可选：若使用本地模型，可跳过此步

密钥获取方式：登录 NousResearch 控制台 → 创建新密钥。

5. 验证安装

python -m hermes_agent --version

预期输出：Hermes Agent v1.0.0 或类似版本号。

首次运行

启动代理

python -m hermes_agent --mode interactive

预期结果：终端显示 Hermes Agent ready. Type your command:，表示代理已就绪。

测试基础指令

在交互模式下输入以下指令：

请列出当前目录下所有文件，并按大小排序

预期行为：代理会执行 ls -lhS（Linux/macOS）或 dir /o-s（Windows），并返回结果。

配置说明

配置文件位于 config/default.yaml，关键参数如下：

示例：限制代理只能执行 ls 和 cat 命令：

allowed_commands:
- ls
- cat

常见问题排查

问题 1：代理无法识别指令

• 原因：模型未正确加载或 API 密钥无效
• 解决：检查 .env 文件中的密钥是否正确，并确认网络能访问 API 端点

问题 2：命令执行超时

• 原因：timeout 设置过短，或命令本身耗时较长
• 解决：在 config/default.yaml 中增大 timeout 值（例如 60）

问题 3：跨平台命令不兼容

• 适用边界：Hermes Agent 会自动检测操作系统，但某些命令（如 grep）在 Windows 上可能不存在
• 解决：在 Windows 上使用 findstr 替代 grep，或通过 WSL 运行

进阶用法

批量任务模式

python -m hermes_agent --mode batch --file tasks.txt

tasks.txt 中每行一条指令，代理会依次执行。

自定义模型

若使用本地模型（如 Ollama），修改 config/default.yaml：

model: ollama/hermes-3
api_base: http://localhost:11434

注意：本地模型需确保已下载并运行，且 API 端口未被占用。