1.1 安装

Windows / macOS / Linux / Docker 完整安装指南，按步骤操作，几分钟内即可启动。

1.2 Windows 详细安装教程

如果你是 Windows 用户，觉得命令行有点陌生，这一节专门为你准备。我们一步步来，不着急。

方式一：WSL2 安装（偏好 Linux 环境 / 需要内嵌终端）

wsl --install

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

source ~/.bashrc
hermes

方式二：PowerShell 原生安装（推荐，官方正式支持）

cd ~
git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git hermes-agent

cd ~
git -C .\hermes-agent status
if ($LASTEXITCODE -ne 0) { Write-Host "hermes-agent 目录不是完整 git 仓库，请删除后重新 clone。" -ForegroundColor Red; return }
Copy-Item "$HOME\hermes-agent\scripts\install.ps1" "$env:TEMP\hermes-install.ps1" -Force
powershell -ExecutionPolicy Bypass -File "$env:TEMP\hermes-install.ps1" -InstallDir "$HOME\hermes-agent"

Get-Command hermes
hermes --version
hermes model
hermes

常见问题

1.3 配置向导教程

安装完成后，运行 hermes 命令，你会看到一个配置向导界面。输入 1 并按回车，进入快速设置模式。

第一步：选择模型提供商

你会看到类似下面的界面，选择你想使用的 AI 模型提供商：

第二步：输入 API 密钥

选择提供商后，系统会提示你输入 API 密钥。不同提供商的获取方式：

第三步：选择默认模型

输入 API Key 后，系统会让你选择默认使用的模型。常见推荐：

第四步：配置工具

接下来会询问你想启用哪些工具。新手建议先启用基础工具：

web          # 网络搜索和网页提取
terminal     # 执行命令
file         # 读写文件
browser      # 浏览器自动化（可选）

配置完成后

配置完成后，你可以直接开始对话：

hermes           # 启动交互式对话
hermes "帮我写一个 Python 脚本"   # 单次提问

重新配置

如果想修改配置，可以运行：

hermes model     # 重新选择模型提供商
hermes tools     # 重新配置工具
hermes setup     # 运行完整设置向导
hermes config set provider.api_key "新的密钥"   # 直接修改配置

1.4 快速入门

curl -fsSL https://ghfast.top/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.5 更新与卸载

更新 Hermes Agent

通过一条命令即可更新到最新版本：

hermes update

这个命令会自动完成以下操作：

1. 拉取最新代码 — 从 GitHub main 分支拉取
2. 更新依赖 — 安装新增或变更的依赖包
3. 配置迁移 — 检测新增的配置选项，提示你设置
4. 重启网关 — 如果消息网关正在运行，会自动重启

更新后验证

更新完成后，建议运行以下命令验证：

hermes --version    # 确认版本号已更新
hermes doctor       # 检查配置和依赖是否正常

检查可用更新

hermes update --check   # 检查是否有新版本可用

回滚到旧版本

如果更新后出现问题，可以回滚到之前的版本：

cd /path/to/hermes-agent
git log --oneline -10          # 查看最近的版本
git checkout v0.9.0            # 回滚到特定版本标签
uv pip install -e ".[all]"     # 重新安装依赖
hermes gateway restart         # 如果网关在运行，重启它

卸载 Hermes Agent

如果你想完全卸载 Hermes Agent：

# 1. 停止网关服务（如果在运行）
hermes gateway stop

# 2. 删除安装目录
rm -rf ~/hermes-agent   # 或者你的安装路径

# 3. 删除配置文件（可选）
rm -rf ~/.hermes

# 4. 从 shell 配置中移除 PATH（如果添加过）
# 编辑 ~/.bashrc 或 ~/.zshrc，删除相关行

1.6 Android / Termux 指南

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

Termux 支持的功能

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

方式一：一行安装器

curl -fsSL https://ghfast.top/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://ghfast.top/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.7 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.8 学习路径

按用例

