Hermes Agent 完整使用指南

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

项目概览
安装部署
初始配置
CLI 基本使用
核心功能详解
- 5.1 工具与工具集
- 5.2 技能系统
- 5.3 持久化记忆
- 5.4 上下文文件
- 5.5 子代理委派
- 5.6 代码执行
- 5.7 定时任务 Cron
- 5.8 检查点与回滚
终端后端
消息平台集成
语音模式
浏览器自动化
MCP 集成
个性化定制
安全机制
高级配置参考
实战应用案例
常见问题 FAQ

Hermes Agent 不是绑定在 IDE 上的编码助手，也不是单纯包装 API 的聊天机器人。它是一个自主代理（Autonomous Agent），运行时间越长就越强大。

核心特性

学习闭环：代理策管的记忆 + 自主技能创建 + 使用中技能自我改进 + FTS5 跨会话召回 + Honcho 辩证用户建模
可部署任何环境：6 种终端后端——本地、Docker、SSH、Daytona、Singularity、Modal；Daytona 和 Modal 提供无服务器持久化，空闲时几乎零成本
多平台即时通讯：CLI、Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、Email、SMS、DingTalk、飞书、企业微信、BlueBubbles、Home Assistant 等 15+ 平台
47 个内置工具：覆盖网页搜索、终端执行、文件编辑、记忆管理、浏览器自动化、图像生成、TTS 等
技能标准开放：兼容 agentskills.io 开放标准，技能可移植、共享
支持并行子代理：最多同时运行 3 个隔离子代理
MCP 协议支持：连接任意 MCP 服务器扩展工具能力
RL 训练就绪：批处理、轨迹导出、Atropos 强化学习训练

2.1 一键安装（推荐）

Linux / macOS / WSL2：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装脚本会自动处理所有依赖（Python 3.11、Node.js v22、ripgrep、ffmpeg）、仓库克隆、虚拟环境创建、全局 hermes 命令设置，以及 LLM 提供商配置。

Android / Termux：

同样使用上述命令，安装脚本会自动检测 Termux 环境并切换到专用 Android 安装流程。

⚠️ Windows：不支持原生 Windows，请安装 WSL2 后在 WSL2 内运行。

2.2 安装完成后

source ~/.bashrc # 或 source ~/.zshrc hermes # 开始聊天！

2.3 手动安装

如果需要完全控制安装过程：

# 1. 安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 克隆仓库 git clone –recurse-submodules https://github.com/NousResearch/hermes-agent.git cd hermes-agent

# 3. 创建虚拟环境 uv venv venv –python 3.11 export VIRTUAL_ENV=“$(pwd)/venv”

# 4. 安装依赖（全量安装） uv pip install -e “.[all]”

# 5. 可选：Node.js 依赖（浏览器自动化和 WhatsApp） npm install

# 6. 创建配置目录 mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session} cp cli-config.yaml.example ~/.hermes/config.yaml touch ~/.hermes/.env

# 7. 添加 API 密钥 echo ‘OPENROUTER_API_KEY=sk-or-v1-your-key’ >> ~/.hermes/.env

# 8. 全局可用 mkdir -p ~/.local/bin ln -sf “$(pwd)/venv/bin/hermes” ~/.local/bin/hermes

# 9. 验证 hermes doctor hermes

2.4 可选依赖包一览

额外包功能安装命令 all 安装全部 uv pip install -e “.[all]” messaging Telegram 和 Discord 网关 uv pip install -e “.[messaging]” cron 定时任务表达式解析 uv pip install -e “.[cron]” modal Modal 云执行后端 uv pip install -e “.[modal]” tts-premium ElevenLabs 高级语音 uv pip install -e “.[tts-premium]” voice CLI 麦克风输入 + 音频播放 uv pip install -e “.[voice]” honcho AI 原生记忆（Honcho 集成） uv pip install -e “.[honcho]” mcp Model Context Protocol 支持 uv pip install -e “.[mcp]” slack Slack 消息 uv pip install -e “.[slack]” termux Android/Termux 专用包 python -m pip install -e “.[termux]”

可组合使用：uv pip install -e “.[messaging,cron,mcp]”

3.1 目录结构

~/.hermes/ ├── config.yaml # 主配置文件（模型、终端、TTS、压缩等） ├── .env # API 密钥和秘密 ├── auth.json # OAuth 提供商凭证 ├── SOUL.md # 代理主要身份（系统提示词第一位） ├── memories/ # 持久化记忆（MEMORY.md、USER.md） ├── skills/ # 代理创建的技能 ├── cron/ # 定时任务 ├── sessions/ # 网关会话 └── logs/ # 日志（自动脱敏）

3.2 配置管理命令

