Hermes Agent 从入门到精通：全流程学习路线分享

如果你关注开源 AI Agent 领域，一定听过 Hermes Agent 这个名字。GitHub 已突破 52K Star，被开发者社区称为"AI 助手界的爱马仕"。它和传统 AI 最大的区别在于：传统 AI 无状态、每次对话重置，而 Hermes Agent 有记忆、会积累、能进化——用得越久，它越懂你。

最近有读者在问：这个东西到底怎么学？从哪入手？有没有一条清晰的学习路径？本文把从入门到精通的最优路线分享给你，结合我们实际使用过程中踩过的坑，帮你少走弯路。

第一阶段：基础入门，先跑通再说

很多新手一上来就想搞懂所有原理，结果卡在环境配置上三天出不来。其实 Hermes Agent 的官方安装已经极度简化了，正确姿势是：先跑通，再深入。

一、系统要求

支持平台一览：

⚠️ 重要提示：Hermes Agent 不支持 Windows 原生环境。Windows 用户请务必使用 WSL2（推荐 Ubuntu 22.04）。

硬件要求：

💡 新手建议：先使用云端 API（如 OpenRouter、OpenAI）体验功能，不需要本地推理。

软件依赖：安装脚本会自动处理 Python 3.11+、Node.js v22、ripgrep、ffmpeg。

二、安装方式一：一键安装（推荐新手）

这是最简单的方式，适合 macOS、Linux 和 WSL2 用户。

一键安装命令：

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

安装后加载环境：

# 如果使用 zsh（macOS 默认）
source ~/.zshrc

# 如果使用 bash
source ~/.bashrc

验证安装：

hermes --version

三、安装方式二：手动安装（适合进阶用户）

如果你想更好地控制安装过程，可以选择手动安装。

克隆仓库：

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

# 如果有子模块
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git

创建虚拟环境：

# 安装 uv（如果你还没有）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建 Python 3.11 虚拟环境
uv venv .venv --python 3.11
source .venv/bin/activate

安装依赖：

# 基础安装
uv pip install -e "."

# 完整安装（包含所有功能）
uv pip install -e ".[all]"

# 或者按需安装
uv pip install -e ".[cli]"      # CLI 菜单界面
uv pip install -e ".[messaging]" # 消息平台 SDK
uv pip install -e ".[voice]"    # 语音合成
uv pip install -e ".[image]"    # 图片生成

创建符号链接：

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

四、Windows 用户：WSL2 安装指南

什么是 WSL2：WSL2（Windows Subsystem for Linux 2）是 Windows 10/11 自带的 Linux 子系统，可以在 Windows 中运行 Linux 环境。

安装 WSL2：以管理员身份打开 PowerShell，执行：

wsl --install -d Ubuntu-22.04

安装完成后，重启电脑。

⚠️ 注意：务必在 WSL2 终端中执行，不要在 PowerShell 或 CMD 中执行。

在 WSL2 里安装 Hermes Agent：打开 Ubuntu 22.04 终端，然后执行与 Linux 相同的安装命令：

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

安装完成后，随便配一个 Anthropic 或者 OpenAI 的 Key，在终端里和它对话几次。观察它是如何拆解问题、如何调用本地工具的。这个阶段的目标不是学多深，而是感受它原生的工作流程，建立直觉。

官方仓库：https://github.com/NousResearch/hermes-agent

第二阶段：进阶配置，把潜力压出来

跑通基础对话之后，你可能会觉得它就是一个"更聪明的聊天框"。错。第二阶段的目标是把它变成真正的生产力工具。

一、运行初始设置向导

安装完成后，运行设置向导：

hermes setup

这会引导你完成：选择模型提供商 → 输入 API Key → 选择默认模型 → 配置工具集。

二、配置模型提供商

Hermes Agent 支持多种模型提供商，以下是常见配置：

OpenRouter（推荐新手）：OpenRouter 提供 200+ 模型，包括 Claude、GPT-4、Llama 等。

# 设置 API Key
hermes config set OPENROUTER_API_KEY your_key_here

# 或者直接编辑配置文件 ~/.hermes/.env
# OPENROUTER_API_KEY=***

# config.yaml 示例
provider:
  name: openrouter
model:
  name: anthropic/claude-sonnet-4-20250514

OpenAI：

hermes config set OPENAI_API_KEY your_key_here
hermes config set model.default gpt-4o

Nous Portal（免费体验 Hermes 模型）：

hermes chat --provider nous

阿里云通义千问：

# 设置环境变量
export DASHSCOPE_API_KEY=your_key_here

# 使用通义千问
hermes chat --provider alibaba --model qwen3.5-plus