2.1 消息平台概述

Hermes Agent 可以接入多种消息平台，让你在微信、飞书、Telegram、Discord 等平台上使用 AI 助手。

支持的平台

接入流程（通用）

uv pip install -e ".[messaging]"

hermes gateway setup

hermes gateway

2.2 微信接入教程

把 Hermes Agent 接入个人微信，让 AI 成为你的微信助手。

前提条件

• 一个个人微信号
• 安装依赖：pip install aiohttp cryptography qrcode

接入步骤

hermes gateway setup

hermes gateway

使用方式

• 私聊：直接发消息给 AI，它会回复
• 群聊：需要 @AI 机器人才会回复

常见问题

2.3 飞书接入教程

把 Hermes Agent 接入飞书，打造企业级 AI 助手。

前提条件

• 飞书管理员权限（或让管理员帮你创建应用）
• 飞书开放平台账号

接入步骤

hermes gateway setup

hermes gateway

使用方式

• 私聊：在飞书里找到应用，直接发消息
• 群聊：把应用添加到群，@它 就能对话

2.4 Telegram 接入

Telegram 是配置最简单的平台之一，适合个人使用。

接入步骤

hermes gateway setup

hermes gateway

2.5 Discord 接入

把 Hermes Agent 接入 Discord，适合游戏社区和技术社区。

接入步骤

hermes gateway setup

hermes gateway

3.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

3.2 TUI 模式（现代终端界面）

TUI 与经典 CLI 使用同一个 Python Agent 运行时、会话数据库、斜杠命令、Skills 和配置，只是提供更流畅的终端交互界面。官方推荐交互式使用优先选择 TUI。

启动、恢复与设为默认

hermes --tui                         # 启动新 TUI 会话
hermes --tui -c                      # 恢复最近会话
hermes --tui --continue              # 同上
hermes --tui -r <session-id>         # 按 ID 恢复
hermes --tui --resume "会话标题"      # 按标题恢复
hermes --tui --dev                   # 开发模式，跳过预构建
hermes --cli                         # 本次强制使用经典 CLI

# 环境变量方式
export HERMES_TUI=1

# ~/.hermes/config.yaml：持久设为默认
display:
  interface: tui                     # cli | tui

运行要求

• 需要 Node.js 20 或更高版本；hermes doctor 会检查。
• 需要交互式 TTY；管道输入或非交互环境会回退到单查询模式。
• 首次启动会在 ui-tui/node_modules 安装依赖，后续启动复用；升级后源文件较新时会自动重建 Bundle。
• 发行版可设置 HERMES_TUI_DIR 指向预构建目录，该目录必须包含 dist/entry.js。

相比经典 CLI 的主要变化

启动横幅与折叠区

横幅包含 Tools、Skills、System Prompt、MCP Servers 四个可折叠区域。Tools 默认展开，其余默认收起；点击标题或箭头切换，每次启动恢复默认状态。

重要快捷键差异

TUI 增强斜杠命令

实时多会话切换器

通过 Ctrl+X、/sessions、/switch 或点击状态栏的实时会话数打开。内部使用方向键选择、Enter 切换、Ctrl+D 关闭、Ctrl+N 新建、Ctrl+R 刷新。选择“+new”后可输入首条提示；按 Tab 可为新会话单独选模型。这里只列当前 TUI 进程内的活跃会话，已关闭记录仍可通过 Resume 恢复。

主题、数学公式和状态栏

• 与 CLI 共用 Skin 和 Personality，/skin、/personality 切换后即时重绘。
• 支持行内与块级 LaTeX 数学公式；不支持的语法以可复制源码显示。
• 自动通过 HERMES_TUI_THEME、COLORFGBG、OSC 11 检测浅色终端。
• 状态栏显示运行状态、工作目录与 Git 分支、当前提示耗时/总会话时长、压缩次数、后台任务数和 YOLO 警告。
• /indicator 可切换 kaomoji、emoji、unicode、ascii 忙碌指示器。

