---

1 -> 先说结论：Hermes 不只是一个聊天机器人

Hermes Agent 是 Nous Research 推出的 self-improving AI agent。官方文档对它的定位不是“套了 API 的聊天界面”，而是一个可以长期运行、接入工具、记住偏好、沉淀技能，并通过 CLI、桌面端、消息平台和自动化任务被调用的 Agent 系统。官方首页强调，它可以运行在本机、VPS、GPU 集群或 serverless 基础设施上，也可以通过 Telegram 等入口和你交互。参考：Hermes Agent Documentation。

如果用一句话概括：

Hermes 的价值不是“装上以后能聊天”，而是把模型、工具、消息入口、记忆、技能和安全边界组织成一个可持续工作的 Agent Loop。

所以搭建 Hermes 时，不要只问“安装命令是什么”。更重要的问题是：

• 它跑在哪里：本机、WSL2、VPS、Docker、远程后端？
• 它用什么模型：Nous Portal、OpenRouter、Anthropic、OpenAI wire-compatible endpoint、本地模型？
• 它通过什么入口接收任务：CLI、Desktop、Telegram、Slack、Discord、Email、Cron？
• 它能用哪些工具：文件、终端、浏览器、搜索、MCP、媒体工具？
• 它如何记住你：MEMORY.md、USER.md、SOUL.md、skills？
• 它的安全边界是什么：approval mode、deny rules、隔离后端、密钥管理？

这篇文章按“从能跑，到好用，再到可控”的顺序展开。

2 -> Hermes 的核心组成

在正式安装前，先建立一个 mental model。

组成	作用	你需要关注什么
CLI / Desktop	本机交互入口	能否正常启动、能否选择模型、能否运行工具
Gateway	消息平台后台进程	Telegram/Slack/Discord/WhatsApp 等入口是否接通
AIAgent	Agent 主循环	Prompt、模型、工具调用、压缩、重试、fallback
Providers	模型供应商	Nous Portal、OpenRouter、Anthropic、OpenAI 兼容端点、本地模型
Tools	Agent 能执行的能力	终端、文件、浏览器、搜索、媒体、记忆、automation
Memory	长期上下文	MEMORY.md、USER.md 是否被合理维护
Skills	可复用知识/流程	操作手册、模板、工作流是否沉淀为 skill
MCP	外部工具服务器接入	是否只暴露必要工具，是否审查 server manifest
Security	安全边界	approval、deny rules、隔离、密钥、日志脱敏

官方架构文档说明，AIAgent 负责组装系统提示、选择 provider/API 模式、执行工具调用、维护会话历史、处理压缩/重试/fallback、跟踪迭代预算等。参考：Architecture、Agent Loop Internals。

3 -> 搭建路线：不要一步到位

建议按下面路线走，不要一上来就接所有消息平台、所有 MCP、所有工具。

推荐顺序：

1. 本机安装 Hermes。
2. 配好一个模型 provider。
3. 跑通第一轮 hermes chat。
4. 接一个消息入口，例如 Telegram 或 Slack。
5. 打开必要工具，不要一口气开放所有权限。
6. 沉淀 memory、skills、SOUL.md。
7. 再考虑 MCP、cron、VPS、Docker、团队化部署。

这个顺序的好处是：每一步都有明确验收点。出了问题时，你知道是安装、模型、工具、消息入口还是权限边界出了问题。

4 -> 安装方式选择

官方安装页给了两类路径：Desktop installer 和命令行安装。参考：Installation。

4.1 -> macOS / Windows：优先 Desktop installer

如果你只是想最快跑起来，官方推荐 macOS 或 Windows 使用 Hermes Desktop installer。安装器会帮你处理命令行和桌面应用。

适合：

• 不想先处理 Python/Node/ffmpeg/ripgrep 依赖；
• 想用桌面端管理会话；
• 在 Windows 上希望少折腾 PATH 和 shell 环境；
• 第一次体验 Hermes。

Windows 原生支持方面，官方 Windows Native Guide 说明，除 dashboard 内嵌 terminal pane 外，大部分能力都能在原生 Windows 上运行，包括 CLI、TUI、gateway、Cron、浏览器工具、MCP、本地 Ollama/LM Studio 等。参考：Windows Native Guide。

4.2 -> Linux / macOS / WSL2 / Termux：命令行安装

