Ubuntu 22.04 零基础安装 Hermes 完整入门指南

本文面向零基础使用者，目标是让你在 Ubuntu 22.04 上，使用你自己的 Python 3.11.15 环境，把 Hermes Agent 安装、部署、配置并跑起来。

Hermes 官方仓库：

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

本文采用的模型方案不是本地模型，而是第三方 OpenAI 兼容接口：

json 复制代码

{"model":"gpt-5.4","key":"sk-xxx","url":"https://xcode.best/v1/chat/completions"}

注意一件非常重要的事：

你提供的是"完整聊天接口地址" https://xcode.best/v1/chat/completions
Hermes 配置时需要填写的是"API 基础地址（base URL）"
所以你真正要填入 Hermes 的地址应当是：https://xcode.best/v1

也就是说：

模型名：gpt-5.4
API Key：sk-xxx
Base URL：https://xcode.best/v1

1. 这份文档适合谁

如果你符合下面这些情况，就可以直接照着本教程做：

你的系统是 Ubuntu 22.04
你已经有本机 Python 环境，版本是 Python 3.11.15
你不打算跑本地大模型
你希望 Hermes 通过第三方 OpenAI 兼容 API 工作
你希望文档足够细，最好一步一步照做就能完成

2. Hermes 是什么

Hermes Agent 是一个命令行里的 AI Agent。安装后你可以：

直接在终端里和它对话
让它读写文件、执行命令、调用工具
保存会话
配置不同模型或不同供应商
后续接入 Telegram、Discord、Slack、WhatsApp 等平台

如果你现在只是想先在 Ubuntu 服务器上把它跑起来，那么最核心的使用方式就是：

bash 复制代码

hermes

进入交互界面后直接聊天。

3. 本教程采用哪种安装方式

Hermes 官方有两种主流安装方式：

方式 A：官方一键安装

优点：

最省事
自动处理很多依赖
新手最容易成功

缺点：

官方安装器会自己处理 Python 和其他依赖
不够适合"我明确想使用本地现有 Python 3.11.15"的场景

方式 B：手动安装

优点：

可控性高
更适合你现在这个需求
可以明确绑定到你现有的 Python 3.11.15

缺点：

步骤比一键安装多

本教程主线使用 方式 B：手动安装。

文末我也会给你附上 方式 A：官方一键安装 的简化版说明，方便你以后切换。

4. 安装前，你最终会得到什么

完成后，系统大致会是这样：

Hermes 源码目录：~/apps/hermes-agent
Hermes 虚拟环境：~/apps/hermes-agent/venv
Hermes 全局命令：~/.local/bin/hermes
Hermes 配置目录：~/.hermes
Hermes 主配置文件：~/.hermes/config.yaml

你以后最常用的几个命令会是：

bash 复制代码

hermes
hermes model
hermes status
hermes doctor
hermes chat -q "你好"

5. 第 0 步：以普通用户登录 Ubuntu

建议不要用 root 直接安装和日常使用，最好使用普通用户，例如：

bash 复制代码

ssh your_user@your_server_ip

后面的命令默认都在普通用户下执行。

如果某一步需要管理员权限，我会明确写 sudo。

6. 第 1 步：先更新系统软件包索引

先执行：

bash 复制代码

sudo apt update

作用：

刷新 Ubuntu 软件源索引
避免后续安装依赖时报"找不到包"或版本过旧

如果你很久没有更新过系统，也可以执行：

bash 复制代码

sudo apt upgrade -y

但如果这是生产服务器，你担心升级影响现有业务，可以只执行 sudo apt update。

7. 第 2 步：安装基础工具

先安装后面要用到的基础命令：

bash 复制代码

sudo apt install -y git curl build-essential

这三个工具的作用：

git：下载 Hermes 源码
curl：下载安装脚本或 uv
build-essential：某些 Python 依赖可能需要编译环境

安装完成后，分别检查：

bash 复制代码

git --version
curl --version

如果命令能输出版本号，说明安装成功。

8. 第 3 步：确认 Python 3.11.15 可用

