hermes 安装与初始化记录

发表于 | 分类于

Hermes Agent 安装使用文档

简介

Hermes Agent 是由 Nous Research 构建的开源自对齐 AI 代理。

核心特性

特性 说明
多模型支持 Anthropic、OpenAI、OpenRouter (200+)、NVIDIA NIM、Hugging Face、MiniMax 等
多平台消息 Telegram、Discord、Slack、WhatsApp、Signal、Email
内置学习循环 技能自动创建、记忆持久化、跨会话检索
定时自动化 Cron 调度 + 多平台推送
终端后端 Local、Docker、SSH、Daytona、Singularity、Modal
MCP 集成 支持 Model Context Protocol 扩展

环境要求

  • Python: 3.11+
  • 系统: Linux、macOS、WSL2、Android (Termux)
  • 网络: 需要访问你所用模型的 API

Windows 用户: 请安装 WSL2 后在 WSL2 内安装。

安装方式

一键安装（推荐）

保证网络环境畅通

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

安装脚本会自动检测平台（桌面/服务器/Android），并完成：

  • 安装 uv 包管理器（桌面端） ~/.local/bin/uv
  • 创建 Python 3.11 虚拟环境 source ~/.hermes/hermes-agent/venv/bin/activate, ~/.hermes/hermes-agent/venv/bin/python
  • 安装所有依赖
  • 创建 .env 配置文件
  • 软链接 hermes 命令到 ~/.local/bin ~/.hermes/hermes-agent/venv/bin/hermes

安装完成后重载 shell 并启动：

1
2
source ~/.bashrc  # 或 source ~/.zshrc
hermes            # 开始对话！

手动安装

如果你更喜欢手动安装(或者网络环境不好)：

主要是 执行 scripts/install.sh 这个脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
mkdir ~/.hermes
cd ~/.hermes
# 克隆仓库
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 运行安装脚本
./setup-hermes.sh

# 或手动分步安装
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all]"

优化

1
2
3
cd ~/.hermes/hermes-agent
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
uv sync

下载 

1
playwright install chromium # 这个需要时间

安装完成后手动链接命令：

1
2
3
4
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Termux (Android) 安装

1
2
3
4
5
6
7
# 安装依赖
pkg install python git curl

# 克隆并安装
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
./setup-hermes.sh

Termux 使用 Python stdlib venv 而非 uv，并安装 .[termux] 精选依赖集（避免 Android 不兼容的语音依赖）。

升级

1
hermes update

初始配置

方式一：交互式向导（推荐首次使用）

1
hermes setup

向导会引导你配置：

  • API Key（Anthropic、OpenRouter 等）
  • 消息平台（Telegram Bot Token 等）
  • 默认模型
  • 工具集启用状态

方式二：手动配置

1
2
3
4
5
6
7
8
9
10
# 编辑配置文件
vim ~/.hermes/.env

# 设置 API Key
ANTHROPIC_API_KEY=sk-ant-xxxxx
OPENROUTER_API_KEY=sk-or-xxxxx

# 或使用 hermes config 命令
hermes config set ANTHROPIC_API_KEY=sk-ant-xxxxx
hermes config set default_model=anthropic/claude-opus-4-6

模型选择

1
2
hermes model                    # 交互式选择
hermes model list               # 列出所有可用模型

支持的模型来源：

  • anthropic/claude-opus-4-6
  • openrouter/anthropic/claude-3.5-sonnet
  • openai/gpt-4o
  • huggingface/meta-llama/Llama-3-70b
  • nvidia/nemotron
  • minimax/minimax …等

基本使用

CLI 交互

1
hermes

进入交互式命令行界面，支持：

  • 多行编辑
  • 斜杠命令自动补全
  • 对话历史
  • 流式工具输出
  • Ctrl+C 中断

常用斜杠命令：

命令 功能
/new 开始新对话
/model [provider:model] 切换模型
/personality [name] 设置人格
/retry 重试上一轮
/undo 撤销上一轮
/compress 压缩上下文
/usage 查看 token 使用量
/skills 浏览技能列表
/stop 停止当前任务

