Hermes Agent 安装及配置

简介

Hermes Agent 是由 Nous Research 开发的自改进 AI Agent。它具有以下特点：

内置学习循环

--- 从经验中创建技能，使用过程中不断改进
跨会话记忆

--- 搜索历史对话，建立用户模型
多平台支持

--- Telegram、Discord、Slack、WhatsApp、Signal 和 CLI
多模型支持

--- 支持 Nous Portal、OpenRouter（200+ 模型）、OpenAI、Anthropic 等多种模型
灵活部署

--- 可在 $5 VPS、GPU 集群或无服务器基础设施上运行

系统要求

macOS 10.15 (Catalina) 或更高版本|WSL
Python 3.11+
网络连接

安装步骤

方法一：一键安装（推荐）

打开终端，执行以下命令：

go 复制代码

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

安装完成后，重新加载 Shell 配置：

go 复制代码

source ~/.zshrc    # 如果使用 zsh（macOS 默认）# 或source ~/.bashrc   # 如果使用 bash

方法二：手动安装

1. 安装依赖

确保已安装 Python 3.11+，可以使用 Homebrew 安装：

go 复制代码

# 安装 Homebrew（如果未安装）/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Pythonbrew install python@3.11

2. 安装 uv（Python 包管理器）

go 复制代码

curl -LsSf https://astral.sh/uv/install.sh | sh

3. 克隆仓库并安装

go 复制代码

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

# 创建虚拟环境uv venv venv --python 3.11source venv/bin/activate

# 安装 Hermes Agentuv pip install -e ".[all]"

快速开始

启动 Agent

go 复制代码

hermes

首次配置

运行设置向导，配置所有选项：

go 复制代码

hermes setup

或使用单独的命令进行配置：

命令	说明
`hermes model`	选择 LLM 提供商和模型
`hermes tools`	配置启用的工具
`hermes config set`	设置单个配置值
`hermes gateway`	启动消息网关（Telegram、Discord 等）

配置模型

支持的模型提供商

Nous Portal
OpenRouter（200+ 模型）
z.ai/GLM
Kimi/Moonshot
MiniMax
OpenAI
Anthropic
自定义端点

切换模型

go 复制代码

hermes model

或在对话中使用：

go 复制代码

/model openrouter:anthropic/claude-3.5-sonnet

CLI 常用命令

对话管理

命令	说明
`/new` 或 `/reset`	开始新对话
`/model [provider:model]`	更换模型
`/personality [name]`	设置个性
`/retry`	重试上一轮
`/undo`	撤销上一轮
`/compress`	压缩上下文
`/usage`	查看使用情况
`/skills`	浏览技能

其他命令

命令	说明
`hermes update`	更新到最新版本
`hermes doctor`	诊断问题

消息网关配置

Hermes Gateway 是一个后台进程，连接所有配置的消息平台，处理会话、运行定时任务并传递语音消息。

网关命令

go 复制代码

hermes gateway              # 前台运行（显示实时日志）hermes gateway setup      # 交互式配置所有消息平台hermes gateway install   # 安装为系统服务（macOS: launchd）hermes gateway start     # 启动服务hermes gateway stop      # 停止服务hermes gateway status   # 查看服务状态

# 查看日志tail -f ~/.hermes/logs/gateway.log  # 实时查看网关日志cat ~/.hermes/logs/gateway.log     # 查看完整日志

# 调试模式（显示详细日志）hermes chat --verbose

服务管理

go 复制代码

hermes gateway install    # 安装为 launchd 服务hermes gateway start   # 启动服务hermes gateway stop   # 停止服务hermes gateway status  # 查看状态tail -f ~/.hermes/logs/gateway.log  # 查看日志

服务文件位于 ~/Library/LaunchAgents/ai.hermes.gateway.plist。

聊天命令（在消息平台中使用）

命令	说明
`/new` 或 `/reset`	开始新对话
`/model [provider:model]`	更换模型
`/personality [name]`	设置个性
`/retry`	重试上一条消息
`/undo`	撤销上一轮对话
`/status`	显示会话信息
`/stop`	停止运行中的 agent
`/approve`	批准待处理的危险命令
`/deny`	拒绝待处理的危险命令
`/sethome`	将此聊天设为主页频道
`/compress`	手动压缩对话上下文
`/title [name]`	设置或显示会话标题
`/resume [name]`	恢复之前命名的会话
`/usage`	查看此会话的 token 使用量
`/insights [days]`	显示使用分析和洞察
`/voice [on\	off\	tts]`	控制语音回复
`/background <prompt>`	在后台会话中运行任务
`/reload-mcp`	重新加载 MCP 服务器
`/update`	更新 Hermes Agent
`/help`	显示可用命令
`/<skill-name>`	调用任何已安装的技能

