从零部署Hermes Agent的保姆级安装教程

目录

• 前言
• 一、Hermes Agent 是什么？（30 秒速览）
• 二、环境准备
• 2.1 系统要求
• 2.2 前置依赖
• 2.3 网络加速（国内用户必看）
• 三、一键安装
• 3.1 执行安装脚本
• 3.2 重新加载 Shell 配置
• 3.3 验证安装
• 四、模型配置
• 4.1 交互式配置（推荐）
• 4.2 支持的模型提供商
• 4.3 手动配置示例
• 4.4 辅助模型配置（进阶）
• 五、开始使用
• 5.1 CLI 模式（命令行交互）
• 5.2 消息网关模式（手机/多平台）
• 六、目录结构说明
• 七、从 OpenClaw 迁移
• 八、常见问题排查
• ❌ 问题 1：hermes: command not found
• ❌ 问题 2：安装脚本下载超时 / 连接失败
• ❌ 问题 3：Python 版本冲突
• ❌ 问题 4：模型调用失败 / API Key 无效
• ❌ 问题 5：Docker 后端启动失败
• ❌ 问题 6：网关启动后 Telegram Bot 无响应
• ❌ 问题 7：内存占用过高
• ❌ 问题 8：hermes update更新失败
• 九、进阶配置建议
• 9.1 终端后端选择
• 9.2 记忆系统调优
• 9.3 定时任务
• 十、总结

Hermes Agent —— Nous Research 出品的开源 AI Agent 框架，主打"越用越聪明"。本文手把手带你从安装到配置到排坑，全流程实操记录。

2026 年 AI Agent 赛道卷出了天际。OpenClaw（龙虾）凭借多 Agent 协同火爆出圈后，另一款产品悄然崛起——Hermes Agent（爱马仕），口号是 ** "the agent that grows with you" **，主打单一 Agent 的深度自我进化。

和 OpenClaw 最大的不同在于：Hermes 不是"用完归零"的工具，而是一个会从每次交互中学习、沉淀技能、记住你偏好的成长型搭档。用得越久，它越懂你。

本文将从环境准备 → 一键安装 → 模型配置 → 网关部署 → 常见问题排查，完整记录一次真实的部署过程，帮你少走弯路。

| 项目 | 说明 |

|——|——|

| 开发团队 | Nous Research |

| 开源协议 | MIT（完全免费） |

| 核心卖点 | 闭环学习系统 + 四层记忆架构 + 40+ 内置工具 |

| 支持平台 | Linux、macOS、WSL2、Android（Termux） |

| 消息平台 | Telegram、Discord、Slack、WhatsApp、飞书 |

| 支持模型 | Claude、OpenRouter、DeepSeek、Qwen、Ollama 本地模型等 |

官方资源：

• 官网：hermes-agent.nousresearch.com
• 文档：hermes-agent.nousresearch.com/docs
• GitHub：https://github.com/NousResearch/hermes-agent
• Discord 社区：官网底部 Join Discord 入口

Hermes Agent 支持 Linux、macOS、WSL2，不支持原生 Windows。

Windows 用户必须先安装 WSL2（Windows Subsystem for Linux），然后在 WSL2 内运行。

推荐配置：

• CPU：2 核以上
• 内存：4GB 以上（推荐 8GB+）
• 磁盘：10GB+ 可用空间
• 网络：能访问 GitHub（或配置镜像）

好消息是——几乎不需要手动装任何东西。安装脚本会自动处理：

• Python 3.11
• Node.js v22
• uv（Python 包管理器）
• ripgrep
• ffmpeg
• 虚拟环境

你唯一需要确保的是系统里有 git：

# 检查 git 是否已安装

git --version

  


# Ubuntu/Debian

sudo apt install git

  


# macOS（通常自带，或用 Homebrew）

brew install git

如果你在国内服务器部署，GitHub 和 npm/pip 的访问速度可能很慢。建议提前配置镜像：

Git 镜像加速：

git config --global url."https://mirror.ghproxy.com/https://github.com".insteadOf "https://github.com"

pip 镜像加速：

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip config set install.trusted-host mirrors.aliyun.com

npm 镜像加速：

npm config set registry https://mirrors.cloud.tencent.com/npm/ --global

安装完成后如果不需要加速了，可以用 git config –global –unset-all url.https://mirror.ghproxy.com/https://github.com".insteadOf 清除配置。

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

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

