Hermes Agent 官方入门指南

9 章 · 约 39 千字

第一章：Hermes Agent概述
第二章：Hermes Agent安装
第三章：Hermse Agent 上下文文件
第四章：Hermes Agent——Persistent Memory
第五章：Hermes Agent工具与工具集
第六章：Hermes Agent的Skills System
第七章：Learning Path
安卓系统上使用Termux的Hermes
Hermes Agent更新与卸载

第一章：Hermes Agent概述

Hermes Agent 具备丰富的功能，远远超越了基本的聊天功能。从持久记忆和文件感知上下文到浏览器自动化和语音对话，这些功能共同作用，使 Hermes 成为一个强大的自主助手

核心

工具与工具集 — 工具是扩展代理能力的功能。它们被组织成逻辑工具集，可按平台启用或禁用，涵盖网络搜索、终端执行、文件编辑、内存、委托等。

技能系统 — 按需知识文档，代理可在需要时加载。技能遵循渐进式披露模式，以尽量减少令牌使用，并与 agentskills.io 开放标准兼容。

持久内存 — 有界的、经过整理的内存，可在会话之间持久存在。Hermes 会记住你的偏好、项目、环境以及通过和学到的东西。 MEMORY.mdUSER.md

上下文文件 — Hermes会自动发现并加载项目上下文文件（.hermes.md、AGENTS.md、CLAUDE.md、SOUL.md、cursorrules），这些文件决定了它在您项目中的行为方式。 .hermes.md、AGENTS.md、CLAUDE.md、SOUL.md、cursorrules

上下文引用 — 类型后面跟一个引用，可直接将文件、文件夹、git差异和URL注入到您的消息中。Hermes会内联展开引用并自动追加内容。 @

检查点 — Hermes在进行文件更改之前会自动对工作目录进行快照，为你提供一个安全网，以便在出现问题时可以回滚。 /回滚

自动化

计划任务（Cron） — 使用自然语言或cron表达式安排任务自动运行。作业可以附加技能，将结果发送到任何平台，并支持暂停/恢复/编辑操作。

子代理委派 — 该工具会生成具有独立上下文、受限工具集和自己的终端会话的子代理实例。最多可运行3个并发子代理以处理并行工作流。委派任务

代码执行 — 该工具允许代理编写Python脚本，以编程方式调用Hermes工具，通过沙盒化的RPC执行将多步骤工作流合并为单个大语言模型回合。 execute_code

事件钩子 — 在关键生命周期点运行自定义代码。网关钩子处理日志记录、警报和 Webhook；插件钩子处理工具拦截、指标和护栏。

批量处理 — 并行运行 Hermes 代理，处理成百上千个提示，生成结构化的 ShareGPT 格式轨迹数据，用于训练数据生成或评估。

媒体与网络

语音模式 — 在CLI和消息平台上实现全面语音交互。使用麦克风与代理对话，听取语音回复，并在Discord语音频道中进行实时语音对话。

浏览器自动化 — 支持多后端的全浏览器自动化：Browserbase云、Browser Use云、通过CDP的本地Chrome或本地Chromium。浏览网站、填写表单并提取信息。

视觉与图像粘贴 — 多模态视觉支持。将剪贴板中的图像粘贴到 CLI 中，并要求智能体使用任何具备视觉能力的模型对其进行分析、描述或处理。

图像生成 — 使用 FAL.ai 的 FLUX 2 Pro 模型，通过文本提示生成图像，并通过 Clarity Upscaler 自动进行 2 倍超分辨率处理。

语音与TTS — 跨所有消息平台的文本转语音输出和语音消息转录，有五个供应商选项：Edge TTS（免费）、ElevenLabs、OpenAI TTS、MiniMax和NeuTTS。

集成

MCP集成 — 通过标准输入输出或HTTP传输连接到任何MCP服务器。无需编写原生Hermes工具即可访问GitHub上的外部工具、数据库、文件系统和内部API。包括按服务器进行工具过滤和采样支持。

供应商路由 — 对哪些AI供应商处理您的请求进行细粒度控制。通过排序、白名单、黑名单和优先级排序，针对成本、速度或质量进行优化。

备用提供商 — 当您的主模型遇到错误时，自动故障转移到备用大语言模型（LLM）提供商，包括针对视觉和压缩等辅助任务的独立备用。

凭证池 — 跨同一提供商的多个密钥分发 API 调用。在达到速率限制或发生故障时自动轮换。

内存提供程序 — 插入外部内存后端（Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover），以实现跨会话用户建模和超越内置内存系统的个性化。

API服务器 — 将Hermes作为兼容OpenAI的HTTP端点公开。连接任何支持OpenAI格式的前端 — Open WebUI、LobeChat、LibreChat等等。

IDE集成（ACP） — 在与ACP兼容的编辑器（如VS Code、Zed和JetBrains）中使用Hermes。聊天、工具活动、文件差异和终端命令都在编辑器内呈现。

强化学习训练 — 从智能体会话中生成轨迹数据，用于强化学习和模型微调。

定制

Personality & SOUL.md — 完全可定制的代理个性。是主要身份文件 — 系统提示中的第一项 — 你可以在每个会话中切换内置或自定义预设。 SOUL.md/personality

皮肤与主题 — 自定义CLI的视觉呈现：横幅颜色、加载动画的外观和动词、响应框标签、品牌文本以及工具活动前缀。

插件 — 添加自定义工具、钩子和集成，而无需修改核心代码。有三种插件类型：通用插件（工具/钩子）、内存提供程序（跨会话知识）和上下文引擎（替代上下文管理）。通过统一的交互式 UI 进行管理。 hermes 插件

第二章：Hermes Agent安装

安装

使用单行安装程序在两分钟内启动并运行 Hermes Agent，或按照手动步骤进行完全控制。

快速安装

Linux / macOS / WSL2

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

安卓 / Termux

现在，Hermes也提供了一个支持Termux的安装路径：

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

安装程序会自动检测Termux并切换到经过测试的安卓流程：

使用 Termux 软件包来处理系统依赖项（ git 、 python 、 nodejs 、 ripgrep 、 ffmpeg 、构建工具）

创建虚拟环境与 python-m venv

自动导出 ANDROID_API_LEVEL 用于 Android wheel 构建

安装一个精心挑选的 [termux] 额外组件，使用 pip

默认跳过未经测试的浏览器/WhatsApp引导程序

如果您需要完整的详细路径，请遵循专门的 Termux指南。

Windows

原生Windows 不支持。请安装 WSL2 并从那里运行Hermes Agent。上述安装命令在WSL2中有效。

安装程序的作用

安装程序会自动处理一切——所有依赖项（Python、Node.js、ripgrep、ffmpeg）、仓库克隆、虚拟环境、全局 hermes 命令设置以及大语言模型（LLM）提供商配置。完成后，你就可以开始聊天了。

安装后

重新加载你的shell并开始聊天：

source ~/.bashrc # or: source ~/.zshrc

hermes # Start chatting!

若要稍后重新配置个别设置，请使用专用命令：

hermes model # Choose your LLM provider and model

hermes tools # Configure which tools are enabled

hermes gateway setup # Set up messaging platforms

hermes config set # Set individual config values

