Hermes Agent 完全配置手册

来源：Hermes 官方文档、CSDN、腾讯云开发者社区、Hermes 中文社区

📎 官方社区安装配置文档 — 遇到问题先查这里

安装与更新

# macOS / Linux 一键安装
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 国内加速镜像
curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

# 安装后重载 shell
source ~/.zshrc

# 验证
hermes --version
hermes doctor          # 检查依赖和配置是否完整

# 更新
hermes update

安装后核心目录：

~/.hermes/
├── config.yaml         # 全局配置主文件
├── .env                # API Key 等敏感凭证
├── skills/             # 技能目录
├── profiles/           # 多 Profile
├── sessions/           # 会话记录
└── logs/               # 日志

常用命令速查

启动与恢复

hermes                       # classic CLI
hermes --tui                 # TUI 模式
hermes --tui -c              # 恢复最近会话
hermes --tui -r <session_id> # 恢复指定会话

# 默认 TUI：在 shell profile 中设置
export HERMES_TUI=1

工具与技能管理

hermes tools list            # 列出所有工具及状态
hermes tools enable NAME     # 启用工具集
hermes tools disable NAME    # 禁用工具集
hermes skills list           # 已安装技能列表
hermes skills search QUERY   # 搜索技能
hermes skills install ID     # 安装技能
hermes skills browse         # 浏览所有可用技能

状态诊断

1
2
3

hermes doctor           # 检查依赖和配置
hermes status           # 显示组件状态
hermes insights         # 使用分析

会话内斜杠命令

参考：斜杠命令参考

命令	作用
`/new` / `/reset`	开始新会话
`/clear`	清屏并开始新会话
`/retry`	重试最后一条消息
`/undo`	撤销上一轮对话
`/title`	命名当前会话
`/sessions`	浏览并恢复历史会话
`/model`	切换模型（TUI 下按提供商分组带费用提示）
`/usage`	Token 用量 / 费用 / 上下文面板
`/compress`	手动压缩上下文（刷新记忆 + 摘要）
`/stop`	终止所有后台进程
`/bg` / `/btw`	在后台独立会话中运行任务
`/help`	显示帮助信息
`/reload`	热加载 `.env` 变量到运行中会话
`/reload-skills`	重载技能目录
`/reload-mcp`	重载 MCP 服务器
`/plugins`	列出已安装插件及状态
`/skills`	搜索、安装、管理 skill

CC Switch — 多 CLI 模型管理

CC Switch 是一款桌面 GUI 工具，统一管理 Claude Code、Codex、Gemini CLI、OpenCode、Hermes Agent 等多款 AI CLI 工具的 API 后端、MCP 服务器和用量统计。

核心能力：

一键切换 Provider：管理各 CLI 工具的 API 后端，内置 50+ 中转节点预设
MCP 服务器统一管理：支持 stdio/http/sse，添加一次即可同步到所有客户端
跨工具用量统计

1	brew install cc-switch

CC Switch 通过自定义（custom）添加模型，支持 API 同步。

CC Switch 配置示意图

Web 搜索与内容提取后端

Hermes 采用 后端分离 模式：搜索和提取可指向不同提供商，按需组合以降低成本。

# 按能力分离
web:
  search_backend: "searxng"     # 搜索用自托管
  extract_backend: "firecrawl"  # 提取用专业服务

# 或用单一后端
web:
  backend: "tavily"

参考：Web 搜索配置文档（含各提供商注册方法）

提供商	搜索	提取	爬取	免费额度
Firecrawl	✔	✔	✔	500/月
SearXNG（自托管 Docker）	✔	—	—	免费
Brave Search	✔	—	—	2000/月
DDGS（`pip install ddgs`）	✔	—	—	免费无限制
Tavily（推荐）	✔	✔	✔	1000/月
Exa	✔	✔	—	1000/月

三列能力说明

搜索 → 给定关键词，返回 URL + 摘要列表。Hermes 用它”发现”页面
提取 → 给定 URL，抓取全文并清洗成 Markdown。Hermes 用它”读”页面
爬取 → 递归遍历子链接，批量提取多个页面

SearXNG 自托管

# docker-compose.yml
services:
  searxng:
    image: searxng/searxng:latest
    ports: ["8888:8080"]
    environment:
      - SEARXNG_BASE_URL=http://localhost:8888/

# settings.yml — 必须启用 JSON API
formats:
  - html
  - json

长页面提取机制

页面 <5k 字符原样返回，5k–500k 自动摘要（上限 5k），500k–2M 分块并行，>2M 拒绝。

专用摘要模型配置

web_extract:
  provider:        # 低成本模型处理结果
  model: 
  base_url: 
  api_key: ""
  timeout: 360
  extra_body: {}

Camofox 防爬浏览器

Camofox 是一台 隐身浏览器引擎，专门渲染动态 JS 页面、模拟真人浏览器指纹以绕过反爬检测。它不直接提取内容，而是作为浏览器后端供 Hermes 的 browser_navigate + browser_console 工具链调用。

安装

# 第 1 步：npm 全局安装（自动触发 postinstall 下载浏览器内核）
npm install -g camofox-browser

