Hermes-agent（爱马仕）

2026/04/09 ai ai · agent · tools · dev · desktop 10039 字 · 约 29 分钟 阅读 次
Hermes Agent 完整使用指南 — 安装配置、桌面版发布、命令速查、模型配置、飞书集成，持续跟踪更新。

Hermes简介

NousResearch/hermes-agent: The agent that grows with you

由Nous Research开发的自我改进型 AI 代理。它是唯一一款内置学习循环的代理——它从经验中创造技能，在使用过程中不断改进，自我引导以巩固知识，并在不同会话中构建一个不断加深的关于你的模型。

文档：Hermes Agent Documentation

安装

统一安装命令：

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

Windows子系统WSL2下安装

Windows下必须在WSL里安装，不支持Windows原生系统，使用统一安装命令安装即可。 可以在 WSL 的 Ubuntu 里安装个GUI版本的文本编辑工具：gedit（sudo apt install gedit），方便后面编辑配置文件。

Windows原生系统安装

20260518，hermes在0.1.4版本支持Windows原生系统安装了，安装步骤如下。

在powershell中执行如下命令安装：

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

如果执行失败，可以先在浏览器中访问：https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 然后保存为一个本地的文件，例如：install.ps1

然后再执行：

powershell -ExecutionPolicy Bypass -File .\install.ps1

后面的安装向导基本是一致的，一路安装。

有一个小区别，在Windows系统上，配置目录在：%LOCALAPPDATA%\hermes

权限

在 WSL2 中给 Hermes Agent 开通命令执行权限，核心是修改 ~/.hermes/config.yaml，开启终端工具并调整审批策略。

一、用 gedit 打开配置文件

gedit ~/.hermes/config.yaml

二、开启命令执行（终端权限）

在 config.yaml 中添加 / 修改 tools.terminal 部分：

tools:
  terminal:
    enabled: true          # 开启终端命令执行（关键）
    require_approval: true # 每次执行前需你确认（安全默认）
    backend: local         # 本地执行（WSL2 直接用）
    timeout: 300           # 超时时间（秒）
  • enabled: true：必须设为 true，否则完全不能执行命令。
  • require_approval: true：默认安全，每次命令都会问你确认。

三、可选：关闭审批（自动执行，谨慎！）

如果你信任环境、不想每次确认，把审批模式改成 off：

approvals:
  mode: off  # manual（默认）/ smart / off
  • mode: manual：默认，每次都问。
  • mode: smart：AI 自动判断风险，低风险自动放行。
  • mode: off：所有命令自动执行（危险）。

四、可选：限制可执行路径（更安全）

限制 Hermes 只能在指定目录执行命令：

filesystem:
  enabled: true
  allowed_paths:
    - ~/workspace
    - /tmp
    - ~/projects

五、保存并生效

  1. 保存 gedit 并关闭
  2. 重启 Hermes（必须）
hermes gateway restart

busy模式

busy模式默认配置在~/.hermes/config.yaml：

display:
  busy_input_mode: "queue"

busy_input_mode共有三种模式：

  1. interrupt 打断模式
    • 正在执行任务时发指令，直接终止当前任务
    • 立刻切换执行新指令
    • 适用：改错、紧急叫停、换思路
  2. queue 排队模式
    • 新指令存入队列，不打断正在运行任务
    • 原有任务跑完，自动依次执行排队指令
    • 适用：连续下达有序任务
  3. steer 引导微调模式
    • 不终止、不排队
    • 等待本轮工具执行间隙，插入新要求修正当前流程
    • 适用：中途改细节、补条件、调整执行方向

快捷命令

/busy interrupt
/busy queue
/busy steer
/busy status 查看当前模式

DNS配置

WSL2 Hermes 飞书机器人偶发 Temporary failure in name resolution 问题，需要配置下DNS，具体配置方法及步骤参考：Linux - Ubuntu（WSL）的常用命令汇总 — 朱皮特的烂笔头

桌面版

📅 2026-06-03 更新：Hermes Desktop 桌面版正式发布，以下是基于官方文档及社区评测整理的信息。

Hermes Desktop 是 Nous Research 官方推出的桌面 GUI 应用，将原本的终端操作全面迁移到图形界面，覆盖 macOS 和 Windows 两大平台。

下载与安装

官方下载地址：https://hermes-agent.nousresearch.com/desktop（跳转到 GitHub Releases）

桌面版提供两种安装方式：

  1. 直接下载安装包：从 GitHub Releases 下载对应平台版本：
    • macOS：已签名/公证的 .dmg 安装包
    • Windows：.exe 安装程序（附带校验文件 checksum）
  2. 已有 CLI 用户升级：在终端执行 hermes desktop 命令，自动拉起桌面版安装向导

