Hermes Agent 完全指南：安装部署、双入口使用与内置学习闭环的源码级解读

本文基于 hermes-agent 仓库的主 README 与配套源码，系统讲解这个由 Nous Research 开发的"自我改进 AI Agent"的完整落地路径：从 Linux/macOS/Windows 两种平台的一键安装、核心 CLI 命令、模型提供方切换、消息网关（Telegram/Discord/Slack 等）接入，到 OpenClaw 迁移，并结合仓库源码剖析其学习闭环（技能自动维护、跨会话记忆检索）的实现机制。读完后你可以独立完成 Hermes Agent 的部署、配置、迁移，并理解其"窄核心 + 边缘扩展"的架构设计依据。

1. 项目定位：一个带内置学习循环的个人 AI Agent

Hermes Agent 的自我定位是"The agent that grows with you"（与你共同成长的 Agent）。README 的核心论点是：它是唯一一个把学习闭环做进内核的 Agent——从经验中创建技能、在使用过程中改进技能、自我提示去持久化知识、检索自己的历史会话、并跨会话构建对你这个人的不断加深的模型。它的部署弹性也很突出：可以跑在一台 5 美元的 VPS 上、GPU 集群上，或近乎零成本空闲计费的 serverless 基础设施上；它不绑定你的笔记本，你可以在 Telegram 上跟它对话，而它正在云端 VM 上干活。

README 中给出的能力清单（表格形式，原文完整保留语义）如下：

能力	说明
真正的终端界面	完整 TUI，支持多行编辑、斜杠命令自动补全、会话历史、中断并转向、流式工具输出
驻留在你所驻留的平台	Telegram、Discord、Slack、WhatsApp、Signal 与 CLI，全部来自单个 gateway 进程；支持语音消息转写与跨平台会话连续性
闭环学习循环	Agent 自管的记忆与周期性 nudge（提示）；复杂任务后自主创建技能；技能在使用中自我改进；基于 FTS5 的会话检索配合 LLM 摘要实现跨会话召回；兼容 agentskills.io 开放标准
计划自动化	内置 cron 调度器，可投递到任意平台。日报、夜间备份、每周审计——全部用自然语言配置，无人值守运行
委派与并行	派生隔离的子 Agent 做并行工作流；编写通过 RPC 调用工具的 Python 脚本，把多步流水线压缩成零上下文成本的回合
随处运行，不只是你的笔记本	七种终端后端——local、Docker、SSH、Singularity、Modal、Daytona、Vercel Sandbox；Daytona 与 Modal 提供 serverless 持久化，环境空闲时休眠、按需唤醒
研究就绪	批量轨迹（trajectory）生成、轨迹压缩，用于训练下一代工具调用模型

模型方面，README 明确它支持任意模型——Nous Portal、OpenRouter、OpenAI、自建端点及其他——切换只需一条命令：

hermes model    # 更换 LLM 提供方与模型，无需改代码，无锁定

1.1 从源码结构看它的架构分界

仓库根目录的 AGENTS.md（开发者指南）揭示了塑造其所有设计决策的两条原则：

1. 按会话的 prompt 缓存是神圣的——长会话每轮复用缓存前缀，任何修改历史上下文、中途换工具集、重建系统提示的行为都会击穿缓存并放大用户成本，内核中唯一的例外是上下文压缩；
2. 核心是"窄腰"，能力在边缘——每新增一个模型工具都会随每次 API 调用发出，所以核心工具门槛极高，新能力优先以"CLI 命令 + 技能"、服务门控工具（check_fn）或插件形式落地。

从目录结构看，这套原则是可见的：agent/ 目录容纳了提供方适配器（anthropic_adapter.py、bedrock_adapter.py、gemini_native_adapter.py 等）、记忆（memory_manager.py、memory_provider.py）、压缩与缓存（context_compressor.py、prompt_caching.py、native_compaction.py）等内部机制；apps/desktop/ 是 Electron 桌面端，apps/bootstrap-installer/ 是 Tauri 引导安装器，acp_adapter/ 提供 ACP 协议服务器用于 IDE 集成。

