Hermes-Agent 安装与基础配置完整指南

一、项目简介

Hermes-Agent 是由 Nous Research 开发的开源自主 AI 代理（MIT 许可证），其核心设计理念是 “一个与你共同成长的 Agent”。

核心特性

特性	说明
三层记忆系统	会话记忆（当前对话）、持久记忆（跨会话事实）、技能记忆（解决方案模式）
自我进化能力	完成复杂任务后自动创建技能，持续学习改进
终端访问	支持本地、Docker、SSH 三种终端后端，安全执行命令
多平台集成	支持 Telegram、Discord、Slack、WhatsApp 等消息平台
内置技能库	预置 40+ 技能（MLOps、GitHub、研究工具等）
MCP 集成	连接 MCP 服务器，安全扩展工具集
多配置文件	支持运行多个隔离的 Hermes 实例

二、环境要求

要求	详情
Python 版本	Python 3.9+
操作系统	Linux / macOS / Windows (WSL2)
内存要求	建议 8GB+
磁盘空间	2GB+（含依赖）
必需工具	curl、git、bash

三、安装方式

3.1 方式一：一键安装脚本（推荐）

最快 2 分钟完成安装，适合大多数用户：

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

安装脚本自动完成以下工作：

步骤	操作	说明
1	检测/安装 uv	uv 是 Astral 开发的超快 Python 包管理器
2	检测/安装 Python	确保使用兼容的 Python 版本
3	检测/安装 Node.js	部分技能依赖 Node.js
4	检测/安装 ripgrep	用于高效文本搜索
5	检测/安装 ffmpeg	音视频处理支持
6	创建虚拟环境	在 ~/.hermes-venv 创建隔离环境
7	克隆仓库	拉取最新代码到本地
8	安装依赖	使用 uv.lock 进行哈希验证安装
9	安装子模块	包括 mini-swe-agent、tinker-atropos 等
10	配置 PATH	将 hermes 命令添加到 PATH

安装后激活：

# 重新加载 shell 配置
source ~/.bashrc   # Bash 用户
source ~/.zshrc    # Zsh 用户

# 运行设置向导（配置 API Key）
hermes setup

# 启动对话
hermes

3.2 方式二：手动安装

适合需要完全控制安装过程的高级用户：

步骤 1：安装 uv 包管理器

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

# 或通过 pip
pip install uv

步骤 2：克隆仓库并创建虚拟环境

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

# 创建虚拟环境
uv venv
source .venv/bin/activate

步骤 3：安装依赖

选项	说明	命令
all	完整安装（推荐）	`uv pip install -e ".[all]"`
cli	仅终端菜单 UI	`uv pip install -e ".[cli]"`
messaging	消息平台支持	`uv pip install -e ".[messaging]"`

步骤 4：安装终端工具后端

# 必需
uv pip install -e "./mini-swe-agent"

# 可选：强化学习训练后端
uv pip install -e "./tinker-atropos"

步骤 5：安装 Node.js 依赖（可选）

npm install

3.3 方式三：Docker 安装

适合容器化部署和生产环境：

# 拉取官方镜像
docker pull nousresearch/hermes-agent:latest

# 创建数据目录
mkdir -p ~/.hermes

# 首次配置（交互式）
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  -e OPENAI_API_KEY="your-key" \
  nousresearch/hermes-agent:latest \
  hermes setup

# 启动 Gateway 服务（后台运行）
docker run -d \
  --name hermes \
  -v ~/.hermes:/opt/data \
  -p 8000:8000 \
  -e OPENAI_API_KEY="your-key" \
  nousresearch/hermes-agent:latest \
  hermes gateway run

3.4 方式四：本地 Ollama 免费运行

完全免费，无需 API Key：

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 启动 Ollama 服务
ollama serve

# 下载模型
ollama pull llama3.1

# 配置 Hermes 使用 Ollama
hermes setup

四、核心目录结构

~/.hermes/
├── config.yaml           # 主配置文件
├── .env                  # API 密钥和敏感信息
├── auth.json             # OAuth 凭证
├── SOUL.md               # 可选：全局人格设定
├── active_profile        # 当前激活的配置文件
├── memories/             # 持久化记忆
│   ├── MEMORY.md         # Agent 的记忆存储
│   └── USER.md           # 用户偏好记录
├── skills/               # Agent 创建的技能
├── cron/                 # 定时任务
├── sessions/             # Gateway 会话
├── state.db              # 状态数据库
└── logs/                 # 日志文件
    ├── errors.log        # 错误日志
    └── gateway.log       # Gateway 日志

五、基础配置

5.1 运行设置向导

hermes setup

设置向导将引导完成：选择 LLM 提供商 → 输入 API Key → 选择终端后端 → 配置消息平台（可选）→ 调整 Agent 设置。

5.2 配置 API Key

支持的 LLM 提供商