桌面版安装器首次启动时，会自动执行 install.ps1（Windows）在后台完成 Python（通过 uv）、Node.js、PortableGit 等依赖的安装。桌面版和 CLI 共享同一套安装目录和数据目录，两者可并行使用。

从下载到完成设置，整个过程不到 5 分钟。

⚠️ 注意山寨版本：官方唯一下载入口是该文档开头提供的地址，社区已有仿冒版本出现，请务必确认来源。

核心功能

功能说明
会话管理 (Session)为不同场景创建独立会话（内容创作、编程、投资等），GUI 界面管理
分支聊天 (Branch Chat)从现有会话分支出新会话，支持并发会话
浏览器预览 (Browser Preview)内置浏览器预览面板，带 Console Log，实时查看 Agent 执行结果
Artifacts 文件管理所有 Agent 创建和交互的文档集中管理，支持链接、文件、图片
消息集成 (Messaging)GUI 界面配置 Telegram、Discord、Slack、WhatsApp、Signal 等
技能管理 (Skills & Tools)可视化管理已安装技能，按需启用/禁用，节省 Token 消耗
Profile 管理创建不同人格、不同模型、不同技能集的独立 Agent
Cron 定时任务直接在桌面 App 中管理后台定时任务
TTS 语音支持 11 Labs、Edge 等 TTS 提供商
Memory Budget持久记忆预算设置
自改进技能 (Self-improving Skills)Agent 执行任务时自动创建和改进技能

模型配置

桌面版提供直观的模型配置界面，推荐使用 OpenRouter（单一 API Key 访问几乎所有模型）：

  • 主模型：可选 GPT 5.5、Claude Sonnet 4.6 等
  • 辅助模型 (Auxiliary Model)：主模型用推理型（如 Opus 4.8），图像分析用视觉型（如 Gemini 3.5 Flash）
  • 模型切换在 GUI 中操作，比 CLI 改配置简单直观

使用

常用命令如下：

# 修改配置
gedit ~/.hermes/config.yaml

# 修改环境变量配置
gedit ~/.hermes/.env

# 网关配置
hermes gateway setup

# 更新
hermes update 

# 启动网关
hermes gateway
hermes gateway start
hermes gateway restart

# 停止网关
hermes gateway stop

# 配置大模型
hermes model

# 命令行启动
hermes

基础配置命令

hermes setup # 交互式配置向导
hermes setup model # 配置模型/提供商
hermes setup terminal # 配置终端后端
hermes setup gateway # 配置消息网关
hermes setup tools # 配置工具集
hermes setup agent # 配置代理参数

hermes model # 交互式模型/提供商选择器
hermes config # 查看当前配置
hermes config edit # 用编辑器打开 config.yaml
hermes config set KEY VAL # 设置配置项
hermes config path # 打印配置文件路径
hermes config env-path # 打印 .env 文件路径
hermes config check # 检查缺失/过时的配置
hermes config migrate # 更新配置到新选项

hermes login --provider P # OAuth 登录 (nous, openai-codex, qwen-oauth 等)
hermes logout # 清除存储的认证信息

hermes doctor # 检查依赖和配置
hermes doctor --fix # 自动修复问题
hermes status # 显示组件状态
hermes status --all # 显示所有组件状态

工具集配置

hermes tools # 交互式工具启用/禁用 (curses UI)
hermes tools list # 显示所有工具及状态
hermes tools enable NAME # 启用工具集
hermes tools disable NAME # 禁用工具集

技能配置

hermes skills list # 列出已安装技能
hermes skills search QUERY # 搜索技能中心
hermes skills install ID # 安装技能
hermes skills inspect ID # 安装前预览
hermes skills config # 按平台启用/禁用技能
hermes skills check # 检查更新
hermes skills update # 更新过时技能
hermes skills uninstall N # 移除技能
hermes skills publish PATH # 发布到注册中心
hermes skills browse # 浏览所有可用技能
hermes skills tap add REPO # 添加 GitHub 仓库作为技能源

MCP 服务器配置

hermes mcp add NAME --url URL # 添加 MCP 服务器
hermes mcp add NAME --command CMD # 添加命令式 MCP 服务器
hermes mcp remove NAME # 移除 MCP 服务器
hermes mcp list # 列出配置的服务器
hermes mcp test NAME # 测试连接
hermes mcp configure NAME # 切换工具选择
hermes mcp serve # 将 Hermes 作为 MCP 服务器运行

网关/平台配置

hermes gateway setup # 配置平台
hermes gateway run # 前台启动网关
hermes gateway install # 安装为后台服务
hermes gateway start # 启动服务
hermes gateway stop # 停止服务
hermes gateway restart # 重启服务
hermes gateway status # 检查状态