2. 快速安装

2.1 Linux / macOS / WSL2 / Termux

官方推荐的一键安装：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Android/Termux 用户注意：README 指出完整 .[all] extra 目前会拉入与 Android 不兼容的语音依赖，因此 Termux 上 Hermes 会安装精选的 .[termux] extra；手动路径见官方 Termux 指南。

2.2 Windows 原生（PowerShell）

Windows 原生运行无需 WSL——CLI、gateway、TUI 与工具全部原生可用。在 PowerShell 中执行：

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

安装器负责处理一切依赖：uv、Python 3.11、Node.js、ripgrep、ffmpeg，以及一个便携版 Git Bash（MinGit，解压到 %LOCALAPPDATA%\hermes\git——不需要管理员权限，与系统已装的 Git 完全隔离）。Hermes 使用这个捆绑的 Git Bash 来执行 shell 命令。如果你已经装了 Git，安装器会检测到并改用你现有的；否则只需下载约 45MB 的 MinGit，不会触碰或干扰任何系统 Git。

2.3 安装后启动

source ~/.bashrc    # 重新加载 shell（zsh 用户：source ~/.zshrc）
hermes              # 开始对话

安装位置因平台而异：原生 Windows 安装在 %LOCALAPPDATA%\hermes 下，Linux/WSL2 安装在 ~/.hermes 下。

2.4 故障排查：杀毒软件误报 uv.exe

README 专节处理了一个高频问题：Windows Defender、Bitdefender 等把 Hermes bin 目录（%LOCALAPPDATA%\hermes\bin\uv.exe）下的 uv.exe 当木马隔离。这是误报——该文件是 Astral 的 uv（Rust 编写的 Python 包管理器），ML 引擎经常误标"会下载并安装包的未签名 Rust 二进制"。

官方给出的验证流程（PowerShell，完整保留）：

# Install GitHub CLI if needed
winget install --id GitHub.cli

# Login to GitHub
gh auth login

# Run verification
$uv = "$env:LOCALAPPDATA\hermes\bin\uv.exe"
$ver = (& $uv --version).Split(' ')[1]
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$zip = "$env:TEMP\uv.zip"
Invoke-WebRequest "https://github.com/astral-sh/uv/releases/download/$ver/uv-x86_64-pc-windows-msvc.zip" -OutFile $zip -UseBasicParsing
gh attestation verify $zip --repo astral-sh/uv
Expand-Archive $zip "$env:TEMP\uv_x" -Force
(Get-FileHash "$env:TEMP\uv_x\uv.exe").Hash -eq (Get-FileHash $uv).Hash

若 attestation 输出 "Verification succeeded" 且最后一行打印 True，即可确认文件真实。白名单化建议（注意白名单要加目录而不是文件哈希——Hermes 会更新 uv，哈希每版都在变）：

• Windows Defender：以管理员运行 PowerShell，执行 Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\hermes\bin"
• Bitdefender：在控制台 Protection > Antivirus > Settings > Manage Exceptions 中添加例外

3. 核心命令速查：Getting Started

README 给出的入门命令集（原表完整保留）：

hermes              # 交互式 CLI —— 开始对话
hermes model        # 选择 LLM 提供方与模型
hermes tools        # 配置启用哪些工具
hermes config set   # 设置单个配置项
hermes config get   # 打印单个配置项
hermes gateway      # 启动消息网关（Telegram、Discord 等）
hermes setup        # 运行完整设置向导（一次配好所有东西）
hermes claw migrate # 从 OpenClaw 迁移（如果来自 OpenClaw）
hermes update       # 更新到最新版本
hermes doctor       # 诊断问题

