Hermes Agent 技术指南：自进化 AI 代理的安装、配置与源码架构解析

Hermes Agent 是由 Nous Research 构建的自进化个人 AI 代理，内置"学习闭环"——从经验中创建技能、在使用中改进技能、主动持久化知识并在跨会话中构建对用户与项目的深度理解。本文基于仓库根目录的中文主文档 README.zh-CN.md 展开，完整覆盖安装、核心命令、模型接入、消息网关、OpenClaw 迁移与贡献流程，并结合 agent/、acp_adapter/、apps/ 等真实源码目录解析其背后的实现结构，读完即可独立完成部署并定位各功能对应的源码模块。

一、Hermes Agent 是什么：定位与核心能力

Hermes 的核心定位可以概括为三个关键词：自进化、多入口、随处运行。

• 自进化：代理管理记忆并定期自我提醒；完成复杂任务后自动创建技能；技能在使用中自我改进；通过 FTS5 会话搜索配合 LLM 摘要实现跨会话回溯；兼容 agentskills.io 开放标准。
• 多入口：完整 TUI 终端界面（多行编辑、斜杠命令自动补全、对话历史、中断重定向、流式工具输出），以及从单个网关进程同时服务 Telegram、Discord、Slack、WhatsApp、Signal 和 CLI 的消息网关能力。
• 随处运行：六种终端后端——本地、Docker、SSH、Daytona、Singularity 和 Modal。其中 Daytona 与 Modal 提供 Serverless 持久化：代理环境空闲时休眠、按需唤醒，空闲期间几乎零成本。$5 的 VPS 或 GPU 集群都能跑，它不绑定你的笔记本——你可以在 Telegram 上与它对话，而它在云端 VM 上工作。

此外它还具备：

能力	说明	仓库中的实现落点
闭环学习	记忆、技能、跨会话回溯	agent/memory_manager.py、agent/skill_bundles.py、agent/skill_commands.py、agent/learning_graph.py
定时自动化	内置 cron 调度器，向任何平台投递，自然语言描述、无人值守	agent/monitoring/cron_health.py 等健康监控模块
委派与并行	生成隔离子代理处理并行工作流；编写 Python 脚本通过 RPC 调用工具	agent/subagent_lifecycle.py、agent/relay_runtime.py
研究就绪	批量轨迹生成、轨迹压缩，用于训练下一代工具调用模型	agent/trajectory.py、agent/moa_trace.py
多端界面	CLI/TUI、Electron 桌面端、Tauri 引导安装器	apps/desktop/、apps/bootstrap-installer/
可观测性	监控事件、OTLP 导出、脱敏	agent/monitoring/otlp_exporter.py、agent/monitoring/redaction.py

从源码结构看，agent/ 目录按职责拆分为上百个单文件模块（会话循环、上下文压缩、提示缓存、凭据池、LSP、传输层等），acp_adapter/ 提供独立的协议适配层（含 权限管理 与编辑审批），apps/ 承载桌面端与安装器这一层——这与其在开发指南 AGENTS.md 中声明的设计哲学一致："核心是窄腰（narrow waist），能力长在最外层"，新功能优先以插件、技能、CLI 命令形式落地，而非膨胀核心。

二、快速安装

支持 Linux、macOS、WSL2 和 Android (Termux)，一条命令完成：

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

安装程序会自动处理平台特定的配置。

Android / Termux：在 Termux 上，Hermes 会安装精选的 .[termux] 扩展，因为完整的 .[all] 扩展会拉取 Android 不兼容的语音依赖。

Windows：在 PowerShell 中运行：

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

安装完成后，可能需要重启终端，然后运行 hermes 开始对话。

安装后重新加载 shell 并启动：

source ~/.bashrc    # 重新加载 shell（或: source ~/.zshrc）
hermes              # 开始对话！

安装布局上，安装器会在 $HERMES_HOME（通常是 ~/.hermes）下创建完整的 git checkout（~/.hermes/hermes-agent），这与 hermes update、托管 venv、lazy dependencies、网关及文档工具使用的布局一致——理解这一点是后面"贡献与二次开发"一节的前提。

三、快速入门：核心命令体系

安装完成后，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 支持任意模型——Nous Portal、OpenRouter（200+ 模型）、NVIDIA NIM（Nemotron）、小米 MiMo、z.ai/GLM、Kimi/Moonshot、MiniMax、Hugging Face、OpenAI 或自定义端点。使用 hermes model 即可切换，无需改代码、无锁定。从源码结构看，多提供商的接入分散在 agent/transports/ 目录下，按协议划分：Anthropic 传输、Bedrock 传输、通用 Chat Completions 传输、Codex 系列传输与事件投影等；另有 agent/anthropic_adapter.py、agent/bedrock_adapter.py、agent/gemini_native_adapter.py、agent/vertex_adapter.py 等适配器文件，印证了"提供商可插拔"的架构设计。

