Hermes Agent 完全指南：安装、配置与功能详解

Hermes Agent 是由 Nous Research 开发的开源自我进化 AI Agent，2026年2月发布，MIT 协议，GitHub 星标超 4.3 万。它不是普通的聊天机器人——它拥有内置学习循环，能从经验中创建技能、在使用中自我改进、主动持久化知识，并在跨会话中建立对你的深层理解。

---

目录

1. 核心特性
2. 安装
3. 常用命令速查
4. 目录结构
5. 配置系统
6. 功能模块详解
7. 终端后端
8. 技能系统
9. 记忆系统
10. 消息网关
11. 定时任务
12. 从 OpenClaw 迁移

---

1. 核心特性

特性	说明
自我进化	内置学习循环——从经验创建技能，使用中改进，主动保存知识
持久记忆	跨会话记忆，FTS5 会话搜索，LLM 摘要召回
全平台接入	Telegram、Discord、Slack、WhatsApp、Signal、CLI 统一网关
任意模型	支持 OpenRouter（200+模型）、Nous Portal、OpenAI、Anthropic、z.ai/GLM、Kimi 等，一行命令切换
多终端后端	本地、Docker、SSH、Modal、Daytona、Singularity 六种执行环境
子代理并行	可派生隔离子代理并行工作，Python 脚本通过 RPC 调用工具
定时自动化	内置 Cron 调度器，支持自然语言描述任务
Android 支持	通过 Termux 在 Android 上运行

---

2. 安装

系统要求

• 必须：Git
• 自动安装：Python 3.11（via uv）、Node.js v22、ripgrep、ffmpeg（安装脚本自动处理）

一键安装（推荐）

Linux / macOS / WSL2：

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

Android / Termux：

# 同一条命令，安装脚本自动检测 Termux 环境
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Windows： 不支持原生 Windows，需先安装 WSL2，然后在 WSL2 中执行上述命令。

安装后启动

source ~/.bashrc   # 或 source ~/.zshrc
hermes             # 开始对话！

手动安装

如果需要完全控制安装过程：

# 1. 克隆仓库（含子模块）
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 2. 安装 uv 并创建虚拟环境
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv venv --python 3.11

# 3. 安装依赖（全部功能）
export VIRTUAL_ENV="$(pwd)/venv"
uv pip install -e ".[all]"

# 仅核心（无 Telegram/Discord/Cron）：
# uv pip install -e "."

# 4. 创建配置目录
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

# 5. 添加 API Key
# 编辑 ~/.hermes/.env，至少添加一个 LLM 提供商密钥：
# OPENROUTER_API_KEY=sk-or-v1-your-key-here

# 6. 链接命令
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# 7. 配置模型
hermes model

可选依赖（按需安装）

扩展包	功能	安装命令
all	全部功能	uv pip install -e ".[all]"
messaging	Telegram & Discord 网关	uv pip install -e ".[messaging]"
cron	定时任务	uv pip install -e ".[cron]"
cli	终端菜单 UI	uv pip install -e ".[cli]"
modal	Modal 云执行	uv pip install -e ".[modal]"
tts-premium	ElevenLabs 语音	uv pip install -e ".[tts-premium]"
voice	麦克风输入+音频播放	uv pip install -e ".[voice]"
pty	PTY 终端支持	uv pip install -e ".[pty]"
termux	Android 测试套件	pip install -e ".[termux]" -c constraints-termux.txt
honcho	AI 原生记忆	uv pip install -e ".[honcho]"
mcp	Model Context Protocol	uv pip install -e ".[mcp]"
homeassistant	Home Assistant 集成	uv pip install -e ".[homeassistant]"
acp	ACP 编辑器集成	uv pip install -e ".[acp]"
slack	Slack 消息	uv pip install -e ".[slack]"
dev	测试工具	uv pip install -e ".[dev]"

可组合安装：uv pip install -e ".[messaging,cron,voice]"

---

3. 常用命令速查

启动与管理

hermes                          # 启动交互式 CLI 对话
hermes model                    # 选择 LLM 提供商和模型
hermes tools                    # 配置启用的工具集
hermes setup                    # 运行完整设置向导
hermes config                   # 查看当前配置
hermes config edit              # 编辑 config.yaml
hermes config set KEY VAL       # 设置配置值
hermes config check             # 检查缺失配置
hermes update                   # 更新到最新版本
hermes doctor                   # 诊断问题

网关（消息平台）

hermes gateway setup            # 配置消息平台
hermes gateway start            # 启动消息网关

对话中命令（CLI 和消息平台通用）

