01-Hermes Agent 安装全攻略：Python 环境下的第一个自进化 Agent

Hermes Agent 安装全攻略：Python 环境下的第一个自进化 Agent

第 3 篇让你认识了 Hermes Agent——一个会记住你、理解你、越用越像你的 AI。现在该动手了。这篇文章的目标和第 4 篇一样：不管你用什么系统、什么网络环境，15 分钟内装好 Hermes Agent 并跑通验证。但 Hermes 是 Python 生态，坑和 OpenClaw（Node.js 生态）完全不同。

系统要求

Hermes Agent 对环境有三条硬性要求，比 OpenClaw 更严格：

Python 3.12+（为什么必须是 3.12+？）
→ Hermes 大量使用了 Python 3.12 的新特性：
– PEP 695: type statement（类型形参语法）
– PEP 701: f-string 改进
– 更好的 asyncio 支持
→ 3.11 及以下无法运行，硬性报错

SQLite 3.40+（为什么？）
→ Hermes 的持久记忆和技能存储依赖 SQLite
→ 使用了 FTS5 全文检索（会话历史搜索）
→ 使用了 JSON 函数（记忆条目的结构化存储）
→ Python 3.12 自带的 sqlite3 模块版本通常 >= 3.40，但如果系统
libsqlite3 太老，需要升级

内存最低 4GB（为什么？）
→ Hermes 的内存系统会缓存向量索引（用于语义检索记忆）
→ 单 Agent 模式 ~2GB 够用，但自学习 + 多记忆检索需要更多
→ 低于 4GB 会导致频繁 swap → 响应极慢

环境检查

# Python 版本
python3 –version
# 必须是 3.12.x 或更高

# SQLite 版本
python3 -c "import sqlite3; print(sqlite3.sqlite_version)"
# 必须是 3.40.0 或更高

# 内存
free -h
# total 至少 4GB

安装方式一：pip 安装（最简单）

第一步：确认 Python 版本并创建虚拟环境

# 确认 Python 版本
python3 –version

# 强烈建议用虚拟环境（隔离依赖，不污染系统 Python）
python3 -m venv ~/hermes-env
source ~/hermes-env/bin/activate

# 升级 pip
pip install –upgrade pip

第二步：安装

pip install hermes-agent

# 安装过程可能持续 2-5 分钟（需要编译部分依赖的 C 扩展）

第三步：验证

hermes –version
# 输出类似：hermes-agent v0.12.0

hermes doctor
# 诊断环境：
# ✅ Python 3.12.4
# ✅ sqlite3 3.45.0
# ✅ Memory: 7.8GB available
# ✅ Config: ~/.hermes/config.yml
# ⚠️ Docker not found (optional)

pip 安装的常见坑

坑一：Python 版本不对

$ python3 –version
Python 3.11.9 ← 不够

$ pip install hermes-agent
ERROR: Package 'hermes-agent' requires Python >= 3.12

解决：

# 用 pyenv 安装 Python 3.12（推荐，不影响系统 Python）
# macOS
brew install pyenv
pyenv install 3.12.4
pyenv global 3.12.4

# Linux
curl https://pyenv.run | bash
# 添加到 ~/.bashrc：
# export PYENV_ROOT="$HOME/.pyenv"
# export PATH="$PYENV_ROOT/bin:$PATH"
# eval "$(pyenv init -)"
pyenv install 3.12.4
pyenv global 3.12.4

# 验证
python –version # Python 3.12.4

坑二：SQLite 版本过低（Linux 老系统）

$ python3 -c "import sqlite3; print(sqlite3.sqlite_version)"
3.34.0 ← 不够

这个问题比较麻烦——Python 的 sqlite3 模块编译时链接了系统的 libsqlite3，单纯升级 Python 解决不了。

# 方案一：用 Docker 绕开（推荐，见安装方式二）