会话管理

会话持续性

会话在重置前会持续保留，agent 会记住对话上下文。

重置策略

策略	默认值	说明
每日	4:00 AM	每天特定时间重置
闲置	1440 分钟	闲置 N 分钟后重置
组合	(综合)	触发时更早的那个

可以在 ~/.hermes/gateway.json 中为每个平台配置覆盖：

go 复制代码

{"reset_by_platform":{"telegram":{"mode":"idle","idle_minutes":240},"discord":{"mode":"idle","idle_minutes":60}}}

后台会话

在独立的背景会话中运行任务，让 agent 独立工作而主聊天保持响应：

go 复制代码

/background 检查集群中的所有服务器，报告任何宕机的服务器

Hermes 会立即确认：

go 复制代码

🔄Background task started:"检查集群中的所有服务器..."Task ID: bg_143022_a1b2c3

后台任务完成时，结果会发送回同一聊天，前缀为 "✅ Background task complete"。

安全设置

默认情况下，网关拒绝所有不在白名单中或未通过 DM 配对的用户。 这是具有终端访问权限的机器人的安全默认设置。

用户白名单

go 复制代码

# 限制特定用户（推荐）：TELEGRAM_ALLOWED_USERS=123456789,987654321DISCORD_ALLOWED_USERS=123456789012345678SIGNAL_ALLOWED_USERS=+155****4567,+155****6543FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy

# 或允许所有用户（不推荐）：GATEWAY_ALLOW_ALL_USERS=true

DM 配对（白名单的替代方案）

不需要手动配置用户 ID，未知用户在 DM 机器人时会收到一次性的配对码：

go 复制代码

# 用户看到："配对码: XKGH5N7P"# 您批准他��：hermes pairing approve telegram XKGH5N7P

# 其他配对命令：hermes pairing list          # 查看待批准 + 已批准用户hermes pairing revoke telegram 123456789# 移除访问权限

配对码 1 小时后过期，有速率限制，使用加密随机数。

消息平台支持

平台	语音	图片	文件	线程	表情	打字	流式
Telegram	✅	✅	✅	✅	---	✅	✅
Discord	✅	✅	✅	✅	✅	✅	✅
Slack	✅	✅	✅	✅	✅	✅	✅
WhatsApp	---	✅	✅	---	---	✅	✅
Signal	---	✅	✅	---	---	✅	✅
飞书/Lark	✅	✅	✅	✅	✅	✅	✅
企业微信	✅	✅	✅	---	---	✅	✅
微信	✅	✅	✅	---	---	✅	✅

Web 界面

Hermes Agent 支持通过 Open WebUI 或 API Server 提供 Web 界面。

Open WebUI 集成

Open WebUI 是一个开源的 Web UI，可以连接到 Hermes 作为后端。

配置步骤：

首先在 Hermes 中配置 API 服务器
然后将 Open WebUI 连接到 Hermes

具体配置请参考官方文档：Open WebUI + API Server

API 服务器

Hermes 也提供 API 服务器模式，可以通过 HTTP API 访问。

Webhooks

Hermes 支持 Webhooks，可以接收外部 HTTP 请求触发。

具体配置请参考官方文档：Webhooks

飞书 / Lark 集成

Hermes Agent 可以作为飞书或 Lark 机器人进行集成，支持私聊和群聊、定时任务通知、文本/图片/音频/文件附件等。

连接模式

支持两种连接模式：

模式	说明	适用场景
`websocket` （推荐）	Hermes 主动建立出站连接，无需公网地址	笔记本、工作站、私有服务器
`webhook`	飞书推送事件到 Hermes 的 HTTP 端点	已有公网可访问的 HTTP 服务

步骤 1：创建飞书应用

方式一：扫码创建（推荐）

go 复制代码

hermes gateway setup

选择 Feishu / Lark，使用飞书或 Lark 移动端应用扫描二维码。Hermes 会自动创建机器人应用并保存凭证。

方式二：手动创建

打开飞书开发者控制台：

飞书：https://open.feishu.cn/
Lark：https://open.larksuite.com/

创建新应用
在 凭证与基础信息 中复制 App ID 和 App Secret
启用应用的 机器人 能力
运行 hermes gateway setup，选择 Feishu / Lark 并输入凭证

⚠️ 注意：请妥善保管 App Secret，拥有它的人可以冒充您的应用。

步骤 2：选择连接模式

WebSocket 模式（推荐）

当 Hermes 运行在笔记本、工作站或私有服务器时使用，无需公网 URL：

go 复制代码

FEISHU_CONNECTION_MODE=websocket

要求：需要安装 websockets Python 包。SDK 会自动处理连接生命周期、心跳和自动重连。