hermes config # 查看当前配置 hermes config edit # 编辑器打开 config.yaml hermes config set KEY VAL # 设置特定值 hermes config check # 检查缺失选项 hermes config migrate # 交互式添加缺失选项

hermes model # 选择 LLM 提供商和模型 hermes tools # 配置启用的工具 hermes gateway setup # 设置消息平台 hermes setup # 完整设置向导

3.3 配置优先级

优先级从高到低：

CLI 参数 — 如 hermes chat –model anthropic/claude-sonnet-4
/.hermes/config.yaml — 主配置文件
/.hermes/.env — 环境变量，API 密钥必须存放于此
内置默认值

经验法则：秘密信息（API 密钥、令牌、密码）放 .env。其他所有内容放 config.yaml。

3.4 支持的 LLM 提供商

Hermes 兼容多种提供商：

OpenRouter — 路由到数百个模型（推荐入门）
Nous Portal — Nous Research 官方门户
Anthropic — Claude 系列
OpenAI — GPT 系列
Codex — ChatGPT OAuth 方式
自定义端点 — 任何 OpenAI 兼容 API（本地模型、Ollama、vLLM 等）

hermes # 启动交互式聊天 hermes chat -q “你好！” # 单次查询 hermes chat –model openai/gpt-4o -q “解释量子计算” # 指定模型

# 常用斜杠命令 /help # 帮助信息 /tools # 查看可用工具 /skills # 查看已安装技能 /memory # 查看记忆内容 /voice on # 启用语音模式 /verbose # 切换工具输出详细度 /reasoning high # 设置推理强度 /rollback # 回滚到上一个检查点 /clear # 清除当前会话 /exit # 退出

上下文引用（@ 语法）

在消息中输入 @ 后跟引用即可注入外部内容：

@file.py # 注入文件内容 @src/ # 注入目录结构 @git:diff # 注入 git 差异 @https://url.com # 注入网页内容

5.1 工具与工具集（Tools & Toolsets）

Hermes 内置 47 个工具，按逻辑分组为工具集：

工具集包含工具示例 terminal 终端命令执行 file 文件读写、编辑、搜索 web 网页搜索、网页提取、网页爬取 browser 浏览器导航、截图、表单填写 memory 记忆管理、会话搜索 skills 技能列表、查看、创建、管理 delegation 子代理任务委派 code_execution Python 沙盒代码执行 media 图像生成、TTS、视觉分析 cron 定时任务管理

通过 hermes tools 配置启用/禁用各工具集。

5.2 技能系统（Skills）

技能是代理按需加载的知识文档，遵循渐进式披露模式以最小化 token 消耗。

使用方式：

# 作为斜杠命令使用 /gif-search funny cats /axolotl help me fine-tune Llama 3 /plan design a rollout for auth migration

# 通过对话自然触发 “你有什么技能？”

渐进式加载层次：

层级调用内容 Level 0 skills_list() 名称、描述、分类概览（ 3k tokens） Level 1 skill_view(name) 完整内容 + 元数据 Level 2 skill_view(name, path) 特定参考文件

技能目录： /.hermes/skills/

代理可以自主创建和改进技能——当它发现某个流程值得记录时，会自动将其保存为可复用的技能。

SKILL.md 格式示例：

— name: my-skill description: 简要描述技能功能 version: 1.0.0 platforms: [macos, linux] metadata: hermes:

tags: [python, automation] category: devops

—

# 技能标题

When to Use 触发条件

Procedure

步骤一
步骤二

Pitfalls - 已知故障模式和修复

Verification 确认生效的方法

5.3 持久化记忆（Memory）

Hermes 的记忆由两个文件组成，持久化于 ~/.hermes/memories/：

文件用途字符限制 MEMORY.md 代理个人笔记——环境事实、约定、经验教训 2,200 字符（~800 tokens） USER.md 用户画像——偏好、沟通风格、期望 1,375 字符（~500 tokens）

记忆工作方式：

两个文件在会话启动时作为冻结快照注入系统提示词
代理通过 memory 工具管理记忆（add、replace、remove）
代理会主动保存学到的信息，无需用户要求
记忆写入即时持久化到磁盘，但在当前会话的系统提示词中不变（下次会话生效）
包含安全扫描，防止注入攻击

代理自动保存的内容示例：

用户偏好：“我偏好 TypeScript”
环境事实：“该服务器运行 Debian 12 + PostgreSQL 16”
纠正：“Docker 命令不需要 sudo”
编码约定：“项目使用 tabs、120 字符行宽”

会话搜索（session_search）：

除了 MEMORY.md 和 USER.md，代理还能通过 FTS5 全文搜索回顾所有历史会话。

5.4 上下文文件（Context Files）

Hermes 自动发现并加载多种项目上下文文件：