官方命令行安装方式：

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

4.3 -> Windows 原生 PowerShell：命令行安装

官方 Windows 原生命令：

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

这里要说清楚一个安全边界：curl | bash 或 iex (irm ...) 都是“从网络下载脚本并执行”。这在官方安装文档里很常见，但不代表你应该在生产机器上无脑运行。

更稳的做法是：

• 确认来源是 Hermes 官方域名；
• 先在测试环境运行；
• 有安全要求时先下载脚本，人工检查关键逻辑；
• 不要在有生产密钥、客户数据、重要私钥的机器上直接试错；
• 企业环境最好走受控镜像、固定版本或内部脚本审查。

4.4 -> 安装器会做什么

官方安装文档说明，installer 会处理依赖、repo clone、虚拟环境、全局 hermes 命令、模型 provider 配置等。常见依赖包括 Python、Node.js、ripgrep、ffmpeg 等。

安装结束后，先开一个新终端，再检查：

hermes --help
hermes doctor

如果 hermes 命令找不到，通常是 PATH 没刷新、终端没重开、Windows shell 环境没有加载新变量，或者安装过程被杀毒软件/权限拦截

5 -> 最快跑通：hermes setup --portal

官方 Quickstart 和 Nous Portal 指南都推荐第一次配置直接走：

hermes setup --portal

参考：Quickstart、Run Hermes Agent with Nous Portal。

根据官方说明，这个命令会做几件事：

1. 打开浏览器完成 Nous Portal OAuth 登录。
2. 把 refresh token 存到 ~/.hermes/auth.json。
3. 把模型 provider 设置为 Nous。
4. 选择默认 agentic model。
5. 打开 Tool Gateway，用于 web search、image generation、TTS、browser automation 等工具路由。

验证命令：

hermes portal info
hermes chat

你可以在首次对话里让 Hermes 做一个轻量任务，例如：

请搜索 Hermes Agent release notes，并总结最近三个变化点。

这个任务能同时验证：

• 模型是否能正常响应；
• web search 工具是否通；
• Tool Gateway 是否配置成功；
• Hermes 是否能把工具结果整合成答案。

6 -> 配置目录：理解 ~/.hermes/

Hermes 的配置核心在 ~/.hermes/。官方配置文档列出了典型结构。参考：Configuration。

~/.hermes/
├── config.yaml
├── .env
├── auth.json
├── SOUL.md
├── memories/
├── skills/
├── cron/
├── sessions/
└── logs/

每个文件/目录的意义：

路径	用途
config.yaml	非密钥配置：模型、终端 backend、toolsets、压缩、记忆限制等
.env	API keys、bot tokens、passwords 等 secret
auth.json	OAuth provider credential，例如 Nous Portal
SOUL.md	Agent 主身份和长期行为设定
memories/	MEMORY.md、USER.md 等长期记忆
skills/	bundled、hub-installed、agent-created skills
cron/	定时任务
sessions/	gateway 会话状态
logs/	错误和 gateway 日志，官方说明日志会做 secret redaction

配置优先级通常是：

1. CLI 参数；
2. config.yaml；
3. .env；
4. 内置默认值。

最重要的规则：

Secrets 放 .env，普通配置放 config.yaml。

不要把 API key、bot token、数据库密码写进 Markdown、Git 仓库、团队聊天或公开 issue。

7 -> 模型与工具配置

7.1 -> 模型 provider

Hermes 支持多种 provider：Nous Portal、OpenRouter、Anthropic、OpenAI-compatible endpoint、本地模型等。官方 AI Providers 文档说明，使用 Nous Portal 时，hermes setup --portal 会同时完成 provider 和 Tool Gateway 配置。参考：AI Providers。

常用命令：

hermes model

进入 chat session 后可以使用：

/model

经验上，做 Agent 工作不要只看模型“聊天能力”，还要看：

• tool calling 是否稳定；
• 长上下文是否可靠；
• 输出是否可控；
• 价格和延迟是否可接受；
• 是否适合多步任务和外部工具调用。

7.2 -> Tools 与 Toolsets

Hermes 的 Tools 是 Agent 能执行的函数，按 toolsets 组织。官方工具页说明 toolsets 可以按平台启用或禁用，内置能力覆盖 web search、terminal、file editing、memory、browser、delegation 等。参考：Tools & Toolsets、Built-in Tools Reference。