TUI 界面

1
hermes --tui

启动带有富文本界面的终端 UI。

消息网关

配置后可通过 Telegram/Discord 等平台与 Hermes 对话：

1
2
3
4
5
6
7
8
# 初始化网关配置
hermes gateway setup

# 启动网关服务
hermes gateway start

# 作为 systemd 服务运行（Linux 服务器）
hermes gateway install

支持的平台：

平台 配置方式
Telegram Bot Token + 允许的用户 ID
Discord Bot Token + Server ID
Slack Bot Token + Workspace
WhatsApp 扫码登录
Signal Phone number
Email IMAP/SMTP
Home Assistant Webhook URL

主要命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# 基础命令
hermes                  # 启动交互式 CLI
hermes setup            # 运行配置向导
hermes model            # 选择模型
hermes tools            # 配置工具集
hermes config           # 查看/修改配置
hermes status           # 查看当前状态
hermes doctor           # 诊断问题

# 网关命令
hermes gateway setup    # 配置消息平台
hermes gateway start    # 启动网关
hermes gateway install  # 安装为系统服务
hermes gateway stop     # 停止网关

# 定时任务
hermes cron list        # 列出所有定时任务
hermes cron create      # 创建新任务
hermes cron remove      # 删除任务

# Webhook
hermes webhook subscribe # 订阅 GitHub/通用 webhook
hermes webhook list     # 列出 webhook 订阅

# 技能
hermes skills           # 浏览/管理技能
# 自动化迁移
hermes claw migrate     # 从 OpenClaw 迁移数据

# 更新
hermes update           # 更新到最新版本

定时任务

创建定时任务

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 基础用法（每日上午 9 点）
hermes cron create "0 9 * * *" \
	"生成每日 AI 新闻摘要并发送到 Telegram" \
	--name "每日摘要" \
	--deliver telegram

# 自然语言简写
hermes cron create "every 1h" \
	"检查网站状态，如有异常则报警" \
	--name "网站监控" \
	--deliver telegram

# 带技能的定时任务
hermes cron create "0 8 * * 1" \
	"搜索 arXiv 论文，保存前 3 篇到 Obsidian" \
	--skills "arxiv,obsidian" \
	--name "每周论文" \
	--deliver telegram

# 带脚本预处理的定时任务
hermes cron create "every 30m" \
	"如果 CHANGE DETECTED 则摘要变化，否则回复 [SILENT]" \
	--script ~/.hermes/scripts/watch.py \
	--name "价格监控"

定时任务交付目标

1
2
3
4
5
6
7
--deliver telegram                    # Telegram 主会话
--deliver discord                     # Discord 主频道
--deliver slack                       # Slack 频道
--deliver sms:+155****4567            # 短信
--deliver telegram:-1001234567890:42  # Telegram 论坛主题
--deliver github_comment              # GitHub PR 评论
--deliver local                       # 仅保存文件，不通知

查看和管理

1
2
3
4
5
hermes cron list              # 列出所有任务
hermes cron pause <job_id>    # 暂停任务
hermes cron resume <job_id>    # 恢复任务
hermes cron remove <job_id>    # 删除任务
hermes cron run <job_id>       # 手动触发一次

Webhook 自动化

订阅 GitHub 事件

1
2
3
4
hermes webhook subscribe pr-review \
	--events "pull_request" \
	--prompt "PR #{pull_request.number}: {pull_request.title} — 检查是否涉及认证模块" \
	--deliver slack

订阅通用 webhook

1
2
3
hermes webhook subscribe alert-triage \
	--prompt "告警: {alert.name}，严重度: {alert.severity}。找到负责服务并给出处理建议" \
	--deliver telegram

支持的交付目标与定时任务相同。

技能系统

技能（Skills）是 Hermes 的程序性记忆系统，让 Agent 在特定领域具备专业能力。

内置技能

1
2
3
hermes skills                    # 浏览技能列表
hermes skills enable <name>      # 启用技能
hermes skills disable <name>     # 禁用技能

部分内置技能：

