1.1 安装

两分钟内安装 Hermes Agent，使用一行安装器获取开箱即用体验，或手动步骤获取完全控制。

安装器自动处理

• Python 3.11（通过 uv，无需 sudo）
• Node.js v22（浏览器自动化和 WhatsApp 桥接）
• ripgrep（快速文件搜索）
• ffmpeg（TTS 音频格式转换）
• 全局 hermes 命令配置
• LLM 提供商初始配置向导

安装后

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

稍后重新配置

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

扩展包（可选）

故障排除

运行 hermes doctor 获取完整诊断信息。

1.2 快速入门

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

hermes model       # 选择提供商和模型
hermes tools       # 配置工具
hermes setup       # 或一次性配置所有内容

hermes

# 让代理使用终端
❯ 我的磁盘使用情况如何？显示最大的 5 个目录。

# 使用斜杠命令（输入 / 查看补全列表）
/tools        # 列出可用工具
/model        # 切换模型
/save         # 保存对话
/personality pirate   # 有趣的人格模式

hermes --continue   # 恢复最近的会话
hermes -c           # 简写形式

快速参考命令

1.3 Android / Termux 指南

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

Termux 支持的功能

• Hermes CLI、cron 支持、PTY/后台终端
• MCP 支持、Honcho 记忆、ACP 支持

方式一：一行安装器

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

方式二：手动安装

# 1. 安装系统包
pkg update
pkg install -y git python clang rust make pkg-config libffi openssl nodejs ripgrep ffmpeg

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

# 3. 创建虚拟环境
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

# 4. 安装 Termux 包
python -m pip install -e '.[termux]' -c constraints-termux.txt

# 5. 添加到 PATH
ln -sf "$PWD/venv/bin/hermes" "$PREFIX/bin/hermes"

# 6. 验证
hermes version
hermes doctor

1.4 Nix & NixOS 设置

Hermes Agent 附带一个 Nix flake，提供三个层级的集成。

快速开始

nix run github:NousResearch/hermes-agent -- setup
nix run github:NousResearch/hermes-agent -- chat

# 或持久安装
nix profile install github:NousResearch/hermes-agent
hermes setup
hermes chat

NixOS 模块示例

# configuration.nix
{ config, ... }: {
  services.hermes-agent = {
    enable = true;
    settings.model.default = "anthropic/claude-sonnet-4";
    environmentFiles = [ config.sops.secrets."hermes-env".path ];
    addToSystemPackages = true;
  };
}

1.5 学习路径

按用例

2.1 CLI 界面

运行方式

hermes                                    # 交互式会话
hermes chat -q "Hello"                    # 单查询模式
hermes chat --model "anthropic/claude-sonnet-4"  # 指定模型
hermes chat --toolsets "web,terminal"     # 指定工具集
hermes --continue                         # 恢复最近会话
hermes --resume <session_id>             # 恢复特定会话
hermes chat --verbose                     # 详细模式

状态栏说明

 ⚕ claude-sonnet-4-20250514 │ 12.4K/200K │ [██████░░░░] 6% │ $0.06 │ 15m

快捷键

斜杠命令（常用）

内置人格

helpful、concise、technical、creative、teacher、kawaii、catgirl、pirate、shakespeare、surfer、noir、uwu、philosopher、hype

2.2 配置

目录结构

~/.hermes/
├── config.yaml     # 设置（模型、终端、TTS、压缩等）
├── .env            # API 密钥和秘密
├── auth.json       # OAuth 提供商凭据
├── SOUL.md         # 主要代理身份
├── memories/       # 持久记忆（MEMORY.md, USER.md）
├── skills/         # 代理创建的技能
├── cron/           # 定时任务
├── sessions/       # 网关会话
└── logs/           # 日志

管理配置

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

配置优先级

1. CLI 参数（最高优先级）
2. ~/.hermes/config.yaml
3. ~/.hermes/.env
4. 内置默认值

终端后端配置

terminal:
  backend: local    # local | docker | ssh | modal | daytona | singularity
  cwd: "."
  timeout: 180

上下文压缩

compression:
  enabled: true
  threshold: 0.50
  summary_model: "google/gemini-3-flash-preview"

智能批准模式

approvals:
  mode: manual   # manual | smart | off

2.3 会话

每个对话作为包含完整消息历史的会话存储，通过两个系统追踪：SQLite 数据库（结构化元数据，带 FTS5 全文搜索）和 JSONL 转录文件。

会话管理命令

hermes sessions list
hermes sessions export backup.jsonl
hermes sessions delete <session_id>
hermes sessions rename <session_id> "新标题"
hermes sessions prune --older-than 90
hermes sessions stats

恢复会话