配置文件的组织方式在源码中有明确依据：仓库的 .env.example 文件头注释写明"Copy this file to .env and fill in your API keys"，而 AGENTS.md 进一步规定了一条纪律——.env 只放密钥（API key、token、密码），所有行为性设置（超时、阈值、特性开关、显示偏好）一律进 ~/.hermes/config.yaml；config.yaml 的顶层分区包括 model、agent、terminal、compression、display、stt、tts、memory、security、delegation、cron、profiles、plugins、honcho 等。从 .env.example 的分区注释可以确认它覆盖的提供方范围相当宽：Fireworks、OpenRouter、NovitaAI、Google AI Studio/Gemini、Ollama Cloud、z.ai/GLM、Kimi/Moonshot（含中国区 key 与 base URL 覆盖）、MiniMax、Hugging Face Inference Providers 等 LLM 提供方，以及 FIRECRAWL_API_KEY（网页搜索）、FAL_KEY（图像生成）、BROWSERBASE_API_KEY（云浏览器）、OPENAI_API_KEY（语音转写与 TTS）、ELEVENLABS_API_KEY（云 STT/TTS）等工具密钥，并带 BROWSER_SESSION_TIMEOUT=300、BROWSER_INACTIVITY_TIMEOUT=120、HERMES_HUMAN_DELAY_MODE 等可调参数。

4. 免 API-key 收集：Nous Portal

Hermes 保持"任意提供方"这一基本盘不变，但如果你不想为模型、网页搜索、图像生成、TTS、云浏览器分别收集五份 API key，README 推荐 Nous Portal 一个订阅打包覆盖全部：

• 300+ 模型——任选其一，用 /model <name> 切换
• Tool Gateway——网页搜索（Firecrawl）、图像生成（FAL）、文本转语音（OpenAI）、云浏览器（Browser Use）全部经由你的订阅路由，无需额外账号

全新安装后一条命令即可：

hermes setup --portal

该命令会通过 OAuth 登录、把 Nous 设为你的提供方、并打开 Tool Gateway。随时可用 hermes portal info 检查当前接入了什么。README 特别强调：网关是按后端生效的（per-backend），不是全有或全无——你仍可以为任意单个工具自带 key。

5. CLI vs 消息平台：双入口速查表

Hermes 有两个入口：用 hermes 启动终端 UI，或运行 gateway 后从 Telegram、Discord、Slack、WhatsApp、Signal 或 Email 与它对话。进入会话后，许多斜杠命令在两种界面间是共享的。README 的对照表（完整保留）：

动作	CLI	消息平台
开始聊天	hermes	运行 hermes gateway setup + hermes gateway start，然后给机器人发消息
开新会话	/new 或 /reset	/new 或 /reset
切换模型	/model [provider:model]	/model [provider:model]
设置人格	/personality [name]	/personality [name]
重试或撤销上一轮	/retry、/undo	/retry、/undo
压缩上下文 / 查看用量	/compress、/usage、/insights [--days N]	/compress、/usage、/insights [days]
浏览技能	/skills 或 /<skill-name>	/<skill-name>
中断当前工作	Ctrl+C 或发送新消息	/stop 或发送新消息
平台特定状态	/platforms	/status、/sethome

值得从源码结构补充的一点：AGENTS.md 说明所有斜杠命令都定义在 hermes_cli/commands.py 的集中式 COMMAND_REGISTRY 中，CLI 派发、gateway 派发、Telegram BotCommand 菜单、Slack 子命令映射、自动补全都从这一个注册表自动派生——这就是同一批命令能在两个入口无缝共享的原因。

6. 学习闭环的源码级解读

README 宣称的"学习闭环"在仓库中不是营销空话，源码可以逐条对应：

（1）技能后台维护：curator。 agent/curator.py 的模块 docstring 完整描述了这一机制：curator 是一个辅助模型任务，周期性审查 Agent 自建的技能并维护整个技能集合；它采用空闲触发而非 cron 守护进程——当 Agent 空闲且上次运行早于 interval_hours 时，maybe_run_curator() 派生一个 forked AIAgent 执行审查。其 docstring 还声明了严格的不变式：只碰 Agent 自建的技能、永不自动删除（只归档，归档可恢复）、被 pin 的技能绕过所有自动迁移、使用辅助客户端、绝不触碰主会话的 prompt 缓存。配置项对应 AGENTS.md 中记载的 config.yaml 的 curator 分区：enabled、interval_hours、min_idle_hours、stale_after_days、archive_after_days 及嵌套的 backup。