技能 功能
arxiv 搜索 arXiv 学术论文
obsidian 读写 Obsidian 笔记库
github-pr-workflow GitHub PR 全流程管理
k8s Kubernetes 集群管理
kibana-log 查询 K8s 日志
notion Notion API 集成
xitter Twitter/X 操作
youtube-content YouTube 内容处理

技能市场

1
2
hermes skills hub                # 浏览社区技能
hermes skills install <skill>    # 安装技能

创建自定义技能

在 ~/.hermes/skills/ 目录下创建技能：

1
2
3
~/.hermes/skills/my-skill/
├── SKILL.md        # 技能定义（必需）
└── references/     # 参考文档（可选）

SKILL.md 示例：

1
2
3
4
5
6
7
8
9
10
11
---
name: my-skill
description: 我的自定义技能
triggers:
	- /my-skill
	- 使用我的技能处理
---

# 使用说明

这个技能用于...

配置说明

配置文件位置

  • 主配置：~/.hermes/config.yaml
  • 环境变量：~/.hermes/.env
  • 记忆数据：~/.hermes/memory/
  • 技能目录：~/.hermes/skills/
  • 会话历史：~/.hermes/sessions/

常用配置项

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# ~/.hermes/config.yaml

# 默认模型
default_model: anthropic/claude-opus-4-6

# 推理努力程度 (none/minimal/low/medium/high/xhigh)
reasoning_effort: medium

# 工具集配置
tools:
	enabled:
	- terminal
	- file
	- web
	- search
	disabled: []

# 消息网关
gateway:
	enabled_platforms:
	- telegram
	- discord

# 网络
network:
	force_ipv4: false  # 启用 IPv4 优先（解决 IPv6 不通的问题）

# 安全
security:
	dangerous_commands_approval: "ask"  # ask/always/never

环境变量配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# API Keys
ANTHROPIC_API_KEY=sk-ant-xxxxx
OPENROUTER_API_KEY=sk-or-xxxxx
OPENAI_API_KEY=sk-xxxxx

# 默认模型
DEFAULT_MODEL=anthropic/claude-opus-4-6

# 代理
HTTP_PROXY=http://127.0.0.1:7890
HTTPS_PROXY=http://127.0.0.1:7890

# 自定义目录
HERMES_HOME=~/.hermes

# IPv4 优先
NETWORK_FORCE_IPV4=true

常见问题

安装后找不到命令

1
2
source ~/.bashrc
which hermes

或检查 ~/.local/bin 是否在 PATH 中：

1
echo $PATH | tr ':' '\n' | grep local

uv 安装失败

手动安装 uv：

1
2
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.cargo/env  # 如果 uv 被安装到 ~/.cargo/bin

模型连接超时

检查网络和代理设置：

1
hermes doctor

若 IPv6 不通，在 ~/.hermes/.env 中添加：

1
NETWORK_FORCE_IPV4=true

定时任务没有执行

1
2
hermes cron list
hermes doctor

检查 systemd 用户服务是否运行：

1
2
systemctl --user status hermes-gateway
journalctl --user -u hermes-gateway -f

从 OpenClaw 迁移

1
2
hermes claw migrate --dry-run  # 预览迁移内容
hermes claw migrate            # 执行迁移

进阶用法

MCP 服务器连接

在 config.yaml 中配置 MCP 服务器：

1
2
3
4
5
6
7
mcp:
	servers:
	my-server:
		command: npx
		args: ["-y", "@some/mcp-server"]
		env:
		API_KEY: xxx

或通过环境变量配置（参见 MCP 集成文档）。

子代理并行任务

1
2
/hermes delegate "研究 Topic A" --parallel
/hermes delegate "研究 Topic B" --parallel

脚本预处理

在自动化任务中，运行 Python 脚本注入上下文：

1
2
3
4
hermes cron create "0 2 * * *" \
	"处理脚本输出" \
	--script ~/.hermes/scripts/my_preprocessor.py \
	--name "夜间任务"

脚本的 stdout 会被注入为任务上下文。

个性化配置