hermes --continue                         # 恢复最近的 CLI 会话
hermes -c "my project"                    # 恢复命名会话
hermes --resume 20250305_091523_a1b2c3d4  # 恢复特定会话

2.4 消息网关

通过 Telegram、Discord、Slack、WhatsApp、Signal、Email、钉钉、飞书/Lark、企业微信、微信、iMessage 等平台与 Hermes 聊天。

快速设置

hermes gateway setup        # 交互式设置所有消息平台
hermes gateway              # 前台运行
hermes gateway start        # 启动为服务
hermes gateway status       # 检查状态

平台功能对比

用户授权

# 限制特定用户
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678

# DM 配对
hermes pairing approve telegram XKGH5N7P
hermes pairing list
hermes pairing revoke telegram 123456789

2.5 安全

Hermes Agent 采用纵深防御安全模型，包含七层安全边界：

1. 用户授权 — 白名单、DM 配对
2. 危险命令审批 — 破坏性操作需要人工确认
3. 容器隔离 — Docker/Singularity/Modal 沙箱
4. MCP 凭证过滤 — MCP 子进程的环境变量隔离
5. 上下文文件扫描 — 项目文件中的提示注入检测
6. 跨会话隔离 — 会话之间无法访问彼此数据
7. 输入消毒 — 工作目录参数白名单验证

YOLO 模式（跳过审批）

hermes --yolo          # CLI 标志
/yolo                  # 斜杠命令切换
HERMES_YOLO_MODE=1     # 环境变量

3.1 工具与工具集

使用工具集

hermes chat --toolsets "web,terminal"
hermes tools              # 查看所有可用工具

3.2 技能系统

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

使用技能

/gif-search funny cats
/github-pr-workflow create a PR for the auth refactor
/plan design a rollout for migrating our auth provider

渐进式披露

Level 0: skills_list()           → [{name, description, category}] (~3k tokens)
Level 1: skill_view(name)        → 完整内容 + 元数据
Level 2: skill_view(name, path)  → 特定引用文件

技能中心

hermes skills browse
hermes skills search kubernetes
hermes skills install openai/skills/k8s
hermes skills update         # 更新有变化的技能

SKILL.md 格式

---
name: my-skill
description: 此技能的功能简述
version: 1.0.0
platforms: [macos, linux]
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    requires_toolsets: [terminal]
---
# 技能标题

## 何时使用
## 流程
## 陷阱
## 验证

3.3 持久化记忆

Hermes Agent 拥有有界的、经过筛选的跨会话持久化记忆。

什么该保存

• 用户偏好："我更喜欢 TypeScript 而非 JavaScript"
• 环境事实："此服务器运行 Debian 12"
• 更正："不要用 sudo 运行 Docker 命令"
• 约定："项目使用 tabs，120 字符行宽"

配置

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375

3.4 MCP（模型上下文协议）

MCP 让 Hermes Agent 连接到外部工具服务器，扩展代理的工具能力。

配置 MCP 服务器

# ~/.hermes/config.yaml
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]

管理 MCP 服务器

hermes mcp list              # 列出配置的服务器
hermes mcp test github       # 测试连接
hermes mcp add               # 交互式添加新服务器

3.5 上下文文件

在项目目录放置上下文文件，代理启动时自动注入到系统提示中。

HERMES.md          # 项目级上下文（类似 CLAUDE.md）
AGENTS.md          # 代理行为指令
.hermes/context/   # 额外上下文文件目录

3.6 个性与 SOUL.md

~/.hermes/SOUL.md 定义代理的主要身份和行为风格，在所有会话中持久存在。

# 示例 SOUL.md
你是一个专注于 Python 开发的助手。
- 优先使用类型注解
- 始终建议编写测试
- 代码风格遵循 PEP 8

也可通过 /personality 命令临时切换人格，退出后恢复 SOUL.md 定义的默认风格。

3.7 语音模式

安装

pip install "hermes-agent[voice]"
pip install faster-whisper

启用

/voice on        # 启用语音模式
/voice tts       # 切换语音播放（TTS）
Ctrl+B           # 开始/停止录音

高品质 TTS（ElevenLabs）

pip install "hermes-agent[tts-premium]"
hermes config set tts.provider elevenlabs
hermes config set ELEVENLABS_API_KEY your_key

3.8 浏览器自动化

Hermes 支持完整的浏览器自动化，通过 Playwright 或 Browserbase 后端操控真实浏览器。

# 安装 Node.js 依赖（必需）
npm install
# 安装 Playwright 浏览器
npx playwright install chromium

可用浏览器工具