你已经说明本地 Python 环境是 Python 3.11.15，但正式安装前还是要确认系统里能调用到它。

执行：

bash 复制代码

python3.11 --version

你应该看到类似输出：

bash 复制代码

Python 3.11.15

再执行：

bash 复制代码

which python3.11

你应该看到一个路径，例如：

bash 复制代码

/usr/bin/python3.11

如果这一步没有输出路径，或者提示命令不存在，那么说明当前系统虽然"有 Python"，但终端并不能直接调用 python3.11，这种情况下先不要继续下面的步骤。

9. 第 4 步：安装 uv

Hermes 官方手动安装流程里使用 uv 来创建虚拟环境和安装依赖。我们也沿用官方方式，这样兼容性更好。

执行：

bash 复制代码

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

安装完成后，重新加载 shell：

bash 复制代码

source ~/.bashrc

然后检查：

bash 复制代码

uv --version

如果能显示版本号，说明 uv 已经可用。

10. 第 5 步：创建安装目录

为了让目录结构清晰，建议新建一个应用目录：

bash 复制代码

mkdir -p ~/apps
cd ~/apps

这个目录以后可以专门放你安装的各种服务或工具源码。

11. 第 6 步：下载 Hermes 源码

执行：

bash 复制代码

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

下载完成后进入目录：

bash 复制代码

cd ~/apps/hermes-agent

为什么一定要带 --recurse-submodules：

Hermes 仓库里包含子模块
如果不带这个参数，后面可能出现功能不完整或依赖缺失

如果你已经克隆过仓库，但忘了加这个参数，那么在项目目录执行：

bash 复制代码

git submodule update --init --recursive

12. 第 7 步：使用本机 Python 3.11.15 创建虚拟环境

这一步是本教程的关键。

因为你明确要用本地现有 Python 3.11.15，所以不要直接让 Hermes 自动选解释器，而是明确指定。

先看一下 Python 路径：

bash 复制代码

which python3.11

假设输出为：

bash 复制代码

/usr/bin/python3.11

那么执行：

bash 复制代码

uv venv venv --python /usr/bin/python3.11

如果你机器上输出的路径不是 /usr/bin/python3.11，就把上面命令里的路径换成你机器实际输出的那个路径。

然后激活虚拟环境：

bash 复制代码

source venv/bin/activate

激活成功后，终端前面通常会出现 (venv)。

再检查当前 Python：

bash 复制代码

python --version

如果显示：

bash 复制代码

Python 3.11.15

就说明 Hermes 后续安装会基于你的本地 Python 3.11.15 环境。

13. 第 8 步：安装 Hermes Python 依赖

在 ~/apps/hermes-agent 目录下执行：

bash 复制代码

export VIRTUAL_ENV="$(pwd)/venv"
uv pip install -e ".[all]"

解释一下这两个命令的作用：

export VIRTUAL_ENV="$(pwd)/venv"：告诉 uv 把包装到当前项目的虚拟环境里
uv pip install -e ".[all]"：以开发模式安装 Hermes，并安装官方定义的全部常用扩展

为什么这里建议装 .[all]：

对新手更省心
后续很多功能不用再反复补装
更接近官方完整能力

如果你只想要非常精简的 CLI 基础版，也可以改成：

bash 复制代码

uv pip install -e "."

但对于零基础用户，我更建议直接按本教程装 .[all]。

14. 第 9 步：可选安装附加模块

官方文档里还有一个可选模块：

bash 复制代码

uv pip install -e "./tinker-atropos"

这个模块主要用于更高级的训练/研究相关能力。

如果你当前只是想：

在终端里使用 Hermes
接第三方 API
做常规聊天和工具调用

那么这一项可以先跳过。

建议初学者现在先不装，等你确认 Hermes 正常工作后，如果确实需要相关功能，再补装。

15. 第 10 步：是否需要安装 Node.js 依赖

官方文档说明：

npm install 主要用于浏览器自动化和 WhatsApp bridge
如果你当前只想在终端里用 Hermes，对接第三方 API 聊天
那么这一步不是必须的

也就是说，你现在可以先跳过。