Webhook 模式

仅当您已有可访问的 HTTP 端点时使用：

go 复制代码

FEISHU_CONNECTION_MODE=webhook

在 webhook 模式下，Hermes 启动 HTTP 服务器（通过 aiohttp），端点路径为 /feishu/webhook。

可自定义 webhook 服务器配置：

go 复制代码

FEISHU_WEBHOOK_HOST=127.0.0.1# 默认：127.0.0.1FEISHU_WEBHOOK_PORT=8765# 默认：8765FEISHU_WEBHOOK_PATH=/feishu/webhook  # 默认：/feishu/webhook

步骤 3：配置 Hermes

方式一：交互式配置

go 复制代码

hermes gateway setup

选择 Feishu / Lark 并按提示填写。

方式二：手动配置

在 ~/.hermes/.env 中添加：

go 复制代码

FEISHU_APP_ID=cli_xxxFEISHU_APP_SECRET=secret_xxxFEISHU_DOMAIN=feishuFEISHU_CONNECTION_MODE=websocket

# 可选但强烈推荐FEISHU_ALLOWED_USERS=ou_xxx,ou_yyyFEISHU_HOME_CHANNEL=oc_xxx

FEISHU_DOMAIN 取值：

feishu
- 飞书（中国）
lark
- Lark（国际版）

步骤 4：启动网关

go 复制代码

hermes gateway

然后从飞书/Lark 给机器人发送消息，确认连接正常。

行为说明

场景	行为
私聊	Hermes 响应每条消息
群聊	仅当 @提及机器人时响应
共享群聊	默认每个用户有独立的会话历史

共享群聊行为可通过 config.yaml 控制：

go 复制代码

group_sessions_per_user:true

设为 false 则整个群聊共享一个对话。

安全设置

用户白名单

生产环境建议设置飞书 Open ID 白名单：

go 复制代码

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy

如果白名单为空，任何能访问机器人的用户都可以使用它。

Webhook 加密密钥

在 webhook 模式下，设置加密密钥以启用签名验证：

go 复制代码

FEISHU_ENCRYPT_KEY=your-encrypt-key

此密钥可在飞书应用配置的 事件订阅 部分找到。

验证令牌

额外的身份验证层：

go 复制代码

FEISHU_VERIFICATION_TOKEN=your-verification-token

群消息策略

FEISHU_GROUP_POLICY 环境变量控制群聊响应行为：

值	行为
`open`	响应任何用户在任何群中的 @提及
`allowlist`	仅响应白名单用户的 @提及（默认）
`disabled`	忽略所有群消息

Home Chat（主页聊天）

在飞书/Lark 聊天中使用 /set-home 将其标记为定时任务结果和跨平台通知的主页频道。

也可以预配置：

go 复制代码

FEISHU_HOME_CHANNEL=oc_xxx

交互式卡片操作

当用户点击机器人发送的交互式卡片按钮时，适配器将其路由为 /card 命令事件。

必须的飞书应用配置（交互式卡片）：

交互式卡片需要在飞书开发者控制台完成三项配置：

订阅卡片操作事件 ：在 事件订阅 中添加 card.action.trigger
启用交互式卡片能力 ：在 应用功能 > 机器人 中启用 消息卡片 开关
配置卡片请求 URL （仅 webhook 模式）：在 应用功能 > 机器人 > 消息卡片请求 URL 设置与事件 webhook 相同的端点

⚠️ 警告：缺少任何配置都会导致点击卡片按钮时返回错误 200340。

媒体支持

接收媒体

类型	扩展名	处理方式
图片	.jpg, .jpeg, .png, .gif, .webp, .bmp	通过飞书 API 下载并缓存
音频	.ogg, .mp3, .wav, .m4a, .aac, .flac, .opus, .webm	下载并缓存
视频	.mp4, .mov, .avi, .mkv, .webm, .m4v, .3gp	作为文档下载缓存
文件	.pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx 等	作为文档下载缓存

发送媒体

方法	发送内容
`send`	文本或富文本消息
`send_image` / `send_image_file`	图片气泡（可选标题）
`send_document`	文件附件
`send_voice`	音频文件附件
`send_video`	视频消息

Markdown 渲染

当输出文本包含 markdown 格式时，适配器会自动将其作为飞书帖子消息发送，支持富文本渲染。

如果飞书 API 拒绝帖子内容，会自动回退为纯文本发送。

ACK 表情反应

适配器收到消息后会立即添加 ✅ 表情反应，表示消息已接收并正在处理。

环境变量完整列表