（2）跨会话记忆与用户画像。 README 提到"Agent-curated memory with periodic nudges"与"FTS5 session search with LLM summarization"。从 AGENTS.md 的项目结构看，hermes_state.py 中的 SessionDB 是 SQLite 会话存储（含 FTS5 全文索引），这对应 README 所称的 FTS5 会话检索；记忆后端则是插件化的——plugins/memory/ 下有 honcho、mem0、supermemory 等多个内置提供方，各自实现 agent/memory_provider.py 中的 MemoryProvider 抽象基类（生命周期钩子包括 sync_turn、prefetch、shutdown），由 agent/memory_manager.py 编排，通过 config.yaml 的 memory.provider 激活。

（3）技能即程序性记忆。 仓库内置技能位于 skills/，重量级/小众技能位于 optional-skills/（通过 hermes skills install official/<category>/<skill> 显式安装）。技能斜杠命令的注入方式在 agent/skill_commands.py 中：技能扫描 ~/.hermes/skills/ 后以用户消息（而非系统提示词）注入，这正是 AGENTS.md 第一条"prompt 缓存神圣"原则的直接落地。

（4）辅助 LLM 分账。 记忆审查、标题生成、视觉理解等旁路任务不必占用主会话的模型——AGENTS.md 记载 config.yaml 的 auxiliary 分区允许每类任务（curator、vision、embedding、title generation、session_search 等）单独固定 provider/model/base_url/max_tokens/reasoning_effort，解析顺序见 agent/auxiliary_client.py 的 _resolve_auto。

7. 从 OpenClaw 迁移

如果你来自 OpenClaw，Hermes 可以自动导入你的设置、记忆、技能与 API key：

• 首次设置时：设置向导（hermes setup）会自动检测 ~/.openclaw，并在配置开始前提供迁移选项；
• 安装后的任意时间：

hermes claw migrate              # 交互式迁移（完整预设）
hermes claw migrate --dry-run    # 预览将要迁移的内容
hermes claw migrate --preset user-data   # 不迁移密钥
hermes claw migrate --overwrite  # 覆盖已存在的冲突项

导入清单（README 原列表完整保留）：

• SOUL.md——人格文件
• Memories——MEMORY.md 与 USER.md 条目
• Skills——用户自建技能 → ~/.hermes/skills/openclaw-imports/
• Command allowlist——命令审批模式
• Messaging settings——平台配置、允许的用户、工作目录
• API keys——白名单内的密钥（Telegram、OpenRouter、OpenAI、Anthropic、ElevenLabs）
• TTS assets——工作区音频文件
• Workspace instructions——AGENTS.md（配合 --workspace-target）

完整选项见 hermes claw migrate --help；也可以用 openclaw-migration 技能进行带 dry-run 预览的 Agent 引导式交互迁移。

8. 安全模型：唯一承重边界是操作系统

理解 Hermes 的部署安全姿态，推荐结合仓库的 SECURITY.md（README 文档索引中的 Security 章节对应物）。该文档开宗明义：对抗恶意 LLM 的唯一安全边界是操作系统——进程内的审批门、输出脱敏、模式扫描器、工具白名单都不构成隔离，任何检查 LLM 输出的进程内组件都只是"作用于攻击者可影响字符串上的启发式"。它支持两种 OS 级隔离姿态：

1. 终端后端隔离——非默认终端后端把 LLM 发出的 shell 命令跑在容器、远程主机或云沙箱里（对应 README 中 Docker/SSH/Modal/Daytona/Singularity 等七种后端）；文件工具（read_file、write_file、patch）也经由该后端运行，因此触碰不到后端未暴露的路径。但它不约束 Agent 自身 Python 进程内的一切（代码执行工具、MCP 子进程、插件加载等）；
2. 整进程包裹——把整个 Agent 进程树放进沙箱，官方 Docker 镜像与 Compose 即支持此姿态。

