Hermes Agent 安装、配置与核心能力实战指南：从终端到多平台消息网关的完整上手路径

2026-09-05 22:27:58作者：房伟宁

本文基于仓库中的 README.es.md（西班牙语官方 README，内容与英文主 README 保持一致）整理并扩充，覆盖 Hermes Agent 的完整安装流程（Linux/macOS/WSL2/Termux/Windows 原生）、首次配置命令、Nous Portal 单订阅接入、CLI 与消息平台的双入口命令对照、从 OpenClaw 的迁移路径，并结合当前仓库源码目录结构佐证其网关、定时任务与终端后端等核心能力的落地位置。读完本文，你可以独立完成 Hermes Agent 的安装、选型模型、启动消息网关并评估其架构实现。

项目定位：一个带闭环学习能力的 AI Agent

Hermes Agent 是 Nous Research 出品的、具备持续改进能力的 AI 智能体，其核心卖点是内置学习闭环：从经验中创建技能（Skills）、在使用中自动改进技能、自我驱动地持久化知识、检索自身过往对话，并跨会话逐步构建对用户更深的画像理解。它不绑定笔记本——你可以部署在 5 美元的 VPS、GPU 集群或近乎零成本的无服务器基础设施上，并在 Telegram 中与其对话，而它本身运行在云 VM 里。

官方 README 以表格形式总结了七大核心能力，这里完整继承并展开：

能力	说明
真实的终端界面	完整 TUI，支持多行编辑、命令自动补全、对话历史、中断与重定向，以及工具输出的流式展示
驻留在你所在的多平台	Telegram、Discord、Slack、WhatsApp、Signal 与 CLI，全部由单一 gateway 进程托管；支持语音留言转写、跨平台对话连续性
闭环学习循环	由 Agent 自主整理的记忆（附带周期性提醒）、复杂任务后自动创建技能、技能在使用中自我改进、基于 SQLite FTS5 的会话全文检索（配合 LLM 摘要实现跨会话记忆召回）、基于 Honcho 的辩证式用户建模，并兼容 agentskills.io 开放标准
定时自动化	内置 cron 调度器，可投递到任意平台；日报、夜间备份、周审计等全部以自然语言定义、自主运行
委派与并行	启动隔离的子 Agent 处理并行工作流；编写通过 RPC 调用工具的 Python 脚本，把多步流水线压缩为“零上下文成本”的轮次
随处运行，不止笔记本	六种终端后端：local、Docker、SSH、Singularity、Modal、Daytona。其中 Daytona 和 Modal 提供无服务器持久化——Agent 环境空闲时休眠、按需唤醒，会话间隙成本极低
面向研究场景	支持批量轨迹（trajectory）生成与轨迹压缩，用于训练下一代工具调用模型

从当前仓库的源码结构可以印证这些能力并非空谈：agent/ 目录承载核心运行时（如 conversation_loop.py 主对话循环、context_compressor.py 上下文压缩、trajectory.py 轨迹生成），agent/monitoring/cron_health.py 体现定时任务健康监控，agent/monitoring/ 下的 gateway_health.py、emitter.py 则对应 gateway 可观测性；acp_adapter/ 提供 ACP（Agent Client Protocol）适配层，而 apps/desktop/ 是 Electron 桌面端实现，其中 electron 主进程模块（如 backend-health.ts、gateway-ws-probe.ts）负责桌面端与后端网关的健康探测。

快速安装

Linux、macOS、WSL2、Termux

一键脚本即可完成安装：

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

注：该安装脚本托管在项目官方文档域名上，属于仓库外部资源，当前仓库内不包含脚本本体；安装后如遇到问题可用 hermes doctor 诊断。

Windows（原生 PowerShell，无需 WSL）

Windows 原生环境下 Hermes 的 CLI、gateway、TUI 与工具链均为原生运行，不依赖 WSL。在 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，安装器会检测到并直接复用，不再下载 MinGit；
否则，安装器仅下载约 45MB 的 MinGit，不会触碰也不会干扰系统 Git。

Android / Termux 说明：Termux 下经过验证的手动路径在官方 Termux 指南中。Termux 场景下 Hermes 安装的是精简 extra .[termux]，因为完整的 .[all] extra 目前包含与 Android 不兼容的语音相关依赖。