详情面板与鼠标配置

display:
  details_mode: collapsed             # hidden | collapsed | expanded
  sections:
    thinking: expanded
    tools: expanded
    activity: hidden
  mouse_tracking: all                 # off | wheel | buttons | all
  tui_status_indicator: kaomoji

默认 thinking 和 tools 展开，subagents 跟随全局模式，activity 隐藏。tmux 中若悬停事件干扰提示行，推荐 mouse_tracking: wheel。

自动恢复与会话共享

export HERMES_TUI_RESUME=1             # 自动恢复最近 TUI 会话
export HERMES_TUI_RESUME=<session-id>  # 自动恢复指定会话

TUI 与经典 CLI 共用 ~/.hermes/state.db，可以跨界面恢复同一会话。默认 TUI 启动自己的进程内 Gateway；HERMES_TUI_GATEWAY_URL 是 Dashboard 内嵌 Chat 的内部连线参数，不是连接任意远程 Gateway 的公开配置。OpenAI 兼容 API Server 不提供 TUI 的 /api/ws 控制通道。

3.3 配置

目录结构

~/.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

3.4 配置文件与多 Agent

Profiles（配置文件）让你可以为不同场景创建独立的配置，比如工作配置、个人配置、测试配置等。

创建配置文件

每个 Profile 是一个独立的配置目录，位于 ~/.hermes/ 下：

~/.hermes/
├── config.yaml          # 默认配置
├── profiles/
│   ├── work/
│   │   └── config.yaml  # 工作配置
│   ├── personal/
│   │   └── config.yaml  # 个人配置
│   └── test/
│       └── config.yaml  # 测试配置

使用配置文件

# 使用默认配置
hermes

# 使用指定配置文件
hermes --profile work
hermes -p personal

# 创建新配置文件
hermes -p newprofile setup

配置文件继承

子配置可以继承父配置，只覆盖需要修改的部分：

# profiles/work/config.yaml
inherits: ../config.yaml  # 继承默认配置

provider:
  model: claude-opus-4    # 覆盖模型

memory:
  enabled: true           # 覆盖记忆设置

同时运行多个 Agent

使用 Git Worktrees 可以同时运行多个独立的 Hermes Agent：

# 创建 worktree
git worktree add ../hermes-work main
git worktree add ../hermes-personal main

# 在不同终端运行不同的 Agent
cd ../hermes-work && hermes -p work
cd ../hermes-personal && hermes -p personal

3.5 会话

每个对话作为包含完整消息历史的会话存储，通过两个系统追踪：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  # 恢复特定会话

3.6 检查点与回滚

检查点（Checkpoint）是会话状态的快照，让你可以随时保存当前进度，并在需要时回滚到之前的状态。

创建检查点

# 在对话中创建检查点
/checkpoint              # 自动命名
/checkpoint "重构前"     # 命名检查点

查看检查点

/checkpoints             # 列出当前会话的所有检查点
hermes checkpoints list  # CLI 命令

回滚到检查点

# 在对话中回滚
/rollback                # 回滚到最近的检查点
/rollback "重构前"       # 回滚到命名检查点

# CLI 命令
hermes rollback --checkpoint "重构前"

检查点存储

检查点存储在会话数据库中，包含：

• 完整的消息历史
• 当前工作目录状态
• 已加载的技能和工具配置
• 记忆状态

与 Git 配合

检查点主要针对对话状态，文件修改建议用 Git 管理：

# 执行操作前
git add . && git commit -m "操作前保存"

# 如果操作失败
git checkout .           # 恢复文件
/rollback               # 恢复对话状态

3.7 消息网关

通过 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

3.8 安全

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://ghfast.top/https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

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

# 运行测试
pytest tests/

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

6.1 WebUI 可视化界面

如果你不想用命令行，可以使用 WebUI 在浏览器里操作 Hermes Agent。

Web3Hermes 特点