提供商	环境变量	说明
OpenAI	OPENAI_API_KEY	GPT-4、GPT-4o 等
Anthropic	ANTHROPIC_API_KEY	Claude 系列
OpenRouter	OPENROUTER_API_KEY	聚合多模型，推荐新手
Kimi	KIMI_API_KEY	Moonshot AI
Ollama	无需 Key	本地运行，完全免费

手动配置 .env 文件示例：

nano ~/.hermes/.env

# OpenAI
OPENAI_API_KEY=sk-your-openai-key

# Anthropic (Claude)
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

# OpenRouter（聚合多模型，推荐）
OPENROUTER_API_KEY=sk-or-your-openrouter-key

5.3 config.yaml 基础配置

# 模型配置
model: "gpt-4o"

# 上下文压缩
compression:
  enabled: true
  trigger_threshold: 0.50

# 终端配置
terminal:
  backend: "local"  # local / docker / ssh

# 记忆配置
memory:
  enabled: true
  persist: true

# 显示配置
display:
  skin: "default"
  streaming: true

# TTS 配置
tts:
  enabled: false

5.4 SOUL.md 人格设定（可选）

通过 ~/.hermes/SOUL.md 定义 Agent 的全局人格，内容示例可在官方文档查看。

5.5 终端沙箱配置

Docker 沙箱（推荐生产环境）

terminal:
  backend: "docker"
  docker:
    image: "python:3.11-slim"
    timeout: 300

SSH 远程终端

terminal:
  backend: "ssh"
  ssh:
    host: "your-server.com"
    user: "hermes"
    port: 22
    key_path: "~/.ssh/hermes_key"

5.6 多配置文件（Profiles）

# 创建新配置文件
hermes profile create work --clone

# 切换配置文件
hermes profile use work

# 列出所有配置文件
hermes profile list

# 删除配置文件
hermes profile delete work

六、验证与测试

6.1 验证安装

# 查看版本
hermes --version

# 查看当前配置
hermes config

# 运行诊断
hermes doctor

诊断输出示例：

✓ Python 版本: 3.11.5
✓ config.yaml 存在
✓ .env 文件存在
✓ API Key 已配置
✓ 终端后端可用
✓ Gateway 服务运行中

6.2 基础使用示例

# 启动交互式对话
hermes

# 恢复最近会话
hermes chat --continue

# 使用指定模型
hermes chat --model gpt-4o

6.3 切换模型

# 交互式切换模型
hermes model

# 直接指定模型启动
hermes chat --model gpt-4o
hermes chat --model claude-3-opus
hermes chat --model ollama/llama3.1

七、常用命令速查

基础命令

命令	功能
`hermes`	启动交互式对话
`hermes chat --continue`	恢复最近会话
`hermes chat --model <模型>`	使用指定模型
`hermes model`	交互式切换模型

配置命令

命令	功能
`hermes setup`	运行完整设置向导
`hermes config`	查看当前配置
`hermes config set <key> <value>`	设置配置项

Gateway 与消息平台

命令	功能
`hermes gateway setup`	配置消息平台网关
`hermes gateway start`	启动网关服务
`hermes channels test`	测试消息通道连接

Profile 配置文件

命令	功能
`hermes profile list`	列出所有配置文件
`hermes profile create <name>`	创建新配置文件
`hermes profile use <name>`	切换配置文件

八、常见问题

问题	原因	解决方案
命令未找到	PATH 未配置	执行 `source ~/.bashrc` 或重新打开终端
API Key 无效	Key 过期或错误	重新运行 `hermes setup` 配置
Gateway 启动失败	端口被占用	检查端口：`lsof -i :8000`
Ollama 连接失败	服务未启动	运行 `ollama serve` 启动服务
模型响应慢	网络或模型问题	尝试切换模型或使用本地 Ollama

总结

步骤	关键操作
1. 安装	一键脚本或手动安装
2. 配置	运行 `hermes setup` 配置 API Key
3. 验证	运行 `hermes doctor` 检查环境
4. 使用	运行 `hermes` 启动对话

建议：初次使用推荐一键安装脚本 + OpenRouter 提供商（聚合多模型，配置简单）。本地免费使用可选择 Ollama。

官方资源：

官方文档：https://hermes-agent.nousresearch.com
GitHub 仓库：https://github.com/NousResearch/hermes-agent

一、项目简介#

核心特性#

二、环境要求#

三、安装方式#

3.1 方式一：一键安装脚本（推荐）#

3.2 方式二：手动安装#

3.3 方式三：Docker 安装#

3.4 方式四：本地 Ollama 免费运行#

四、核心目录结构#

五、基础配置#

5.1 运行设置向导#

5.2 配置 API Key#

5.3 config.yaml 基础配置#

5.4 SOUL.md 人格设定（可选）#

5.5 终端沙箱配置#

5.6 多配置文件（Profiles）#

六、验证与测试#

6.1 验证安装#

6.2 基础使用示例#

6.3 切换模型#

七、常用命令速查#

八、常见问题#

总结#