如果你后续要启用浏览器自动化或 WhatsApp，再回到 Hermes 项目目录执行：

bash 复制代码

npm install

如果系统里没有 npm，以后再按需安装：

bash 复制代码

sudo apt install -y nodejs npm

16. 第 11 步：创建 Hermes 配置目录

现在开始准备 Hermes 的配置文件目录。

在 ~/apps/hermes-agent 目录中执行：

bash 复制代码

mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env

这三个命令分别做了什么：

第 1 行：创建 Hermes 运行所需目录
第 2 行：把官方示例配置文件复制到用户配置目录
第 3 行：创建 .env 文件

注意：

现在的 Hermes 中，模型、接口地址、provider 等核心模型配置应当写入 ~/.hermes/config.yaml
不要把 OPENAI_BASE_URL、LLM_MODEL 这种旧变量写进 .env
官方文档已经明确说明：这些旧环境变量不再作为 Hermes 的模型配置来源

.env 现在更适合放其他附加服务的 key，比如网页抓取或图像服务的 key。

17. 第 12 步：把 hermes 命令加入全局 PATH

如果你希望以后不必每次都进入 venv/bin 目录再执行命令，就把 hermes 做成全局命令。

执行：

bash 复制代码

mkdir -p ~/.local/bin
ln -sf "$HOME/apps/hermes-agent/venv/bin/hermes" ~/.local/bin/hermes

然后把 ~/.local/bin 加到 PATH：

bash 复制代码

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

检查是否成功：

bash 复制代码

which hermes

如果输出类似：

bash 复制代码

/home/你的用户名/.local/bin/hermes

说明全局命令已经配置成功。

18. 第 13 步：配置你的第三方 API

这一部分最重要。

你给出的原始参数是：

json 复制代码

{"model":"gpt-5.4","key":"sk-xxx","url":"https://xcode.best/v1/chat/completions"}

18.1 推荐方式：使用 `hermes model` 交互配置

先执行：

bash 复制代码

hermes model

然后按提示操作。

你要选择或填写的内容如下：

Provider 类型：选择 Custom endpoint (self-hosted / VLLM / etc.)
API base URL：填写 https://xcode.best/v1
API key：填写 sk-xxx
Model name：填写 gpt-5.4

请特别注意第 2 项：

正确：https://xcode.best/v1
错误：https://xcode.best/v1/chat/completions

原因是 Hermes 要求填写"基础地址"，不是完整聊天接口路径。

18.2 为什么推荐 `hermes model`

因为它会：

帮你按 Hermes 当前版本需要的格式写入配置
避免你手动改 YAML 时缩进写错
保存为持久配置，后续重启仍然有效

19. 第 14 步：手动检查 `config.yaml` 是否正确

执行：

bash 复制代码

nano ~/.hermes/config.yaml

你重点检查 model 相关配置。

对于你的场景，核心内容应该类似下面这样：

yaml 复制代码

model:
  default: gpt-5.4
  provider: custom
  base_url: https://xcode.best/v1
  api_key: sk-xxx

说明：

default：模型名
provider：这里是 custom
base_url：一定要写基础地址 https://xcode.best/v1
api_key：你的第三方接口 key

如果这个文件里还有其他配置项，不要随便删掉。

你只需要确保 model: 这部分是正确的。

保存退出 nano 的方法：

按 Ctrl + O 保存
回车确认
按 Ctrl + X 退出

20. 第 15 步：首次自检

配置完成后，执行下面几条命令检查安装是否成功：

bash 复制代码

hermes version
hermes doctor
hermes status

你可以这样理解：

hermes version：检查命令是否存在
hermes doctor：检查依赖、配置和常见问题
hermes status：查看当前 Hermes 的状态

如果这三条都没有明显报错，基本就说明安装已经完成。

再执行一个最简单的单次测试：

bash 复制代码

hermes chat -q "你好，请简单介绍一下你自己。"

如果能正常返回内容，就说明：

Hermes 已经成功启动
你的第三方 API 可以正常访问
模型 gpt-5.4 已经被 Hermes 正确调用

21. 第 16 步：正式开始使用 Hermes

21.1 进入交互模式