四、省去到处收集 API Key：Nous Portal 与 Tool Gateway

Hermes 始终允许使用任意服务商。但如果不想为模型、网页搜索、图像生成、TTS、云浏览器分别申请五个不同的 API Key，Nous Portal 用一个订阅就能覆盖全部：

• 300+ 模型 — 用 /model <name> 随时切换；
• Tool Gateway — 网页搜索（Firecrawl）、图像生成（FAL）、文本转语音（OpenAI）、云浏览器（Browser Use），全部通过订阅托管，无需额外注册账户。

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

hermes setup --portal

它会通过 OAuth 登录、把 Nous 设为推理服务商，并启用 Tool Gateway。随时用 hermes portal info 查看路由状态。关键在于粒度：你随时可以按工具单独切回自己的 API Key——Gateway 是按工具粒度生效的，不是一刀切。从源码结构看，各能力均通过独立的注册器实现可替换路由，例如 agent/web_search_registry.py、agent/image_gen_registry.py、agent/tts_registry.py、agent/video_gen_registry.py，每个注册器对应一种"自建 Key 或走 Gateway"的二选一接入路径；agent/portal_tags.py 则处理 Portal 相关的路由标记。

五、CLI 与消息平台快速对照

Hermes 有两种入口：用 hermes 启动终端 UI，或运行网关从 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>	/skills 或 /<skill-name>
中断当前工作	Ctrl+C 或发送新消息	/stop 或发送新消息
平台特定状态	/platforms	/status、/sethome

斜杠命令的解析与执行逻辑可以从 agent/skill_commands.py（技能命令）与 agent/skill_bundles.py（技能捆绑）中追溯；网关侧的健康与事件上报则见 agent/monitoring/gateway_health.py 与 agent/monitoring/events.py。更完整的命令列表与消息网关配置，请参阅官方文档站的 "CLI 指南" 和 "消息网关指南" 章节（文档章节索引见第七节）。

六、从源码看架构：两条设计铁律与模块地图

开发指南 AGENTS.md（约 1800 行）明确了两条塑造几乎所有设计决策的铁律（见 AGENTS.md 第 19–27 行）：

1. 按会话的提示词缓存是神圣不可侵犯的。 长生命周期会话每轮复用缓存前缀；任何中途改写历史上下文、更换工具集或重建系统提示的操作都会使缓存失效并成倍放大用户成本——唯一的例外是上下文压缩。这一点在源码中有直接对应：agent/prompt_caching.py、agent/prompt_cache_boundary.py、agent/prompt_cache_scope.py 三个文件专门守护缓存边界，而 agent/context_compressor.py 与 agent/conversation_compression.py 就是文档中 /compress 命令背后的压缩实现。
2. 核心是窄腰，能力长在最外层。 每一个模型工具都会随每次 API 调用发送，因此新增核心工具的门槛极高。新增能力的优先顺序是：扩展现有代码 → CLI 命令 + 技能 → 服务门控工具（check_fn）→ 插件 → MCP 目录中的 MCP 服务器 → 新核心工具（最后手段）。

结合目录结构，可以把 Hermes 的模块地图归纳为：