变量	必需	默认值	说明
`FEISHU_APP_ID`	✅	---	飞书/Lark App ID
`FEISHU_APP_SECRET`	✅	---	飞书/Lark App Secret
`FEISHU_DOMAIN`	---	`feishu`	`feishu` （中国）或 `lark`（国际）
`FEISHU_CONNECTION_MODE`	---	`websocket`	`websocket` 或 `webhook`
`FEISHU_ALLOWED_USERS`	---	(空)	用户白名单 Open ID，逗号分隔
`FEISHU_HOME_CHANNEL`	---	---	定时任务/通知输出的聊天 ID
`FEISHU_ENCRYPT_KEY`	---	(空)	Webhook 签名验证加密密钥
`FEISHU_VERIFICATION_TOKEN`	---	(空)	Webhook 载荷验证令牌
`FEISHU_GROUP_POLICY`	---	`allowlist`	群消息策略：`open`、`allowlist`、`disabled`
`FEISHU_BOT_OPEN_ID`	---	(空)	机器人的 open_id（用于 @提及检测）
`FEISHU_BOT_NAME`	---	(空)	机器人显示名称
`FEISHU_WEBHOOK_HOST`	---	`127.0.0.1`	Webhook 服务器绑定地址
`FEISHU_WEBHOOK_PORT`	---	`8765`	Webhook 服务器端口
`FEISHU_WEBHOOK_PATH`	---	`/feishu/webhook`	Webhook 端点路径

故障排除

问题	解决方案
`lark-oapi not installed`	安装 SDK：`pip install lark-oapi`
`websockets not installed`	安装：`pip install websockets`
`aiohttp not installed`	安装：`pip install aiohttp`
机器人不在群聊中响应	确保机器人被 @提及，检查 `FEISHU_GROUP_POLICY` 和白名单
`Webhook rejected: invalid verification token`	确保 `FEISHU_VERIFICATION_TOKEN` 匹配飞书应用配置
`Webhook rejected: invalid signature`	确保 `FEISHU_ENCRYPT_KEY` 匹配飞书应用配置
图片/文件未被机器人接收	为飞书应用授予 `im:message` 和 `im:resource` 权限
错误 200340（点击按钮）	启用交互式卡片能力并配置卡片请求 URL

从 OpenClaw 迁移

如果您之前使用 OpenClaw，可以自动迁移设置：

go 复制代码

# 交互式迁移hermes claw migrate

# 预览迁移内容hermes claw migrate --dry-run

# 仅迁移用户数据（不含密钥）hermes claw migrate --preset user-data

# 覆盖已存在的内容hermes claw migrate --overwrite

迁移内容包括：

SOUL.md（个性文件）
记忆（MEMORY.md 和 USER.md）
技能
命令白名单
消息设置
API 密钥
TTS 资源

项目结构

go 复制代码

~/.hermes/├── config.yaml          # 主配置文件├── memories/# 持久化记忆├── skills/# 用户技能├── sessions/# 会话历史└── context/# 上下文文件

故障排除

常见问题

命令未找到
1. source ~/.zshrc
2. # 或重新打开终端
Python 版本问题
1. # 检查 Python 版本
2. python3 --version
4. # 使用指定版本
5. uv venv venv --python 3.11
权限问题
1. # 确保脚本有执行权限
2. chmod +x ~/.hermes/scripts/*

诊断工具

go 复制代码

hermes doctor

许可证

MIT License --- 详见 LICENSE。

Hermes Agent 安装及配置

简介

系统要求

安装步骤

方法一：一键安装（推荐）

方法二：手动安装

1. 安装依赖

2. 安装 uv（Python 包管理器）

3. 克隆仓库并安装

快速开始

启动 Agent

首次配置

配置模型

支持的模型提供商

切换模型

CLI 常用命令

对话管理

其他命令

消息网关配置

网关命令

服务管理

聊天命令（在消息平台中使用）

会话管理

会话持续性

重置策略

后台会话

安全设置

用户白名单

DM 配对（白名单的替代方案）

消息平台支持

Web 界面

Open WebUI 集成

API 服务器

Webhooks

飞书 / Lark 集成

连接模式

步骤 1：创建飞书应用

方式一：扫码创建（推荐）

方式二：手动创建

步骤 2：选择连接模式

WebSocket 模式（推荐）

Webhook 模式

步骤 3：配置 Hermes

方式一：交互式配置

方式二：手动配置

步骤 4：启动网关

行为说明

安全设置

用户白名单

Webhook 加密密钥

验证令牌

群消息策略

Home Chat（主页聊天）

交互式卡片操作

媒体支持

接收媒体

发送媒体

Markdown 渲染

ACK 表情反应

环境变量完整列表

故障排除

从 OpenClaw 迁移

项目结构

故障排除

常见问题

诊断工具

相关链接

许可证