• browser_navigate — 导航到 URL
• browser_snapshot — 截图当前页面
• browser_vision — 视觉分析页面内容
• browser_click — 点击元素
• browser_type — 在输入框中输入文字
• browser_scroll — 滚动页面
• browser_execute_js — 执行 JavaScript

3.9 定时任务（Cron）

直接用自然语言创建定时任务，无需手写 cron 表达式。

❯ 每天早上9点，检查 Hacker News 上的 AI 新闻并在 Telegram 上给我发送摘要。

支持的时间格式

• 相对延迟：30m、2h、1d
• 间隔：every 30m、every 2h
• Cron 表达式：0 9 * * *、0 */6 * * *
• ISO 时间戳：2026-03-15T09:00:00

管理任务

/cron list
/cron pause <job_id>
/cron resume <job_id>
/cron run <job_id>
/cron remove <job_id>

3.10 子代理委派

delegate_task 工具生成子 AI Agent 实例，拥有隔离上下文和受限工具集。

单任务委派

delegate_task(
    goal="调试测试失败的原因",
    context="错误：test_foo.py 第 42 行断言失败",
    toolsets=["terminal", "file"]
)

并行批量委派（最多 3 个并发）

delegate_task(tasks=[
    {"goal": "研究主题 A", "toolsets": ["web"]},
    {"goal": "研究主题 B", "toolsets": ["web"]},
    {"goal": "修复构建", "toolsets": ["terminal", "file"]}
])

模型覆盖

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

3.11 ACP 编辑器集成

通过 ACP（Agent Control Protocol）在 VS Code、Cursor 等编辑器中直接使用 Hermes Agent。

pip install -e '.[acp]'
hermes acp          # 启动 ACP 服务器

3.12 凭据池（Credential Pools）

凭据池允许在多个 Agent 实例或会话之间安全共享 API 密钥和凭证，避免重复配置。

hermes creds add github GITHUB_TOKEN ghp_xxx
hermes creds list
hermes creds remove github GITHUB_TOKEN

3.13 插件系统（Plugins）

插件系统允许扩展 Hermes 的核心功能，包括自定义记忆提供者和上下文引擎。

# 插件目录结构
~/.hermes/
├── plugins/
│   ├── memory/           # 记忆提供者插件
│   └── context_engine/   # 上下文引擎插件

3.14 皮肤与主题（Skins & Themes）

通过皮肤系统自定义 CLI 界面的外观风格。

/skin                    # 查看当前皮肤
/skin list               # 列出可用皮肤
/skin set dark-minimal   # 切换皮肤

4.1 架构

核心目录

hermes-agent/
├── run_agent.py              # AIAgent — 核心对话循环（~9,200 行）
├── cli.py                    # HermesCLI — 交互式终端 UI（~8,500 行）
├── model_tools.py            # 工具发现、模式收集、调度
├── toolsets.py               # 工具分组和平台预设
├── hermes_state.py           # SQLite 会话数据库（带 FTS5）
├── agent/                    # Agent 内部模块
│   ├── prompt_builder.py     # 系统提示词组装
│   ├── context_compressor.py # 有损摘要压缩
│   └── memory_manager.py     # 记忆管理器
├── tools/                    # 工具实现（48+ 工具）
├── gateway/                  # 消息平台网关（15 个适配器）
└── tests/                    # Pytest 测试套件（3,000+ 测试）

4.2 贡献指南

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

# 安装开发依赖
uv pip install -e ".[all,dev]"

# 运行测试
pytest tests/

# 运行特定测试
pytest tests/test_memory.py -v

5.1 AI 提供商

Hermes Agent 支持众多 AI 提供商，通过 hermes model 交互式选择。

国内常用提供商配置

# 阿里云 Qwen
hermes config set DASHSCOPE_API_KEY your_key

# 智谱 GLM
hermes config set GLM_API_KEY your_key

# Kimi
hermes config set KIMI_API_KEY your_key

# MiniMax
hermes config set MINIMAX_API_KEY your_key

# DeepSeek
hermes config set DEEPSEEK_API_KEY your_key

6.1 CLI 命令参考

6.2 斜杠命令参考

6.3 环境变量

6.4 MCP 配置参考

# ~/.hermes/config.yaml
mcp_servers:
  # stdio 传输（最常见）
  my-server:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-name"]
    env:
      API_KEY: "your_key"

  # SSE 传输（基于 HTTP）
  remote-server:
    url: "https://my-mcp-server.example.com/sse"
    headers:
      Authorization: "Bearer your_token"

  # 本地脚本
  local-tools:
    command: python
    args: ["/path/to/mcp_server.py"]

6.5 FAQ 与故障排除

更多帮助请访问 GitHub Issues 或加入 Hermes Agent 中文社区。