三、常用配置命令

四、配置文件结构

所有配置存储在 ~/.hermes/ 目录：

~/.hermes/
├── config.yaml    # 设置（模型、终端、TTS、压缩等）
├── .env           # API Keys 和密钥
├── auth.json      # OAuth 凭据（Nous Portal 等）
├── SOUL.md        # 全局人格定义（可选）
├── memories/      # 持久记忆
├── skills/        # 沉淀的技能
├── cron/          # 定时任务
├── sessions/      # 对话会话
└── logs/          # 日志文件

五、进阶配置的核心：SOUL.md

进阶配置的核心是 SOUL.md 文件——这是控制 Hermes Agent 底层行为的配置文件。新手容易踩的坑是直接改 Prompt，其实 SOUL.md 才是精髓所在。通过它你可以精确控制 Agent 的思考方式、工具调用策略和记忆行为。

六、配置工具集

Hermes Agent 内置 40+ 工具，建议新手先开启核心工具集：

hermes tools --set all   # 开启所有工具

# 或者按需开启
hermes tools --set web,terminal,file,memory,skills,cron

常用工具集说明：

七、启动与使用

# 启动交互式会话
hermes

# 单次查询模式
hermes chat -q "请给我解释一下什么是 REST API"

常用命令：

八、避坑大全

坑一：安装后找不到 hermes 命令
原因：shell 配置没有重新加载。解决方案：

# 方法1：重新加载配置文件
source ~/.zshrc   # zsh 用户
source ~/.bashrc  # bash 用户

# 方法2：检查 hermes 是否安装
which hermes

# 方法3：如果是手动安装，创建符号链接
sudo ln -sf "$(pwd)/.venv/bin/hermes" /usr/local/bin/hermes

坑二：模型选择报 401/403 错误
原因：API Key 配置错误或模型提供商不支持。解决方案：

# 1. 检查 API Key 是否正确
hermes config show | grep API_KEY

# 2. 运行诊断命令
hermes doctor

# 3. 重新配置模型
hermes model

坑三：安装时报 Python/Cython 错误
解决方案（Ubuntu/Debian）：

# 安装编译工具
sudo apt update
sudo apt install -y python3-dev build-essential

# 清理后重试
pip install --no-cache-dir -e ".[all]"

坑四：工具执行报权限错误
解决方案：

# 检查终端配置
cat ~/.hermes/config.yaml

# 如果使用 Docker 后端
terminal:
  backend: docker
  docker_image: python:3.11-slim

# 如果需要 sudo 权限
sudo usermod -aG docker $USER
newgrp docker

坑五：消息平台（TG/Discord）收不到消息
解决方案：

# 1. 启动网关
hermes gateway start

# 2. 检查网关状态
hermes gateway status

# 3. 查看网关日志
tail -f ~/.hermes/logs/gateway.log

# 4. 检查白名单配置
# 确保在 ~/.hermes/.env 中配置了正确的用户 ID
TELEGRAM_ALLOWED_USERS=your_user_id

坑六：上下文窗口不足
解决方案：

# 1. 使用上下文更大的模型
hermes model

# 2. 如果使用 Ollama，确保 num_ctx 配置匹配
ollama run --num_ctx 16384 your_model

# 3. 开启上下文压缩
# 在 config.yaml 中：
compression:
  enabled: true
  threshold: 0.50

坑七：技能不触发或不被复用
解决方案：

# 1. 查看当前技能
/hermes skills list

# 2. 手动触发技能学习
# 在对话中明确要求 Agent 沉淀技能：
# "请把刚才的操作沉淀为一个技能，命名为 xxx"

# 3. 检查技能目录
ls ~/.hermes/skills/

坑八：从 OpenClaw 迁移后配置丢失
解决方案：

# Hermes Agent 原生支持从 OpenClaw 迁移
# 只需在新环境运行
hermes setup
# 迁移程序会自动检测并导入旧配置

九、安全配置（生产环境必看）

Hermes Agent 拥有终端命令执行、文件操作等高危权限，务必做好安全配置：

消息平台白名单：

# ~/.hermes/.env
TELEGRAM_ALLOWED_USERS=your_user_id_1,your_user_id_2
DISCORD_ALLOWED_USERS=your_user_id_1,your_user_id_2

⚠️ 严禁设置 GATEWAY_ALLOW_ALL_USERS=true，否则任何人可以访问你的 Agent！

危险命令审批：

# ~/.hermes/config.yaml
security:
  dangerous_command_approval: always  # 始终审批危险命令
  # 或
  dangerous_command_approval: high_risk_only  # 仅高风险命令审批