• 浏览器里直接使用 Hermes，不用命令行
• 三栏布局：会话列表、聊天区、工作区文件浏览
• 支持 Docker 部署和远程 SSH 隧道
• 中文界面，适合国内用户

安装 Web3Hermes

# 克隆项目（国内镜像）
git clone https://cnb.cool/hermesagent-cn/Web3Hermes-cn-mirror.git web3hermes
cd web3hermes

# 安装依赖
pip install -e ".[all]"
pnpm install

# 启动服务
python bootstrap.py

# 浏览器打开 http://localhost:8000

6.2 Docker 部署

使用 Docker 可以快速部署 Hermes Agent，适合服务器环境。

快速启动

# 拉取镜像
docker pull ghcr.io/nousresearch/hermes-agent:latest

# 运行容器
docker run -it --rm \
  -v ~/.hermes:/root/.hermes \
  -e OPENROUTER_API_KEY=your_key \
  ghcr.io/nousresearch/hermes-agent:latest

完整配置

# docker-compose.yml
version: '3'
services:
  hermes:
    image: ghcr.io/nousresearch/hermes-agent:latest
    volumes:
      - ./hermes-data:/root/.hermes
      - ./workspace:/workspace
    environment:
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
      - HERMES_MODEL=anthropic/claude-sonnet-4
    ports:
      - "8000:8000"  # WebUI 端口（可选）
    restart: unless-stopped

启动服务

docker-compose up -d

# 查看日志
docker-compose logs -f hermes

# 进入容器交互
docker-compose exec hermes hermes

7.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

8.1 CLI 命令参考

8.2 斜杠命令参考

8.3 环境变量

8.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"]

8.5 术语解释

这里是 Hermes Agent 文档中常见的专业术语解释，帮助新手快速理解。

8.6 FAQ 与故障排除

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

8.7 社区与支持

加入 Hermes Agent 中文社区，获取帮助、分享经验、交流使用技巧。

社区适合分享的内容

• Hermes Agent 安装、升级、使用相关问题
• 主流模型使用体验、获取方式分享
• 高性价比模型提供商推荐
• Skills、Memory、MCP、自动化工作流实践
• 前沿科技信息、新框架、新模型

9.1 缺口检查结果

本节依据官方 机器可读文档索引逐页比对。已有章节不重复搬运；以下内容重点补齐本页原先没有独立说明、或新版能力已明显扩展的主题。

9.2 界面、模型与运行环境

TUI（Ink 终端界面） · 官方原文

已新增独立的 3.2 TUI 模式完整中文章节，覆盖正确启动命令 hermes --tui、依赖、快捷键、实时多会话、Overlay、状态栏、详情面板、鼠标模式、自动恢复、会话共享和 Dashboard 网关边界。

配置模型 · 官方原文

• hermes model 用于登录提供商、浏览推荐模型并设置主模型。
• hermes model current 查看主模型和辅助任务模型；hermes model set 修改主模型。
• 摘要、会话命名、技能选择等辅助任务可单独指定便宜或更快的模型；重置为 auto 可恢复自动选择。
• 自定义 OpenAI 兼容端点时，需要同时核对 Base URL、API Key、上下文窗口与工具调用兼容性。

Git Worktree 并行工作 · 官方原文

在同一仓库并行运行多个 Hermes 时，应让每个 Agent 使用独立 worktree，避免同时修改同一工作目录。可用 hermes -w 启动隔离工作树，也可先通过 git worktree add 创建独立分支目录。完成后先提交或迁移成果，再删除 worktree。

Docker 后端 · 官方原文

Docker 既可运行完整 Hermes，也可作为终端执行后端，为命令提供隔离环境。生产环境应持久化 ~/.hermes、限制挂载目录、配置健康检查，并避免将宿主机 Docker Socket 暴露给不可信任务。

功能总览 · 官方原文

Hermes 的核心闭环由工具、技能、记忆、上下文文件、定时任务和子 Agent 组成：工具负责行动，技能保存流程知识，记忆保存跨会话事实，自动化负责持续执行，消息网关把结果送到用户所在平台。