脚本会自动完成以下操作：

1. 检测系统架构（x86_64 / arm64）
2. 安装 uv、Python 3.11、Node.js v22
3. 克隆 Hermes Agent 仓库
4. 创建 Python 虚拟环境并安装依赖
5. 注册 hermes 全局命令

整个安装过程大约需要 3-10 分钟（取决于网络速度）。

安装完成后，必须重新加载 shell 配置才能使用 hermes 命令：

# bash 用户
source ~/.bashrc
# zsh 用户（macOS 默认）
source ~/.zshrc

hermes --version

如果输出了版本号，说明安装成功！

安装好之后，下一步是配置 LLM 提供商。Hermes 支持多种模型后端：

hermes setup

这会启动一个交互式向导，引导你完成：

• 选择模型提供商
• 输入 API Key
• 基本偏好设置

或者直接用模型选择命令：

hermes model

| 提供商 | 配置方式 | 说明 |

|——–|———|——|

| Nous Portal | OAuth 登录，零配置 | 官方订阅服务，最简单 |

| Anthropic Claude | API Key 或 Claude Code 授权 | 注意：目前尚未被封禁 |

| OpenRouter | API Key | 支持 200+ 模型，灵活度高 |

| DeepSeek | API Key | 国内用户友好，性价比高 |

| 阿里云 DashScope | API Key | 支持 Qwen 系列 |

| Ollama | 本地运行 | 完全离线，隐私优先 |

| 小米 MiMo-V2 | Nous Portal 接入 | 曾限免两周 |

| 自定义端点 | OpenAI 兼容 API | vLLM、SGLang 等 |

如果你想手动编辑配置文件：

# 打开配置文件
hermes config edit

配置文件位于 ~/.hermes/config.yaml，API Key 等密钥会自动存入 ~/.hermes/.env。

使用 DeepSeek 的配置示例：

hermes config set model deepseek/deepseek-chat

hermes config set DEEPSEEK_API_KEY sk-your-key-here

使用 Ollama 本地模型的配置示例：

# 先启动 Ollama

ollama serve

  


# 配置 Hermes 使用本地模型

hermes config set model ollama/llama3

Hermes 有一个 Auxiliary Models 模块，专门处理图像分析、网页提取、Skill 匹配等"侧任务"，自动分配给轻量模型以节省成本：

# ~/.hermes/config.yaml
auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
  delegation:
    api_key: ${DELEGATION_KEY}

默认会自动检测并优先使用 Gemini Flash，无需手动配置。

直接输入：

hermes

即可进入全交互式终端界面，开始和 Agent 对话。支持所有内置工具（文件操作、终端命令、网页搜索等）。

常用斜杠命令：

| 命令 | 功能 |

|——|——|

| /new 或 /reset | 开启新对话 |

| /model [provider:model] | 快速切换模型 |

| /skills | 浏览已安装技能 |

| /usage | 查看 Token 使用量 |

| /tools | 查看可用工具列表 |

如果你希望通过 Telegram、Discord、Slack 等平台和 Agent 交互：

# 第一步：交互式网关配置

hermes gateway setup

  


# 第二步：启动网关

hermes gateway

  


# 第三步（可选）：安装为系统服务，开机自启

hermes gateway install

按照向导提示，输入各平台的 Bot Token 即可完成接入。一套网关进程连接所有平台，会话统一管理。

了解配置目录结构，有助于后续排查问题：

~/.hermes/

├── config.yaml     # 主配置文件（模型、终端、TTS 等）

├── .env            # API Key 等密钥（不要提交到 Git！）

├── auth.json       # OAuth 凭证（Nous Portal 等）

├── SOUL.md         # Agent 人格设定（系统提示词 slot #1）

├── memories/       # 持久记忆（MEMORY.md、USER.md）

├── skills/         # Agent 自动创建的技能文件

├── cron/           # 定时任务

├── sessions/       # 网关会话记录

└── logs/           # 日志（errors.log、gateway.log）

常用管理命令：

hermes config              # 查看当前配置

hermes config edit         # 编辑配置文件

hermes config check        # 检查缺失配置

hermes config migrate      # 交互式补充缺失配置

hermes update              # 更新到最新版本

如果你之前是 OpenClaw 用户，Hermes 提供了一键迁移工具：

# 首次 setup 时会自动检测 ~/.openclaw 目录并提示迁移