文件用途 SOUL.md 代理主要身份，占系统提示词第一位 .hermes.md / HERMES.md 项目特定指令（最高优先级） AGENTS.md 项目特定指令、编码约定（支持子目录层级合并） CLAUDE.md Claude Code 上下文文件 .cursorrules Cursor IDE 规则

优先级：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules（仅加载第一个匹配）。SOUL.md 始终独立加载。

5.5 子代理委派（Delegation）

delegate_task 工具可以派生子代理实例，具有隔离的上下文、受限的工具集和独立的终端会话。

最多同时运行 3 个并行子代理
子代理可以使用不同的模型（如用便宜模型处理子任务）
配置示例：

delegation: model: “google/gemini-3-flash-preview” provider: “openrouter”

5.6 代码执行（Code Execution）

execute_code 工具让代理编写 Python 脚本，通过沙盒 RPC 调用 Hermes 工具，将多步骤工作流合并为单次 LLM 推理。

code_execution: timeout: 300 max_tool_calls: 50

5.7 定时任务 Cron

支持自然语言或 cron 表达式调度任务。任务可以附加技能，将结果推送到任意消息平台。

# 在对话中 “每天早上 8 点给我发送天气预报到 Telegram” “每周一生成项目进度报告”

5.8 检查点与回滚（Checkpoints）

Hermes 在执行破坏性文件操作前自动创建文件系统快照。

checkpoints: enabled: true max_snapshots: 50

使用 /rollback 命令回滚到之前的状态。

Hermes 支持 6 种终端后端，决定代理的 Shell 命令在哪里执行：

后端执行位置隔离级别适用场景 local 本地机器无开发、个人使用 docker Docker 容器完全隔离安全沙盒、CI/CD ssh 远程服务器网络边界远程开发、强力硬件 modal Modal 云沙盒完全隔离（云 VM）临时云计算、评估 daytona Daytona 工作空间完全隔离（云容器）托管云开发环境 singularity Singularity 容器命名空间隔离 HPC 集群、共享机器

配置示例：

terminal: backend: docker docker_image: “nikolaik/python-nodejs:python3.11-nodejs20” container_cpu: 1 container_memory: 5120 container_persistent: true timeout: 180

Docker 后端安全加固：

–cap-drop ALL，仅恢复 DAC_OVERRIDE、CHOWN、FOWNER
–security-opt no-new-privileges
–pids-limit 256
大小受限的 tmpfs

Hermes 支持 15+ 消息平台，通过统一消息网关接入：

平台特性 Telegram 完整支持，含语音消息、文件、流式编辑 Discord 服务器频道、DM、语音频道、线程 Slack 频道、线程、应用集成 WhatsApp 通过 WhatsApp Web 桥接 Signal 安全消息 Matrix 去中心化协议 Email IMAP/SMTP SMS 短信 DingTalk / 飞书 / 企业微信 国内企业通讯平台 Home Assistant 智能家居集成

设置命令：

hermes gateway setup # 交互式设置 hermes gateway start # 启动网关

群聊会话隔离：

group_sessions_per_user: true # 每个用户独立会话（默认推荐）

Hermes 支持完整的语音交互，覆盖 CLI 和消息平台。

CLI 语音：

/voice on # 启用麦克风模式 /voice tts # 开启语音回复

TTS 提供商：

提供商说明 Edge TTS 免费，322 种声音，74 种语言 ElevenLabs 高质量高级语音 OpenAI TTS GPT-4o-mini-tts NeuTTS 本地运行

STT 提供商： local（faster-whisper）、groq、openai

配置：

tts: provider: “edge” edge:

voice: "zh-CN-XiaoxiaoNeural" # 中文语音示例

voice: record_key: “ctrl+b” max_recording_seconds: 120

stt: provider: “local” local:

model: "base"

支持多后端浏览器自动化：Browserbase 云、Browser Use 云、本地 Chrome CDP、本地 Chromium。

能力包括：

网页导航和截图
表单填写
信息提取
视觉分析（配合多模态模型）

browser: inactivity_timeout: 120 command_timeout: 30 record_sessions: false

Hermes 可以连接任意 MCP（Model Context Protocol）服务器，通过 stdio 或 HTTP 传输协议访问外部工具。

功能包括：

连接 GitHub、数据库、文件系统、内部 API 等
无需编写原生 Hermes 工具
支持每服务器工具过滤和采样

SOUL.md — 代理身份

/.hermes/SOUL.md 定义代理的核心身份，是系统提示词的第一部分。完全可自定义。

人格预设

使用 /personality 命令切换预设人格，或在 SOUL.md 中完全自定义。

皮肤与主题

display: skin: default # 内置或自定义 CLI 皮肤 compact: false

