Hermes Agent 完整使用教程（WSL2 版）

本文适用于 Windows 用户，详细介绍如何在 WSL2（Windows Subsystem for Linux 2）环境下安装、配置和使用 Hermes Agent，助你快速上手这个"越用越聪明"的自进化 AI 智能体。

一、Hermes Agent 是什么？

Hermes Agent 是由 Nous Research 于 2026 年 2 月开源的自主 AI 智能体框架，采用 MIT 协议发布。它不是一个简单的聊天机器人，而是一个能够自主规划任务、沉淀经验、跨会话记忆的数字助手，随着使用时间的增长会变得越来越懂你。

Hermes Agent 与此前大火的 OpenClaw（龙虾）项目有着紧密联系——它内置了 hermes claw migrate 命令，支持一键迁移 OpenClaw 的设置、记忆、技能和 API 密钥。

1.1 核心能力

能力	说明
持久化记忆	跨会话保存用户偏好、项目信息、学习成果，重启不丢失
技能系统	内置 40+ 技能，支持自动生成和自主改进，完成任务后可沉淀为可复用的 Skill 文件
多工具调用	支持终端执行、文件读写、浏览器自动化、定时任务等
多平台接入	支持 CLI、Telegram、Discord、Slack、WhatsApp、飞书、钉钉、企业微信等 15+ 平台
多模型支持	支持 OpenRouter、OpenAI、Anthropic、MiniMax、Kimi、智谱 GLM 等 200+ 模型，一行命令切换
Cron 定时任务	内置定时调度器，支持自然语言设置周期性任务，结果自动推送
安全沙盒	内置命令审批、容器隔离、用户白名单等六层纵深防护机制

1.2 数据隐私

所有对话记录、记忆和技能文件均存储在本地 ~/.hermes/ 目录下，不会上传到任何第三方服务器，数据完全由你掌控。

二、环境准备：安装 WSL2

⚠️ 重要：Hermes Agent 目前不支持 Windows 原生环境，Windows 用户必须先安装 WSL2 并在其中运行。

2.1 启用 WSL2 必要组件

以管理员身份打开 PowerShell，依次执行以下命令：

# 启用适用于 Linux 的 Windows 子系统
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 启用虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

执行完毕后，请务必重启电脑，否则 WSL2 内核无法正常加载。

2.2 设置 WSL2 为默认版本并安装 Ubuntu

重启后，以管理员身份打开 PowerShell，执行：

# 将 WSL2 设置为默认版本
wsl --set-default-version 2

# 安装 Ubuntu 22.04 LTS（推荐，Python 包兼容性较好）
wsl --install -d Ubuntu-22.04

首次启动 Ubuntu 时，系统会提示你创建一个 UNIX 用户名和密码。用户名建议使用全小写字母（如 hermes 或 user），因为 Linux 系统对用户名有严格的命名规则限制。

2.3 优化 WSL2 资源配置（可选但推荐）

Hermes Agent 对内存带宽与 I/O 延迟敏感，建议通过 .wslconfig 文件限制资源分配。

1. 在 Windows 用户目录下（即 C:\Users\你的用户名\）创建 .wslconfig 文件
2. 用记事本或 VS Code 编辑，写入以下内容：

   [wsl2]
   memory=6GB
   swap=2GB
   localhostForwarding=true
   

3. 在 PowerShell 中执行 wsl --shutdown，再重新启动 Ubuntu，运行 free -h 验证内存配置是否生效

2.4 验证 WSL2 安装

在 Ubuntu 终端中运行：

wsl --version

如果正常显示版本信息，说明 WSL2 已就绪。

三、安装 Hermes Agent

3.1 更新系统包并安装依赖

打开 Ubuntu 终端，执行：

# 更新系统包
sudo apt update && sudo apt upgrade -y

# 安装必要依赖
sudo apt install -y curl git python3 python3-pip