Windows 安装位置：Windows 原生安装在 %LOCALAPPDATA%\hermes；若走 WSL2 路线，则与 Linux 一致安装在 ~/.hermes。

安装后

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

首次上手：核心命令一览

安装完成后，以下命令构成日常操作的骨架：

hermes              # 交互式 CLI——开始一段对话
hermes model        # 选择 LLM 供应商与模型
hermes tools        # 配置启用哪些工具
hermes config set   # 设置单项配置值
hermes gateway      # 启动消息网关（Telegram、Discord 等）
hermes setup        # 运行完整配置向导
hermes claw migrate # 从 OpenClaw 迁移（如你来自 OpenClaw）
hermes update       # 升级到最新版本
hermes doctor       # 诊断任何问题

其中 hermes model 体现了官方强调的“模型无关”原则：无论底层走 Nous Portal、OpenRouter（200+ 模型）、NovitaAI、NVIDIA NIM（Nemotron）、Xiaomi MiMo、z.ai/GLM、Kimi/Moonshot、MiniMax、Hugging Face、OpenAI 还是自托管 endpoint，切换模型都无需改代码、无需换依赖。从源码结构看，agent/model_metadata.py 与 agent/transports/ 目录下的多后端实现（anthropic.py、bedrock.py、chat_completions.py、codex.py 等）正是这种“同一 Agent 核心、可插拔模型传输层”设计的落地。

用 Nous Portal 免收一堆 API Key

Hermes 支持任意供应商，这一点不会改变。但如果你不想分别为模型、网络搜索、图像生成、TTS 和云浏览器收集五把独立的 API Key，Nous Portal 提供单一订阅覆盖全部能力：

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

全新安装后一条命令接入：

hermes setup --portal

它会通过 OAuth 完成认证、把 Nous 设为默认供应商并激活 Tool Gateway。任何时刻可用 hermes portal info 查看当前接入状态。一个重要的设计细节：Tool Gateway 是按 backend 粒度生效的，而非全有或全无——你可以让某些工具继续走自己的 Key，其余走订阅。仓库中 agent/web_search_provider.py、agent/image_gen_provider.py、agent/tts_provider.py 等 provider/registry 成对文件，印证了这种“每类能力独立注册、可自由路由”的插件式工具网关实现。

快速参考：CLI 与消息平台命令对照

Hermes 有两个入口：hermes 直接打开终端界面；或运行 gateway 后从 Telegram、Discord、Slack、WhatsApp、Signal、Email 发消息。进入会话后，大量斜杠命令在两种界面间共享：

