Hermes Agent零基础部署保姆级教程

先说个结论：2026年的AI Agent赛道，已经卷到让人目不暇接了。OpenClaw（龙虾）靠着多Agent协同打出了名声，但另一股新势力正在悄然崛起——Hermes Agent（爱马仕）。它的核心理念很有意思：「the agent that grows with you」——一个会跟你一起成长的Agent。

前言

和OpenClaw最大的区别在于：Hermes不是那种“用完就清零”的工具。它是一个会从每次交互中不断学习、沉淀技能、记住你偏好的成长型搭档。用久了，它会越来越懂你，越来越顺手。

本文会完整记录一次真实的部署过程，从环境准备到一键安装，从模型配置到网关部署，再到常见问题排查，一步步走下来，帮你少踩坑。

一、Hermes Agent 是什么？（30秒速览）

二、环境准备

2.1 系统要求

Hermes Agent 原生支持 Linux、macOS 和 WSL2，但注意，它不支持原生 Windows。Windows 用户必须先安装 WSL2，然后在里面运行。

推荐配置方面，2核CPU、4GB内存起步，8GB以上会更从容。磁盘需要10GB以上可用空间。网络方面，只要能访问GitHub就行，国内用户建议提前配置镜像。

2.2 前置依赖

这点值得表扬：几乎不需要手动装任何东西。安装脚本会把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

2.3 网络加速（国内用户必看）

如果部署在国内服务器，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 清除配置。

三、一键安装

3.1 执行安装脚本

打开终端，执行下面这行命令：

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

脚本会自动完成：系统架构检测（x86_64 / arm64），安装uv、Python 3.11、Node.js v22，克隆Hermes Agent仓库，创建虚拟环境并安装依赖，最后注册 hermes 全局命令。整个过程大概3到10分钟，具体取决于网络速度。

3.2 重新加载 Shell 配置

安装完成后，必须重新加载shell配置才能使用 hermes 命令。bash用户执行 source ~/.bashrc，zsh用户（macOS默认）执行 source ~/.zshrc。

3.3 验证安装

运行 hermes --version，如果输出了版本号，就说明安装成功了。

四、模型配置

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

4.1 交互式配置（推荐）

直接运行 hermes setup，会启动一个交互式向导，引导你完成模型提供商选择、API Key输入和基本偏好设置。或者，也可以直接用 hermes model 命令来配置。

4.2 支持的模型提供商

4.3 手动配置示例

如果想手动编辑配置文件，运行 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

4.4 辅助模型配置（进阶）

Hermes有一个辅助模型模块，专门处理图像分析、网页提取、Skill匹配等“侧任务”。它会自动分配给轻量模型以节省成本。配置文件示例：

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

默认会自动检测并优先使用 Gemini Flash，基本不用手动配置。

五、开始使用

5.1 CLI 模式（命令行交互）

直接输入 hermes，就能进入全交互式终端界面，开始和Agent对话。支持所有内置工具，包括文件操作、终端命令、网页搜索等。

几个常用的斜杠命令：

5.2 消息网关模式（手机/多平台）

如果你希望通过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 迁移

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

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

# 或手动触发迁移
hermes claw migrate

迁移内容包括：SOUL.md（人格设定）、MEMORY.md / USER.md（记忆文件）、已有技能、API Key配置、消息平台配置。

八、常见问题排查

❌ 问题1：hermes: command not found

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

解决： 执行 source ~/.bashrc 或 source ~/.zshrc。如果还不行，手动添加PATH：export PATH="$HOME/.hermes/bin:$PATH"。

❌ 问题2：安装脚本下载超时 / 连接失败

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

解决： 配置Git镜像（参考2.3节），或者手动克隆后安装：git clone https://github.com/NousResearch/hermes-agent.git 然后 cd hermes-agent && bash scripts/install.sh。

❌ 问题3：Python 版本冲突

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

解决： Hermes使用 uv 管理独立的Python环境，通常不会冲突。如果仍有问题，检查uv是否正常：uv --version，手动安装uv：curl -LsSf https://astral.sh/uv/install.sh | sh，然后重新运行安装脚本。

❌ 问题4：模型调用失败 / API Key 无效

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

解决： 检查当前模型配置：hermes config，重新配置模型：hermes model，或者检查 ~/.hermes/.env 文件中的Key是否正确。

❌ 问题5：Docker 后端启动失败

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

解决： 检查Docker状态：docker version。未安装的话，Ubuntu上安装：sudo apt install docker.io && sudo systemctl start docker && sudo usermod -aG docker $USER。macOS用户安装Docker Desktop。或者切换回本地后端：hermes config set terminal.backend local。

❌ 问题6：网关启动后 Telegram Bot 无响应

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

解决： 检查网关日志：cat ~/.hermes/logs/gateway.log，重新配置网关：hermes gateway setup，并在Telegram中找 @BotFather 验证Token是否有效。

❌ 问题7：内存占用过高

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

解决： 查看会话列表：hermes sessions list，清理旧会话：hermes sessions clean --before 2026-04-01。检查记忆使用量，系统提示中会显示百分比。

❌ 问题8：hermes update 更新失败

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

解决： 先暂存本地修改，再更新：cd ~/.hermes && git stash && hermes update && git stash pop。

九、进阶配置建议

9.1 终端后端选择

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

切换到Docker后端（推荐生产环境）：hermes config set terminal.backend docker。

9.2 记忆系统调优

# ~/.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会自动合并和精简条目。

9.3 定时任务

Hermes内置cron调度器，支持自然语言设置定时任务。在对话中直接说“每天早上9点给我发一份天气报告”或“每周五下午5点生成本周工作总结”即可。

十、总结

整个部署流程总结下来就是三步：

# 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确实值得花时间认真部署和打磨。