3.2 执行一键安装脚本

运行官方一键安装命令：

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

脚本会自动处理以下内容：

• 克隆 Hermes Agent 仓库
• 创建 Python 虚拟环境
• 安装 Node.js v22（浏览器自动化和微信桥接需要）
• 安装 ripgrep（快速文件搜索）
• 安装 ffmpeg（TTS 音频转换）
• 将 hermes 命令全局安装

3.3 国内网络加速（如遇下载缓慢）

若 GitHub 访问不稳定，可采用镜像方案：

# 先克隆镜像仓库
git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git ~/.hermes/hermes-agent

# 再执行安装脚本
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

脚本检测到 ~/.hermes/hermes-agent 已存在后，会自动跳过 clone 步骤，直接进入依赖安装阶段。

3.4 刷新环境变量并验证安装

安装完成后，执行以下命令刷新环境变量：

source ~/.bashrc

验证安装是否成功：

hermes doctor

若一切正常，会显示系统检查通过的提示。同时可运行 hermes --version 查看版本号（预期输出如 hermes v0.8.0）。

常见问题：若提示 hermes: command not found，请执行 source ~/.bashrc 重新加载 shell 配置，或手动添加 PATH：echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc。

四、配置 Hermes Agent

4.1 方法一：交互式配置向导（推荐新手）

运行配置向导：

hermes setup

向导会依次引导你完成以下步骤：

1. 选择 LLM provider（模型提供商）
2. 输入 API Key
3. 选择默认模型
4. 配置终端后端（local / docker / ssh）
5. 配置消息平台网关（可选）

4.2 支持的模型提供商

Provider	说明
OpenRouter	聚合 100+ 模型，一个密钥通吃，最推荐国内用户
OpenAI	GPT 系列模型直连
Anthropic	Claude 系列模型直连
Nous Portal	官方订阅服务，OAuth 登录
Custom endpoint	任意 OpenAI 兼容的自定义端点
阿里云 DashScope	国内用户直连通义千问等模型
MiniMax China	MiniMax-M2.7 等模型，支持国内直连

4.3 配置 API Key

方式一：在配置向导中输入（推荐）

在向导中按提示粘贴 API Key 即可，输入时屏幕不会显示任何字符。

方式二：通过命令行直接设置

# OpenRouter
hermes config set OPENROUTER_API_KEY "sk-or-v1-你的key"

# OpenAI
hermes config set OPENAI_API_KEY "sk-你的key"

# 智谱 GLM
hermes config set ZHIPUAI_API_KEY "你的key"

# MiniMax（国内节点）
hermes config set MINIMAX_API_KEY "你的key"

方式三：编辑配置文件

hermes config edit

密钥建议放在 ~/.hermes/.env 文件中，不要直接写入 config.yaml。

4.4 切换模型

如果想快速切换已有配置中的模型，使用简洁命令：

hermes model

在交互菜单中选择已有的 provider 和模型即可完成切换，无需重新运行完整 setup。

4.5 配置说明

Hermes Agent 有三个核心配置文件：

文件路径	作用
~/.hermes/config.yaml	主配置文件，存放模型选择、provider、base_url、终端后端、工具集等核心设置
~/.hermes/.env	环境变量文件，存放各类 API 密钥（权限自动设为 0600，仅所有者可读写）
~/.hermes/state.db	SQLite 数据库，存放跨会话的记忆和用户档案

五、基础使用

5.1 启动交互式对话

直接运行 hermes 即可进入交互式对话界面：

hermes

进入对话后，用自然语言直接下指令即可：

hermes ❯ 帮我整理一下桌面上的文件，按类型分类到对应文件夹
hermes ❯ 每天早上9点检查 Hacker News 上的 AI 新闻，发到 Telegram
hermes ❯ 帮我写一个爬取京东商品价格的 Python 脚本并运行

5.2 非交互式单次查询

如果只需一次回答后退出，使用 -q 参数：