• 代理内核（agent/）：agent/conversation_loop.py 承载主对话循环，agent/system_prompt.py 与 agent/prompt_builder.py 构建系统提示，agent/tool_executor.py 与 agent/tool_guardrails.py 负责工具执行与护栏，[agent/ttl... 各 turn_* 文件（如 agent/turn_context.py、agent/turn_finalizer.py）处理单轮生命周期。
• 记忆与学习：agent/memory_manager.py、agent/memory_provider.py、agent/learning_graph.py、agent/learning_mutations.py。
• 凭据与密钥：agent/credential_pool.py、agent/secret_scope.py、agent/redact.py，以及 agent/secret_sources/ 下的 Bitwarden、1Password、命令式密钥源。
• 协议与适配层：acp_adapter/ 提供独立的会话（session.py）、权限（permissions.py）、编辑审批（edit_approval.py）与来源证明（provenance.py）实现。
• 工程支撑：agent/lsp/（LSP 客户端与服务器管理）、agent/verify/（验证配方与运行器）、agent/pet/、Dockerfile（Docker 后端镜像）、24KB 的 .env.example（环境变量全量示例，仅用于存放密钥）。

安全模型方面，SECURITY.md 将 Hermes 定义为单租户个人代理，并明确指出了项目视为承载性（load-bearing）的安全边界，建议部署前通读其信任模型章节；容器隔离、命令审批、DM 配对等话题在官方文档站的 "安全" 章节有进一步展开。

七、文档索引

官方文档站点提供以下章节（中文主文档中的链接统一指向该站点，此处列出章节名与内容，便于按需检索）：

章节	内容
快速开始	安装 → 设置 → 2 分钟内开始首次对话
CLI 使用	命令、快捷键、人格、会话
配置	配置文件、提供商、模型、所有选项
消息网关	Telegram、Discord、Slack、WhatsApp、Signal、Home Assistant
安全	命令审批、DM 配对、容器隔离
工具与工具集	40+ 工具、工具集系统、终端后端
技能系统	过程记忆、技能中心、创建技能
记忆	持久记忆、用户画像、最佳实践
MCP 集成	连接任意 MCP 服务器扩展能力
定时调度	定时任务与平台投递
上下文文件	影响每次对话的项目上下文
架构	项目结构、代理循环、关键类
贡献	开发设置、PR 流程、代码风格
CLI 参考	所有命令和标志
环境变量	完整环境变量参考

在仓库内，与上述章节对应的本地可查证材料包括：开发指南 AGENTS.md、贡献流程 CONTRIBUTING.md、安全策略 SECURITY.md，以及各功能模块的源码目录本身。

八、从 OpenClaw 迁移

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

首次安装时：安装向导（hermes setup）会自动检测 ~/.openclaw 并在配置开始前提供迁移选项。这一点在源码中有直接佐证——agent/onboarding.py 中的 openclaw_residue_hint_cli() 会在 Hermes 首次启动且发现 ~/.openclaw/ 目录时打印横幅，引导先运行 hermes claw migrate（非破坏性地搬运配置、记忆与技能），完成迁移后可选运行 hermes claw cleanup（将旧目录重命名为 ~/.openclaw.pre-migration 归档）；detect_openclaw_residue() 负责检测残留目录。

安装后任意时间执行：

hermes claw migrate              # 交互式迁移（完整预设）
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/；
• 命令白名单 — 审批模式；
• 消息设置 — 平台配置、允许用户、工作目录；
• API 密钥 — 白名单中的密钥（Telegram、OpenRouter、OpenAI、Anthropic、ElevenLabs）；
• TTS 资产 — 工作区音频文件；
• 工作区指令 — AGENTS.md（使用 --workspace-target）。

使用 hermes claw migrate --help 查看所有选项；也可以让代理引导式迁移（含干运行预览）。

九、贡献与二次开发

欢迎贡献。开发设置、代码风格和 PR 流程见 CONTRIBUTING.md 及官方文档站的 "贡献" 章节。

贡献者快速开始——使用标准安装器，然后在它创建的完整 git checkout 中开发（$HERMES_HOME/hermes-agent，通常是 ~/.hermes/hermes-agent），该布局与 hermes update、托管 venv、lazy dependencies、gateway 和 docs tooling 保持一致：

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 / CI，或你明确不想使用 managed install layout 时）：

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]"
python -m pytest tests/ -q

从源码结构看，手动路径要求 Python 3.11（与仓库根目录的 .python-version 约定一致）；.[all,dev] 扩展组合覆盖了平台相关的完整依赖与开发工具链，这也解释了 Termux 上为何改用精选的 .[termux] 子集。

十、社区与许可证

• 社区交流：Nous Research 官方 Discord 频道；
• 技能中心：agentskills.io 开放标准（Hermes 技能系统兼容该标准，技能文件导入目录约定为 ~/.hermes/skills/openclaw-imports/ 等）；
• 问题反馈与讨论：项目官方 issue 与 discussions 区；
• 社区桥接：HermesClaw 项目（社区维护的微信桥接，可在同一微信账号上同时运行 Hermes Agent 和 OpenClaw）。

许可证为 MIT，详见 LICENSE。本项目由 Nous Research 构建。

小结

Hermes Agent 的实践路径可以压缩为四步：一条 curl 命令完成安装 → hermes setup（或 hermes setup --portal）一次性配置模型与工具路由 → 按需 hermes gateway 打通 Telegram/Discord 等消息入口 → 用 hermes claw migrate 无缝承接 OpenClaw 存量数据。理解其"窄腰核心 + 边缘扩展"的架构与"提示缓存神圣"的铁律后，再对照 agent/ 下的模块地图，任何功能——从 /compress 到 Tool Gateway、从技能学习到轨迹压缩——都能在源码中找到明确落点，这为二次开发、插件扩展与问题定位提供了清晰的路径。