# 第 2 步：验证
camofox --version

⚠️ 如果下载卡住/超时，可以启用代理手动补跑：
1
2
cd /opt/homebrew/lib/node_modules/camofox-browser
ALL_PROXY=http://127.0.0.1:7890 npx camoufox-js fetch

1
2
3

# 第 3 步：启动服务（后台常驻，监听 localhost:9377）
cd /opt/homebrew/lib/node_modules/camofox-browser
npm start

📌 Camofox 必须保持运行，占用 ~200-300MB 内存。Hermes 会自动检查端口 9377，不通则自动唤醒。

配置

1
2
3

# ~/.hermes/config.yaml
browser:
  engine: camofox

1 2	# ~/.hermes/.env CAMOFOX_URL=http://localhost:9377

验证

1	hermes doctor

静态普通页面 → web_extract；有反爬/动态页面 → Camofox + browser 工具链

记忆系统 — Hindsight

Hermes 有两种记忆层：常规记忆（memory 工具写入，约 2200 字符，直接注入到 LLM 上下文）和 Hindsight 长期记忆。

Hindsight 从对话中自动提取实体、关系和时间线索，构建成知识图谱并持久化到独立存储。每次会话开始时，Hindsight 自动检索相关记忆注入上下文——即使隔了几周，也能记得用户的环境配置、偏好和项目决策。

初次配置

1	hermes memory setup

可选Cloud储存（配置方便但是额度少） → 输入 API Key（官网可申领），向导会自动写入配置。

Cloud 到期后切换本地

Hindsight 支持 Cloud 和 Local 两种运行模式。Cloud 到期后无需重装，只需重新执行一次配置向导：

1	hermes memory setup

交互时选择 local_embedded，向导会自动启动守护进程和内嵌 PostgreSQL，配置无缝迁移。

中文优化：替换嵌入与重排序模型

默认的英文嵌入/重排序模型在处理中文内容时召回效果不理想。在 ~/.hermes/.env 追加以下环境变量，替换为中文优化版：

1
2
3

HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL=BAAI/bge-small-zh-v1.5
HINDSIGHT_API_RERANKER_LOCAL_MODEL=maidalun1020/bce-reranker-base_v1
HINDSIGHT_API_RERANKER_LOCAL_TRUST_REMOTE_CODE=true

模型下载（国内镜像）

Hindsight 本地模式需要下载两种模型：嵌入模型（将文本转为向量）和 重排序模型（精排检索结果）。通过 Hugging Face 国内镜像下载：

# 1️⃣ 下载嵌入模型（BAAI/bge-small-zh-v1.5，384维，轻量中文）
HF_ENDPOINT=https://hf-mirror.com python3 -c "
from sentence_transformers import SentenceTransformer
SentenceTransformer('BAAI/bge-small-zh-v1.5')
print('嵌入模型下载完成')
"

# 2️⃣ 下载重排序模型（maidalun1020/bce-reranker-base_v1，中文通用）
HF_ENDPOINT=https://hf-mirror.com python3 -c "
from sentence_transformers import CrossEncoder
CrossEncoder('maidalun1020/bce-reranker-base_v1', trust_remote_code=True)
print('重排序模型下载完成')
"

下载完成后，在 .env 中追加离线标记，避免每次启动联网检查：

1	echo "HF_HUB_OFFLINE=1" >> ~/.hermes/.env

切换不同维度的嵌入模型后，务必清空 memory_units（旧向量与新模型不兼容）。

可选模型列表

以下为兼容的中文/多语言模型，可按需替换（无需额外下载方式，修改 .env 变量名后重复上述步骤即可）。

用途	模型	维度	说明
嵌入	`BAAI/bge-small-zh-v1.5`	384	轻量够用
嵌入	`BAAI/bge-base-zh-v1.5`	768	质量更好，资源消耗中等
嵌入	`BAAI/bge-large-zh-v1.5`	1024	最佳质量，适合离线服务器
嵌入	`BAAI/bge-m3`	1024	多语言（100+语言），非纯中文场景推荐
嵌入	`intfloat/multilingual-e5-small`	384	微软多语言 E5 轻量版
嵌入	`intfloat/multilingual-e5-base`	768	微软多语言 E5 中等版
重排序	`maidalun1020/bce-reranker-base_v1`	—	中文通用
重排序	`BAAI/bge-reranker-v2-m3`	—	多语言 reranker，与 bge-m3 搭配
重排序	`BAAI/bge-reranker-v2-gemma`	—	质量更高，资源需求大

切换不同维度的嵌入模型后，务必清空 memory_units（旧向量与新模型不兼容）。

参考：完整配置

以下为 Hindsight 本地模式的完整配置示例：

~/.hermes/.env（Hindsight 相关变量）:

HINDSIGHT_API_KEY=sk-...
HINDSIGHT_API_LLM_API_KEY=sk-...
HINDSIGHT_API_LLM_BASE_URL=https://token.sensenova.cn/v1
HINDSIGHT_API_LLM_MODEL=deepseek-v4-flash
HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL=BAAI/bge-small-zh-v1.5
HINDSIGHT_API_RERANKER_LOCAL_MODEL=maidalun1020/bce-reranker-base_v1
HINDSIGHT_API_RERANKER_LOCAL_TRUST_REMOTE_CODE=true
HF_HUB_OFFLINE=1