命令	说明
/new 或 /reset	开始新对话
/model provider:model	切换模型
/personality name	设置人格
/retry	重试上一轮
/undo	撤销上一轮
/compress	压缩上下文
/usage	查看使用情况
/insights [--days N]	使用洞察
/skills	浏览技能
/skill-name	调用技能
/stop	中断当前工作（消息平台）

---

4. 目录结构

Hermes 的所有数据存储在 ~/.hermes/ 目录：

~/.hermes/
├── config.yaml          # 主配置文件（模型、终端、TTS、压缩等设置）
├── .env                 # API 密钥和秘密信息
├── auth.json            # OAuth 提供商凭证（如 Nous Portal）
├── SOUL.md              # Agent 身份定义（系统提示第一段）
├── memories/            # 持久化记忆（MEMORY.md、USER.md）
├── skills/              # Agent 创建/安装的技能
│   └── openclaw-imports/  # 从 OpenClaw 迁移的技能
├── cron/                # 定时任务定义
├── sessions/            # 网关会话数据
├── logs/                # 日志（自动脱敏秘密信息）
│   ├── errors.log
│   └── gateway.log
├── pairing/             # 设备配对数据
├── hooks/               # 钩子脚本
├── image_cache/         # 图片缓存
├── audio_cache/         # 音频缓存
└── whatsapp/
    └── session/         # WhatsApp 会话数据

项目源码结构

hermes-agent/
├── run_agent.py            # 主入口（AIAgent 类）
├── cli-config.yaml.example # 示例配置文件
├── scripts/
│   └── install.sh          # 一键安装脚本
├── tools/                  # 内置工具实现
├── skills/                 # 内置技能
├── plugins/                # 插件（如 Honcho 记忆）
├── tinker-atropos/         # RL 训练后端（子模块，可选）
└── venv/                   # Python 虚拟环境

---

5. 配置系统

配置优先级（高→低）

1. CLI 参数 — 如 hermes chat --model anthropic/claude-sonnet-4
2. ~/.hermes/config.yaml — 非秘密设置主文件
3. ~/.hermes/.env — 环境变量回退，用于密钥
4. 内置默认值 — 硬编码安全默认值

规则

• 秘密信息（API Key、Bot Token、密码）→ 放 .env
• 其他设置（模型、终端后端、压缩、记忆限制）→ 放 config.yaml
• hermes config set 自动路由：API Key 存入 .env，其他存入 config.yaml

环境变量引用

在 config.yaml 中可用 ${VAR_NAME} 语法引用环境变量：

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

关键配置项

# ~/.hermes/config.yaml 示例
model: openrouter/deepseek/deepseek-chat    # 默认模型
terminal:
  backend: local       # local | docker | ssh | modal | daytona | singularity
  cwd: "."             # 工作目录
  timeout: 180         # 命令超时（秒）
  container_cpu: 1     # CPU 核心数
  container_memory: 5120  # 内存（MB）
  container_disk: 51200   # 磁盘（MB）
  container_persistent: true  # 跨会话持久化文件系统

---

6. 功能模块详解

工具系统（40+ 内置工具）

工具按逻辑分组为工具集（Toolsets），可按平台启用/禁用：

分类	工具示例	说明
Web	web_search, web_extract	搜索和提取网页内容
终端 & 文件	terminal, process, read_file, patch	执行命令、操作文件
浏览器	browser_navigate, browser_snapshot, browser_vision	交互式浏览器自动化
媒体	vision_analyze, image_generate, text_to_speech	多模态分析与生成
Agent 编排	todo, clarify, execute_code, delegate_task	规划、澄清、代码执行、子代理委派
记忆 & 召回	memory, session_search	持久记忆和会话搜索
自动化 & 投递	cronjob, send_message	定时任务和消息投递
集成	ha_*（Home Assistant）, MCP 工具, RL 工具	第三方平台集成

配置工具集：

hermes tools                    # 交互式配置
hermes chat --toolsets "web,terminal"  # 指定工具集启动

后台进程管理

# 启动后台进程
terminal(command="pytest -v tests/", background=true)
# 返回: {"session_id": "proc_abc123", "pid": 12345}

# 管理进程
process(action="list")                          # 列出所有进程
process(action="poll", session_id="proc_abc123") # 检查状态
process(action="wait", session_id="proc_abc123") # 等待完成
process(action="log", session_id="proc_abc123")  # 查看输出
process(action="kill", session_id="proc_abc123") # 终止
process(action="write", session_id="proc_abc123", data="y")  # 发送输入

---

7. 终端后端

