Windows系统下安装Hermes Agent 智能体详细步骤
Windows 前置准备
Hermes Agent 原生支持 Windows(PowerShell、cmd、Windows Terminal),但推荐在 WSL2 上运行以获得完整体验。
安装 WSL2 + Ubuntu
-
以管理员身份打开 PowerShell,执行:
wsl --install
这将自动安装 WSL2 和默认的 Ubuntu 发行版。完成后重启电脑。 -
确认 WSL2 版本:
wsl --version wsl -l -v
确保默认版本是 2。如果不是:wsl --set-version Ubuntu 2
-
启动 Ubuntu:
wsl ~
首次启动会创建 Linux 用户和密码。 -
更新系统包:
sudo apt update && sudo apt upgrade -y
-
安装基础工具:
sudo apt install -y curl git build-essential python3 python3-pip
[boot] systemd=true然后在 PowerShell 中重启 WSL:wsl --shutdown && wsl ~
终端与 PowerShell 配置
推荐的 Windows 终端设置:
- 安装 Windows Terminal(Microsoft Store 免费)
- 将默认配置文件设为 Ubuntu(WSL)
- 在 Windows Terminal 设置中将 Alt+Enter 快捷键移除(它和 Hermes 的输入冲突)——改用 Ctrl+Enter 换行
键位说明
Windows Terminal 拦截 Alt+Enter 切换全屏,不会传给 Hermes。使用 Ctrl+Enter 代替 Alt+Enter 来在输入中插入换行。
如果你用 git-bash / mintty,Alt+Enter 同样被拦截。在 Options → Keys 中可关闭 Alt+Fn 快捷键。
安装 Hermes Agent
方法一:WSL2 / Linux 环境(推荐)
-
一键安装:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
-
验证安装:
hermes --version
-
启动交互式聊天:
hermes
方法二:PowerShell / Windows 原生
- 打开 PowerShell(建议管理员):
-
从 GitHub 下载手安装:
# 安装 Python 3.11+ winget install Python.Python.3.11 # 克隆仓库 git clone https://github.com/NousResearch/hermes-agent.git cd hermes-agent # 安装 python install.py
- 添加环境变量,将%USERPROFILE%\.local\bin加入 PATH。
-
运行:
hermes
运行体检
安装完成后,运行以下命令检查环境和依赖:
hermes doctor
会自动检查:Python 版本、依赖完整性、Git 配置、系统环境变量等。遇到缺失项它会给出修复建议。自动修复请加:
hermes doctor --fix
选择模型与 Provider
Hermes 支持 20+ 模型提供商,这是它最大的优势之一——你可以在不同任务间随意切换模型,无需改变任何其他配置。
支持的 Providers 一览
| Provider | 认证方式 | 环境变量 |
|---|---|---|
| OpenRouter | API Key | OPENROUTER_API_KEY |
| Anthropic (Claude) | API Key | ANTHROPIC_API_KEY |
| OpenAI | API Key | OPENAI_API_KEY |
| DeepSeek | API Key | DEEPSEEK_API_KEY |
| Google Gemini | API Key | GOOGLE_API_KEY |
| GitHub Copilot | OAuth | hermes login |
| xAI / Grok | API Key | XAI_API_KEY |
| 本地模型 | 自定义端点 | model.base_url配置 |
| 智谱 GLM | API Key | GLM_API_KEY |
| 阿里 DashScope | API Key | DASHSCOPE_API_KEY |
| Kimi/Moonshot | API Key | KIMI_API_KEY |
| 小米 MiMo | API Key | XIAOMI_API_KEY |
| MiniMax | API Key | MINIMAX_API_KEY |
| Hugging Face | Token | HF_TOKEN |
配置模型
交互式选择模型和 Provider:
hermes model
或者通过 setup 向导:
hermes setup model
单次运行指定模型:
hermes chat -m "anthropic/claude-sonnet-4" -q "解释量子计算" hermes --model "deepseek-chat" chat
Credential Pools — API 密钥轮换
可以为同一个 Provider 配置多个 API Key,自动轮换和故障转移:
hermes auth add # 交互式添加凭证 hermes auth list openrouter # 查看所有 OpenRouter Key hermes auth remove openrouter 1 # 删除指定索引
当一个 Key 被限流或耗尽后,自动切换到下一个。
配置文件详解
核心配置文件位置:
~/.hermes/config.yaml # 主配置 ~/.hermes/.env # API Key 等敏感信息
查看和编辑配置:
hermes config # 查看当前配置 hermes config edit # 在编辑器中打开 hermes config path # 打印配置路径 hermes config env-path # 打印 .env 路径 hermes config set section.key value # 设置某个值
配置结构
| 配置段 | 常用键 | 说明 |
|---|---|---|
| model | default,provider,base_url | 模型和 Provider 设置 |
| agent | max_turns(90) | 单轮对话最大工具调用次数 |
| terminal | backend,timeout(180) | 终端后端(local/docker/ssh) |
| compression | threshold,target_ratio | 上下文压缩策略 |
| display | skin,tool_progress | 界面主题和显示选项 |
| memory | memory_enabled,provider | 持久记忆设置 |
| security | tirith_enabled | 安全扫描设置 |
| delegation | model,max_iterations | 子任务委派配置 |
| stt | provider(local/groq/openai) | 语音转文字 |
| tts | provider(edge/elevenlabs/...) | 文字转语音 |
API Keys 配置
.env文件存放所有敏感凭据。以你使用 DeepSeek 为例:
# ~/.hermes/.env DEEPSEEK_API_KEY=sk-your-key-here OPENROUTER_API_KEY=sk-or-your-key-here # 仅在需要时添加以下内容 ANTHROPIC_API_KEY=sk-ant-your-key OPENAI_API_KEY=sk-proj-your-key GOOGLE_API_KEY=AIza-your-key
SOUL.md — 给智能体写入灵魂
SOUL.md 是 Hermes 最强大的自定义功能之一。它定义智能体的身份、性格、价值观、行为规范。写入 SOUL.md 后,每次对话智能体都会以此身份与你互动。
SOUL.md 位置
~/.hermes/SOUL.md # 默认 Profile 的 SOUL ~/.hermes/profiles/<名称>/SOUL.md # 特定 Profile 的 SOUL
SOUL.md 示例
# 角色定义 你是一位务实的资深全栈工程师,拥有 10 年以上架构设计与系统运维经验。 逻辑缜密、技术洁癖、极简务实、拒绝废话。 遇事先定位根因,再给可直接执行方案。 # 核心能力 - 精通前后端:Python/Java/Go/Node/数据库/架构/分布式/高并发 - 精通 Linux/WSL 运维、报错排查、环境配置 - 精通 AI Agent 框架与本地模型部署 # 行为准则 - 不闲聊、不绕弯,直击问题根因 - 先判断环境 → 定位报错 → 给出原因 → 分步方案 - 只给可复制执行的命令和代码 - 能极简绝不复杂,能自动化绝不手动 # 对话风格 冷静理性、言简意赅、句句干货,不煽情、不废话。
应用 SOUL.md
写入文件后,下次新会话自动生效:
# 创建 SOUL.md echo "你是一位幽默风趣的创意助手" > ~/.hermes/SOUL.md # 开始新会话 hermes # 或在已有会话中 /reset
Personality 预设
Hermes 内置了几种 Personality 预设,可通过界面快速切换:
/personality [name]
也可以用hermes setup agent选择。Personality 是一种简化的身份配置,而 SOUL.md 是更深度、更灵活的自定义方案。
Profiles — 运行多个独立 Agent
Profiles 是 Hermes 的多智能体方案。每个 Profile 拥有完全独立的:配置文件、会话记录、技能库、记忆、SOUL.md、API 密钥。
创建新 Profile
# 交互式创建 hermes profile create 名称 # 克隆默认 Profile 的所有配置 hermes profile create 名称 --clone # 只克隆配置和技能(不克隆会话/记忆) hermes profile create 名称 --clone-all # 从指定 Profile 克隆 hermes profile create 名称 --clone-from 源名称
管理 Profiles
hermes profile list # 列出所有 Profile hermes profile show 名称 # 查看详细 hermes profile use 名称 # 设为默认 hermes profile delete 名称 # 删除 hermes profile rename 旧名 新名 # 重命名 hermes profile export 名称 # 导出为 tar.gz hermes profile import 文件 # 导入 Profile
为 Profile 生成启动脚本
hermes profile alias 名称 # 生成 ~/.local/bin/名称 脚本 # 之后就可以直接运行:名称
使用指定 Profile 运行
hermes -p 名称 # 使用指定 Profile 名称 # 如果创建了 alias
多 Agent 分工方案
| Profile | 角色 | 模型 | SOUL.md |
|---|---|---|---|
| default | 日常助手 | deepseek-v4-flash | 通用全能 |
| coder | 资深架构师 | claude-sonnet-4 | 技术专家 |
| writer | 内容创作 | gpt-4o | 创意写手 |
| ops | 运维排查 | deepseek-v4-pro | 故障诊断专家 |
| researcher | 深度研究 | gemini-2.5-pro | 学术分析 |
进程级独立实例
除了 Profiles,还可以启动完全独立的 Hermes 进程作为子进程运行——每个拥有自己的会话、工具和环境。
一次性任务
# 后台运行一个独立任务 hermes chat -q '调研 GRPO 论文并写入 ~/research/grpo.md' & # 或者用 tmux 运行交互式实例 tmux new-session -d -s agent1 'hermes -p coder' sleep 8 tmux send-keys -t agent1 '写一个 FastAPI 用户认证服务' Enter
多 Agent 并行协作
# Agent A: 后端 tmux new-session -d -s backend 'hermes -p coder' sleep 8 tmux send-keys -t backend '构建用户管理 REST API' Enter # Agent B: 前端 tmux new-session -d -s frontend 'hermes -p writer' sleep 8 tmux send-keys -t frontend '构建 React 用户管理仪表盘' Enter # 在它们之间传递上下文 tmux send-keys -t frontend '后端 API 如下:...' Enter
Kanban 协作
Hermes 内置看板系统,让多个 Profile / 多个智能体通过一个共享看板协作:
hermes kanban init # 初始化看板 hermes kanban create "开发用户登录模块" hermes kanban list # 查看任务列表 hermes kanban assign 1 coder # 指派给 coder Profile
被指派的 Profile 在启动时自动获取任务上下文,完成后在看板更新状态。
Gateway 架构
Gateway 是 Hermes 的消息网关。它将同一个智能体实例连接到多个消息平台——你在 Telegram 上发一条消息,Hermes 在服务器上处理,结果回到 Telegram。所有平台共享同一个会话上下文。
用户 [Telegram] \
用户 [Discord] |---> Gateway ---> Agent ---> LLM
用户 [Slack] / | └─> Tools
Logs └─> Skills
管理 Gateway
hermes gateway run # 前台启动 hermes gateway install # 安装为后台服务 hermes gateway start # 启动服务 hermes gateway stop # 停止 hermes gateway restart # 重启 hermes gateway status # 查看状态 hermes gateway setup # 配置平台
接入消息平台
Gateay Setup 支持多种平台。以下是最常用的三种。
Telegram
- 在 Telegram 中搜索 @BotFather,发送/newbot,按提示创建 Bot,获得 Token。
- 运行hermes gateway setup,选择 Telegram,填入 Token。
- 配置完成后启动 Gateway:hermes gateway start。
- 在 Telegram 中搜索你的 Bot 用户名,发送/start。
或直接手动修改配置文件:
# config.yaml
gateway:
platforms:
telegram:
enabled: true
token: "你的BOT_TOKEN"
Discord
- 前往 Discord Developer Portal。
- 创建 Application → Bot → 获取 Token。
- 在 Bot 设置中开启 Message Content Intent。
- 在 OAuth2 → URL Generator 中选择bot权限,生成邀请链接。
- 用链接将 Bot 邀请到你的服务器。
- 在 Hermes 中配置:hermes gateway setup→ Discord。
Slack
- 前往 Slack API 创建 App。
- 添加 Bot Token Scopes:chat:write,im:history,channels:history,groups:history。
- 订阅 Events:message.im,message.channels。
- 安装 App 到工作区,获取 Bot Token。
- 配置:hermes gateway setup→ Slack。
Hermes Web UI — 可视化仪表盘
Hermes Web UI 是一个独立的前端界面,基于 Vue 3 构建,提供多模型聊天、终端访问、文件管理、会话历史等功能。它作为 Node.js BFF(Backend For Frontend)服务运行。
安装
# 全局安装 npm install -g hermes-web-ui # 或使用 yarn yarn global add hermes-web-ui # 验证安装 hermes-web-ui -v
启动
hermes-web-ui start # 后台启动(守护进程) hermes-web-ui start --port 9000 # 自定义端口 hermes-web-ui status # 查看运行状态 hermes-web-ui stop # 停止 hermes-web-ui restart # 重启 hermes-web-ui update # 更新到最新版并重启
自动配置
启动时,BFF 服务器会自动:
- 检查并补全~/.hermes/config.yaml中的api_server段
- 备份原始配置到config.yaml.bak(如果修改过)
- 自动检测并启动 Hermes Gateway(如果需要)
- 解决端口冲突(杀死残留进程)
- 启动成功后自动打开浏览器
Web UI 功能
- 多模型对话 — 在同一界面切换不同 Provider 的模型
- 终端访问 — 浏览器内终端
- 文件管理 — 浏览、上传、下载服务器文件
- 会话历史 — 查看、搜索、恢复历史会话
- 群组聊天 — 群聊支持
端口冲突排查
hermes-web-ui stop && hermes-web-ui start # 干净重启 hermes-web-ui start --port 9000 # 换端口 tail -20 ~/.hermes-web-ui/logs/server.log # 查看日志 ps aux | grep hermes-web-ui # 检查残留进程
Skills — 技能系统
Skills 是 Hermes 最独特的功能——智能体从经验中学习,把可复用的工作流程保存为 Skills 文档。每次解决复杂问题或发现新工作流后,Hermes 可以将其持久化为技能,在后续会话中自动加载。
Skill 生命周期
# 查看已安装的技能 hermes skills list # 浏览可安装的技能库 hermes skills browse # 搜索技能 hermes skills search "flask" # 安装技能(从 Hub) hermes skills install 技能ID # 安装技能(从 URL) hermes skills install https://example.com/SKILL.md --name my-skill # 加载技能到会话 /skill 技能名称 # 启动时预加载技能 hermes -s 技能名称
Curator — 技能自动维护
Hermes 内置 Curator 后台,自动管理智能体创建的技能:
/curator status # 查看 Curator 状态 /curator run # 运行一次维护 /curator pin 技能名 # 锁定技能不被自动清理 /curator unpin 技能名 # 解锁
Memory — 持久记忆
Hermes 跨会话记住你是谁、你的偏好和环境细节。支持多种记忆后端。
hermes memory setup # 配置记忆后端 hermes memory status # 查看记忆状态 hermes memory off # 关闭记忆 # 配置记忆 hermes config set memory.memory_enabled true hermes config set memory.provider builtin # 内置记忆
支持的记忆后端:内置 SQLite、Honcho、Mem0 等。
Cron — 定时任务
让 Hermes 按计划自动执行任务,无人值守。支持一次性定时、重复任务、多平台送达。
hermes cron list # 查看所有任务 hermes cron create "30m" # 每30分钟执行一次 hermes cron create "0 9 * * *" # 每天9点执行(cron 格式) hermes cron create "every monday 9am" # 每周一9点 # 创建带技能的定时任务 hermes cron create "2h" \ --skills "research-paper-writing" \ --prompt "检查 arXiv 论文更新并总结" hermes cron pause 任务ID # 暂停 hermes cron resume 任务ID # 恢复 hermes cron remove 任务ID # 删除
Cron 任务示例
- 每 30 分钟检查一次服务器状态
- 每天早晨 8 点推送 Hacker News 精选摘要到 Telegram
- 每周一自动代码审查和报告
- 每小时监控磁盘空间,超过阈值自动告警
Delegation — 任务委派
Hermes 可以委派子任务给子 Agent 并行执行,每个子 Agent 有独立的上下文和工具集。
# 单任务委派
delegate_task(
goal="分析这个 API 的性能瓶颈",
context="...",
toolsets=["terminal", "file"]
)
# 并行批处理
delegate_task(tasks=[
{goal: "分析前端性能", context: "...", toolsets: ["terminal"]},
{goal: "扫描后端日志", context: "...", toolsets: ["terminal"]},
{goal: "检查数据库慢查询", context: "...", toolsets: ["terminal"]}
])
| delegate_task | 独立进程 spawn | |
|---|---|---|
| 隔离程度 | 独立会话,共享进程 | 完全独立进程 |
| 持续时间 | 分钟级(受限) | 小时/天数 |
| 并行能力 | 最多 3 个(可配) | 无上限 |
| 交互 | 否 | 是(PTY/Tmux) |
| 适用场景 | 快速并行子任务 | 长期自主任务 |
MCP 服务器
Hermes 原生支持 MCP(Model Context Protocol),可以连接外部 MCP 服务器扩展能力:
# Hermes 作为 MCP Server hermes mcp serve # 添加外部 MCP Server hermes mcp add my-server \ --url http://localhost:8000 # 或通过命令启动 hermes mcp add my-tools \ --command "node my-mcp-server.js" hermes mcp list # 列出所有 MCP Server hermes mcp remove my-server # 删除 hermes mcp test my-server # 测试连接 hermes mcp configure my-server # 启禁用工具
CLI 命令速查
会话管理
hermes # 启动交互式聊天 hermes chat -q "查询" # 一次性查询 hermes --continue # 恢复最近会话 hermes --resume 会话ID # 恢复指定会话
Profile 管理
hermes profile list # 列出所有 Profile hermes profile create 名称 # 创建 hermes profile use 名称 # 设为默认 hermes profile show 名称 # 查看详情 hermes profile delete 名称 # 删除
配置
hermes setup # 交互式向导 hermes model # 选模型 hermes config # 查看配置 hermes config set section.key value # 设置 hermes config edit # 编辑 hermes doctor # 检查健康
Gateway
hermes gateway run # 前台运行 hermes gateway start/stop # 启停服务 hermes gateway setup # 配置平台 hermes gateway status # 状态
Slash 命令
在交互式会话中直接使用:
| 命令 | 用途 |
|---|---|
| /new或/reset | 新会话 |
| /model [名称] | 切换模型 |
| /personality [名称] | 设置人格 |
| /retry | 重新发送上一条 |
| /undo | 撤销上一轮 |
| /compress | 压缩上下文 |
| /skill 名称 | 加载技能 |
| /reload-skills | 重新扫描技能目录 |
| /reload | 重载 .env 变量 |
| /save | 保存会话到文件 |
| /image | 附加本地图片 |
| /voice on|off|tts | 语音模式 |
| /yolo | 跳过危险命令确认 |
| /stop | 终止后台进程 |
| /help | 查看所有命令 |
| /usage | Token 使用量 |
| /profile | 当前 Profile 信息 |
| /quit或/exit | 退出 |
工具集管理
Hermes 内置丰富的工具集,可以根据需要启禁用:
hermes tools # 交互式管理 hermes tools list # 列出所有工具 hermes tools enable 工具集名称 # 启用 hermes tools disable 工具集名称 # 禁用
| 工具集 | 功能 |
|---|---|
| web | 网页搜索和内容抓取 |
| browser | 浏览器自动化 |
| terminal | Shell 命令和执行 |
| file | 文件读写、搜索、编辑 |
| code_execution | 沙箱 Python 执行 |
| vision | 图片分析 |
| image_gen | AI 图片生成 |
| memory | 持久记忆 |
| session_search | 历史会话搜索 |
| delegation | 子任务委派 |
| cronjob | 定时任务 |
| skills | 技能管理 |
| spotify | Spotify 播放控制 |
| homeassistant | 智能家居控制 |
语音与转录
语音输入 (STT)
消息平台上的语音消息自动转录:
hermes config set stt.enabled true hermes config set stt.provider local # local/groq/openai/mistral
Provider 优先级:
- local (faster-whisper) — 免费,需pip install faster-whisper
- Groq Whisper — 免费额度,设GROQ_API_KEY
- OpenAI Whisper — 付费
- Mistral Voxtral — 付费
语音输出 (TTS)
# 在会话中切换语音模式 /voice on # 语音对话(你说它听,它说你也听) /voice tts # 仅语音输出 /voice off # 关闭语音
支持的 TTS Provider:
- Edge TTS(默认,免费)
- ElevenLabs(API Key:ELEVENLABS_API_KEY)
- OpenAI TTS
- MiniMax、Mistral Voxtral
- NeuTTS(本地,需pip install neutts[all])
安全与隐私
密钥抹除
# 自动抹除工具输出中的 API Key 等敏感信息 hermes config set security.redact_secrets true # 关闭 hermes config set security.redact_secrets false
PII 脱敏
对 Gateway 消息中的用户 ID 和电话号码进行哈希/脱敏:
hermes config set privacy.redact_pii true # 开启 hermes config set privacy.redact_pii false # 关闭命令审批
# manual: 高危命令总是提示确认(默认) # smart: 辅助 LLM 自动审批低风险命令 # off: 跳过所有审批 hermes config set approvals.mode smart # 推荐 hermes config set approvals.mode off # 不推荐 hermes --yolo # 一次性跳过常见问题排查
语音不工作
- 检查stt.enabled: true
- 验证 Provider:安装faster-whisper或设置 API Key
- Gateway 用户:/restart;CLI 用户:退出重进
400电话办理