搭建初期建议：

• 先启用最小工具集；
• 先跑只读或低风险工具；
• 终端工具保持审批；
• 文件写入、删除、shell 命令、浏览器自动化都要留边界；
• 确认每个工具失败时怎么观察日志。

不要一开始就把所有工具全开。

8 -> 消息网关：让 Hermes 进入你的日常入口

Hermes 的 Gateway 是后台进程，负责把 Telegram、Discord、Slack、WhatsApp、Signal、SMS、Email、Home Assistant、DingTalk、Feishu/Lark、WeCom、Weixin 等入口接到 Hermes 会话上。官方文档首页和 messaging 指南都强调了多平台入口能力。

建议先接一个平台，不要一口气接所有平台。

8.1 -> 推荐第一站：Telegram 或 Slack

原因：

• 配置路径相对清晰；
• Bot 模型成熟；
• 适合个人或小团队验证；
• 日志和权限更容易理解。

Telegram 文档中特别提醒：Telegram bot 默认 privacy mode 开启，在群组里只能看到 / 命令、回复 bot 的消息、服务消息、bot 管理的频道消息等；关闭 privacy mode 后才能看到群内所有消息。参考：Telegram。

这点非常重要，因为它关系到隐私与群聊噪音：

不要为了“方便”随便关闭隐私模式，除非你明确知道 bot 会看到什么、记录什么、回复什么。

8.2 -> Gateway 常见运维方式

先手动跑：

hermes gateway run

再考虑常驻：

• macOS：launchd；
• Linux / VPS：systemd、tmux、nohup；
• Windows：Task Scheduler 或 WSL 启动任务；
• Docker：容器 supervisor。

FAQ 里也提到，WSL 场景可用 tmux、nohup 或 Windows Task Scheduler 做稳定自启动。参考：FAQ & Troubleshooting。

9 -> Memory、Skills 与 SOUL.md：真正拉开长期差异的部分

9.1 -> Memory：有限、整理过的长期记忆

Hermes 的 memory 不是“无限聊天记录”。官方记忆文档强调，它更接近 bounded curated memory。MEMORY.md 和 USER.md 位于 ~/.hermes/memories/，会在会话开始时注入系统提示。

这意味着：

• 记忆应该是整理后的事实和偏好；
• 不应该把所有聊天原文都塞进去；
• 未验证猜测不应该混进事实源；
• 记忆有容量和质量管理问题；
• 记忆更新需要定期清理、修正和过期处理。

9.2 -> SOUL.md：Agent 的身份与行为边界

SOUL.md 是 Hermes 的主身份设定。官方 Prompt Assembly 文档说明，SOUL.md 会作为 agent identity 出现在系统提示的最前面。参考：Prompt Assembly。

建议 SOUL.md 里不要写过度抽象的“你是最强 AI”。更实用的是：

• 你服务谁；
• 你默认怎么沟通；
• 你不应该做什么；
• 哪些动作必须确认；
• 哪些信息不能外发；
• 哪些输出需要附带证据；
• 哪些任务要先问清楚。

9.3 -> Skills：把流程变成可复用能力

官方 Skills 文档说明，skills 是按需加载的知识文档，遵循 progressive disclosure，减少 token 使用，并位于 ~/.hermes/skills/。参考：Skills System、Creating Skills。

适合做成 skill 的内容：

• 客户研究流程；
• PR review 标准；
• 外贸邮件模板；
• 数据清洗步骤；
• 竞品分析框架；
• 项目复盘模板；
• 团队安全边界；
• 特定软件/平台操作手册。

判断标准：

如果一个流程你会反复解释给 Agent，就应该考虑把它沉淀成 skill。

10 -> MCP：把外部工具接进 Hermes，但不要“全接”

MCP 是 Model Context Protocol。Hermes 的 MCP 文档说明，它可以让 Hermes 连接外部工具服务器，例如 GitHub、数据库、文件系统、浏览器栈、内部 API 等。参考：MCP、Use MCP with Hermes。

MCP 的正确心智模型是：

Hermes 仍然是 agent，MCP server 只是贡献工具；你要控制每个 server 暴露多少工具面。

不要这样做：

• 一次性接所有 MCP；
• 给数据库读写全权限；
• 把生产 API 暴露给未隔离 agent；
• 不看 manifest 和 bootstrap 命令；
• 让 agent 自己决定是否能访问敏感系统。