容器隔离：

# ~/.hermes/config.yaml
terminal:
  backend: docker
  docker_image: python:3.11-slim

其次是记忆模块的升级。默认的记忆是基于简单文本的，随着对话增多会出现上下文混乱。进阶玩法是用 LightRAG 替换默认记忆模块，LightRAG 是基于知识图谱的，能够理解实体之间的关系，大幅提升复杂上下文的理解能力。

第三是接入消息通道（平台）。Hermes Agent 的真正壁垒是它的多平台接入能力——通过网关（Gateway）把 AI 带到你日常最常用的聊天工具里。跑通之后，你用手机随时调遣它，真正实现"关机也能持续运行"。主流平台全部支持：Telegram、Discord、Slack、WhatsApp、飞书、企业微信、个人微信、邮件、短信等，每个平台的接入流程都遵循同一套逻辑：安装平台依赖 → 运行设置向导 → 扫码/填令牌 → 配置访问策略 → 启动网关。

一、网关核心概念

Gateway（网关）是 Hermes Agent 连接外部消息平台的桥梁。它基于 ACP（Agent Communication Protocol）协议，运行在你的服务器上，通过长轮询（Long-Polling）或 Webhook 方式与各平台服务器保持通信。

核心优势：

• 不需要固定公网 IP（长轮询模式）
• 消息自动加解密，媒体文件走 AES-128-ECB 加密 CDN
• 多平台统一接入，统一管理
• 定时任务（Cron）自动推送到指定通道

Gateway 工作原理： 你的 VPS 作为客户端，主动定时向各平台服务器"敲门"问"有没有我的消息"，有就拿回来处理，没有就继续等。由于是客户端发起连接，完全不需要配置Webhook或开放端口，在内网里跑着的服务器也能用。

二、通用接入步骤（Telegram / Discord / Slack 等）

除了微信之外的大多数平台（Telegram、Discord、Slack、WhatsApp、Signal、邮件等）都遵循以下通用流程：

第一步：安装依赖

不同平台需要不同的 Python 包：

# Telegram
pip install aiohttp

# Discord（需要 discord.py）
pip install discord.py aiohttp

# Slack
pip install slack-sdk aiohttp

# WhatsApp
pip install aiohttp cryptography

# Signal
pip install aiohttp

# 通用基础依赖
pip install aiohttp cryptography

第二步：创建平台 Bot / 应用

各平台创建方式不同：

第三步：运行设置向导

hermes gateway setup

向导会引导你：选择要接入的平台 → 输入 Bot Token → 配置白名单 → 自动保存配置。

第四步：启动网关

hermes gateway

第五步：验证

在对应平台给 Bot 发一条消息，确认响应正常。

三、Telegram 接入详解（步骤最全的示例）

Telegram 是接入最简单、最稳定的平台，以下是完整步骤：

1. 创建 Bot

在 Telegram 里搜索 @BotFather，发送 /newbot，按提示填写 Bot 名称和用户名（须以 bot 结尾，如 MyHermesBot）。完成后 BotFather 会给你一个 Bot Token，格式类似：123456789:ABCdefGHIjklMNOpqrsTUVwxyz。

2. 安装依赖

pip install aiohttp

3. 运行设置向导

hermes gateway setup

• 选择 Telegram
• 输入 Bot Token
• 询问 DM 策略：选 allowlist（仅白名单用户可私聊）或 open（任何人可聊）
• 如果选白名单，会要求输入你的 Telegram User ID（发送 /start 给 @userinfobot 获取）

4. 配置白名单（如需）

编辑 ~/.hermes/.env：

TELEGRAM_ALLOWED_USERS=your_telegram_user_id
TELEGRAM_DM_POLICY=allowlist

5. 启动网关

hermes gateway

看到 Telegram: Connected ✓ 即表示成功。

6. 开始对话

在 Telegram 找到你的 Bot，点 Start，直接发送消息即可。

四、微信（Weixin）接入详解（含扫码后选项步骤）

微信接入国内用户最常用，但流程和其他平台略有不同——它使用 iLink Bot API，通过扫码授权，不需要 Bot Token。

1. 安装依赖

pip install aiohttp cryptography
# 可选：终端二维码显示
pip install qrcode

2. 运行设置向导

hermes gateway setup

• 选择 Weixin（注意：不是 WeCom，WeCom 是企业微信）

3. 扫码登录

向导会显示一个二维码（终端内直接显示，或提供 URL 链接在浏览器打开）。用微信扫一扫：