Hermes 支持六种终端执行环境：

后端	执行位置	隔离级别	适用场景
local	本机直接执行	无	开发、个人使用
docker	Docker 容器	完全隔离（namespace、cap-drop）	安全沙箱、CI/CD
ssh	远程服务器	网络边界	远程开发、高性能硬件
modal	Modal 云沙箱	完全隔离（云 VM）	无服务器计算、评估
daytona	Daytona 工作区	完全隔离（云容器）	托管云开发环境
singularity	Singularity 容器	namespace（--containall）	HPC 集群、共享机器

Docker 后端安全加固

• 只读根文件系统
• 丢弃所有 Linux capabilities
• 禁止权限提升（no-new-privileges）
• PID 限制（256 进程）
• 完整 namespace 隔离
• 临时文件系统大小限制

SSH 后端（推荐安全方案）

让 Agent 远离自身代码，运行在远程服务器上：

# ~/.hermes/.env
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=ubuntu
TERMINAL_SSH_PORT=22          # 可选，默认 22
TERMINAL_SSH_KEY=~/.ssh/id_rsa # 可选，默认系统密钥

---

8. 技能系统

技能是 Agent 按需加载的知识文档，遵循 agentskills.io 开放标准。

使用技能

/gif-search funny cats
/plan design a rollout for migrating our auth provider
/github-pr-workflow create a PR for the auth refactor

渐进式加载（节省 Token）

层级	调用	大小
Level 0	skills_list() → 名称+描述	~3k tokens
Level 1	skill_view(name) → 完整内容+元数据	可变
Level 2	skill_view(name, path) → 特定参考文件	可变

SKILL.md 格式

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]    # 可选：限定平台
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]   # 仅在缺少这些工具集时显示
    requires_toolsets: [terminal]  # 仅在有这些工具集时显示
    requires_environment_variables:
      - name: TENOR_API_KEY
        prompt: Tenor API key
        help: Get a key from https://developers.google.com/tenor
---

# Skill Title

## When to Use
触发条件

## Procedure
1. 步骤一
2. 步骤二

## Pitfalls
- 已知问题和修复方法

## Verification
如何确认工作正常

条件激活

• fallback_for_toolsets：仅在指定工具集不可用时显示（如免费替代方案）
• requires_toolsets：仅在指定工具集可用时显示
• 无条件字段：始终显示

---

9. 记忆系统

Hermes 的记忆系统是其"自我进化"的核心：

• MEMORY.md：持久化记忆文件，Agent 定期整理和更新
• USER.md：用户画像，跨会话积累
• SOUL.md：Agent 身份定义，系统提示第一段
• FTS5 会话搜索：全文本搜索历史对话，LLM 摘要跨会话召回
• Honcho 集成（插件）：AI 原生对话式用户建模

Agent 会主动"自我提醒"保存重要知识，而不是被动等待。

---

10. 消息网关

通过单一网关进程连接所有消息平台：

hermes gateway setup    # 配置平台（Telegram、Discord 等）
hermes gateway start    # 启动网关

支持平台：Telegram、Discord、Slack、WhatsApp、Signal、Email

特性：

• 语音备忘录转录
• 跨平台对话连续性
• 平台特定命令：/status、/sethome

---

11. 定时任务

内置 Cron 调度器，用自然语言描述定时任务：

# 示例
每天早上 9 点发送天气预报
每周一生成周报
每晚 2 点备份数据库

支持的动作：create、list、update、pause、resume、run、remove

---

12. 从 OpenClaw 迁移

Hermes 提供自动迁移工具，从 OpenClaw 导入设置：

hermes claw migrate              # 交互式迁移（完整预设）
hermes claw migrate --dry-run    # 预览将要迁移的内容
hermes claw migrate --preset user-data  # 仅迁移用户数据（不含密钥）
hermes claw migrate --overwrite  # 覆盖已有冲突

自动导入的内容：

项目	说明
SOUL.md	人格文件
记忆	MEMORY.md 和 USER.md
技能	用户创建的技能 → ~/.hermes/skills/openclaw-imports/
命令白名单	审批模式
消息设置	平台配置、允许用户、工作目录
API 密钥	Telegram、OpenRouter、OpenAI、Anthropic、ElevenLabs
TTS 资产	工作区音频文件
工作区指令	AGENTS.md

---

13. 常见安装问题

国内服务器一键换源（推荐）

在国内服务器安装 Hermes 前，建议先统一换源，避免所有下载卡住。以下全部使用阿里云镜像（已验证可用）：

# ===== 1. Ubuntu/Debian 系统源 =====
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