这一"按威胁选隔离层级"的分层模型，与 README 中"Runs anywhere"能力章节是同一枚硬币的两面。

9. 文档索引

官方文档站点为 hermes-agent.nousresearch.com/docs，README 给出的章节索引（内容完整保留，外链从略）：

章节	覆盖内容
Quickstart	安装 → 设置 → 2 分钟内完成第一次对话
CLI Usage	命令、快捷键、人格、会话
Configuration	配置文件、提供方、模型、所有选项
Messaging Gateway	Telegram、Discord、Slack、WhatsApp、Signal、Home Assistant
Security	命令审批、DM 配对、容器隔离
Tools & Toolsets	40+ 工具、工具集系统、终端后端
Skills System	程序性记忆、Skills Hub、创建技能
Memory	持久记忆、用户画像、最佳实践
MCP Integration	接入任意 MCP 服务器扩展能力
Cron Scheduling	带平台投递的计划任务
Context Files	塑造每次对话的项目上下文
Architecture	项目结构、Agent 循环、关键类
Contributing	开发环境搭建、PR 流程、代码风格
CLI Reference	全部命令与标志
Environment Variables	完整环境变量参考

10. 贡献者上手

仓库欢迎贡献（完整规范见 CONTRIBUTING.md 与 AGENTS.md）。README 给出的贡献者快速路径是：使用标准安装器，然后在其创建的完整 git checkout（$HERMES_HOME/hermes-agent，通常 ~/.hermes/hermes-agent）中开发——这个布局与 hermes update、托管 venv、懒加载依赖、gateway 和文档工具一致：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
cd "${HERMES_HOME:-$HOME/.hermes}/hermes-agent"
uv pip install -e ".[all,dev]"
scripts/run_tests.sh

手动 clone 的回退路径（用于一次性 clone/CI 等刻意不想用托管安装布局的场景）——注意 README 特意强调 venv 要建在源码树外面，因为 Agent 在其工作目录上运行的相对路径命令可能误删树内 venv，摧毁运行中的运行时：

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv ~/.hermes/venvs/hermes-dev --python 3.11
source ~/.hermes/venvs/hermes-dev/bin/activate
uv pip install -e ".[all,dev]"
scripts/run_tests.sh

依赖治理方面，AGENTS.md 规定所有依赖必须带上界以限制供应链攻击面：PyPI 包用 >=floor,<next_major，Git 依赖锁定 40 位提交 SHA，CI-only 依赖锁 ==exact，新增依赖后需运行 uv lock 重新生成带哈希的锁文件。

11. 社区与许可

• 社区交流：Nous Research Discord
• 技能生态：agentskills.io（Skills Hub，Hermes 技能格式与之兼容）
• 问题反馈：仓库 Issues
• 社区生态示例：computer-use-linux（Linux 桌面控制 MCP 服务器，提供 AT-SPI 可访问性树、Wayland/X11 输入、截图与合成器窗口定位）；HermesClaw（社区微信桥，让 Hermes Agent 与 OpenClaw 共用同一微信账号）

许可：MIT，见 LICENSE。项目由 Nous Research 构建；多语言 README 可用（README.zh-CN.md、README.es.md、README.ur-pk.md）。

12. 小结

Hermes Agent 的 README 勾勒的是一个"以学习闭环为内核、以双入口（CLI/消息网关）为界面、以插件与技能为扩展面"的个人 Agent 系统。从仓库源码可以验证：curator 的只归档不删除不变式、FTS5 会话存储、auxiliary 分账、COMMAND_REGISTRY 单一命令注册表，都在为 README 中的每项宣称提供实现背书；而 AGENTS.md 中"prompt 缓存神圣"与"核心窄腰"两条原则，则解释了为什么这个系统既能跨 Telegram/Discord/Docker/云沙箱等七种后端无处不在，又能在成本上保持可控。