更稳的做法：

1. 从只读工具开始；
2. 只暴露一个 server 的少量工具；
3. 给工具命名清楚；
4. 为写操作保留人工审批；
5. 记录 MCP server 来源和版本；
6. 定期审查工具列表；
7. 禁用不需要的 resource/prompt utility wrappers。

MCP 很强，但它本质上是在扩展 Agent 的手脚。越强的手脚，越需要边界。

11 -> 安全基线：不要把 Agent 当成普通聊天窗口

Hermes 官方安全文档描述了多层安全模型，包括用户授权、危险命令审批、容器隔离、MCP 凭据过滤、上下文文件扫描、跨会话隔离、输入清洗等。参考：Security。

11.1 -> Approval mode：默认保守

官方 Tips 里提醒，危险命令审批可能给出 once、session、always、deny 这类选项；选择 always 前要谨慎。参考：Tips & Best Practices。

建议：

• 新手阶段使用 manual；
• 熟悉后可以逐步使用 smart；
• 不要轻易使用 off 或 YOLO；
• 高风险命令不要永久 allow；
• 团队环境应写清楚审批规则。

11.2 -> Deny rules：即使 YOLO 也要有硬边界

官方配置文档提到，approvals.deny 可以无条件阻止匹配的 terminal commands，甚至在 --yolo、/yolo 或 mode: off 下也阻止。参考：Configuration - Deny rules。

可以考虑阻止：

• force push；
• 递归删除；
• 格式化磁盘；
• 删除密钥目录；
• 直接推生产；
• 下载脚本后直接 pipe 到 shell；
• 数据库 destructive operation；
• 未经确认的外部发送脚本。

注意 YAML glob pattern 要正确引用，官方安全页也提醒通配符、冒号、感叹号等在 YAML 里有特殊含义，最好加引号。

11.3 -> 终端 backend：生产环境优先隔离

Hermes 配置支持不同 terminal backend，例如 local、docker、ssh、modal、daytona、singularity。参考：Configuration、Docker。

选择建议：

场景	推荐后端
个人本机试用	local，但保持审批
代码实验/不可信命令	docker
云端长期运行	VPS + docker 或受控 ssh
高风险数据/生产资源	不建议直接给 agent 访问，先做只读和隔离

11.4 -> Dashboard 不要随便暴露到公网

官方 Web Dashboard 文档说明，hermes dashboard 默认在 127.0.0.1:9119 启动；--insecure 会允许绑定非 localhost，并明确标为危险，因为可能把 API keys 暴露到网络上。参考：Web Dashboard。

所以：

• 本地管理就保持 localhost；
• 远程访问优先 SSH tunnel；
• 不要直接 --host 0.0.0.0 --insecure；
• 如果必须远程暴露，至少要强认证、防火墙、反向代理 TLS、IP allowlist。

12 -> 从个人可用到团队可用

个人可用和团队可用是两回事。

12.1 -> 个人可用

最低要求：

• 本机安装成功；
• 模型可用；
• CLI 可用；
• 一个消息平台可用；
• 基础工具可用；
• manual approval；
• .env 不进 Git；
• memory 不乱写。

12.2 -> 团队可用

额外要求：

• 统一 profiles 或配置模板；
• 明确哪些工具允许使用；
• 明确哪些数据不能进 agent；
• 明确哪些外发动作必须人工确认；
• Gateway 日志可观测；
• 定时任务可暂停和审计；
• skills 有版本管理；
• MCP server 有来源审查；
• 更新前有备份和回滚。

团队化最容易出问题的不是安装，而是权限和责任：

Agent 一旦能替团队做事，就必须知道它不能替团队决定什么。

13 -> 最小可行搭建方案

如果你希望少走弯路，可以按这个 MVP 执行。

13.1 -> 本机跑通

目标：

• 安装 Hermes；
• 配好 Nous Portal 或一个 provider；
• hermes chat 正常；
• hermes portal info 或 provider 状态正常；
• hermes doctor 不报关键错误。

验收：

• 能完成一次包含 web search 的对话；
• 能解释当前 provider 和工具 routing；
• 能找到 ~/.hermes/。

13.2 -> 接一个消息入口

目标：

• 选择 Telegram 或 Slack；
• 配 bot token；
• 启动 gateway；
• 测试私聊或受控群组。

