️ Hermes Portable — 从零构建教程

面向完全不懂编程的用户，手把手教你构建自己的 AI Agent U盘

第一步：安装必要工具

构建前需要安装两个工具：Python（编程语言）和 Git（下载代码用）。

macOS

Windows

Linux

1检查是否已安装

打开终端（按 Command + 空格，输入 终端，回车），输入：

python3 --version

如果显示 Python 3.x.x 说明已安装，跳到第二步。

如果提示 command not found，继续下面的步骤。

2安装 Python

打开浏览器，访问：https://www.python.org/downloads/

点击大的黄色按钮 "Download Python 3.12.x"

下载完成后双击 .pkg 文件，一路点 "继续" 安装即可。

3安装 Git

在终端输入：

git --version

如果提示安装 Xcode Command Line Tools，点 "安装" 等待完成即可。

如果没有提示，说明已安装。

1安装 Python

打开浏览器，访问：https://www.python.org/downloads/

点击大的黄色按钮 "Download Python 3.12.x"

下载完成后双击 .exe 文件。

安装时 务必勾选 "Add Python to PATH"（底部的复选框），然后点 "Install Now"。

2安装 Git

打开浏览器，访问：https://git-scm.com/download/win

下载会自动开始，双击 .exe 文件，一路点 "Next" 安装即可。

3打开命令行

按 Win + R，输入 cmd，回车。

或者在文件管理器地址栏输入 cmd 回车。

1安装 Python 和 Git

打开终端，输入：

sudo apt update && sudo apt install -y python3 python3-pip git curl

输入密码（不显示），等待安装完成。

第二步：下载代码

macOS

Windows

Linux

1打开终端，输入以下命令

cd Desktop

git clone https://github.com/yuluyangguang1/hermes-portable.git

cd hermes-portable

这会把代码下载到桌面的 hermes-portable 文件夹。

1打开 CMD，输入以下命令

cd %USERPROFILE%\Desktop

git clone https://github.com/yuluyangguang1/hermes-portable.git

cd hermes-portable

这会把代码下载到桌面的 hermes-portable 文件夹。

1打开终端，输入以下命令

cd ~/Desktop

git clone https://github.com/yuluyangguang1/hermes-portable.git

cd hermes-portable

第三步：开始构建

macOS

Windows

Linux

1运行构建脚本

确保终端已经在 hermes-portable 目录中（上一步的 cd hermes-portable），然后输入：

python3 tools/build.py

构建过程大约需要 5-10 分钟，取决于网速。你会看到进度信息：

[1/10] Downloading uv (package manager)
[[ok]] uv ready
[2/10] Installing portable Python
[[ok]] Python 3.12 installed
[3/10] Cloning hermes-agent
[[ok]] hermes-agent cloned
...
[[ok]] BUILD COMPLETE

2构建完成！

构建产物在 dist/HermesPortable/ 文件夹中。

把 HermesPortable 文件夹复制到U盘，双击 Hermes.command 即可使用。

1运行构建脚本

确保 CMD 已经在 hermes-portable 目录中，然后输入：

python build_windows.py

构建过程大约需要 5-10 分钟。

如果提示 python 不是内部或外部命令，说明 Python 没有安装或没有勾选 "Add to PATH"。请重新安装 Python 并确保勾选。

2构建完成！

构建产物在 dist\HermesPortable\ 文件夹中。

把 HermesPortable 文件夹复制到U盘，双击 Hermes.bat 即可使用。

1运行构建脚本

python3 tools/build.py

构建完成后的产物在 dist/HermesPortable/ 文件夹中。

直接构建到U盘（可选）

如果你想直接把产物构建到U盘，而不是先构建再复制：

macOS / Linux

python3 tools/build.py /Volumes/你的U盘名

Windows

先用资源管理器打开U盘，在地址栏输入 cmd 回车，然后：

python build_windows.py

构建产物会直接生成在U盘的 dist\HermesPortable\ 中。

第四步：首次使用

1双击启动

系统	双击的文件
macOS	`Hermes.command`
Windows	`Hermes.bat`
Linux	终端运行 `./Hermes.sh`

2配置 API Key

首次启动会自动打开浏览器，显示配置面板。

选择一个 AI 提供商（推荐 OpenRouter），填入你的 API Key，点击 "测试连接"，成功后点击 "启动"。

3开始对话

启动后终端中即可与 AI 对话。所有数据存储在U盘的 data/ 目录中。

常见问题

Q: 构建时提示 "git clone failed" 怎么办？

A: 网络问题。确保能访问 GitHub。如果在中国大陆，可能需要使用代理。

Q: Windows 双击 .bat 没反应？

A: 右键 Hermes.bat → 以管理员身份运行。如果还是没反应，打开 CMD，手动输入 Hermes.bat 查看错误信息。

Q: macOS 提示 "无法打开，因为无法验证开发者"？

A: 右键 Hermes.command → 打开，然后点 "仍然打开"。

Q: 构建时提示 "No module named pip"？

A: Python 安装不完整。重新安装 Python，确保安装时勾选了 pip。

Q: 可以不用构建，直接下载使用吗？

A: 可以！从 GitHub Releases 下载预构建包，解压即可使用。