操作	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`

完整命令清单在官方文档站的 CLI 指南与消息网关指南中（本文不输出外部链接，可通过 hermes doctor、hermes setup 等命令在本地获得交互式引导）。

文档体系地图

官方 README 指向一套分层的文档结构，按主题划分如下（内容为各文档页的定位说明，便于你按需检索）：

文档板块	覆盖内容
快速上手	安装 → 配置 → 2 分钟完成第一次对话
CLI 使用	命令、快捷键、人格（personalities）、会话管理
配置	配置文件、供应商、模型与全部选项
消息网关	Telegram、Discord、Slack、WhatsApp、Signal、Home Assistant
安全	命令审批、DM 配对、容器隔离
工具与 Toolsets	40+ 工具、toolset 系统、终端后端
技能系统	程序性记忆、Skills Hub、技能创建
记忆	持久记忆、用户画像、最佳实践
MCP 集成	连接任意 MCP 服务器扩展能力
Cron 定时	带平台投递的任务调度
上下文文件	塑造每次对话的项目上下文
架构	项目结构、Agent 主循环、核心类
贡献指南	开发环境、PR 流程、代码风格
CLI 参考	全部命令与 flag
环境变量参考	环境变量完整清单

从 OpenClaw 迁移

如果你来自 OpenClaw，Hermes 可以自动导入你的配置、记忆、技能和 API Key。

首次配置时：hermes setup 向导会自动检测 ~/.openclaw 目录，并在开始配置前提供迁移选项。

安装后任意时刻：

hermes claw migrate              # 交互式迁移（完整 preset）
hermes claw migrate --dry-run    # 预览将迁移什么
hermes claw migrate --preset user-data   # 只迁移非机密数据
hermes claw migrate --overwrite  # 覆盖已存在的冲突项

迁移覆盖的内容：

SOUL.md——人格文件；
记忆——MEMORY.md 与 USER.md 条目；
技能——用户创建的技能 → 导入到 ~/.hermes/skills/openclaw-imports/；
允许命令列表——审批模式（allowlist patterns）；
消息配置——平台配置、允许的用户、工作目录；
API Key——允许清单中的密钥（Telegram、OpenRouter、OpenAI、Anthropic、ElevenLabs）；
TTS 素材——工作区中的音频文件；
工作区指令——AGENTS.md（需加 --workspace-target）。

完整选项见 hermes claw migrate --help；仓库中 agent/onboarding.py 等引导模块承载了安装/迁移阶段的交互式流程。

贡献与开发环境

贡献流程详见 CONTRIBUTING.es.md（西班牙语）与 CONTRIBUTING.md（英语），涵盖开发环境搭建、代码风格与 PR 流程。协作者快速通道——克隆后用 setup-hermes.sh 一键就绪：

git clone https://gitcode.com/GitHub_Trending/he/hermes-agent
cd hermes-agent
./setup-hermes.sh     # 安装 uv、创建 venv、安装 .[all]、链接 ~/.local/bin/hermes
./hermes              # 自动检测 venv，无需先 source

手动路径（与上面等价）：

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

需要说明的是，当前仓库快照中未包含 setup-hermes.sh、pyproject.toml 与 scripts/run_tests.sh（本快照以 agent/、acp_adapter/、apps/ 等核心目录为主），以上命令以 README 描述的完整发行仓库为准；快照中的 Dockerfile 则提供了容器化构建的参考。另外，仓库根的 AGENTS.md 是为 AI 协作者编写的项目约定文件，贡献前值得通读。

仓库结构速览：能力与代码的对应关系

结合当前仓库，可将 README 宣称的能力映射到具体代码位置，便于继续深入：

Agent 核心运行时：agent/ 目录，含对话循环、上下文压缩与压缩（conversation_compression.py、native_compaction.py）、记忆（memory_manager.py、memory_provider.py）、技能（skill_bundles.py、skill_commands.py）、轨迹（trajectory.py）等模块；
模型接入层：agent/ 下众多 *_adapter.py（anthropic_adapter.py、bedrock_adapter.py、vertex_adapter.py、gemini_native_adapter.py）加上 agent/transports/ 的传输实现，对应“任意模型、hermes model 一键切换”；
监控与可观测：agent/monitoring/ 提供 cron 健康、gateway 健康、OTLP 导出与脱敏（redaction.py），支撑“定时自动化”与“网关”的运维面；
ACP 适配：acp_adapter/ 提供认证、权限、事件、会话等模块，服务于外部客户端接入；
桌面端：apps/desktop/ 为 Electron 应用，electron 主进程内有大量 *.test.ts 单测与 e2e/ Playwright 用例（如 boot.spec.ts、chat.spec.ts），是验证“桌面端 + 后端 gateway”行为的入口；
安装器应用：apps/bootstrap-installer/ 是基于 Tauri 的引导安装器，含进度/成功/失败页面与 Rust 侧的安装脚本、更新逻辑（src-tauri/src/install_script.rs、update.rs），与安装章节的“安装器负责一切”相呼应。

许可

MIT 协议——见 LICENSE。项目由 Nous Research 制作。

小结

安装按平台二选一：Linux/macOS/WSL2/Termux 用 install.sh，Windows 原生用 PowerShell 的 install.ps1，Windows 下无 Git 时自动附带隔离的 MinGit；
日常操作围绕 hermes、hermes model、hermes gateway、hermes setup、hermes doctor 等少量命令展开，斜杠命令在 CLI 与消息平台间高度共享；
不想管理多把 Key 时，hermes setup --portal 一条命令接入 Nous Portal，且 Tool Gateway 按 backend 粒度生效，可与自有 Key 混用；
从 OpenClaw 迁移用 hermes claw migrate，支持 --dry-run 预览与 user-data 无密钥 preset；
本文所有命令与能力描述以当前仓库 README.es.md 为准，外部文档站与安装脚本不在本仓库快照内，适用前提为官方文档站可访问；具体版本能力以拉取到的仓库实际内容为准。