验收：

• 平台消息能进入 Hermes；
• Hermes 回复正常；
• 日志能定位失败；
• 隐私模式和权限符合预期。

13.3 -> 打开必要工具

目标：

• 明确需要哪些 toolsets；
• 终端工具保持 manual approval；
• 禁止危险命令；
• 只给当前项目目录访问。

验收：

• 能执行低风险终端/文件任务；
• 危险命令会触发审批或被 deny；
• 工具失败有可读日志。

13.4 -> 沉淀 Memory / Skills

目标：

• 写好 SOUL.md；
• 维护 USER.md 和 MEMORY.md；
• 把一个重复流程做成 skill。

验收：

• 新会话能继承基本偏好；
• skill 可被按需调用；
• memory 没有混入未验证猜测。

13.5 -> 接 MCP 或上 VPS

目标：

• 只接一个 MCP；
• 只暴露少量必要工具；
• 或把 gateway 迁到 VPS / Docker。

验收：

• MCP 工具列表可解释；
• 写操作有审批；
• 服务重启后能恢复；
• 日志和备份策略明确。

14 -> 常见问题排查

14.1 -> hermes: command not found

可能原因：

• 安装未完成；
• PATH 没刷新；
• Windows 需要重开终端；
• shell 与安装器写入的环境变量不一致；
• Windows 原生需要 Git Bash 路径。

处理：

hermes doctor

如果命令本身找不到，先回到安装器输出，看它把 binary 放在哪里。

14.2 -> 模型没有响应

检查：

• provider 是否配置；
• .env 或 OAuth 是否有效；
• hermes portal info 是否正常；
• 模型名是否存在；
• 网络是否可访问 provider；
• 是否被 rate limit。

14.3 -> Tool Gateway 不工作

检查：

• 是否通过 hermes setup --portal 启用；
• 工具 routing 是否显示 through Nous Portal；
• 单独调用工具是否失败；
• 是否缺依赖，例如 Node、browser、ffmpeg；
• gateway 日志是否有错误。

14.4 -> 消息平台收不到消息

检查：

• bot token 是否正确；
• gateway 是否在运行；
• bot 是否在群组；
• Telegram privacy mode 是否符合预期；
• 平台 SDK 是否安装；
• 防火墙、代理、webhook 或 polling 模式是否正常。

14.5 -> Agent 一直要求审批

这不一定是坏事。先确认：

• 当前是否 manual mode；
• 命令是否真的危险；
• 是否应该用 session 而不是 always；
• 是否可以把任务拆成更低风险步骤；
• 是否应该添加 deny rules，而不是简单放开。

14.6 -> Dashboard 能不能远程开

可以，但不建议裸开。官方 dashboard 默认 localhost；--insecure 是危险选项。远程管理优先用 SSH tunnel。

15 -> 一张总检查表

阶段	检查项
安装	hermes --help、hermes doctor 可运行
Provider	hermes setup --portal 或 hermes model 配置成功
首聊	hermes chat 能正常响应
工具	web/search/browser/terminal 按需启用
配置	secret 在 .env，普通配置在 config.yaml
消息	gateway 可运行，一个平台先跑通
安全	approval manual/smart，危险命令不自动放行
隔离	高风险任务用 docker/ssh/cloud backend
记忆	MEMORY.md、USER.md 不乱写，不污染事实源
技能	重复流程沉淀为 skill
MCP	只接必要 server，只暴露必要工具
运维	logs、backup、update、rollback 有路径

16 -> 结语：搭建 Hermes 的重点不是“装上”，而是形成闭环

Hermes Agent 的搭建可以很快，官方甚至说安装可以在很短时间内完成。但真正决定它是否好用的，不是安装命令，而是你有没有把这些部分设计成闭环：

• 一个稳定入口；
• 一个适合 agentic 工作的模型；
• 一组最小但够用的工具；
• 一套可维护的记忆与技能；
• 一个可审计的消息网关；
• 一条明确的安全边界；
• 一个能持续运行、能排错、能回滚的部署方式。

如果只是把 Hermes 当聊天窗口，它的价值会被低估。
如果把它当成“入口 + 工具 + 记忆 + 技能 + 安全边界”的系统来搭，它才会真正变成一个能长期工作的 Agent。

---

感谢各位大佬支持！！！
互三啦！！！