执行：

bash 复制代码

hermes

进入后你就可以直接输入中文提问，例如：

text 复制代码

请帮我查看当前目录下有哪些文件

或者：

text 复制代码

帮我解释一下这个 Python 项目怎么启动

21.2 单次问答模式

如果你不想进入交互界面，只想让它回答一句话，可以这样：

bash 复制代码

hermes chat -q "现在这台机器的磁盘空间使用情况如何？"

这种模式适合：

快速测试
脚本里调用
临时执行一个任务

21.3 指定本次对话的模型

如果以后你切换了默认模型，也可以在单次运行时临时指定：

bash 复制代码

hermes chat -m "gpt-5.4" -q "请用 3 句话介绍 Ubuntu 22.04。"

22. 常用命令总表

下面这些命令，是你以后最常用的一批。

22.1 基础命令

bash 复制代码

hermes
hermes chat -q "你好"
hermes model
hermes setup
hermes tools
hermes status
hermes doctor
hermes version

含义：

hermes：进入交互界面
hermes chat -q "..."：执行一次性问答
hermes model：重新配置模型、provider、API key、base URL
hermes setup：运行完整设置向导
hermes tools：查看和管理可用工具
hermes status：查看当前状态
hermes doctor：诊断问题
hermes version：查看版本

22.2 配置相关

bash 复制代码

hermes config path
hermes config env-path
hermes config edit
hermes config show
hermes config check
hermes config migrate

含义：

hermes config path：显示 config.yaml 路径
hermes config env-path：显示 .env 路径
hermes config edit：直接编辑配置文件
hermes config show：显示当前配置
hermes config check：检查配置问题
hermes config migrate：迁移配置格式

22.3 会话相关

bash 复制代码

hermes --continue
hermes --resume <session_id>
hermes sessions

含义：

hermes --continue：继续最近一次会话
hermes --resume <session_id>：恢复指定会话
hermes sessions：查看和管理历史会话

22.4 更新和卸载

bash 复制代码

hermes update
hermes uninstall

含义：

hermes update：更新 Hermes
hermes uninstall：卸载 Hermes

23. 交互界面里最常用的斜杠命令

当你已经进入 hermes 交互界面后，可以输入下面这些命令。

23.1 基础控制

text 复制代码

/help
/quit
/clear
/new
/reset

含义：

/help：显示帮助
/quit：退出
/clear：清屏并重置对话
/new：开始新会话
/reset：只重置当前对话

23.2 工具与配置

text 复制代码

/tools
/toolsets
/model
/provider
/config

含义：

/tools：查看可用工具
/toolsets：查看工具集
/model：查看或切换当前模型
/provider：查看 provider 状态
/config：查看当前配置

23.3 会话管理

text 复制代码

/history
/retry
/undo
/save
/compress
/usage

含义：

/history：查看历史
/retry：重试上一轮
/undo：撤销上一轮
/save：保存会话
/compress：压缩上下文
/usage：查看 token 使用情况

24. 适合你的最小可用配置

如果你只是想稳定地把 Hermes 跑起来，并使用第三方 API，那么你的最小可用思路其实很简单：

必须有的东西

git
curl
Python 3.11.15
uv
Hermes 源码
~/.hermes/config.yaml
你的第三方 API 参数

目前可以先不折腾的东西

本地模型
GPU
npm install
WhatsApp bridge
Telegram/Discord 网关
高级 memory / training 组件

也就是说，你完全可以先把最核心的 CLI 版本跑起来，用顺手之后再继续扩展。

25. 部署建议：Ubuntu 服务器上该怎么用

如果你是在一台云服务器上部署 Hermes，我建议这样理解"部署"：

场景 1：只在 SSH 终端里使用

这是最简单、最推荐的方式。

你只需要：

bash 复制代码

ssh user@server
hermes

适合：

个人使用
开发测试
先验证 Hermes 是否能稳定跑起来

场景 2：以后要接消息平台

如果以后你要把 Hermes 挂到 Telegram、Discord、Slack、WhatsApp 等平台上，再考虑：

bash 复制代码