hermes -q "什么是 Python 装饰器？"

5.3 指定模型运行

# 使用指定 provider 的特定模型
hermes -m openrouter/deepseek/deepseek-chat

# 示例：使用 Claude
hermes -m anthropic/claude-opus-4.6

5.4 对话内斜杠命令

在对话中可直接输入以下斜杠命令：

命令	说明
/skills	查看 Agent 积累的所有技能
/insights --days 7	查看最近 7 天的学习周报
/memory	查看持久记忆内容
/help	查看可用命令帮助

六、进阶使用

6.1 接入消息平台（Gateway）

Hermes Agent 支持接入多种主流通讯平台，让你随时随地通过日常聊天工具与 Agent 交互。

6.1.1 接入 Telegram（最常用）

1. 在 Telegram 中搜索 @BotFather，发送 /newbot 创建机器人，获取 Bot Token
2. 配置 Gateway：

   hermes gateway setup
   

3. 在渠道列表中选择 Telegram，输入 Bot Token
4. 启动 Gateway：

   hermes gateway start
   

5. 之后直接在 Telegram 里和你的 Agent 对话，支持跨平台上下文连续

6.1.2 接入飞书（Feishu）

飞书开放平台侧配置：

1. 访问 https://open.feishu.cn/，进入开发者后台
2. 创建企业自建应用，添加机器人能力
3. 在权限管理中添加 im:message 和 im:resource 权限
4. 记录 App ID 和 App Secret
5. 在"事件与回调"中选择订阅方式为"长连接"，添加事件 im.message.receive_v1
6. 发布应用

Hermes Agent 侧配置：

1. 启动 Gateway 配置向导：

   hermes gateway setup
   

2. 选择"飞书（Feishu）"，填写 App ID、App Secret
3. Domain 国内版填 feishu，Connection mode 选择 websocket
4. 启动 Gateway：

   hermes gateway start
   

6.2 设置定时任务

Hermes Agent 内置 Cron 调度器，支持以自然语言设置定时任务。在对话中直接输入即可：

hermes ❯ 每天早上8点给我推送今日天气
hermes ❯ 每周五下午5点生成本周工作总结并发送到 Telegram

也可以在配置文件中手动设置 cron 表达式。

6.3 工具集管理

查看所有可用工具及其启用状态：

hermes tools list

启用/禁用特定工具（以 CLI 平台为例）：

# 启用浏览器工具
hermes tools enable browser --platform cli

# 禁用浏览器工具
hermes tools disable browser --platform cli

# 为 Telegram 平台启用特定工具
hermes tools list --platform telegram

6.4 技能管理

查看已积累的技能：

hermes skills list

手动预加载技能：

# 在对话中预加载特定技能
hermes -s code_review -s web_search

6.5 从 OpenClaw 迁移

如果你之前使用过 OpenClaw，可以通过以下命令一键迁移：

hermes claw migrate

该命令会自动迁移 OpenClaw 的设置、记忆、技能和 API 密钥。

七、安全与隐私

7.1 安全机制

Hermes Agent 从设计之初就内置了六层纵深防护体系：

• 命令审批：检测到危险命令时，会提示用户确认（手动/智能审批）
• 容器隔离：支持通过 Docker 等容器后端运行，实现环境隔离
• 技能扫描：对执行的技能进行安全检查
• 数据加密：敏感信息加密存储
• 密钥脱敏：日志输出中自动隐藏 API 密钥
• 用户白名单：可配置允许访问的用户列表

7.2 危险命令审批模式

当检测到危险命令时，Hermes Agent 提供三种审批选择：

模式	说明
manual	始终提示用户确认（默认）
smart	辅助 LLM 评估风险，低风险自动批准，高风险提示确认
auto	绕过所有审批（需显式启用 --yolo 标志）

使用 --yolo 标志可绕过所有审批提示（慎用）：