会话管理

hermes sessions list # 列出最近会话
hermes sessions browse # 交互式选择器
hermes sessions export OUT # 导出为 JSONL
hermes sessions rename ID T # 重命名会话
hermes sessions delete ID # 删除会话
hermes sessions prune # 清理旧会话 (--older-than N 天)
hermes sessions stats # 会话存储统计

Cron 定时任务

hermes cron list # 列出任务 (--all 显示禁用的)
hermes cron create SCHED # 创建：'30m', 'every 2h', '0 9 * * *'
hermes cron edit ID # 编辑计划、提示、投递
hermes cron pause/resume ID # 控制任务状态
hermes cron run ID # 触发下次执行
hermes cron remove ID # 删除任务
hermes cron status # 调度器状态

Webhooks 配置

hermes webhook subscribe N # 创建路由 /webhooks/
hermes webhook list # 列出订阅
hermes webhook remove NAME # 移除订阅
hermes webhook test NAME # 发送测试 POST

Profiles 配置

hermes profile list # 列出所有配置文件
hermes profile create NAME # 创建 (--clone, --clone-all, --clone-from)
hermes profile use NAME # 设置粘性默认值
hermes profile delete NAME # 删除配置文件
hermes profile show NAME # 显示详情
hermes profile alias NAME # 管理包装脚本
hermes profile rename A B # 重命名配置文件
hermes profile export NAME # 导出为 tar.gz
hermes profile import FILE # 从归档导入

凭证池配置

hermes auth add # 交互式凭证向导
hermes auth list [PROVIDER] # 列出 pooled 凭证
hermes auth remove P INDEX # 按提供商 + 索引移除
hermes auth reset PROVIDER # 清除耗尽状态

其他命令

hermes insights [--days N] # 使用分析
hermes update # 更新到最新版本
hermes plugins list/install/remove # 插件管理
hermes honcho setup/status # Honcho 内存集成
hermes memory setup/status/off # 内存提供器配置
hermes completion bash|zsh # Shell 自动补全
hermes acp # ACP 服务器 (IDE 集成)
hermes uninstall # 卸载 Hermes

会话内斜杠命令(运行时配置)

/model [name] # 查看或更改模型
/provider # 显示提供商信息
/personality [name] # 设置个性
/reasoning [level] # 设置推理级别 (none|minimal|low|medium|high|xhigh|show|hide)
/verbose # 循环：off → new → all → verbose
/voice [on|off|tts] # 语音模式
/tools # 管理工具
/skills # 搜索/安装技能
/config # 显示配置
/yolo # 切换批准绕过
/skin [name] # 更改主题 (CLI)
/new 或 /reset # 新会话
/clear # 清屏 + 新会话
/quit 或 /exit 或 /q # 退出 CLI

配置文件位置

主配置： ~/.hermes/config.yaml
API 密钥： ~/.hermes/.env
技能目录： ~/.hermes/skills/
会话记录： ~/.hermes/sessions/
日志： ~/.hermes/logs/
OAuth 令牌： ~/.hermes/auth.json

常用提供商及环境变量

OpenRouter: OPENROUTER_API_KEY
Anthropic: ANTHROPIC_API_KEY
DeepSeek: DEEPSEEK_API_KEY
Google Gemini: GOOGLE_API_KEY 或 GEMINI_API_KEY
xAI/Grok: XAI_API_KEY
Hugging Face: HF_TOKEN
Alibaba: DASHSCOPE_API_KEY

LLM大模型

主要是修改配置文件config.yaml：

gedit ~/.hermes/config.yaml

如果要配置三方大模型，在文件末尾按照如下格式配置：

custom_providers:
- name: myllm-glm5
  base_url: https://abc.xyz.com/v1
  api_key: sk-your-key
  api_mode: chat_completions
  model: glm-5
- name: myllm-k2.5
  base_url: https://abc.xyz.com/v1
  api_key: sk-your-key
  api_mode: chat_completions
  model: kimi-k2.5

然后使用hermes model命令来选择配置的模型即可。

渠道

参考资料：

执行如下命令开启配置向导：

hermes gateway setup

群组消息策略

需要修改环境变量：

~/.hermes/.env

设置 FEISHU_REQUIRE_MENTION=true 允许被其他机器人@提及，设置为false无法响应（主人的可以）。

参考配置：

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=l53xxx3
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_ALLOW_ALL_USERS=true
FEISHU_ALLOWED_USERS=oc_xxx
FEISHU_GROUP_POLICY=open
FEISHU_REQUIRE_MENTION=true
FEISHU_ALLOW_BOTS=mentions
FEISHU_HOME_CHANNEL=oc_xxx

飞书

参考资料：