# Ubuntu 24.04 (noble)
sudo tee /etc/apt/sources.list << 'EOF'
deb https://mirrors.aliyun.com/ubuntu/ noble main restricted universe multiverse
deb https://mirrors.aliyun.com/ubuntu/ noble-updates main restricted universe multiverse
deb https://mirrors.aliyun.com/ubuntu/ noble-backports main restricted universe multiverse
deb https://mirrors.aliyun.com/ubuntu/ noble-security main restricted universe multiverse
EOF

# 其他版本替换 noble：
# Ubuntu 22.04 → jammy | Ubuntu 20.04 → focal | Debian 12 → bookworm

sudo apt update

# ===== 2. Python 包源（uv / pip） =====
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
export UV_EXTRA_INDEX_URL=https://pypi.org/simple/  # 回退源
export PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/

# ===== 3. npm 源 =====
npm config set registry https://registry.npmmirror.com/
# 或临时使用：export npm_config_registry=https://registry.npmmirror.com/

# ===== 4. 一键换源脚本（可复制粘贴执行） =====
cat << 'SCRIPT' > /tmp/mirror-setup.sh
#!/bin/bash
# Hermes 国内镜像一键配置
set -e

# -- Ubuntu 源 --
CODENAME=$(lsb_release -cs 2>/dev/null || echo "noble")
echo "检测到系统代号: $CODENAME"
sudo cp -n /etc/apt/sources.list /etc/apt/sources.list.bak 2>/dev/null || true
cat << EOF | sudo tee /etc/apt/sources.list
deb https://mirrors.aliyun.com/ubuntu/ $CODENAME main restricted universe multiverse
deb https://mirrors.aliyun.com/ubuntu/ $CODENAME-updates main restricted universe multiverse
deb https://mirrors.aliyun.com/ubuntu/ $CODENAME-backports main restricted universe multiverse
deb https://mirrors.aliyun.com/ubuntu/ $CODENAME-security main restricted universe multiverse
EOF
sudo apt update

# -- Python 源 --
grep -q 'UV_INDEX_URL' ~/.bashrc 2>/dev/null || {
  echo 'export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/' >> ~/.bashrc
  echo 'export UV_EXTRA_INDEX_URL=https://pypi.org/simple/' >> ~/.bashrc
  echo 'export PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/' >> ~/.bashrc
}
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
export UV_EXTRA_INDEX_URL=https://pypi.org/simple/
export PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/

# -- npm 源 --
npm config set registry https://registry.npmmirror.com/ 2>/dev/null || true

echo "✓ 镜像源配置完成"
echo "  Ubuntu → mirrors.aliyun.com"
echo "  Python → mirrors.aliyun.com/pypi (+ pypi.org 回退)"
echo "  npm    → npmmirror.com"
SCRIPT

chmod +x /tmp/mirror-setup.sh
bash /tmp/mirror-setup.sh

提示：换源脚本会自动检测 Ubuntu 版本代号，写入 ~/.bashrc 持久化环境变量。执行完后直接运行 Hermes 安装命令即可。

镜像源列表（备用）

类型	阿里云（推荐）	中科大	清华
Ubuntu	https://mirrors.aliyun.com/ubuntu/	https://mirrors.ustc.edu.cn/ubuntu/	https://mirrors.tuna.tsinghua.edu.cn/ubuntu/
PyPI	https://mirrors.aliyun.com/pypi/simple/	https://mirrors.ustc.edu.cn/pypi/simple/	https://pypi.tuna.tsinghua.edu.cn/simple/
npm	https://registry.npmmirror.com/	—	https://mirrors.tuna.tsinghua.edu.cn/npm/

注意：清华 PyPI 镜像偶尔出现 403 错误，建议优先使用阿里云源，并配置 UV_EXTRA_INDEX_URL=https://pypi.org/simple/ 作为回退。

缺少编译工具

某些 Python 包（如 cryptography、psutil）需要 C 编译器。安装脚本会提示 Some build tools may be needed。

# Debian / Ubuntu
sudo apt install build-essential python3-dev

# CentOS / RHEL
sudo yum groupinstall "Development Tools"

# Alpine
sudo apk add build-base python3-dev

---

参考链接

• 官网文档：https://hermes-agent.nousresearch.com/docs/
• GitHub：https://github.com/NousResearch/hermes-agent
• Skills Hub：https://agentskills.io
• Discord 社区：https://discord.gg/NousResearch
• Nous Research：https://nousresearch.com

---

本文基于 Hermes Agent 2026年4月版本编写，基于官方文档整理。