hermes --yolo -q "删除 /tmp 目录下的所有临时文件"

7.3 推荐部署方式

官方建议将 Hermes Agent 部署在与个人主力电脑隔离的环境中，以保障数据安全。对于 Windows 用户，WSL2 已提供了一定程度的隔离；如需更高安全性，可考虑将 Agent 部署在云服务器上，实现 7×24 小时不间断运行。

八、命令行参考

所有命令遵循 hermes <subcommand> [flags] 模式。运行 hermes 不带参数时，启动交互式对话。

8.1 核心命令

命令	说明
hermes 或 hermes chat	启动交互式对话
hermes -q "查询内容"	非交互式单次查询
hermes -m <模型>	指定模型运行
hermes -s <技能名>	预加载指定技能
hermes --resume <会话ID>	恢复之前的会话
hermes --continue	恢复最近的会话

8.2 配置命令

命令	说明
hermes setup	运行交互式配置向导
hermes setup model	仅配置模型部分
hermes setup terminal	仅配置终端后端
hermes model	交互式选择模型提供商和默认模型
hermes config edit	编辑配置文件
hermes config set <key> <value>	设置配置项
hermes config list	查看当前所有配置
hermes doctor	诊断系统配置

8.3 工具与技能命令

命令	说明
hermes tools list	查看所有工具及其启用状态
hermes tools enable <工具名>	启用指定工具
hermes tools disable <工具名>	禁用指定工具
hermes skills list	查看已积累的技能

8.4 网关命令

命令	说明
hermes gateway setup	配置消息平台网关
hermes gateway start	启动网关
hermes gateway stop	停止网关
hermes gateway status	查看网关状态

8.5 其他命令

命令	说明
hermes doctor	系统诊断
hermes update	更新到最新版本
hermes claw migrate	从 OpenClaw 迁移
hermes --version	查看版本

九、常见问题与排障

9.1 hermes: command not found

根因：PATH 未刷新，而非安装失败

修复：

source ~/.bashrc
# 或手动添加 PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

9.2 API Key 认证失败

根因：Key 无效、格式错误，或配置了错误的 provider

修复：

# 查看当前配置
hermes config list

# 重新配置模型
hermes model

# 或直接设置正确的 Key
hermes config set OPENROUTER_API_KEY "sk-or-v1-你的key"

9.3 Gateway 启动后不回消息

排查步骤：

1. 确认 Gateway 状态：hermes gateway status
2. 查看日志：journalctl -u hermes-gateway -f（如配置了 systemd）
3. 检查 API Key 是否配置正确
4. 确认飞书/Telegram 侧的应用已发布

9.4 Python 版本不兼容

Hermes Agent 要求 Python 3.10 或更高版本。

# 检查当前 Python 版本
python3 --version

# 如版本过低，使用 pyenv 安装
curl https://pyenv.run | bash
pyenv install 3.11
pyenv global 3.11

9.5 国内网络访问 GitHub 过慢

使用镜像源安装：

git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git ~/.hermes/hermes-agent
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

9.6 内存不足导致 Agent 被终止

• 浏览器自动化需要至少 2GB 内存，推荐配置 4GB+ 内存
• 通过 .wslconfig 限制 WSL2 内存分配（见 2.3 节）

十、数据存储说明

所有 Hermes Agent 相关数据均存储在 ~/.hermes/ 目录下：

路径	说明
~/.hermes/config.yaml	主配置文件
~/.hermes/.env	API 密钥等环境变量
~/.hermes/state.db	持久化记忆数据库
~/.hermes/skills/	技能文件存储目录
~/.hermes/hermes-agent/	Agent 源码目录

备份建议：如更换设备或重装系统，备份整个 ~/.hermes/ 目录即可保留所有记忆和技能。

---

本文档基于 Hermes Agent 当前版本编写，项目仍在快速迭代中，建议定期运行 hermes update 获取最新功能。