hermes setup

  


# 或手动触发迁移

hermes claw migrate

迁移内容包括：

• SOUL.md（人格设定）
• MEMORY.md / USER.md（记忆文件）
• 已有技能
• API Key 配置
• 消息平台配置

原因： Shell 配置未重新加载。

解决：

source ~/.bashrc   # 或 source ~/.zshrc

  


# 如果还不行，手动添加到 PATH

export PATH="$HOME/.hermes/bin:$PATH"

原因： 国内网络无法直接访问 GitHub。

解决：

# 方案一：配置 Git 镜像（见 2.3 节）

git config --global url."https://mirror.ghproxy.com/https://github.com".insteadOf "https://github.com"

  


# 方案二：手动克隆后安装

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

cd hermes-agent

bash scripts/install.sh

原因： 系统已有 Python 版本和 Hermes 要求的 3.11 冲突。

解决： Hermes 使用 uv 管理独立的 Python 环境，通常不会冲突。如果仍有问题：

# 检查 uv 是否正常

uv --version

  


# 手动安装 uv

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

  


# 重新运行安装脚本

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

原因： API Key 配置错误或余额不足。

解决：

# 检查当前模型配置

hermes config

  


# 重新配置模型

hermes model

  


# 检查 .env 文件中的 Key 是否正确

cat ~/.hermes/.env

原因： Docker 未安装或未运行。

解决：

# 检查 Docker 状态

docker version

  


# 如果 Docker 未安装

# Ubuntu

sudo apt install docker.io

sudo systemctl start docker

sudo usermod -aG docker $USER

  


# macOS：安装 Docker Desktop

  


# 或者切换回本地后端

hermes config set terminal.backend local

原因： Bot Token 配置错误或网络问题。

解决：

# 检查网关日志

cat ~/.hermes/logs/gateway.log

  


# 重新配置网关

hermes gateway setup

  


# 确认 Bot Token 有效（在 Telegram 中找 @BotFather 验证）

原因： Hermes 会话积累过多或技能文件膨胀。

解决：

# 查看会话列表

hermes sessions list

  


# 清理旧会话

hermes sessions clean --before 2026-04-01

  


# 检查记忆使用量（系统提示中会显示百分比）

hermes config edit  # 查看 memories/ 目录

原因： Git 仓库有本地修改冲突。

解决：

cd ~/.hermes

git stash          # 暂存本地修改

hermes update      # 重新更新

git stash pop      # 恢复本地修改

Hermes 支持 6 种终端后端，根据你的使用场景选择：

| 后端 | 适用场景 | 安全性 |

|——|———|——–|

| local | 个人开发机，快速上手 | 无隔离 |

| docker | 需要沙箱隔离 | 完全隔离 |

| ssh | 远程服务器部署 | 网络隔离 |

| modal | 弹性云计算 | 云 VM 隔离 |

| daytona | 托管云开发环境 | 云容器隔离 |

| singularity | HPC 集群 | 命名空间隔离 |

# 切换到 Docker 后端（推荐生产环境使用）

hermes config set terminal.backend docker

# ~/.hermes/config.yaml

memory:

  memory_enabled: true

  user_profile_enabled: true

  memory_char_limit: 2200    # Agent 记忆上限（~800 tokens）

  user_char_limit: 1375      # 用户画像上限（~500 tokens）

当记忆使用超过 80% 时，Agent 会自动合并和精简条目。

Hermes 内置 cron 调度器，支持自然语言设置定时任务：

# 在对话中直接说

"每天早上 9 点给我发一份天气报告"

"每周五下午 5 点生成本周工作总结"

Hermes Agent 的安装过程整体非常流畅，官方的一键脚本几乎把所有脏活都干了。整个部署流程总结下来就是三步：

# 1. 安装

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

source ~/.bashrc

  


# 2. 配置模型

hermes setup

  


# 3. 开始使用

hermes

相比 OpenClaw 的"多 Agent 并行"思路，Hermes 走的是"单 Agent 深度进化"路线——它不是最早上手的那个，但可能是越用越值的那个。如果你有一些重复性、会演化的工作流，愿意让 AI 从日常使用中积累经验，Hermes Agent 值得花时间认真部署和打磨。

以上就是从零部署Hermes Agent的保姆级安装教程的详细内容，更多关于Hermes Agent安装与部署教程的资料请关注风君子博客其它相关文章！