.env 里手动新增配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 配置邮箱
EMAIL_ADDRESS=111@qq.com
EMAIL_PASSWORD=xxx
EMAIL_IMAP_HOST=imap.qq.com
EMAIL_IMAP_PORT=993
EMAIL_SMTP_HOST=smtp.qq.com
EMAIL_SMTP_PORT=587
EMAIL_POLL_INTERVAL=15
EMAIL_ALLOWED_USERS=222@qq.com
EMAIL_HOME_ADDRESS=222@qq.com

# 配置 dingtalk
DINGTALK_CLIENT_ID=dingxxx
DINGTALK_CLIENT_SECRET=xxxx
DINGTALK_ALLOWED_USERS=*
DINGTALK_HOME_CHANNEL=cidHCrTZYI0XmFkPyvZnOJFEuagqmHyKCAjptbnhITU0n4=

# 配置 model，使用 minimax cn
MINIMAX_CN_API_KEY=xxxx

# 配置 gateway token
HERMES_GATEWAY_TOKEN=xxx

# sudo 权限
SUDO_PASSWORD=xxx

config.yaml 里手动配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# 使用 minimax-cn
model:
  default: MiniMax-M2.7-highspeed
  provider: minimax-cn
  base_url: https://api.minimaxi.com/anthropic


# 额外的 skills 目录
skills:
  external_dirs:
    - ~/.agents/skills
  creation_nudge_interval: 15
  disabled: []

# 添加 webhook

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      routes:
        agent:
          events: []
          secret: testpass
          prompt: "\u6536\u5230\u544A\u8B66\uFF0C\u8BF7\u5206\u6790\u539F\u56E0\u5E76\
            \u7ED9\u51FA\u5904\u7406\u5EFA\u8BAE\u3002\n\u544A\u8B66\u5185\u5BB9\uFF1A\
            \n{__raw__}\n"
          deliver: email

发送 webhook 请求方式，最终结果通过 deliver: email 发出

1
2
3
4
5
6
7
8
9
10
11
12
#在上面的配置中 webhook 是固定的， route 自定义为 agent, secret 自定义 testpass
port=8644
route=agent
secret=testpass
BODY='{"alertname":"HighCPU","severity":"critical","host":"web-server-01","message":"CPU usage 95%"}'
curl -s -X POST http://127.0.0.1:8644/webhooks/${route} \
      -H "Content-Type: application/json" \
      -H "X-Webhook-Signature: $(echo -n "$BODY" | openssl dgst -sha256 -hmac ${secret} | cut -d' ' -f2)" \
      -d "$BODY"
      
# 请求返回
{"status": "accepted", "route": "agent", "event": "unknown", "delivery_id": "1776580775689"}

获取结果过程 

1
1776580775689 -> ~/.hermes/sessions/sessions.json -> 20260419_143935_73e269b4 -> ~/.hermes/sessions/20260419_143935_73e269b4.jsonl ->  "finish_reason": "stop" 的数据

gateway 安装启动

1
2
3
4
5
6
7
8
9
10
11
12
$ hermes gateway install
Installing user systemd service to: ~/.config/systemd/user/hermes-gateway.service
Created symlink ~/.config/systemd/user/default.target.wants/hermes-gateway.service → ~/.config/systemd/user/hermes-gateway.service.

✓ User service installed and enabled!

Next steps:
  hermes gateway start              # Start the service
  hermes gateway status             # Check status
  journalctl --user -u hermes-gateway -f  # View logs

✓ Systemd linger is enabled (service survives logout)

开启 dashboard

hermes dashboard

这会启动一个本地 Web 服务器，并在你的浏览器中打开 http://127.0.0.1:9119

1
hermes dashboard --port 8080 --host 0.0.0.0  --no-open --insecure

资源链接

资源 地址
官方文档 https://hermes-agent.nousresearch.com/docs/
GitHub 仓库 https://github.com/NousResearch/hermes-agent
Discord 社区 https://discord.gg/NousResearch
自动化模板 https://hermes-agent.nousresearch.com/docs/guides/automation-templates

Hermes Agent 由 Nous Research 构建，开源 MIT 协议。