hermes setup # Or run the full setup wizard to configure everything at once

先决条件

唯一的先决条件是 Git 。安装程序会自动处理其他所有事项：

UV （快速Python包管理器）

Python 3.11 （通过 UV，无需 sudo）

Node.js v22 （用于浏览器自动化和WhatsApp桥接）

ripgrep （快速文件搜索）

ffmpeg （用于TTS的音频格式转换）

信息

你无需手动安装 Python、Node.js、ripgrep 或 ffmpeg。安装程序会检测缺少的内容并为你安装。只需确保 git 可用（ git --version ）。

Nix用户

如果您使用 Nix（在 NixOS、macOS 或 Linux 上），有一个专门的设置路径，包含 Nix flake、声明式 NixOS 模块和可选的容器模式。请参阅《Nix 和 NixOS 设置》指南。

手动安装

如果您希望完全掌控安装过程，请按照以下步骤操作。

步骤1：克隆仓库

使用 --recurse-submodules 克隆以拉取所需的子模块：

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git

cd hermes-agent

如果您已经克隆但没有使用 --recurse-submodules ：

git submodule update --init --recursive

步骤2：安装UV并创建虚拟环境

Install uv (if not already installed)

curl -LsSf https://astral.sh/uv/install.sh | sh# Create venv with Python 3.11 (uv downloads it if not present — no sudo needed)

uv venv venv --python 3.11

提示

你不需要激活虚拟环境来使用 hermes 。入口点有一个硬编码的shebang指向虚拟环境的Python，因此一旦创建符号链接，它就可以全局使用。

步骤3：安装Python依赖项

Tell uv which venv to install into

export VIRTUAL_ENV="$(pwd)/venv"# Install with all extras

uv pip install -e ".[all]"

如果您只需要核心代理（不支持Telegram/Discord/cron）：

uv pip install -e "."

可选附加项明细

步骤4：安装可选子模块（如有需要）

RL training backend (optional)

uv pip install -e "./tinker-atropos"

两者都是可选的 —— 如果您跳过它们，相应的工具集将不会可用。

步骤5：安装Node.js依赖项（可选）

仅适用于浏览器自动化（由Browserbase驱动）和 WhatsApp桥接：

npm install

步骤6：创建配置目录

Create the directory structure

mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}

Copy the example config file

cp cli-config.yaml.example ~/.hermes/config.yaml

Create an empty .env file for API keys

touch ~/.hermes/.env

步骤7：添加您的API密钥

打开 ~/.hermes/.env 并至少添加一个大语言模型（LLM）提供商密钥：

Required — at least one LLM provider:

OPENROUTER_API_KEY=sk-or-v1-your-key-here

Optional — enable additional tools:

FIRECRAWL_API_KEY=fc-your-key # Web search & scraping (or self-host, see docs)

FAL_KEY=your-fal-key # Image generation (FLUX)

或者通过CLI设置它们：

hermes config set OPENROUTER_API_KEY sk-or-v1-your-key-here

步骤 8：将 hermes 添加到您的 PATH 环境变量中

mkdir -p ~/.local/bin

ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

如果 ~/.local/bin 不在您的PATH中，请将其添加到您的shell配置中：

Bash

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

Zsh

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Fish

fish_add_path $HOME/.local/bin

步骤9：配置您的提供商

hermes model # Select your LLM provider and model

步骤10：验证安装

hermes version # Check that the command is available

hermes doctor # Run diagnostics to verify everything is working

hermes status # Check your configuration

hermes chat -q "Hello! What tools do you have available?"

快速参考：手动安装（精简版）

对于那些只想知道命令的人：

Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh# Clone & enter

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git

cd hermes-agent

Create venv with Python 3.11

uv venv venv --python 3.11

export VIRTUAL_ENV="$(pwd)/venv"# Install everything

uv pip install -e ".[all]"

uv pip install -e "./tinker-atropos"

npm install # optional, for browser tools and WhatsApp# Configure

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

echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env

Make hermes available globally

mkdir -p ~/.local/bin

ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

Verify

hermes doctor

hermes

故障排除

问题

解决方案

hermes: 未找到命令

重新加载你的 shell（source ~/.bashrc）或检查 PATH

未设置 API 密钥

运行hermes模型来配置您的提供商，或者使用hermes config set OPENROUTER_API_KEY your_key

更新后缺少配置

运行hermes config check，然后运行hermes config migrate

如需更多诊断信息，请运行 hermes doctor — 它将准确告诉你缺少什么以及如何修复。

第三章：Hermse Agent 上下文文件

Hermes Agent 会自动发现并加载决定其行为方式的上下文文件。其中一些是项目本地的，从你的工作目录中发现。现在对 Hermes 实例是全局的，并且仅从加载。SOUL.mdHERMES_HOME

支持的上下文文件

文件

目的

发现

.hermes.md / HERMES.md

项目说明（最高优先级）

走到git根目录

AGENTS.md

项目说明、约定、架构

CLAUDE.md

Claude代码上下文文件（也已检测到）

SOUL.md

此爱马仕实例的全局个性和语气定制

仅HERMES_HOME/SOUL.md

.cursorrules

Cursor IDE编码规范

仅CWD