# 方案二：手动编译 SQLite + 重新链接 Python sqlite3
# （复杂，不推荐初学者操作）
sudo apt install -y build-essential tcl-dev
wget https://www.sqlite.org/2024/sqlite-autoconf-3450000.tar.gz
tar xzf sqlite-autoconf-3450000.tar.gz
cd sqlite-autoconf-3450000
./configure –prefix=/usr/local
make -j$(nproc)
sudo make install
# 然后需要重装 Python 使其链接新的 libsqlite3…
# 建议：直接用 Docker，别折腾这个

坑三：C 扩展编译失败（缺编译工具）

error: command 'gcc' failed: No such file or directory

# macOS
xcode-select –install

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

# CentOS/RHEL
sudo yum install -y gcc gcc-c++ python3-devel

安装方式二：Docker 部署（推荐，最省心）

Docker 方式完全避开了 Python 版本和 SQLite 版本的问题——容器内已经配好了。

第一步：拉取镜像并配置

mkdir -p ~/hermes-agent/{config,data,skills,logs}
cd ~/hermes-agent

# ~/hermes-agent/docker-compose.yml
version: "3.8"

services:
hermes:
image: nousresearch/hermes–agent:latest
container_name: hermes–agent
restart: unless–stopped

environment:
– HERMES_MODEL_PROVIDER=anthropic # anthropic | openai | deepseek | ollama
– ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
– HERMES_DEFAULT_MODEL=claude–sonnet–4–6
– HERMES_MEMORY_BACKEND=sqlite # sqlite | redis | postgres
– HERMES_LOG_LEVEL=info
– TZ=Asia/Shanghai

volumes:
– ./config:/app/config # 配置文件
– ./data:/app/data # 记忆数据库 + 持久化
– ./skills:/app/skills # 自定义 Skills
– ./logs:/app/logs # 日志

ports:
– "8080:8080" # Hermes HTTP API（可选）

healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8080/health')"]
interval: 15s
timeout: 5s
retries: 3
start_period: 20s

deploy:
resources:
limits:
memory: 4g
cpus: "2.0"

第二步：配置 API Key

# 创建 .env 文件
cat > .env << 'EOF'
ANTHROPIC_API_KEY=sk-ant-your-key-here
# 如果用 OpenAI
# OPENAI_API_KEY=sk-your-key-here
EOF

echo ".env" >> .gitignore

第三步：启动

docker compose up -d

# 查看启动日志
docker compose logs -f

# 期望看到：
# [INFO] Hermes Agent v0.12.0 starting…
# [INFO] Memory backend: sqlite (path: /app/data/memory.db)
# [INFO] Model: anthropic/claude-sonnet-4-6
# [INFO] Health check: http://0.0.0.0:8080/health
# [INFO] Ready. 开始对话: hermes chat

第四步：验证

# 进入容器对话
docker compose exec hermes hermes chat

# 第一次对话
🤖 Hermes > 你好！我是 Hermes，有什么可以帮你的？
👤 > 你好，我叫 Barry，是一个全栈工程师，主要用 FastAPI 和 React
🤖 > 你好 Barry！已记住你的信息。需要我做什么？

安装方式三：源码安装（适合需要深度定制）

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

# 用 Poetry 管理依赖
pip install poetry
poetry install

# 激活虚拟环境
poetry shell

# 验证
hermes –version

各平台的专属坑

macOS 专属坑

坑一：brew 安装的 Python 和 pyenv 冲突

第 4 篇也提到过类似问题，但在 Python 生态下更常见：

# 检查当前用的是哪个 Python
which python3
# /opt/homebrew/bin/python3 ← brew 装的
# /Users/barry/.pyenv/shims/python3 ← pyenv 装的

# 如果 pyenv global 没生效：
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zshrc

坑二：Apple Silicon + tokenizers 库编译失败

error: can't find Rust compiler

原因：Hermes 依赖的 tokenizers 库（HuggingFace 出品）需要 Rust 编译器。