9.3 学习、记忆与扩展机制

技能 Curator · 官方原文

Curator 在后台维护 Agent 创建的技能：记录使用情况、识别长期未使用内容、归档陈旧技能，并可选择使用辅助模型进行合并审查。常规清理默认不需要 LLM；只有明确启用 consolidation 时才产生辅助模型消耗。

外部记忆提供商 · 官方原文

除内置 MEMORY.md 与 USER.md 外，还可接入 Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover 和 Supermemory。选择时重点比较数据托管位置、自动写入策略、召回延迟、成本和多用户隔离能力；外部记忆不能替代敏感数据访问控制。

上下文引用（@ 语法） · 官方原文

在消息中使用 @ 可显式附加文件、目录、Git diff 或 URL，让模型只在需要时读取相关上下文。大型目录应缩小范围，二进制文件先确认是否支持解析；引用不等于长期记忆，跨会话事实仍应写入记忆或项目上下文文件。

内置插件 · 官方原文

Hermes 自带通过生命周期 Hook 自动运行的插件，例如磁盘清理等维护能力。内置插件与普通技能不同：技能提供任务知识，插件可以注册工具、监听事件并执行代码。启用前应检查权限、配置和触发频率。

Honcho 记忆 · 官方原文

Honcho 使用辩证推理建立更深的用户模型，适合长期、多 Agent 共享的个性化场景。配置时要明确用户身份、工作区隔离和数据保留策略；团队部署不可让不同用户共享同一个身份命名空间。

9.4 自动化与多 Agent

Kanban 多 Agent 看板 · 官方原文

Kanban 是基于 SQLite 的持久任务板，用来让多个 Profile 领取、更新和交接任务。它适合跨会话的长期协作：任务状态不会因单次聊天结束而消失，worker 可按 Profile、工具集和模型进行分工。

Kanban 教程 · 官方原文

推荐流程是：创建任务板 → 拆分可验证任务 → 为 worker 分配 Profile → 启动 dispatcher → 观察阻塞与重试 → 由验证节点验收。任务描述必须包含产物、约束和完成条件，避免只写模糊目标。

持久目标（/goal） · 官方原文

持久目标让 Hermes 跨多个 turn 持续推进同一个结果，类似 Ralph loop。使用 /goal 设置清晰、可验收的目标；Agent 会持续工作，直到完成、被用户停止或确认确实受阻。目标不是后台无限任务，仍受权限、预算与会话运行条件约束。

代码执行（Programmatic Tool Calling） · 官方原文

execute_code 允许模型在受控 Python 环境中通过 RPC 调用工具，把多步数据处理压缩为一次推理。适合批量转换、筛选和聚合；涉及外部写操作时仍应保留确认和幂等保护。

事件 Hooks · 官方原文

Hooks 可在会话、Agent、工具调用和压缩等生命周期节点执行自定义逻辑，用于日志、告警、Webhook 和审计。Hook 应快速、可失败隔离且不能泄露完整提示词或密钥；长任务应转交队列。

批处理 · 官方原文

批处理用于并行生成大量 Agent 轨迹，支持断点、工具集分布和结果导出，适合评测、数据生成与 RL 训练。运行前应固定模型与配置版本，记录随机性参数，并把失败样本与成功样本同样保留以便复现。

后台子 Agent

新版 delegate_task(background=true) 会立即返回任务句柄，父 Agent 可继续工作；子任务完成后结果自动进入会话。后台委派适合耗时研究和构建，但任务必须独立、上下文完整，避免与父任务同时修改相同文件。

9.5 多媒体与 Web 能力

视觉与图片粘贴 · 官方原文

Hermes 可分析截图、照片和图表，并在支持的终端或消息平台接收粘贴图片。排错截图应保留完整错误区域；含隐私信息的图片应先脱敏。视觉能力取决于当前模型是否支持多模态输入。

