本文面向零基础使用者，目标是让你在 Ubuntu 22.04 上，使用你自己的 Python 3.11.15 环境，把 Hermes Agent 安装、部署、配置并跑起来。
Hermes 官方仓库：
https://github.com/NousResearch/hermes-agent
本文采用的模型方案不是本地模型，而是第三方 OpenAI 兼容接口：
{“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
如果你符合下面这些情况，就可以直接照着本教程做：
- 你的系统是
Ubuntu 22.04 - 你已经有本机 Python 环境，版本是
Python 3.11.15 - 你不打算跑本地大模型
- 你希望 Hermes 通过第三方 OpenAI 兼容 API 工作
- 你希望文档足够细，最好一步一步照做就能完成
Hermes Agent 是一个命令行里的 AI Agent。安装后你可以：
- 直接在终端里和它对话
- 让它读写文件、执行命令、调用工具
- 保存会话
- 配置不同模型或不同供应商
- 后续接入 Telegram、Discord、Slack、WhatsApp 等平台
如果你现在只是想先在 Ubuntu 服务器上把它跑起来，那么最核心的使用方式就是：
hermes 进入交互界面后直接聊天。
Hermes 官方有两种主流安装方式：
方式 A：官方一键安装
优点：
- 最省事
- 自动处理很多依赖
- 新手最容易成功
缺点：
- 官方安装器会自己处理 Python 和其他依赖
- 不够适合“我明确想使用本地现有 Python 3.11.15”的场景
方式 B：手动安装
优点：
- 可控性高
- 更适合你现在这个需求
- 可以明确绑定到你现有的
Python 3.11.15
缺点：
- 步骤比一键安装多
本教程主线使用 方式 B：手动安装。
文末我也会给你附上 方式 A：官方一键安装 的简化版说明，方便你以后切换。
完成后，系统大致会是这样：
- Hermes 源码目录：
/apps/hermes-agent - Hermes 虚拟环境：
/apps/hermes-agent/venv - Hermes 全局命令：
/.local/bin/hermes - Hermes 配置目录：
/.hermes - Hermes 主配置文件：
~/.hermes/config.yaml
你以后最常用的几个命令会是：
hermes hermes model hermes status hermes doctor hermes chat -q ”你好“ 建议不要用 root 直接安装和日常使用，最好使用普通用户，例如：
ssh your_user@your_server_ip 后面的命令默认都在普通用户下执行。
如果某一步需要管理员权限，我会明确写 sudo。
先执行：
sudo apt update 作用：
- 刷新 Ubuntu 软件源索引
- 避免后续安装依赖时报“找不到包”或版本过旧
如果你很久没有更新过系统，也可以执行：
sudo apt upgrade -y 但如果这是生产服务器，你担心升级影响现有业务，可以只执行 sudo apt update。
先安装后面要用到的基础命令：
sudo apt install -y git curl build-essential 这三个工具的作用：
git：下载 Hermes 源码curl：下载安装脚本或uvbuild-essential：某些 Python 依赖可能需要编译环境
安装完成后，分别检查：
git –version curl –version 如果命令能输出版本号，说明安装成功。
你已经说明本地 Python 环境是 Python 3.11.15，但正式安装前还是要确认系统里能调用到它。
执行：
python3.11 –version 你应该看到类似输出：
Python 3.11.15 再执行：
which python3.11 你应该看到一个路径，例如：
/usr/bin/python3.11 如果这一步没有输出路径，或者提示命令不存在，那么说明当前系统虽然“有 Python”，但终端并不能直接调用 python3.11，这种情况下先不要继续下面的步骤。
Hermes 官方手动安装流程里使用 uv 来创建虚拟环境和安装依赖。我们也沿用官方方式，这样兼容性更好。
执行：
curl -LsSf https://astral.sh/uv/install.sh | sh 安装完成后，重新加载 shell：
source ~/.bashrc 然后检查：
uv –version 如果能显示版本号，说明 uv 已经可用。
为了让目录结构清晰，建议新建一个应用目录：
mkdir -p ~/apps cd ~/apps 这个目录以后可以专门放你安装的各种服务或工具源码。
执行：
git clone –recurse-submodules https://github.com/NousResearch/hermes-agent.git 下载完成后进入目录：
cd ~/apps/hermes-agent 为什么一定要带 –recurse-submodules：
- Hermes 仓库里包含子模块
- 如果不带这个参数，后面可能出现功能不完整或依赖缺失
如果你已经克隆过仓库，但忘了加这个参数，那么在项目目录执行：
git submodule update –init –recursive 这一步是本教程的关键。
因为你明确要用本地现有 Python 3.11.15，所以不要直接让 Hermes 自动选解释器，而是明确指定。
先看一下 Python 路径：
which python3.11 假设输出为：
/usr/bin/python3.11 那么执行：
uv venv venv –python /usr/bin/python3.11 如果你机器上输出的路径不是 /usr/bin/python3.11，就把上面命令里的路径换成你机器实际输出的那个路径。
然后激活虚拟环境：
source venv/bin/activate 激活成功后，终端前面通常会出现 (venv)。
再检查当前 Python：
python –version 如果显示：
Python 3.11.15 就说明 Hermes 后续安装会基于你的本地 Python 3.11.15 环境。
在 ~/apps/hermes-agent 目录下执行：
export VIRTUAL_ENV=”\((pwd)/venv" uv pip install -e ".[all]" 解释一下这两个命令的作用：
export VIRTUAL_ENV="\)(pwd)/venv“：告诉uv把包装到当前项目的虚拟环境里uv pip install -e ”.[all]“：以开发模式安装 Hermes，并安装官方定义的全部常用扩展
为什么这里建议装 .[all]：
- 对新手更省心
- 后续很多功能不用再反复补装
- 更接近官方完整能力
如果你只想要非常精简的 CLI 基础版，也可以改成：
uv pip install -e ”.“ 但对于零基础用户，我更建议直接按本教程装 .[all]。
官方文档里还有一个可选模块：
uv pip install -e ”./tinker-atropos“ 这个模块主要用于更高级的训练/研究相关能力。
如果你当前只是想：
- 在终端里使用 Hermes
- 接第三方 API
- 做常规聊天和工具调用
那么这一项可以先跳过。
建议初学者现在先不装，等你确认 Hermes 正常工作后，如果确实需要相关功能，再补装。
官方文档说明：
npm install主要用于浏览器自动化和 WhatsApp bridge- 如果你当前只想在终端里用 Hermes，对接第三方 API 聊天
- 那么这一步不是必须的
也就是说，你现在可以先跳过。
如果你后续要启用浏览器自动化或 WhatsApp，再回到 Hermes 项目目录执行：
npm install 如果系统里没有 npm，以后再按需安装：
sudo apt install -y nodejs npm 现在开始准备 Hermes 的配置文件目录。
在 ~/apps/hermes-agent 目录中执行：
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。
如果你希望以后不必每次都进入 venv/bin 目录再执行命令，就把 hermes 做成全局命令。
执行：
mkdir -p ~/.local/bin ln -sf ”\(HOME/apps/hermes-agent/venv/bin/hermes" ~/.local/bin/hermes 然后把 ~/.local/bin 加到 PATH：
echo 'export PATH="\)HOME/.local/bin:$PATH“‘ >> ~/.bashrc source ~/.bashrc 检查是否成功：
which hermes 如果输出类似：
/home/你的用户名/.local/bin/hermes 说明全局命令已经配置成功。
这一部分最重要。
你给出的原始参数是：
{”model“:”gpt-5.4“,”key“:”sk-xxx“,”url“:”https://xcode.best/v1/chat/completions";} 18.1 推荐方式：使用 hermes model 交互配置
先执行：
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 时缩进写错
- 保存为持久配置，后续重启仍然有效
执行：
nano ~/.hermes/config.yaml 你重点检查 model 相关配置。
对于你的场景，核心内容应该类似下面这样：
model: default: gpt-5.4 provider: custom base_url: https://xcode.best/v1 api_key: sk-xxx 说明：
default：模型名provider：这里是custombase_url：一定要写基础地址https://xcode.best/v1api_key：你的第三方接口 key
如果这个文件里还有其他配置项，不要随便删掉。
你只需要确保 model: 这部分是正确的。
保存退出 nano 的方法：
- 按
Ctrl + O保存 - 回车确认
- 按
Ctrl + X退出
配置完成后，执行下面几条命令检查安装是否成功：
hermes version hermes doctor hermes status 你可以这样理解：
hermes version：检查命令是否存在hermes doctor：检查依赖、配置和常见问题hermes status：查看当前 Hermes 的状态
如果这三条都没有明显报错，基本就说明安装已经完成。
再执行一个最简单的单次测试：
hermes chat -q “你好，请简单介绍一下你自己。” 如果能正常返回内容，就说明：
- Hermes 已经成功启动
- 你的第三方 API 可以正常访问
- 模型
gpt-5.4已经被 Hermes 正确调用
21.1 进入交互模式
执行：
hermes 进入后你就可以直接输入中文提问，例如：
请帮我查看当前目录下有哪些文件 或者：
帮我解释一下这个 Python 项目怎么启动 21.2 单次问答模式
如果你不想进入交互界面，只想让它回答一句话，可以这样：
hermes chat -q “现在这台机器的磁盘空间使用情况如何？” 这种模式适合：
- 快速测试
- 脚本里调用
- 临时执行一个任务
21.3 指定本次对话的模型
如果以后你切换了默认模型，也可以在单次运行时临时指定：
hermes chat -m “gpt-5.4” -q “请用 3 句话介绍 Ubuntu 22.04。” 下面这些命令，是你以后最常用的一批。
22.1 基础命令
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 URLhermes setup：运行完整设置向导hermes tools：查看和管理可用工具hermes status：查看当前状态hermes doctor：诊断问题hermes version：查看版本
22.2 配置相关
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 会话相关
hermes –continue hermes –resume <session_id> hermes sessions 含义：
hermes –continue：继续最近一次会话hermes –resume：恢复指定会话hermes sessions：查看和管理历史会话
22.4 更新和卸载
hermes update hermes uninstall 含义：
hermes update：更新 Hermeshermes uninstall：卸载 Hermes
当你已经进入 hermes 交互界面后，可以输入下面这些命令。
23.1 基础控制
/help /quit /clear /new /reset 含义：
/help：显示帮助/quit：退出/clear：清屏并重置对话/new：开始新会话/reset：只重置当前对话
23.2 工具与配置
/tools /toolsets /model /provider /config 含义：
/tools：查看可用工具/toolsets：查看工具集/model：查看或切换当前模型/provider：查看 provider 状态/config：查看当前配置
23.3 会话管理
/history /retry /undo /save /compress /usage 含义：
/history：查看历史/retry：重试上一轮/undo：撤销上一轮/save：保存会话/compress：压缩上下文/usage：查看 token 使用情况
如果你只是想稳定地把 Hermes 跑起来，并使用第三方 API，那么你的最小可用思路其实很简单：
必须有的东西
gitcurlPython 3.11.15uv- Hermes 源码
~/.hermes/config.yaml- 你的第三方 API 参数
目前可以先不折腾的东西
- 本地模型
- GPU
npm install- WhatsApp bridge
- Telegram/Discord 网关
- 高级 memory / training 组件
也就是说，你完全可以先把最核心的 CLI 版本跑起来，用顺手之后再继续扩展。
如果你是在一台云服务器上部署 Hermes，我建议这样理解“部署”：
场景 1：只在 SSH 终端里使用
这是最简单、最推荐的方式。
你只需要：
ssh user@server hermes 适合：
- 个人使用
- 开发测试
- 先验证 Hermes 是否能稳定跑起来
场景 2：以后要接消息平台
如果以后你要把 Hermes 挂到 Telegram、Discord、Slack、WhatsApp 等平台上，再考虑：
hermes gateway setup hermes gateway install hermes gateway start hermes gateway status 这里的 hermes gateway install 在 Linux 上会把网关安装成用户级服务，适合长期运行。
但如果你当前只是使用第三方 API 在终端里聊天，这部分先不用做。
26.1 hermes: command not found
先执行：
source ~/.bashrc which hermes 如果还是不行，检查软链接是否存在：
ls -l /.local/bin/hermes 确认它是否指向：
$HOME/apps/hermes-agent/venv/bin/hermes 26.2 API 明明填了，却连接不上
先检查你有没有把地址填错。
很多人会误填成：
https://xcode.best/v1/chat/completions 但 Hermes 需要的是：
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 报配置问题
执行：
hermes config check hermes config migrate 然后重新运行：
hermes doctor 26.5 工具调用效果不稳定，但聊天能正常返回
这通常说明：
- 你的第三方接口虽然兼容 OpenAI Chat Completions
- 但它对 tool calling 的兼容并不完整
这种情况不是 Hermes 本体一定有问题，而是上游接口兼容度不够。
你可以先验证：
- 纯聊天是否正常
- 简单工具任务是否正常
- 复杂代理任务是否出现异常
如果简单聊天正常、复杂工具调用异常，优先怀疑上游 API 兼容性。
26.6 python3.11 有，但建虚拟环境失败
先检查：
python3.11 -m venv –help 如果这里就报错，说明你的 Python 可能没有可用的 venv 模块。
这时你需要先修复本机 Python 3.11.15 环境，再继续安装 Hermes。
完成安装后，不要一上来就让 Hermes 做很复杂的事情。
建议按这个顺序测试：
第一步：测试命令是否存在
hermes version 第二步：测试配置是否通过
hermes doctor hermes status 第三步：测试单次问答
hermes chat -q “请用一句话说明你是否已成功连接模型。” 第四步：进入交互界面
hermes 然后输入：
/help 再输入：
请介绍一下你有哪些能力 这样最容易判断问题到底出在：
- 安装
- 配置
- API 连通性
- 还是交互使用方式
如果你后面不再坚持“必须使用现有 Python 3.11.15”，那么可以使用官方一键安装。
28.1 一键安装命令
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 - 你希望自己完全掌控虚拟环境位置和安装方式
如果你已经看懂全文，后面想快速复装，可以只看这一段。
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
- 你这个场景最适合走“手动安装”，因为你指定了本机
Python 3.11.15 - Hermes 对接第三方接口时，要填的是
base_url，不是完整/chat/completions地址 - 你的正确配置是：
provider=custombase_url=https://xcode.best/v1api_key=sk-xxxmodel=gpt-5.4
- 新版 Hermes 里，模型相关配置以
~/.hermes/config.yaml为准，不要再依赖旧的.env模型变量 - 安装完成后先跑
hermes doctor和hermes chat -q “你好”，不要上来就做复杂任务
如果你愿意，我下一步可以继续帮你补一份：
Ubuntu 22.04 实际可直接复制执行的一键部署脚本
或者帮你继续生成：
针对你的第三方 API 的完整 config.yaml 样板文件
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容，请联系我们，一经查实，本站将立刻删除。
如需转载请保留出处：https://51itzy.com/kjqy/270916.html