hermes gateway setup
hermes gateway install
hermes gateway start
hermes gateway status

这里的 hermes gateway install 在 Linux 上会把网关安装成用户级服务，适合长期运行。

但如果你当前只是使用第三方 API 在终端里聊天，这部分先不用做。

26. 常见问题排查

26.1 `hermes: command not found`

先执行：

bash 复制代码

source ~/.bashrc
which hermes

如果还是不行，检查软链接是否存在：

bash 复制代码

ls -l ~/.local/bin/hermes

确认它是否指向：

bash 复制代码

$HOME/apps/hermes-agent/venv/bin/hermes

26.2 API 明明填了，却连接不上

先检查你有没有把地址填错。

很多人会误填成：

text 复制代码

https://xcode.best/v1/chat/completions

但 Hermes 需要的是：

text 复制代码

https://xcode.best/v1

26.3 配了 `.env` 但没生效

这是因为新版 Hermes 已经把模型相关配置收敛到 config.yaml 里了。

所以：

不要把 OPENAI_BASE_URL
不要把 LLM_MODEL

这些旧变量当作当前 Hermes 的主要模型配置方式。

你应该：

用 hermes model 配
或者直接改 ~/.hermes/config.yaml

26.4 `hermes doctor` 报配置问题

执行：

bash 复制代码

hermes config check
hermes config migrate

然后重新运行：

bash 复制代码

hermes doctor

26.5 工具调用效果不稳定，但聊天能正常返回

这通常说明：

你的第三方接口虽然兼容 OpenAI Chat Completions
但它对 tool calling 的兼容并不完整

这种情况不是 Hermes 本体一定有问题，而是上游接口兼容度不够。

你可以先验证：

纯聊天是否正常
简单工具任务是否正常
复杂代理任务是否出现异常

如果简单聊天正常、复杂工具调用异常，优先怀疑上游 API 兼容性。

26.6 `python3.11` 有，但建虚拟环境失败

先检查：

bash 复制代码

python3.11 -m venv --help

如果这里就报错，说明你的 Python 可能没有可用的 venv 模块。

这时你需要先修复本机 Python 3.11.15 环境，再继续安装 Hermes。

27. 推荐你第一次实际测试时这样做

完成安装后，不要一上来就让 Hermes 做很复杂的事情。

建议按这个顺序测试：

第一步：测试命令是否存在

bash 复制代码

hermes version

第二步：测试配置是否通过

bash 复制代码

hermes doctor
hermes status

第三步：测试单次问答

bash 复制代码

hermes chat -q "请用一句话说明你是否已成功连接模型。"

第四步：进入交互界面

bash 复制代码

hermes

然后输入：

text 复制代码

/help

再输入：

text 复制代码

请介绍一下你有哪些能力

这样最容易判断问题到底出在：

安装
配置
API 连通性
还是交互使用方式

28. 官方一键安装方式（补充）

如果你后面不再坚持"必须使用现有 Python 3.11.15"，那么可以使用官方一键安装。

28.1 一键安装命令

bash 复制代码

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

28.2 它会做什么

官方文档说明，这个安装器会自动处理：

依赖安装
Python 3.11
Node.js
ripgrep
ffmpeg
仓库克隆
虚拟环境
全局 hermes 命令
初始 LLM provider 配置

28.3 什么时候更适合用一键安装

你不关心它使用哪一个 Python
你想最快装好
你是第一次接触 Hermes

28.4 什么时候不建议用一键安装

你明确要求绑定你已有的 Python 3.11.15
你希望自己完全掌控虚拟环境位置和安装方式

29. 最后给你一份最简安装清单

如果你已经看懂全文，后面想快速复装，可以只看这一段。

bash 复制代码

sudo apt update
sudo apt install -y git curl build-essential
python3.11 --version
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
mkdir -p ~/apps
cd ~/apps
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd ~/apps/hermes-agent
uv venv venv --python "$(which python3.11)"
source venv/bin/activate
export VIRTUAL_ENV="$(pwd)/venv"
uv pip install -e ".[all]"
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env
mkdir -p ~/.local/bin
ln -sf "$HOME/apps/hermes-agent/venv/bin/hermes" ~/.local/bin/hermes
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
hermes model
hermes doctor
hermes status
hermes