# 安装 Rust
curl –proto '=https' –tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# 重新安装
pip install –force-reinstall tokenizers
pip install hermes-agent

Linux 专属坑

坑一：apt 源的 Python 太老

Ubuntu 22.04 → apt 只有 Python 3.10
Ubuntu 24.04 → apt 有 Python 3.12 ✅
Debian 12 → apt 只有 Python 3.11

# 用 deadsnakes PPA（Ubuntu）
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install -y python3.12 python3.12-venv python3.12-dev

# 创建 venv
python3.12 -m venv ~/hermes-env
source ~/hermes-env/bin/activate

坑二：libsqlite3 版本低（见上面 pip 安装坑二）

推荐：Linux 老系统直接用 Docker，不要折腾手动编译。

Windows 专属坑

推荐：WSL2（和 OpenClaw 一样，Windows 原生支持不完善）

wsl —install –d Ubuntu-24.04
wsl
# 然后在 WSL2 的 Ubuntu 中按 Linux 方式安装

国内网络问题

pip 源

# 清华源（推荐）
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 阿里源（备选）
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

# 验证
pip config list

HuggingFace 模型下载

Hermes 的自学习功能可能用到 HuggingFace 上的嵌入模型（用于语义检索记忆）。国内直接下载可能很慢或失败：

# 配置 HuggingFace 镜像
export HF_ENDPOINT=https://hf-mirror.com

# 写入 ~/.bashrc 永久生效
echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc

GitHub 加速

# git clone 加速（源码安装时）
git clone https://ghproxy.com/https://github.com/NousResearch/hermes-agent.git

安装后验证清单

# ✅ 版本检查
hermes –version

# ✅ 环境诊断
hermes doctor

# ✅ 如果用 Docker，检查容器状态
docker compose ps
docker compose logs hermes –tail 20

# ✅ 冒烟测试：开始第一段对话
hermes chat
👤 > 你好，我叫 Barry
🤖 > 你好 Barry！已记住你的名字。
👤 > /exit

# ✅ 检查记忆是否保存
hermes memory list
# 应该显示：
# [user] name: Barry
# [session] 2026-06-04: 第一次对话

# ✅ 再次对话，验证记忆持久化
hermes chat
👤 > 我叫什么名字？
🤖 > 你叫 Barry。（从持久记忆中检索到的）

和 OpenClaw 安装的对比

OpenClaw Hermes Agent
─────────────────────────────────────────────────────────
运行时 Node.js 20 Python 3.12+
包管理器 npm / pnpm pip / Poetry
核心依赖坑 node-gyp (C++ 编译) tokenizers (Rust 编译)
数据库依赖 Redis（多 Worker 必须） SQLite（自带，无需额外安装）
Docker 镜像 openclaw/orchestrator nousresearch/hermes-agent
系统要求 2GB 内存 4GB 内存（记忆系统开销大）
安装复杂度 中等（node-gyp 可能踩坑） 中等偏高（Python 版本 + SQLite 版本）
最省心方式 Docker Compose Docker Compose

文章的要点

1. Hermes 的三条硬性要求：
Python 3.12+ / SQLite 3.40+ / 内存 4GB+
→ 缺一不可，不是"建议"是"必须"

2. 三种安装方式：
pip install（最直接，但需要环境达标）
Docker（最省心，避开所有 Python/SQLite 版本问题）
源码（需要 Rust 编译器 + Poetry）

3. 各平台核心坑：
macOS：brew Python vs pyenv + tokenizers 需要 Rust
Linux：老系统 Python/SQLite 版本不够 → 用 Docker
Windows：用 WSL2

4. 国内网络：pip 清华源 + HuggingFace 镜像

5. 验证安装：hermes doctor + 对话 + 记忆持久化测试

延伸阅读

• Hermes Agent 官方安装文档
• pyenv 使用指南
• HuggingFace 镜像站