• 打开微信 → 发现 → 扫一扫
• 对准终端/浏览器中的二维码
• 扫码后微信会弹出确认页面，这是腾讯安全验证，必须点确认才能继续

4. 扫码确认后的选项步骤

扫码成功后，你的微信会收到来自"微信安全验证"或 iLink 的确认通知，点开后会看到类似以下选项：

点击 确认登录 后，终端会显示：

微信连接成功，account_id=your-account-id

配置会自动保存到 ~/.hermes/weixin/accounts/ 目录，下次启动不需要重新扫码。

5. 配置访问策略（白名单模式）

编辑 ~/.hermes/.env：

# 设为白名单模式（强烈建议，避免陌生人骚扰）
WEIXIN_DM_POLICY=allowlist

# 你的微信 ID（user_id，不是微信号）
WEIXIN_ALLOWED_USERS=your_weixin_user_id

如何获取你的微信 User ID：网关运行后，给 Bot 发任意消息，日志里会显示你的 user_id。

6. 启动网关

hermes gateway

连接成功后，你就可以在微信里和 Hermes Agent 私聊了。

7. 微信支持的玩法

8. 安全提醒

⚠️ 严禁设置 WEIXIN_DM_POLICY=open（任何人都能给你发消息并控制你的 AI），建议始终配合白名单使用。

五、接入其他平台速览

六、Home Channel（定时推送的关键）

配置好消息通道后，建议把常用通道设为 Home Channel，这样定时任务（Cron）的结果会自动推送到这里：

# 设为 Telegram 私聊为 Home Channel
hermes config set home_channel telegram:your_user_id

# 设为微信为 Home Channel
hermes config set home_channel weixin:your_user_id

或者在 ~/.hermes/.env 中配置：

# Telegram
TELEGRAM_HOME_CHANNEL=your_user_id

# 微信
WEIXIN_HOME_CHANNEL=your_user_id

Home Channel 的实际用途：

• 每天早上自动推送新闻早报
• 服务器监控告警实时推送
• 定时任务执行结果通知
• 不打开电脑，手机随时查看 AI 执行结果

进阶实战指南（踩坑开发者总结）：https://github.com/OnlyTerp/hermes-optimization-guide

第三阶段：可视化控制中心

到了第三阶段，你应该已经不满足于对着终端敲命令了。Hermes Agent 的真正形态不是"聊天框"，而是一个多能力的 AI 系统。把它通过网关连接到可视化界面后，你可以在图形界面里直观地审查它的完整 Tool Calls 轨迹——每一次工具调用、每一次思考决策全都看得一清二楚。

更重要的是，你可以直接编辑它的大脑记忆。记忆乱了可以手动修正，重要信息可以标记强化，不用担心它跑偏。此外还能管理它的技能树（Skill Tree），增删改查全部可视化操作。

这个阶段的核心价值在于：从"使用者"变成"掌控者"。你不再只是和它对话，而是在真正地管理它。

可视化与工作流管理仓库：https://github.com/outsourc-e/hermes-workspace

第四阶段：生态扩展，触达高阶玩法

能稳定使用之后，视野要打开。Hermes Agent 的真正壁垒是它的生态。

Awesome 资源库里收录了大量成熟场景案例。比如 autonovel 管道——用 Hermes Agent 来全自动写长篇小说，从大纲到章节全部自动完成，中间可以随时干预调整方向。另一个典型场景是定时任务（Cron）配置：让它在你睡觉时自动巡检服务器、整理行业简报、推送关键信息。这类自动化场景一旦搭好，使用频率比日常对话还高。

还有 MCP（Model Context Protocol）扩展能力。接上 MCP Server 之后，Hermes Agent 的工具能力可以无限扩展。你接什么它就能用什么，而且多步骤任务可以压缩执行，效率比单步调用高很多。

Awesome 资源库（精选合集）：https://github.com/0xNyk/awesome-hermes-agent

学习路线总结

整体学习分四个阶段，节奏大概是：

第一周：装好跑通，体验基础对话，感受它的工作方式。

第二周：配置 SOUL.md、升级记忆模块、接入 Telegram。

第三周：搭建可视化控制中心，熟练管理 Skill 和记忆。

第四周及以后：探索生态、接入 MCP、搭自动化管道，形成自己的使用习惯。

最后提醒一点：Hermes Agent 不是传统意义的工具，是一个会越用越强的 AI 系统。你的使用过程就是它的训练过程，积累的经验会沉淀为可复用的 Skills。投入时间越长，它给你的回报越高。52K Star 不是白来的，用起来才知道它有多香。

GitHub：https://github.com/NousResearch/hermes-agent

文档：http://hermes-agent.nousresearch.com/docs