图片生成与编辑 · 官方原文

image_generate 支持文生图以及基于源图的编辑，可完成换色、移除背景和风格转换。不同后端的尺寸、格式、价格与安全策略不同；生成前应明确用途、画幅、视觉风格和必须保留的元素。

语音与 TTS · 官方原文

语音模块覆盖文本转语音、语音消息转写和多平台语音回复。应按平台选择兼容音频格式，并为自动 TTS 设置长度与触发条件，避免每条长回复都产生费用。

Browser 自动化 · 官方原文

浏览器能力支持页面导航、结构化快照、点击、输入、下载和视觉定位。优先使用结构化元素，只有无法定位时再使用视觉坐标；登录态和支付类操作必须启用用户确认。

9.6 更多消息平台

官方消息网关已远超本页原有的 Telegram、Discord、微信和飞书。下表逐项补齐官方文档中的其他平台；部署时统一遵循“最小权限、用户白名单、测试环境先验证”的原则。

9.7 集成与实战教程

API Server · 官方原文

API Server 将 Hermes 暴露为 OpenAI 兼容接口，可供 Open WebUI 或自定义前端调用。对公网开放时必须启用 Token、TLS、速率限制和来源控制；每个用户应使用隔离的 Session/Profile。

Provider Routing · 官方原文

Provider Routing 按模型、任务和可用凭据选择推理端点。主模型与摘要、命名、技能选择等辅助任务可走不同提供商，以平衡质量、延迟和成本。

Fallback Providers · 官方原文

Fallback 在主提供商限流、故障或拒绝时按顺序切换。候选模型应具备相近上下文窗口和工具调用能力；不要把安全策略更弱的端点作为静默降级目标。

Nous Portal 与 Tool Gateway

Nous Portal 可用一次 OAuth 配置模型与工具网关；Tool Gateway 汇集网页搜索、图片生成、TTS 和浏览器工具。执行 hermes setup --portal 是最快的完整配置路径。

MCP 实战 · 官方原文

先添加 MCP Server，再测试连接并过滤实际需要的工具。不要把服务器返回内容视为可信系统指令；高风险 MCP 工具应继续走审批流程。

将 Hermes 作为 Python 库 · 官方原文

可在 Python 脚本、Web 服务或自动化流水线中直接实例化 AIAgent，复用模型、工具和回调能力。应用层需要自行管理事件循环、会话存储、并发、超时和异常边界。

本地 Mac 模型 · 官方原文

Apple Silicon 可通过 llama.cpp 或 MLX 启动 OpenAI 兼容服务，再让 Hermes 指向本地 Base URL。选择模型时先计算统一内存需求，并确保上下文窗口和工具调用模板满足 Agent 工作负载。

实战教程索引

9.8 开发者内部机制

原页面只有架构和贡献指南，缺少官方开发文档中的执行路径。下面按源码阅读顺序补齐。

新版运行时与插件开发页面

• ACP Internals：编辑器协议的会话、事件和工具调用桥接。
• Tools Runtime：工具发现、Schema、执行、结果压缩和审批路径。
• Cron Internals：调度、持久化、并发和投递机制。
• Context Engine Plugins：替换或增强上下文组装与压缩。
• Memory Provider Plugins：实现外部记忆存储与召回适配器。
• 图片 Provider 插件、视频 Provider 插件、搜索 Provider 插件：统一媒体/搜索后端扩展规范。
• Programmatic Integration：在其他应用中嵌入 Hermes 的底层集成方式。
• Trajectory Format：批处理与强化学习使用的轨迹数据结构。

9.9 参考目录与新版能力

缺失参考页

当前版本新增的重要页面

9.10 深层子页面补充

除官方 llms.txt 的主导航外，完整文档还包含以下二级、三级页面。此前中文页没有入口，现按主题逐项补齐。

部署、模型与自动化教程

新版功能与运维子页面

消息平台深层页面

开发者深层页面