yuluyangguang1/hermes-portable 全平台自建打包完整操作文档
文档适用： Windows、Linux、macOS
打包目的： 生成无系统依赖、可 U 盘迁移、重装系统只复制文件夹即可复用的 Hermes 绿色便携包
核心原则： 所有配置统一存放于data文件夹，全平台互通
整体前置总规则（必看，否则大概率报错）
- 路径规范 — 全程所有文件路径无中文、无空格、无括号、无特殊符号；
- 平台对应 — 打包环境和打包平台必须一一对应：Windows 只能打包 Windows 包，Linux 只能打包 Linux 包，macOS 只能打包 macOS 包；
- 需要联网 — 打包需要联网，会拉取 Hermes 官方源码、Python、依赖；离线打包需提前缓存 uv 资源；
- 极简依赖 — 打包仅需要系统有极简基础 Python 用来跑打包脚本，打包成品自带独立 Python，运行 Hermes 不再依赖本机任何软件。
第一部分：全系统通用前置环境安装（打包必备，一次性操作）
需要安装两个工具：Git（拉取源码）、uv（构建隔离运行环境、下载 Python + 依赖）
1. 安装 Git
Windows
Git 官网下载 Windows 安装包，全程默认下一步安装；新开 CMD 执行 git --version，输出版本即正常。
Linux（Ubuntu/Debian）
sudo apt update && sudo apt install git -y
git --version
Linux（CentOS/RHEL）
sudo yum install git -y
git --version
2. 安装 uv（分系统）
Windows（管理员 PowerShell 执行）
常规安装命令：
irm https://astral.sh/uv/install.ps1 | iex
国内下载慢使用带清华镜像的安装命令：
$env:UV_PYTHON_BUILD_MIRROR="https://mirrors.tuna.tsinghua.edu.cn/github-release"
irm https://astral.sh/uv/install.ps1 | iex
安装完成关闭所有终端，重新打开，校验：
uv --version
Linux/macOS 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env
uv --version
Linux 永久生效（新开终端不用重复执行 source）：
~/.bashrc
source ~/.bashrc
3. 国内加速配置（打包必配，解决依赖下载超时）
配置全局 PyPI 清华镜像，加速三方库下载。
Windows（PowerShell 临时生效）
$env:PIP_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"
Linux 临时生效
export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
第二部分：拉取打包仓库源码（全系统操作一致）
找空目录，路径纯英文，示例路径：
| 系统 | 示例路径 |
|---|---|
| Windows | D:\build_hermes |
| Linux | ~/build_hermes |
在目录空白处打开终端（Windows 地址栏输入 cmd 回车；Linux 直接打开终端 cd 进入文件夹）。
克隆打包仓库源码：
git clone https://github.com/yuluyangguang1/hermes-portable.git
cd hermes-portable
各文件作用说明（仓库源码）
| 文件 / 文件夹 | 功能 |
|---|---|
tools/build.py |
打包主程序，全部打包逻辑入口 |
build-guide.md |
官方打包说明文档 |
| 模板文件夹 | 自动生成 bat/sh 启动脚本、目录结构 |
第三部分：分系统打包执行步骤
模块 A：Windows 打包 Windows-x64 便携包
终端当前路径：
D:\build_hermes\hermes-portable
执行打包命令：
python tools/build.py windows-x64打包全程自动执行动作（后台逻辑）：
- Git 拉取上游
NousResearch/hermes-agentmain 分支最新完整源码； - uv 自动下载适配 Hermes 的 Python 3.11（不会下载其他 Python 大版本）；
- 构建完全隔离的虚拟环境
venv-windows-x64； - 自动用 uv 安装 Hermes 全部依赖，使用清华镜像加速；
- 自动生成启动脚本
Hermes.bat、配套运行文件； - 最终在目录生成成品文件夹：
HermesPortable-Windows-x64。
模块 B：Linux 打包（二选一，根据 CPU 架构）
x86_64 普通电脑 / 云服务器
python3 tools/build.py linux-x64
ARM64（树莓派、NAS、ARM 云主机）
python3 tools/build.py linux-arm64
打包自动逻辑：
- 拉取 Hermes 最新官方源码；
- uv 下载 Linux 对应架构 Python 3.11；
- 生成 Linux 隔离 venv 环境；
- 生成启动脚本
Hermes.sh； - 输出成品：
HermesPortable-Linux-x64/HermesPortable-Linux-arm64。
模块 C：macOS 打包
Intel 芯片 macOS
python3 tools/build.py macos-x64
M 系列 ARM macOS
python3 tools/build.py macos-arm64
补充：离线打包（断网内网环境）
- 有网络环境正常打包 1 次，uv 会缓存全部 Python、依赖包；
- 复制缓存目录 + 打包仓库到无网机器；
- 打包命令增加
--offline参数，全程不走外网：
Windows 示例：
python tools/build.py --platform windows-x64 --offline
第四部分：旧配置迁移（新旧包互通核心）
1. 配置核心文件说明
所有个性化数据全部集中在便携包内 data 文件夹：API 密钥、模型配置、聊天记录、会话记忆、自定义技能。
⚠️ 打包不会改动
data，data文件夹全平台通用（Windows、Linux、macOS 可互相复制）。
2. 迁移步骤
- 找到旧 Hermes 便携包，完整复制
data文件夹； - 打开本次全新打包出来的成品文件夹；
- 将旧
data直接粘贴覆盖新文件夹内的data； - 无需重配任何参数，直接启动即可。
第五部分：打包成品目录详解（以 Windows 举例，Linux 逻辑一致）
HermesPortable-Windows-x64/
| 目录 / 文件 | 功能 | 是否可删除 |
|---|---|---|
Hermes.bat |
Windows 一键启动入口，双击打开 WebUI | 不可删 |
Hermes.sh |
Linux/macOS 启动脚本 | Windows 打包可删 |
data |
全部用户配置、聊天数据 | 必须备份，不能删 |
venv-windows-x64 |
uv 生成独立 Python 运行环境，便携根本 | 不可删，删除需重新打包 |
hermes |
上游官方 Hermes 源码 | 不可删 |
Linux 成品目录：启动文件为
Hermes.sh，venv 命名为venv-linux-x64/venv-linux-arm64。
第六部分：打包完成后启动验证
Windows
- 进入打包成品文件夹，双击
Hermes.bat； - 自动弹出浏览器
127.0.0.1:17520； - 验证：WebUI 内原有配置全部保留。
Linux
# 进入打包目录
cd HermesPortable-Linux-x64
# 赋予脚本执行权限
chmod +x Hermes.sh
# 启动
./Hermes.sh
命令行版本校验（确认 Hermes 版本）
Windows cmd 进入成品目录：
venv-windows-x64\Scripts\activate
hermes --version
Linux 终端：
source venv-linux-x64/bin/activate
hermes --version
正常输出版本号 = 打包成功。执行
deactivate退出虚拟环境。
第七部分：后续日常更新两种方案（不用反复重打包）
方案 1：在线原地升级（日常首选，不用重打包）
- 终端进入便携成品目录，激活自带 venv；
- 执行升级命令拉取上游最新 Hermes；
hermes update
# 自动适配新版配置
hermes config migrate
依赖异常修复命令：
uv pip install -e ".[all]"
deactivate 退出环境，重启启动脚本。
方案 2：底层环境损坏彻底重建
venv 环境错乱、Python 底层需要更换：
- 删除成品文件夹内
venv、hermes文件夹； - 返回
hermes-portable打包源码目录，重新执行打包命令； - 再次覆盖旧
data文件夹，配置无损。
第八部分：高频报错解决清单
| 问题 | 原因与解决 |
|---|---|
打包提示 python 不是内部命令 |
打包电脑需要安装系统基础 Python（仅打包用），推荐 Python 3.11；打包成品运行不需要系统 Python |
uv 命令找不到 |
安装 uv 后没有关闭全部终端重启；Linux 未执行 source 加载环境 |
| 下载源码 / 依赖超时 | 配置清华镜像，开启网络代理；或者使用离线打包模式 |
| Linux 启动提示权限不足 | 执行 chmod +x Hermes.sh 添加执行权限 |
| 启动报错路径非法 | 整个文件夹路径存在中文、空格、特殊符号，更换全英文路径 |
第九部分：长期抗风险兜底规则（防止原作者仓库停更）
- 本地永久备份完整
hermes-portable打包源码文件夹，即便 GitHub 仓库被删除，本地依然可以无限打包； - Hermes 版本由上游官方决定，和打包作者无关，每次联网打包自动拉最新 Hermes；
- Python 大版本固定为 3.11（适配 Hermes 稳定），不会无限制自动升级 Python；
- 依赖安装为 Hermes 要求范围内的最新兼容版本，不会乱升级导致报错；
- 所有备份只需要留存
data文件夹，适配所有自行打包的全平台包。
极简流程复盘（一页速查）
① Windows/Linux 装 Git + uv，配置国内镜像
↓
② git clone 拉打包源码
↓
③ 对应系统执行对应平台打包命令
↓
④ 旧包 data 覆盖新打包目录
↓
⑤ 启动测试
↓
⑥ 日常用 hermes update 升级；环境崩了重新打包
文档来源： yuluyangguang1/hermes-portable
最后更新： 2026-07-30
「点点赞赏，手留余香」
声明：本文为原创文章，版权归旷野小站所有，欢迎分享本文，转载请保留出处！