当 hermes model 打开后，请填写：

Provider：Custom endpoint (self-hosted / VLLM / etc.)
Base URL：https://xcode.best/v1
API Key：sk-xxx
Model：gpt-5.4

30. 本教程里最重要的 5 个结论

你这个场景最适合走"手动安装"，因为你指定了本机 Python 3.11.15
Hermes 对接第三方接口时，要填的是 base_url，不是完整 /chat/completions 地址
你的正确配置是：
- provider=custom
- base_url=https://xcode.best/v1
- api_key=sk-xxx
- model=gpt-5.4
新版 Hermes 里，模型相关配置以 ~/.hermes/config.yaml 为准，不要再依赖旧的 .env 模型变量
安装完成后先跑 hermes doctor 和 hermes chat -q "你好"，不要上来就做复杂任务

如果你愿意，我下一步可以继续帮你补一份：

Ubuntu 22.04 实际可直接复制执行的一键部署脚本

或者帮你继续生成：

针对你的第三方 API 的完整 config.yaml 样板文件

Ubuntu 22.04 零基础安装 Hermes 完整入门指南

1. 这份文档适合谁

2. Hermes 是什么

3. 本教程采用哪种安装方式

方式 A：官方一键安装

方式 B：手动安装

4. 安装前，你最终会得到什么

5. 第 0 步：以普通用户登录 Ubuntu

6. 第 1 步：先更新系统软件包索引

7. 第 2 步：安装基础工具

8. 第 3 步：确认 Python 3.11.15 可用

9. 第 4 步：安装 uv

10. 第 5 步：创建安装目录

11. 第 6 步：下载 Hermes 源码

12. 第 7 步：使用本机 Python 3.11.15 创建虚拟环境

13. 第 8 步：安装 Hermes Python 依赖

14. 第 9 步：可选安装附加模块

15. 第 10 步：是否需要安装 Node.js 依赖

16. 第 11 步：创建 Hermes 配置目录

17. 第 12 步：把 hermes 命令加入全局 PATH

18. 第 13 步：配置你的第三方 API

18.1 推荐方式：使用 hermes model 交互配置

18.2 为什么推荐 hermes model

19. 第 14 步：手动检查 config.yaml 是否正确

20. 第 15 步：首次自检

21. 第 16 步：正式开始使用 Hermes

21.1 进入交互模式

21.2 单次问答模式

21.3 指定本次对话的模型

22. 常用命令总表

22.1 基础命令

22.2 配置相关

22.3 会话相关

22.4 更新和卸载

23. 交互界面里最常用的斜杠命令

23.1 基础控制

23.2 工具与配置

23.3 会话管理

24. 适合你的最小可用配置

必须有的东西

目前可以先不折腾的东西

25. 部署建议：Ubuntu 服务器上该怎么用

场景 1：只在 SSH 终端里使用

场景 2：以后要接消息平台

26. 常见问题排查

26.1 hermes: command not found

26.2 API 明明填了，却连接不上

26.3 配了 .env 但没生效

26.4 hermes doctor 报配置问题

26.5 工具调用效果不稳定，但聊天能正常返回

26.6 python3.11 有，但建虚拟环境失败

27. 推荐你第一次实际测试时这样做

第一步：测试命令是否存在

第二步：测试配置是否通过

第三步：测试单次问答

第四步：进入交互界面

28. 官方一键安装方式（补充）

28.1 一键安装命令

28.2 它会做什么

28.3 什么时候更适合用一键安装

28.4 什么时候不建议用一键安装

29. 最后给你一份最简安装清单

30. 本教程里最重要的 5 个结论

18.1 推荐方式：使用 `hermes model` 交互配置

18.2 为什么推荐 `hermes model`

19. 第 14 步：手动检查 `config.yaml` 是否正确

26.1 `hermes: command not found`

26.3 配了 `.env` 但没生效

26.4 `hermes doctor` 报配置问题

26.6 `python3.11` 有，但建虚拟环境失败