插件

将自定义工具、钩子、集成放入 /.hermes/plugins/ 目录，包含 plugin.yaml 和 Python 代码。

命令审批

approvals: mode: manual # manual | smart | off

manual：执行任何危险命令前提示用户
smart：使用辅助 LLM 评估命令风险，低风险自动批准
off：跳过所有审批（仅用于可信沙盒环境）

秘密信息脱敏

security: redact_secrets: true

自动检测并脱敏工具输出和日志中的 API 密钥、令牌、密码。

Tirith 安全扫描

终端命令执行前通过 Tirith 扫描，检测潜在危险操作。

网站黑名单

security: website_blocklist:

enabled: true domains: - "*.internal.company.com" - "admin.example.com"

记忆安全扫描

记忆条目在接受前会扫描注入和数据泄露模式。

上下文压缩

长对话自动压缩以保持在模型上下文窗口内：

compression: enabled: true threshold: 0.50 target_ratio: 0.20 protect_last_n: 20 summary_model: “google/gemini-3-flash-preview” summary_provider: “auto”

辅助模型

图像分析、网页摘要、浏览器截图分析等旁路任务使用轻量级辅助模型：

auxiliary: vision:

provider: "auto" model: ""

web_extract:

provider: "auto" timeout: 360

凭证池

多个 API 密钥轮换策略：

credential_pool_strategies: openrouter: round_robin # fill_first | round_robin | least_used | random

推理强度

agent: reasoning_effort: “” # none | minimal | low | medium | high | xhigh max_turns: 90

流式输出

display: streaming: true show_reasoning: true

streaming: enabled: true transport: edit edit_interval: 0.3

网页搜索后端

web: backend: firecrawl # firecrawl | parallel | tavily | exa

隐私保护

privacy: redact_pii: false # 从 LLM 上下文中脱敏 PII（网关专用）

快速命令

定义零 token 消耗的自定义命令：

quick_commands: status:

type: exec command: systemctl status hermes-agent

disk:

type: exec command: df -h /

gpu:

type: exec command: nvidia-smi --query-gpu=name,utilization.gpu,memory.used --format=csv,noheader

案例 1：个人编程助手

# 在项目目录中启动 cd ~/projects/my-app hermes

# 对话 “分析 src/ 目录的代码结构并给出改进建议” “重构 auth 模块，使用 JWT 替换 session-based auth” “为所有 API 端点编写单元测试”

案例 2：远程服务器管理

# config.yaml terminal: backend: ssh

# 通过 Telegram 远程管理 “检查服务器磁盘使用情况” “重启 nginx 服务” “查看最近的错误日志”

案例 3：自动化工作流

# 设置定时任务 “每天早上 9 点搜索 Hacker News 上关于 AI 的最新文章，生成摘要发送到 Telegram”

# 并行处理 “同时搜索三个竞品的定价页面，整理成对比表格”

案例 4：知识管理

# 技能创建 “基于我们刚才的部署流程，创建一个可复用的技能”

# 跨会话记忆 “上周我们讨论过的数据库迁移方案是什么？”

案例 5：Docker 安全沙盒开发

terminal: backend: docker docker_image: “nikolaik/python-nodejs:python3.11-nodejs20” container_persistent: true docker_volumes:

- "/home/user/projects:/workspace/projects"

“安装 TensorFlow 并运行 benchmark 测试” # 完全隔离，不影响宿主机环境

Q：hermes: command not found
A：重新加载 Shell（source /.bashrc），或检查 /.local/bin 是否在 PATH 中。

Q：API key not set
A：运行 hermes model 配置提供商，或 hermes config set OPENROUTER_API_KEY your_key。

Q：更新后配置缺失
A：运行 hermes config check 然后 hermes config migrate。

Q：如何更新 Hermes？
A：

cd ~/.hermes/hermes-agent # 或你克隆仓库的位置 git pull uv pip install -e “.[all]”

Q：如何完全诊断问题？
A：运行 hermes doctor，它会告诉你缺少什么以及如何修复。

Q：支持哪些模型？
A：通过 OpenRouter 支持数百个模型，也可以使用任何 OpenAI 兼容 API（包括本地部署的 Ollama、vLLM 等）。

Q：如何降低成本？
A：使用便宜的模型（如 Gemini Flash）作为辅助任务模型；使用 delegation 让子代理使用更便宜的模型；启用上下文压缩减少 token 消耗。

📖 官方文档：https://hermes-agent.nousresearch.com/docs
💻 GitHub 仓库：https://github.com/NousResearch/hermes-agent
🎯 技能中心：https://agentskills.io
💬 Discord 社区：https://discord.gg/NousResearch
🏢 Nous Research：https://nousresearch.com