配置方式：

  • 执行命令：hermes gateway setup 后进入配置向导；
  • 在应用列表中选择：Feishu / Lark。
  • 根据提示输入App ID 回车，根据提示输入App Secret（注意：这里默认不会显示你输入的文本内容，直接复制粘贴过来回车即可）。
  • 绑定hermes pairing approve feishu RUEMXXX

飞书群组消息策略

权限开通：获取群组中其他机器人和用户@当前机器人的消息 im:message.group_at_msg.include_bot:readonly 如果机器人之前已经在群里面，需要踢出重新拉进群。

飞书 Markdown 渲染修复

问题现象：Hermes 发到飞书的 Markdown 消息（尤其含管道表格时），显示为源码而非渲染结果。

根因：hermes-agent/gateway/platforms/feishu.py 的 _build_outbound_payload() 方法有一个过时的降级逻辑：

  • 检测到管道表格 → 强制回退为 text 纯文本类型（旧版飞书 Post 格式不支持表格）
  • 无 Markdown 标记 → 也走 text 纯文本

导致 Markdown 源码直接暴露给用户。

修复：将 _build_outbound_payload() 精简为一行——所有消息统一走 Post 格式。

改前（四种返回路径，大部分走 text）：

def _build_outbound_payload(self, content: str) -> tuple[str, str]:
    # Feishu post-type 'md' elements do not render markdown tables; sending
    # table content as post causes the message to appear blank on the client.
    # Force plain text for anything that looks like a markdown table.
    if _MARKDOWN_TABLE_RE.search(content):
        text_payload = {"text": content}
        return "text", json.dumps(text_payload, ensure_ascii=False)
    if _MARKDOWN_HINT_RE.search(content):
        return "post", _build_markdown_post_payload(content)
    text_payload = {"text": content}
    return "text", json.dumps(text_payload, ensure_ascii=False)

改后（单一返回路径，统一走 post）：

def _build_outbound_payload(self, content: str) -> tuple[str, str]:
    # Always use post format with 'md' elements so Feishu renders
    # markdown—tables, bold, code fences, etc. If the post payload
    # is rejected (e.g. exotic table syntax), the caller's
    # send_message loop falls back to plain text automatically.
    return "post", _build_markdown_post_payload(content)

为什么直接改代码就够了？不需要担心表格渲染失败？

因为 send_message() 方法（同文件 line ~1795）已经有一个完善的兜底机制：

except Exception as exc:
    if msg_type != "post" or not _POST_CONTENT_INVALID_RE.search(str(exc)):
        raise
    logger.warning("[Feishu] Invalid post payload rejected by API; falling back to plain text")
    response = await self._feishu_send_with_retry(
        chat_id=chat_id, msg_type="text", ...
    )

如果 Feishu API 确实拒绝了某个 post 格式的内容（例如表格格式太复杂），_POST_CONTENT_INVALID_RE 会检测到 "content format of the post type is incorrect" 错误，自动降级为 text 重发，不会出现空白消息。也就是说——先试 post，不行再退 text。

Issue：#38755

生效方式：改完代码后重启网关：

hermes gateway restart

更新

hermes update

速度较慢的话可以设置下国内镜像。

1、配置 pip 全局镜像（永久）：

在 WSL 终端执行：

mkdir -p ~/.pip
gedit ~/.pip/pip.conf

粘贴下面内容：

[global]
index-url = https://mirrors.aliyun.com/pypi/simple/
timeout = 120
trusted-host = mirrors.aliyun.com

2、配置 uv 全局镜像（永久）：

mkdir -p ~/.config/uv
gedit ~/.config/uv/uv.toml

粘贴下面内容：

index-url = "https://mirrors.aliyun.com/pypi/simple/"
native-tls = true
http-timeout = 120

3、或者：

echo 'export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/' >> ~/.bashrc
source ~/.bashrc

切换回 Windows 终端（CMD/PowerShell），关闭 WSL：

wsl --shutdown

然后重启 WSL，在 WSL 中执行 pip config list，如果看到：

global.index-url='https://mirrors.aliyun.com/pypi/simple/'

说明 pip 已永久配置成功。

备份迁移

完成 Hermes 的配置、技能（Skills）、会话（Sessions）、记忆（Memory）等数据迁移。

# 源环境备份
hermes backup -o backup.zip

# 将 backup.zip 拷贝到目标环境后恢复
hermes import --force backup.zip

参考

文档信息

相关文章

whichllm：一句话找出最适合你硬件的本地大模型 superpowers-zh：AI 编程超能力中文增强版 —— 让 18 款 AI 编程工具真正会干活 Models.dev：AI 模型数据库的开源方案 — 统一查询所有模型的规格与定价 MicroSandbox — 为 AI Agent 打造的微型沙箱
加载评论…