~/.hindsight/profiles/hermes/config.json:

// 交互配置生成内容
{
  "mode": "local_embedded",
  "llm_provider": "openai_compatible",
  "llm_api_key": "sk-...",
  "llm_base_url": "https://token.sensenova.cn/v1",
  "llm_model": "deepseek-v4-flash",
  "recall_budget": "mid"
}

~/.hermes/config.yaml（启用 Hindsight）:

1 2	memory: provider: hindsight

诊断与日志

1 2	hermes memory status # 查看记忆系统运行状态 cat ~/.hindsight/profiles/hermes.log # 查看 Hindsight 守护进程日志

MCP 服务器配置

MCP（Model Context Protocol）是让 Hermes 连接外部能力的标准协议，支持 stdio（子进程）和 HTTP（远程）两种传输方式。工具注册后以 mcp_{服务器名}_{工具名} 格式注入 Hermes 工具集。

mcp_servers:
  # stdio 模式
  cua-driver:
    command: /Users/matebook/.local/bin/cua-driver
    args: ["mcp"]

  # npx 模式
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

  # HTTP 模式
  remote_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer sk-..."

hermes mcp list           # 列出已配置 MCP 服务器
hermes mcp add NAME       # 新增
hermes mcp remove NAME    # 移除
hermes mcp test NAME      # 测试连接

Token 成本管控

Tokescale — Token 用量监控

专为 Hermes 等 AI 编码助手设计的 CLI 监控工具，支持 TUI 可视化 + JSON 导出。

npx tokscale@latest
tokscale --hermes              # 只看 Hermes
tokscale --hermes --week       # 近 7 天趋势
tokscale --json                # JSON 导出
tokscale models                # 按模型统计

RTK — 终端 Token 降本

RTK（Rust Token Killer） 是 Rust 写的零依赖终端输出过滤代理，自动压缩 ls、git status、npm test 等命令输出，减少 60%-90% 的无效 Token。通过 Hermes 插件机制拦截 terminal 调用，用 rtk rewrite 压缩后再执行。

安装与配置

brew install rtk
rtk --version

# 安装 Hermes 插件（关键步骤）
rtk init --agent hermes -g

⚠️ 注意区别： rtk init -g 装的是 Claude Code Hook（对 Hermes 无效），rtk init --agent hermes -g 装的才是 Hermes 插件。

插件结构

1
2
3

~/.hermes/plugins/rtk-rewrite/
├── __init__.py    ← pre_tool_call Hook：拦截 terminal 命令
└── plugin.yaml    ← 插件清单

工作原理

terminal("git status")
    ↓
rtk-rewrite 插件 → rtk rewrite "git status"
    ↓
有压缩版？ → 替换命令 → 输出压缩 → 省 60-90% Token
无压缩版？ → 原样放行

查看节省量

1	rtk gain # 显示累计节省的 Token 量

配置后需重启 Hermes 会话（/new）插件才能加载。fail open 策略：rtk 出错或超时时命令照常执行。

自我进化（Self-Evolution）

Hermes 有两层进化机制：

内置：自动技能创建（日常使用）

每次完成复杂任务（5+ 工具调用），Hermes 自动评估流程价值，生成可复用的 SKILL.md 到 ~/.hermes/skills/。下次遇到类似场景自动匹配调用——“AI 自己总结 skill”。

外挂：Self-Evolution 研究项目（深度优化）

基于 DSPy + GEPA（遗传-帕累托进化算法，ICLR 2026 Oral），对已有 Skill 做进化式优化。

git clone https://github.com/NousResearch/hermes-agent-self-evolution.git
cd hermes-agent-self-evolution
pip install -e ".[dev]"

export HERMES_AGENT_REPO=~/.hermes/hermes-agent

# 进化已有 Skill
python -m evolution.skills.evolve_skill \
    --skill github-code-review \
    --iterations 10 \
    --eval-source sessiondb

进化对象	说明
Skill	优化 SKILL.md 步骤、提示词、约束条件
工具描述	让 LLM 更好理解每个工具
System Prompt	优化人设和系统指令
代码	直接优化 Hermes 源码中的工具实现

项目地址：~/hermes/repos/community/hermes-agent-self-evolution/

角色与技能生态

agency-agents-zh 是专为中文用户打造的角色仓库，每个角色是独立 .md 文件，包含人设、工作流和可交付成果。对话中直接激活即可。

211 个中文专业角色模板，18 个部门分类
46 个中国市场原创智能体（小红书、抖音、微信、飞书等）
GitHub：https://github.com/jnMetaCode/agency-agents-zh

1
2
3

hermes skills search <关键词>    # 搜索技能
hermes skills install <ID>      # 安装技能
hermes skills browse            # 浏览所有可用技能

鸣谢

本文整理过程中参考了以下文章，特此感谢：