.cursor/rules/*.mdc

光标IDE规则模块

仅CWD

优先级系统

每个会话仅加载一种项目上下文类型（首次匹配优先）：→ → → 。 SOUL.md 始终作为代理身份独立加载（插槽 #1）。 .hermes.mdAGENTS.mdCLAUDE.md.cursorrules

AGENTS.md

AGENTS.md 是主要的项目上下文文件。它告诉代理你的项目是如何组织的，要遵循哪些约定，以及任何特殊说明。

渐进式子目录发现

会话开始时，Hermes会将工作目录中的文件加载到系统提示中。在会话期间，当代理导航到子目录（通过、、等）时，它会逐步发现这些目录中的上下文文件，并在它们变得相关时将其注入到对话中。 AGENTS.mdread_fileterminalsearch_files

my-project/

├── AGENTS.md ← Loaded at startup (system prompt)

├── frontend/

│ └── AGENTS.md ← Discovered when agent reads frontend/ files

├── backend/

│ └── AGENTS.md ← Discovered when agent reads backend/ files

└── shared/

└── AGENTS.md ← Discovered when agent reads shared/ files

与在启动时加载所有内容相比，这种方法有两个优点：

无系统提示冗余 — 子目录提示仅在需要时出现

提示缓存保留 —— 系统提示在各轮对话中保持稳定

每个子目录在每个会话中最多检查一次。发现过程还会向上遍历父目录，因此即使没有自己的上下文文件，读取也会发现。 backend/src/main.pybackend/AGENTS.mdbackend/src/

信息

子目录上下文文件与启动上下文文件一样，都要经过安全扫描。恶意文件会被拦截。

示例AGENTS.md

Project Context

This is a Next.js 14 web application with a Python FastAPI backend.

Architecture

Frontend: Next.js 14 with App Router in `/frontend`
Backend: FastAPI in `/backend`, uses SQLAlchemy ORM
Database: PostgreSQL 16
Deployment: Docker Compose on a Hetzner VPS

Conventions

Use TypeScript strict mode for all frontend code
Python code follows PEP 8, use type hints everywhere
All API endpoints return JSON with `{data, error, meta}` shape
Tests go in `__tests__/` directories (frontend) or `tests/` (backend)

Important Notes

Never modify migration files directly — use Alembic commands
The `.env.local` file has real API keys, don't commit it
Frontend port is 3000, backend is 8000, DB is 5432

SOUL.md

SOUL.md 控制代理的个性、语气和沟通风格。完整详情请参阅个性页面。

地点：

~/.hermes/SOUL.md

或者如果您使用自定义主目录运行 Hermes $HERMES_HOME/SOUL.md

重要细节：

如果默认的Hermes种子不存在，系统会自动生成一个 yetSOUL.md

Hermes仅从 SOUL.mdHERMES_HOME加载

Hermes 不会在工作目录中探查 SOUL.md

如果文件是空的，则不会将from添加到 promptSOUL.md

如果文件有内容，则在扫描和截断后逐字注入内容

.cursorrules

Hermes与Cursor IDE的文件和规则模块兼容。如果这些文件存在于项目根目录中，且未找到优先级更高的上下文文件（、或），则会将它们作为项目上下文加载。 .cursorrules.cursor/rules/*.mdc.hermes.mdAGENTS.mdCLAUDE.md

这意味着在使用 Hermes 时，您现有的光标约定会自动适用。

上下文文件的加载方式

启动时（系统提示）

上下文文件通过以下方式加载： build_context_files_prompt()agent/prompt_builder.py

扫描工作目录 — 检查是否存在 → → → （首次匹配成功） .hermes.mdAGENTS.mdCLAUDE.md.cursorrules

内容已读取 — 每个文件均以 UTF-8 文本形式读取

安全扫描 — 检查内容是否存在提示注入模式

截断 — 超过20,000字符的文件将进行首尾截断（头部70%，尾部20%，中间有标记）

汇编 — 所有部分都组合在一个标题下 #项目背景

注入 — 已组装的内容被添加到系统提示中

在会议期间（渐进式发现）

子目录提示跟踪器在文件路径的监视工具调用参数中： agent/subdirectory_hints.py

路径提取 — 在每次工具调用后，从参数（，，shell命令）中提取文件路径路径工作目录

祖先遍历 — 检查当前目录及其最多5个父目录（在已访问的目录处停止）

提示加载 — 如果找到、或，则加载它（每个目录的第一个匹配项） AGENTS.mdCLAUDE.md.cursorrules

安全扫描 — 与启动文件相同的提示注入扫描

截断 — 每个文件上限为8000字符

注入 — 附加到工具结果中，以便模型自然地在上下文中看到它

最终提示部分大致如下：

Project Context

The following project context files have been loaded and should be followed:

AGENTS.md

[Your AGENTS.md content here]

.cursorrules

[Your .cursorrules content here]

[Your SOUL.md content here]

请注意，SOUL内容是直接插入的，没有额外的包装文本。

安全：提示注入防护

所有上下文文件在被包含之前都会被扫描是否存在潜在的提示注入。扫描器会检查以下内容：

指令覆盖尝试：“忽略先前指令”，“无视你的规则”

欺骗模式：“不告诉用户”

系统提示覆盖 : "系统提示覆盖"

隐藏的HTML注释：

隐藏的 div 元素： <div style="display:none">

凭证窃取： curl... $API_KEY

秘密文件访问 :, cat.envcat credentials

不可见字符：零宽空格、双向覆盖符、连字符

如果检测到任何威胁模式，则该文件将被阻止：

[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]

警告

此扫描器可防范常见的注入模式，但它不能替代对共享存储库中上下文文件的审查。始终要验证非你所编写项目中的 AGENTS.md 内容。

尺寸限制

限制

值

每个文件的最大字符数

20,000（约7,000个标记）

头部截断比率

70%

尾部截断比率

20%

截断标记

10%（显示字符数并建议使用文件工具）

当文件超过20,000字符时，截断消息显示为：

[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]

有效上下文文件的提示

AGENTS最佳实践.md

保持简洁 —— 控制在20000字符以内；代理每轮都会读取

带标题的结构 — 使用章节来阐述架构、约定、重要说明 ##

包含具体示例 —— 展示首选的代码模式、API 形态、命名约定

提及不应该做的事情 — “切勿直接修改迁移文件”

列出关键路径和端口 — 代理使用这些来执行终端命令

随着项目的发展进行更新 —— 过时的上下文比没有上下文更糟糕

每个子目录上下文

对于单体仓库，请将特定子目录的说明放在嵌套的 AGENTS.md 文件中：

Frontend Context

Use `pnpm` not `npm` for package management
Components go in `src/components/`, pages in `src/app/`
Use Tailwind CSS, never inline styles
Run tests with `pnpm test`

Backend Context

Use `poetry` for dependency management
Run the dev server with `poetry run uvicorn main:app --reload`
All endpoints need OpenAPI docstrings
Database models are in `models/`, schemas in `schemas/`

第四章：Hermes Agent——Persistent Memory

Hermes Agent拥有有界的、经过整理的记忆，这些记忆会在不同会话中持续存在。这使得它能够记住你的偏好、你的项目、你的环境以及它所学过的东西。

工作原理

代理的记忆由两个文件组成：

文件

目的

字符限制

MEMORY.md

代理的个人笔记——环境事实、惯例、所学知识

2200字符（约800个词元）

用户手册

用户资料 — 您的偏好、沟通风格、期望

1375个字符（约500个词元）

两者都存储在系统提示中，并在会话开始时作为冻结快照注入系统提示。代理通过工具管理自己的内存——它可以添加、替换或删除条目。 ~/.hermes/memories/memory

信息

字符限制有助于集中内存。当内存满时，代理会合并或替换条目，以便为新信息腾出空间。

记忆如何在系统提示中呈现

在每个会话开始时，内存条目会从磁盘加载，并作为一个固定块渲染到系统提示中：

══════════════════════════════════════════════

MEMORY (your personal notes) [67% — 1,474/2,200 chars]

══════════════════════════════════════════════

User's project is a Rust web service at ~/code/myapi using Axum + SQLx

This machine runs Ubuntu 22.04, has Docker and Podman installed

User prefers concise responses, dislikes verbose explanations

格式包括：

显示哪个存储（内存或用户配置文件）的标题

使用百分比和字符计数，以便座席了解容量

由（章节符号）分隔符分隔的单个条目 §

条目可以是多行的

冻结快照模式：系统提示注入在会话开始时被捕获一次，且在会话期间不会改变。这是有意为之的——它保留了大语言模型（LLM）的前缀缓存以提高性能。当代理在会话期间添加/删除记忆条目时，更改会立即持久化到磁盘，但直到下一个会话开始才会出现在系统提示中。工具响应始终显示实时状态。

内存工具操作

代理使用这些操作来使用工具：内存

添加 — 添加新的记忆条目

替换 — 用更新后的内容替换现有条目（通过 old_text 进行子字符串匹配）

移除 — 移除不再相关的条目（通过 old_text 使用子字符串匹配）

无需操作 — 会话开始时，记忆内容会自动注入系统提示中。智能体将其记忆视为对话上下文的一部分。读取

子串匹配

这些操作使用简短的唯一子字符串匹配——你不需要完整的条目文本。参数只需是一个能准确识别一个条目的唯一子字符串即可：替换移除旧文本

If memory contains "User prefers dark mode in all editors"

memory(action="replace", target="memory",

old_text="dark mode",

content="User prefers light mode in VS Code, dark mode in terminal")

如果子字符串匹配多个条目，则会返回错误，要求进行更具体的匹配。

两个目标解析

记忆 — 智能体的个人笔记

关于代理需要记住的有关环境、工作流程和经验教训的信息：

环境信息（OS、工具、项目结构）

项目约定和配置

发现的工具怪癖和变通方法

已完成的任务日记条目

行之有效的技能和技巧

用户 — 用户资料

有关用户身份、偏好和沟通风格的信息：

姓名、角色、时区

沟通偏好（简洁与详细，格式偏好）

令人恼火的事和需要避免的事

工作流习惯

技术技能水平

该保存还是跳过

主动保存这些

智能体自动保存——你无需手动操作。它在学习时就会保存：

用户偏好： "比起 JavaScript，我更喜欢 TypeScript" → 保存到用户

环境信息： “此服务器运行Debian 12和PostgreSQL 16” → 保存到内存

修正内容： “不要用于 Docker 命令，用户已在 Docker 组中” → 保存到 sudo 内存

约定： “项目使用制表符，行宽120字符，采用Google风格的文档字符串” → 保存到内存

已完成工作： "2026年1月15日将数据库从MySQL迁移到PostgreSQL" → 保存到内存

明确请求： “记住我的 API 密钥每月轮换一次” → 保存到内存

跳过这些

琐碎/显而易见的信息： "用户询问了Python" — 过于模糊，没有用处

容易重新发现的事实： "Python 3.12支持f-string嵌套" —— 可以通过网络搜索到

原始数据转储：大代码块、日志文件、数据表 — 太大而无法放入内存

会话特定的临时数据：临时文件路径、一次性调试上下文

上下文文件中已有的信息： SOUL.md和AGENTS.md的内容

容量管理

内存有严格的字符限制，以确保系统提示在可控范围内：

商店

限制

典型条目

内存

2200个字符

8 - 15 项

用户

1375个字符

5 - 10 项

内存满了会发生什么

当您尝试添加一个会超出限制的条目时，该工具会返回一个错误：

{

"success": false,

"error": "Memory at 2,100/2,200 chars. Adding this entry (250 chars) would exceed the limit. Replace or remove existing entries first.",

"current_entries": ["..."],

"usage": "2,100/2,200"

}

代理随后应执行以下操作：

读取当前条目（显示在错误响应中）

识别可以移除或合并的条目

用于将相关条目合并为较短的版本替换

然后新的条目添加

最佳实践：当内存使用率超过80%（可在系统提示标题中查看）时，在添加新条目之前先合并现有条目。例如，将三个单独的“项目使用X”条目合并为一个全面的项目描述条目。

良好记忆条目实例

简洁、信息密集的条目效果最佳：

Good: Packs multiple related facts

User runs macOS 14 Sonoma, uses Homebrew, has Docker Desktop and Podman. Shell: zsh with oh-my-zsh. Editor: VS Code with Vim keybindings.

Good: Specific, actionable convention

Project ~/code/api uses Go 1.22, sqlc for DB queries, chi router. Run tests with 'make test'. CI via GitHub Actions.

Good: Lesson learned with context

The staging server (10.0.1.50) needs SSH port 2222, not 22. Key is at ~/.ssh/staging_ed25519.

Bad: Too vague

User has a project.

Bad: Too verbose

On January 5th, 2026, the user asked me to look at their project which is

located at ~/code/api. I discovered it uses Go version 1.22 and...

重复预防

内存系统会自动拒绝完全重复的条目。如果您尝试添加已存在的内容，系统将返回成功，并附带一条“未添加重复项”的消息。

安全扫描

内存条目在被接受之前会被扫描是否存在注入和数据外泄模式，因为它们会被注入到系统提示中。与威胁模式（提示注入、凭证外泄、SSH后门）匹配或包含不可见Unicode字符的内容将被阻止。

会话搜索

除了MEMORY.md和USER.md之外，代理还可以使用以下工具搜索其过往对话： session_search

所有CLI和消息会话都存储在支持FTS5全文搜索的SQLite中 ~/.hermes/state.db

搜索查询会返回相关的过往对话，并带有Gemini Flash摘要

即使几周前讨论的内容不在其活跃记忆中，智能体也能找到它们

hermes sessions list # Browse past sessions

会话搜索与内存

功能

持久内存

会话搜索

容量

总共约1300个词元

无限制（所有会话）

速度

即时（在系统提示中）

需要搜索+大语言模型总结

用例

关键事实随时可用

查找特定的过往对话

管理

由代理手动整理

自动 — 所有会话均已存储

代币成本

每次会话固定（约1300个词元）

按需（需要时搜索）

记忆用于存储始终应处于上下文之中的关键事实。会话搜索用于处理“我们上周是否讨论过X？”这类查询，在这类查询中，智能体需要回忆过去对话中的具体内容。

配置

In ~/.hermes/config.yaml

memory:

memory_enabled: true

user_profile_enabled: true

memory_char_limit: 2200 # ~800 tokens

user_char_limit: 1375 # ~500 tokens

外部内存提供程序

对于超越MEMORY.md和USER.md的更深入、持久的内存，Hermes附带8个外部内存提供程序插件，包括Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover和Supermemory。

外部供应商运行与内置内存并行（从不替代它），并增加了诸如知识图谱、语义搜索、自动事实提取和跨会话用户建模等功能。

hermes memory setup # pick a provider and configure it

hermes memory status # check what's active

请参阅内存提供程序指南，以了解每个提供程序的完整详细信息、设置说明和比较内容。

第五章：Hermes Agent工具与工具集

工具是扩展代理功能的函数。它们被组织成逻辑工具集，可以按平台启用或禁用。

可用工具

Hermes 附带了一个广泛的内置工具注册表，涵盖网络搜索、浏览器自动化、终端执行、文件编辑、内存、委托、强化学习训练、消息传递、Home Assistant 等功能。

注意

Honcho跨会话内存作为内存提供程序插件（）可用，而不是作为内置工具集。有关安装，请参阅插件。 plugins/memory/honcho/

高级类别：

类别

示例

描述

Web

网页搜索，网页提取

搜索网络并提取页面内容。

终端和文件

终端，进程读取文件补丁

执行命令并操作文件。

浏览器

browser_navigate,, browser_snapshotbrowser_vision

支持文本和视觉的交互式浏览器自动化。

媒体

vision_analyze,, image_generatetext_to_speech

多模态分析与生成。

代理编排

待办事项，澄清执行代码委托任务

规划、澄清、代码执行和子代理委派。

记忆与回忆

内存，会话搜索

持久内存和会话搜索。

自动化与交付

cronjob, send_message

具有创建/列出/更新/暂停/恢复/运行/删除操作的计划任务，以及出站消息传递。

集成

ha_*, MCP服务器工具, rl_*

Home Assistant、MCP、强化学习训练及其他集成。

有关权威的代码派生注册表，请参阅内置工具参考和工具集参考。

使用工具集

Use specific toolsets

hermes chat --toolsets "web,terminal"

See all available tools

hermes tools

Configure tools per platform (interactive)

hermes tools

常见工具集包括,,,,,,,,,,,,,,,,, 和。 webterminalfilebrowservisionimage_genmoaskillsttstodomemorysession_searchcronjobcode_executiondelegationclarifyhomeassistantrl

请参阅工具集参考以获取完整列表，包括平台预设（如、）和动态 MCP 工具集（如）。 hermes-clihermes-telegrammcp-<server>

终端后端

终端工具可以在不同环境中执行命令：

后端

描述

用例

本地

在您的机器上运行（默认）

开发、可信任务

docker

隔离容器

安全性、可重复性

ssh

远程服务器

沙箱化，使代理远离其自身代码

奇点

HPC容器

集群计算，无根

模态

云端执行

无服务器，可扩展

代托纳

云沙箱工作区

持久化远程开发环境

配置

In ~/.hermes/config.yaml

terminal:

backend: local # or: docker, ssh, singularity, modal, daytona

cwd: "." # Working directory

timeout: 180 # Command timeout in seconds

Docker后端

terminal:

backend: docker

docker_image: python:3.11-slim

SSH后端

安全推荐——代理无法修改自身代码：

terminal:

backend: ssh

Set credentials in ~/.hermes/.env

TERMINAL_SSH_HOST=my-server.example.com

TERMINAL_SSH_USER=myuser

TERMINAL_SSH_KEY=~/.ssh/id_rsa

Singularity/Apptainer

Pre-build SIF for parallel workers

apptainer build ~/python.sif docker://python:3.11-slim

Configure

hermes config set terminal.backend singularity

hermes config set terminal.singularity_image ~/python.sif

模态（无服务器云）

uv pip install modal

modal setup

hermes config set terminal.backend modal

容器资源

为所有容器后端配置CPU、内存、磁盘和持久性：

terminal:

backend: docker # or singularity, modal, daytona

container_cpu: 1 # CPU cores (default: 1)

container_memory: 5120 # Memory in MB (default: 5GB)

container_disk: 51200 # Disk in MB (default: 50GB)

container_persistent: true # Persist filesystem across sessions (default: true)

当安装的软件包、文件和配置在会话间保持不变。 container_persistent: true

容器安全

所有容器后端均采用安全强化措施运行：

只读根文件系统（Docker）

所有Linux功能已被移除

无权限提升

PID限制（256个进程）

完全命名空间隔离

通过卷实现持久化工作区，而非可写的根层

Docker可以选择通过接收显式env lowlist，但是转发的变量对容器内的命令是可见的，并且应该被视为暴露给该会话。 docker_forward_env

后台进程管理

启动后台进程并对其进行管理：

terminal(command="pytest -v tests/", background=true)

Returns: {"session_id": "proc_abc123", "pid": 12345}# Then manage with the process tool:

process(action="list") # Show all running processes

process(action="poll", session_id="proc_abc123") # Check status

process(action="wait", session_id="proc_abc123") # Block until done

process(action="log", session_id="proc_abc123") # Full output

process(action="kill", session_id="proc_abc123") # Terminate

process(action="write", session_id="proc_abc123", data="y") # Send input

PTY模式()可启用像Codex和Claude Code这样的交互式CLI工具。 pty=true

超级用户支持

如果某个命令需要sudo权限，系统会提示您输入密码（会话期间会缓存）。或者在 .SUDO_PASSWORD~/.hermes/.env中设置。

警告

在消息传递平台上，如果sudo失败，输出将包含一个提示，要求添加到 .SUDO_PASSWORD~/.hermes/.env

第六章：Hermes Agent的Skills System

Skills是按需提供的知识文档，代理可以在需要时加载。它们遵循渐进式披露模式，以最大限度地减少令牌使用，并与 agentskills.io 开放标准兼容。

所有Skills都存放在 ~/.hermes/skills/ —— 这是主要目录和事实来源。全新安装时，捆绑的技能会从仓库复制过来。通过中心安装和代理创建的技能也会存放在这里。代理可以修改或删除任何技能。

您还可以将 Hermes 指向外部技能目录 —— 与本地目录一起扫描的其他文件夹。请参阅外部技能目录（如下）。

另见：

捆绑技能目录

官方可选技能目录

使用技能

每个已安装的技能都会自动作为斜杠命令可用：

In the CLI or any messaging platform:

/gif-search funny cats

/axolotl help me fine-tune Llama 3 on my dataset

/github-pr-workflow create a PR for the auth refactor

/plan design a rollout for migrating our auth provider

Just the skill name loads it and lets the agent ask what you need:

/excalidraw

捆绑技能是具有自定义行为的技能支持斜杠命令的一个很好的例子。运行该命令会告诉Hermes在必要时检查上下文，编写一个Markdown实现计划而不是执行任务，并将结果保存到相对于活动工作区/后端工作目录的位置。 plan/plan [request].hermes/plans/

您还可以通过自然对话与技能进行交互：

hermes chat --toolsets skills -q "What skills do you have?"

hermes chat --toolsets skills -q "Show me the axolotl skill"

渐进式披露

技能采用了一种高效利用令牌的加载模式：

Level 0: skills_list() → [{name, description, category}, ...] (~3k tokens)

Level 1: skill_view(name) → Full content + metadata (varies)

Level 2: skill_view(name, path) → Specific reference file (varies)

代理仅在实际需要时才加载完整的技能内容。

SKILL.md格式

---

name: my-skill

description: Brief description of what this skill does

version: 1.0.0

platforms: [macos, linux] # Optional — restrict to specific OS platforms

metadata:

hermes:

tags: [python, automation]

category: devops

fallback_for_toolsets: [web] # Optional — conditional activation (see below)

requires_toolsets: [terminal] # Optional — conditional activation (see below)

config: # Optional — config.yaml settings

key: my.setting

description: "What this controls"

default: "value"

prompt: "Prompt for setup"

---

Skill Title

When to Use

Trigger conditions for this skill.

Procedure

1. Step one

2. Step two

Pitfalls

Known failure modes and fixes

Verification

How to confirm it worked.

特定平台技能

技能可以使用以下字段将自身限制在特定的操作系统上：平台

值

匹配项

macos

macOS (Darwin)

linux

Linux

windows

Windows

platforms: [macos] # macOS only (e.g., iMessage, Apple Reminders, FindMy)

platforms: [macos, linux] # macOS and Linux

设置后，该技能会自动在系统提示、不兼容平台的斜杠命令中隐藏。如果省略，则该技能会在所有平台上加载。技能列表()

条件激活（备用技能）

技能可以根据当前会话中可用的工具自动显示或隐藏。这对于备用技能最为有用，备用技能是免费或本地的替代方案，仅在高级工具不可用时才会出现。

metadata:

hermes:

fallback_for_toolsets: [web] # Show ONLY when these toolsets are unavailable

requires_toolsets: [terminal] # Show ONLY when these toolsets are available

fallback_for_tools: [web_search] # Show ONLY when these specific tools are unavailable

requires_tools: [terminal] # Show ONLY when these specific tools are available

字段

行为

工具集回退

当列出的工具集可用时，技能会被隐藏；当它们缺失时，则会显示。

工具的回退

相同，但检查单个工具而非工具集。

需要工具集

当列出的工具集不可用时，技能将被隐藏；当它们存在时，则会显示。

需要工具

相同，但检查单个工具。

示例：内置技能使用。当你设置好后，网络工具集可用，代理使用——DuckDuckGo技能保持隐藏。如果API密钥缺失，网络工具集不可用，DuckDuckGo技能会自动作为备用技能出现。 duckduckgo-searchfallback_for_toolsets: [web]FIRECRAWL_API_KEYweb_search

没有任何条件字段的技能的行为与之前完全相同——它们始终显示。

加载时安全设置

技能可以声明所需的环境变量，而不会在发现过程中消失：

required_environment_variables:

name: TENOR_API_KEY

prompt: Tenor API key

help: Get a key from https://developers.google.com/tenor

required_for: full functionality

当遇到缺失值时，Hermes仅在技能实际加载到本地CLI中时才会安全地请求该值。您可以跳过设置并继续使用该技能。消息界面在聊天中从不询问机密信息，而是提示您使用或在本地使用。 hermes setup~/.hermes/.env

一旦设置，声明的环境变量将自动传递到沙箱中，技能脚本可以直接使用。对于非技能环境变量，请使用配置选项。详情请参阅环境变量传递。 execute_codeterminal$TENOR_API_KEYterminal.env_passthrough

技能配置设置

技能还可以声明存储在以下位置的非机密配置设置（路径、首选项）： config.yaml

metadata:

hermes:

config:

key: wiki.path

description: Path to the wiki directory

default: "~/wiki"

prompt: Wiki directory path

设置存储在您的config.yaml中。提示未配置的设置，并显示它们。当技能加载时，其解析的配置值会被注入到上下文中，以便代理自动知道已配置的值。技能配置hermes配置迁移hermes配置显示

详情请参阅技能设置和创建技能 - 配置设置。

技能目录结构

~/.hermes/skills/ # Single source of truth

├── mlops/ # Category directory

│ ├── axolotl/

│ │ ├── SKILL.md # Main instructions (required)

│ │ ├── references/ # Additional docs

│ │ ├── templates/ # Output formats

│ │ ├── scripts/ # Helper scripts callable from the skill

│ │ └── assets/ # Supplementary files

│ └── vllm/

│ └── SKILL.md

├── devops/

│ └── deploy-k8s/ # Agent-created skill

│ ├── SKILL.md

│ └── references/

├── .hub/ # Skills Hub state

│ ├── lock.json

│ ├── quarantine/

│ └── audit.log

└── .bundled_manifest # Tracks seeded bundled skills

外部技能目录

如果你在Hermes之外维护技能（例如，多个AI工具使用的共享目录），你也可以告诉Hermes扫描这些目录。 ~/.agents/skills/

在以下部分添加： external_dirsskills~/.hermes/config.yaml

skills:

external_dirs:

~/.agents/skills
/home/shared/team-skills
${SKILLS_REPO}/skills

路径支持扩展和环境变量替换。 ~${VAR}

工作原理

只读：仅扫描外部目录以发现技能。当代理创建或编辑技能时，它总是写入 ~/.hermes/skills/

本地优先级：如果同一技能名称在本地目录和外部目录中都存在，则本地版本优先。

完全集成：外部技能会出现在系统提示索引中，并且以斜杠命令的形式呈现，与本地技能并无二致。技能列表技能视图/技能名称

不存在的路径会被默默跳过：如果配置的目录不存在，Hermes会忽略它而不报错。这对于可能并非每台机器上都存在的可选共享目录很有用。

示例

~/.hermes/skills/ # Local (primary, read-write)

├── devops/deploy-k8s/

│ └── SKILL.md

└── mlops/axolotl/

└── SKILL.md

~/.agents/skills/ # External (read-only, shared)

├── my-custom-workflow/

│ └── SKILL.md

└── team-conventions/

└── SKILL.md

所有四项技能都出现在您的技能索引中。如果您创建一个名为本地的新技能，它将覆盖外部版本。我的自定义工作流

代理管理技能（skill_manage工具）

智能体可以通过工具创建、更新和删除自己的技能。这就是智能体的程序性记忆 ——当它想出一个非平凡的工作流程时，它会将该方法保存为一项技能，以备将来复用。 skill_manage

当代理创建技能时

成功完成一项复杂任务（5次以上工具调用）后

当遇到错误或死路时，找到可行的路径

当用户纠正其方法时

当它发现一个非平凡的工作流时

操作

行动

用途

关键参数

创建

从零开始的新技能

名称, (完整的SKILL.md), 可选内容类别

补丁

有针对性的修复（首选）

名称,, 旧字符串新字符串

编辑

重大结构重写

名称, (完整SKILL.md替换)内容

删除

完全移除一项技能

名称

write_file

添加/更新支持文件

名称,, 文件路径文件内容

删除文件

移除一个支持文件

名称，文件路径

提示

此操作更适合更新——它比其他操作更节省令牌，因为只有更改的文本会出现在工具调用中。 patchedit

技能中心

浏览、搜索、安装和管理来自在线注册表、直接知名技能端点和官方可选技能的技能。 skills.sh

常用命令

hermes skills browse # Browse all hub skills (official first)

hermes skills browse --source official # Browse only official optional skills

hermes skills search kubernetes # Search all sources

hermes skills search react --source skills-sh # Search the skills.sh directory

hermes skills search https://mintlify.com/docs --source well-known

hermes skills inspect openai/skills/k8s # Preview before installing

hermes skills install openai/skills/k8s # Install with security scan

hermes skills install official/security/1password

hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force

hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify

hermes skills list --source hub # List hub-installed skills

hermes skills check # Check installed hub skills for upstream updates

hermes skills update # Reinstall hub skills with upstream changes when needed

hermes skills audit # Re-scan all hub skills for security

hermes skills uninstall k8s # Remove a hub skill

hermes skills publish skills/my-skill --to github --repo owner/repo

hermes skills snapshot export setup.json # Export skill config

hermes skills tap add myorg/skills-repo # Add a custom GitHub source

支持的中心源

源

示例

注释

官方

官方/安全/1Password

Hermes附带的可选技能。

技能-sh

skills-sh/vercel-labs/agent-skills/vercel-react-best-practices

可通过. Hermes 在 skills.sh slug 与仓库文件夹不同时解析别名式技能。hermes skills search <查询> --source skills-sh

著名的

知名: https://mintlify.com/docs/.well-known/skills/mintlify

直接从网站提供的技能。使用网站或文档URL/.well-known/skills/index.json进行搜索

github

openai/技能/k8s

直接安装GitHub仓库/路径和自定义taps。

clawhub,, lobehubclaude-marketplace

特定来源标识符

社区或市场集成。

集成枢纽和注册中心

爱马仕目前与这些技能生态系统和发现源集成：

官方可选技能（）官方

这些在Hermes仓库中维护，并以内置信任方式安装。

仓库中的源文件： optional-skills/

示例：

hermes skills browse --source official

hermes skills install official/security/1password

skills.sh () skills-sh

这是Vercel的公共技能目录。Hermes可以直接搜索它，查看技能详情页面，解析别名式的URL段，并从底层源仓库进行安装。

目录： skills.sh

CLI/工具库： vercel-labs/skills

官方 Vercel 技能仓库： vercel-labs/agent-skills

示例：

hermes skills search react --source skills-sh

hermes skills inspect skills-sh/vercel-labs/json-render/json-render-react

hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force

知名技能端点 () 知名

这是基于 URL 的发现机制，来自发布内容的网站。它不是单一的集中式中心——而是一种网络发现约定。 /.well-known/skills/index.json

示例实时端点： Mintlify文档技能索引

参考服务器实现： vercel-labs/skills-handler

示例：

hermes skills search https://mintlify.com/docs --source well-known

hermes skills inspect well-known:https://mintlify.com/docs/.well-known/skills/mintlify

hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify

直接GitHub技能() github

Hermes 可以直接从 GitHub 仓库和基于 GitHub 的 taps 进行安装。当你已经知道仓库/路径，或者想要添加自己的自定义源仓库时，这非常有用。

默认标签（无需任何设置即可浏览）：

openai/技能

anthropics/技能

VoltAgent/出色的代理技能

garrytan/gstack

示例：

hermes skills install openai/skills/k8s

hermes skills tap add myorg/skills-repo

ClawHub () clawhub

作为社区资源集成的第三方技能市场。

站点： clawhub.ai

Hermes源ID： clawhub

Claude市场风格仓库() claude-marketplace

Hermes支持发布Claude兼容插件/市场清单的市场仓库。

已知的集成源包括：

anthropics/技能

aiskillstore/市场

Hermes源ID： claude-marketplace

LobeHub () lobehub

Hermes可以搜索LobeHub公共目录中的代理条目，并将其转换为可安装的Hermes技能。

站点： LobeHub

公共代理索引： chat-agents.lobehub.com

支持仓库： lobehub/lobe-chat-agents

Hermes源ID： lobehub

安全扫描和 --force

所有通过中心安装的技能都会经过安全扫描器的检查，该扫描器会检查数据泄露、提示注入、破坏性命令、供应链信号和其他威胁。

hermes技能检查... 现在在可用时也会显示上游元数据：

仓库URL

skills.sh详情页URL

安装命令

每周安装量

上游安全审计状态

知名索引/端点URL

当你已审核第三方技能并希望覆盖非危险策略阻止时使用： --force

hermes skills install skills-sh/anthropics/skills/pdf --force

重要行为：

--force 可以覆盖针对警告/警示类结果的策略阻止。

--force 不会覆盖扫描结果。危险

官方可选技能（）被视为内置信任，不会显示第三方警告面板。官方/...

信任级别

等级

源

政策

内置

与爱马仕一同发货

始终值得信赖

官方

可选技能/仓库中

内置信任，无第三方警告

可信

受信任的注册表/存储库，如openai/skills、anthropics/skills

比社区来源更宽松的政策

社区

其他所有内容（知名端点、自定义GitHub仓库、大多数市场）skills.sh

非危险发现可以被覆盖；裁决仍被阻止——强制危险

更新生命周期

现在，中心能够追踪足够的来源信息，以便重新检查已安装技能的上游副本：

hermes skills check # Report which installed hub skills changed upstream

hermes skills update # Reinstall only the skills with updates available

hermes skills update react # Update one specific installed hub skill

此方法使用存储的源标识符加上当前上游捆绑包内容哈希来检测偏差。

GitHub速率限制

技能中心操作使用 GitHub API，该 API 对未认证用户的速率限制为每小时 60 个请求。如果在安装或搜索期间遇到速率限制错误，请在 <a i=1>GITHUB_TOKEN.env 文件中设置，将限制提高到每小时 5000 个请求。发生这种情况时，错误消息会包含可操作的提示。</a>

斜杠命令（在聊天中）

所有相同的命令都适用于： /技能

/skills browse

/skills search react --source skills-sh

/skills search https://mintlify.com/docs --source well-known

/skills inspect skills-sh/vercel-labs/json-render/json-render-react

/skills install openai/skills/skill-creator --force

/skills check

/skills update

/skills list

官方可选技能仍使用类似和的标识符。官方/安全/1password官方/迁移/openclaw迁移

第七章：Learning Path

Hermes Agent 功能多样，包括 CLI 助手、Telegram/Discord 机器人、任务自动化、强化学习训练等。本页面将根据你的经验水平和目标，帮助你确定从何处入手以及阅读哪些内容。

从这里开始

如果您尚未安装 Hermes Agent，请先查看安装指南，然后按照快速入门进行操作。以下所有内容均假定您已成功安装。

如何使用本页面

了解自己的水平？跳转到经验等级表，并按照您所在等级的阅读顺序进行。

有特定目标？跳转到按用例并找到匹配的场景。

只是随便看看？查看主要特性表，快速概览 Hermes Agent 的所有功能。

按经验水平

级别

目标

安卓系统上使用Termux的Hermes

这是通过 Termux 直接在安卓手机上运行Hermes Agent的测试路径。

它为你在手机上提供一个可用的本地 CLI，再加上目前已知可在安卓系统上顺利安装的核心附加组件。

测试路径中支持哪些内容？

经过测试的Termux捆绑包安装情况如下：

Hermes CLI

cron支持

PTY/后台终端支持

MCP支持

Honcho内存支持

ACP支持

具体而言，它映射到：

python -m pip install -e '.[termux]' -c constraints-termux.txt

哪些部分尚未纳入测试路径？

有几个功能仍然需要桌面/服务器风格的依赖项，这些依赖项尚未针对安卓系统发布，或者尚未在手机上进行验证：

.[all] 目前在安卓系统上不受支持

额外的被阻止，并且不发布安卓 wheelsvoicefaster-whisper -> ctranslate2ctranslate2

在Termux安装程序中跳过自动浏览器/Playwright引导

基于 Docker 的终端隔离在 Termux 内部不可用

这并不妨碍 Hermes 作为原生手机 CLI 代理正常工作——这只是意味着推荐的移动设备安装范围有意比桌面/服务器安装范围更窄。

选项1：单行安装程序

Hermes现在提供了一个支持Termux的安装路径：

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

在Termux上，安装程序会自动执行以下操作：

系统使用包pkg

创建venv与 python-m venv

安装与 .[termux]pip

链接到其中，以便它保留在你的Termux PATHhermes$PREFIX/bin

跳过未经测试的浏览器/WhatsApp引导程序

如果您需要明确的命令或需要调试安装失败的问题，请使用下面的手动路径。

选项2：手动安装（完全明确）

更新Termux并安装系统软件包

pkg update

pkg install -y git python clang rust make pkg-config libffi openssl nodejs ripgrep ffmpeg

为什么是这些包？

Python — 运行时 + 虚拟环境支持

git — 克隆/更新仓库

clang ,,,,, — 在 Androidrustmakepkg-configlibffiopenssl 上构建一些 Python 依赖项所需的工具

nodejs — 用于测试核心路径之外实验的可选 Node 运行时

ripgrep — 快速文件搜索

ffmpeg — 媒体/TTS转换

克隆Hermes

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git

cd hermes-agent

如果您已经克隆了但没有克隆子模块：

git submodule update --init --recursive

创建虚拟环境

python -m venv venv

source venv/bin/activate

export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"

python -m pip install --upgrade pip setuptools wheel

ANDROID_API_LEVEL 对于基于Rust/maturin的包很重要，例如. jiter

安装经过测试的Termux捆绑包

python -m pip install -e '.[termux]' -c constraints-termux.txt

如果你只需要最小核心代理，这也可行：

python -m pip install -e '.' -c constraints-termux.txt

安装你的Termux PATHhermes

ln -sf "$PWD/venv/bin/hermes" "$PREFIX/bin/hermes"

$PREFIX/bin 已经在Termux的PATH环境变量中，因此这使得命令在新的shell会话中持续生效，而无需每次都重新激活虚拟环境。 hermes

验证安装

hermes version

hermes doctor

启动Hermes

hermes

建议的后续设置

配置模型

hermes model

或者直接在. ~/. hermes/.env中设置密钥

稍后重新运行完整的交互式安装向导

hermes setup

手动安装可选的 Node 依赖项

经过测试的Termux路径会故意跳过Node/浏览器的引导过程。如果您之后想尝试使用浏览器工具：

pkg install nodejs-lts

npm install

浏览器工具会自动将Termux目录（）包含在其PATH搜索中，因此无需任何额外的PATH配置即可找到和。 /data/data/com.termux/files/usr/binagent-browsernpx

在另有文档说明之前，将安卓系统上的浏览器/WhatsApp工具视为实验性工具。

故障排除

未找到解决方案在安装 .[all]时

请使用经过测试的Termux捆绑包代替：

python -m pip install -e '.[termux]' -c constraints-termux.txt

当前的阻碍因素是额外的声音

语音拉取更快的低语

faster-whisper 依赖于 ctranslate2

ctranslate2 不发布安卓版本的wheel包

UV pip install 在安卓系统上失败

请使用带有标准库虚拟环境的Termux路径 + 来代替： pip

python -m venv venv

source venv/bin/activate

export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"

python -m pip install --upgrade pip setuptools wheel

python -m pip install -e '.[termux]' -c constraints-termux.txt

jiter / maturin 抱怨 ANDROID_API_LEVEL

在安装前明确设置 API 级别：

export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"

python -m pip install -e '.[termux]' -c constraints-termux.txt

hermes doctor 提示缺少ripgrep或Node

使用Termux软件包安装它们：

pkg install ripgrep nodejs

安装Python包时构建失败

确保已安装构建工具链：

pkg install clang rust make pkg-config libffi openssl

然后重试：

python -m pip install -e '.[termux]' -c constraints-termux.txt

手机上已知的限制

Docker后端不可用

本地语音转录通过是不可用的测试路径更快-耳语

浏览器自动化设置被安装程序有意跳过

某些可选附加功能可能有效，但目前仅记录为经过测试的安卓捆绑包 .[termux]

如果遇到新的特定于安卓的问题，请在GitHub上创建一个问题，并提供以下内容：

您的安卓版本

termux-info

python --version

爱马仕医生

确切的安装命令和完整的错误输出

Hermes Agent更新与卸载

正在更新

使用单个命令更新到最新版本：

hermes update

此操作会拉取最新代码、更新依赖项，并提示您配置自上次更新以来添加的任何新选项。

提示

hermes update 会自动检测新的配置选项，并提示您添加这些选项。如果您跳过了该提示，可以手动运行以查看缺失的选项，然后以交互方式添加它们。 hermes config checkhermes config migrate

更新期间会发生什么

当你运行时，会发生以下步骤： hermes更新

Git pull — 从分支拉取最新代码并更新子模块

依赖安装 — 运行以获取新的或更改的依赖项uv pip install -e ".[all]"

配置迁移 — 检测自您的版本以来添加的新配置选项，并提示您进行设置

网关自动重启 — 如果网关服务正在运行（Linux 上的 systemd，macOS 上的 launchd），则在更新完成后自动重启，以便新代码立即生效

预期输出如下：

$ hermes update

Updating Hermes Agent...

📥 Pulling latest code...

Already up to date. (or: Updating abc1234..def5678)

📦 Updating dependencies...

✅ Dependencies updated

🔍 Checking for new config options...

✅ Config is up to date (or: Found 2 new options — running migration...)

🔄 Restarting gateway service...

✅ Gateway restarted

✅ Hermes Agent updated successfully!

建议的更新后验证

hermes更新处理主要更新路径，但快速验证确认所有内容都已顺利完成：

git status --short — 如果工作树意外地处于脏状态，请在继续操作前进行检查

hermes doctor — 检查配置、依赖项和服务健康状况

hermes --version — 确认版本按预期升级

如果您使用网关： hermes网关状态

如果报告npm审计问题：在标记的目录中运行npm audit fix

更新后工作树有未提交的更改

如果在更新后显示意外更改，请在继续之前停止并检查它们。这通常意味着本地修改在更新后的代码之上被重新应用，或者依赖步骤刷新了锁定文件。 git status --shorthermes update

正在检查您的当前版本

hermes version

与 GitHub发布页面上的最新版本进行比较，或检查可用更新：

hermes update --check

从消息平台更新

您也可以通过发送以下内容直接从 Telegram、Discord、Slack 或 WhatsApp 进行更新：

/update

此操作将拉取最新代码、更新依赖项并重启网关。重启期间，机器人将短暂离线（通常为5 - 15秒），随后恢复运行。

手动更新

如果您是手动安装（而非通过快速安装程序）：

cd /path/to/hermes-agent

export VIRTUAL_ENV="$(pwd)/venv"

Pull latest code and submodules

git pull origin main

git submodule update --init --recursive

Reinstall (picks up new dependencies)

uv pip install -e ".[all]"

uv pip install -e "./tinker-atropos"

Check for new config options

hermes config check

hermes config migrate # Interactively add any missing options

回滚说明

如果更新引入问题，你可以回滚到之前的版本：

cd /path/to/hermes-agent

List recent versions

git log --oneline -10

Roll back to a specific commit

git checkout <commit-hash>

git submodule update --init --recursive

uv pip install -e ".[all]"

Restart the gateway if running

hermes gateway restart

要回滚到特定的发布标签：

git checkout v0.6.0

git submodule update --init --recursive

uv pip install -e ".[all]"

警告

回滚可能会导致配置不兼容，如果添加了新选项。回滚后运行，遇到错误时移除未识别的选项。 hermes config checkconfig.yaml

给Nix用户的提示

如果你是通过 Nix Flake 安装的，更新会通过 Nix 包管理器来管理：

Update the flake input

nix flake update hermes-agent

Or rebuild with the latest

nix profile upgrade hermes-agent

Nix安装是不可变的——回滚由Nix的生成系统处理：

nix profile rollback

更多详情请参阅 Nix设置。

正在卸载

hermes uninstall

卸载程序提供了保留配置文件（）以便将来重新安装的选项。 ~/.hermes/

手动卸载

rm -f ~/.local/bin/hermes

rm -rf /path/to/hermes-agent

rm -rf ~/.hermes # Optional — keep if you plan to reinstall

信息

如果您将网关作为系统服务安装，请先停止并禁用它：

hermes gateway stop

Linux: systemctl --user disable hermes-gateway

macOS: launchctl remove ai.hermes.gateway