第1章 一键安装 🚀
⏱️ 5 分钟，你就能拥有自己的 AI 助手！
墨鱼 🦑 已经迫不及待要和你见面了，让我们开始吧！
1. 前置条件检查 🔍
在安装 Hermes 之前，我们需要确认你的系统准备好了。别担心，只需要检查几样东西。
支持的平台
| 平台 | 支持情况 |
|---|---|
| macOS | ✅ 完全支持 |
| Linux | ✅ 完全支持 |
| WSL2 (Windows Subsystem for Linux) | ✅ 完全支持 |
| Android (Termux) | ✅ 完全支持 |
| 原生 Windows | ❌ 暂不支持，请使用 WSL2 |
🪟 Windows 用户注意
如果你使用的是 Windows，请先安装 WSL2，然后在 WSL2 终端中操作。打开 PowerShell，运行：
wsl --install安装完成后重启电脑，从开始菜单打开 Ubuntu 即可。
检查 Python 版本
Hermes 需要 Python 3.10 或更高版本。打开终端，运行：
python3 --version你应该看到类似这样的输出：
Python 3.10.12💡 提示
如果你的 Python 版本低于 3.10，请先升级：
- macOS：
brew install python@3.12 - Ubuntu/Debian：
sudo apt install python3.12 - 其他 Linux：参考你的发行版包管理器
检查 curl
curl --version有版本号输出就说明没问题 ✅
检查 Git
git --version有版本号输出就说明没问题 ✅
macOS 额外步骤
如果你使用 macOS，可能还需要安装 Xcode Command Line Tools：
xcode-select --install弹窗点「安装」就行，完成后继续。
Linux 额外步骤
Ubuntu / Debian 用户可能需要安装构建工具和虚拟环境支持：
sudo apt update
sudo apt install -y build-essential python3-venv2. 一键安装 ✨
就是这行命令，复制粘贴到终端，回车：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash然后坐下来，喝口水 ☕，让脚本替你干活。
这行命令做了什么？
| 步骤 | 说明 |
|---|---|
curl -fsSL | 安静地下载安装脚本（-f 遇到错误不输出 HTML，-s 静默，-S 显示错误，-L 跟随重定向） |
下载 install.sh | 从 GitHub 官方仓库获取安装脚本 |
| bash | 将脚本内容直接交给 bash 执行 |
脚本会自动完成以下操作：
- 📋 检测你的操作系统和 Python 版本
- 📦 创建独立的 Python 虚拟环境（不污染系统环境）
- 📥 从 PyPI 安装 Hermes Agent 及其依赖
- 🔧 配置 PATH 环境变量，让
hermes命令全局可用 - 🏗️ 初始化配置目录
~/.hermes/
🔒 安全提示
如果你不放心直接执行远程脚本（这很合理！），可以先下载脚本审查内容：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o install.sh
cat install.sh # 审查脚本内容
bash install.sh # 确认无误后再执行🌏 国内用户网络加速
如果你在中国大陆，可能因为网络原因下载缓慢。设置代理后再安装：
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash🚀 代理小贴士
将 127.0.0.1:7890 替换为你自己的代理地址和端口。常见的有：
- Clash：
http://127.0.0.1:7890 - V2RayN：
http://127.0.0.1:10809 - Shadowsocks：
http://127.0.0.1:1080
如果不想每次都手动设置，可以把 export 那两行加到你的 ~/.bashrc 或 ~/.zshrc 里。
3. 安装后步骤 🔄
安装脚本执行完成后，需要让终端知道新的命令在哪。
刷新环境变量
根据你使用的 Shell，运行对应的命令：
# macOS 默认 Shell (zsh)
source ~/.zshrc
# Linux 默认 Shell (bash)
source ~/.bashrc🤔 不知道自己用的哪个 Shell？
运行这个命令看看：
echo $SHELL- 输出
/bin/zsh→ 用source ~/.zshrc - 输出
/bin/bash→ 用source ~/.bashrc
验证安装
hermes --version看到版本号输出，恭喜你，安装成功！🎉
hermes 0.x.x🦑 墨鱼说：看到版本号的那一刻，就像拆开快递一样开心！
4. 首次启动 🎮
是时候让墨鱼登场了！在终端输入：
hermes首次运行时，Hermes 会：
- 📁 在
~/.hermes/下创建配置目录结构 - 🎨 启动交互式界面
- 🤖 等待你的第一个指令
你会看到一个欢迎界面，墨鱼 🦑 已经准备好为你服务了！
配置目录长什么样？
~/.hermes/
├── config.yaml # 主配置文件
├── history/ # 对话历史
└── plugins/ # 插件目录输入任何问题试试看，比如：
你好，墨鱼！你能做什么？要退出 Hermes，按 Ctrl + C 或输入 /exit。
5. 快速健康检查 🩺
Hermes 内置了一个「医生」命令，可以帮你检查一切是否正常：
hermes doctor它会检查以下项目：
| 检查项 | 说明 |
|---|---|
| ✅ Python 环境 | Python 版本和虚拟环境是否正常 |
| ✅ 网络连接 | 能否访问 API 服务 |
| ✅ 配置文件 | 配置是否完整 |
| ✅ 依赖完整性 | 所需依赖是否都已安装 |
如果所有项目都显示 ✅，说明一切正常，可以开始愉快地使用了！
如果某个项目显示 ❌，hermes doctor 会给出修复建议。
6. 常见问题排查 🔧
遇到问题别慌，墨鱼帮你一个个解决！
❌ permission denied（权限不足）
症状：
Permission denied: '/usr/local/bin/hermes'解决方案：
# 方案一：给安装目录加上写权限
sudo chmod +x /usr/local/bin/hermes
# 方案二：重新运行安装脚本，使用用户目录
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash💡 推荐方案二
安装脚本默认会安装到用户目录下，一般不需要 sudo。如果遇到权限问题，优先选择重新运行安装脚本。
❌ Python 版本过低
症状：
Error: Python 3.10+ is required, found 3.8.x解决方案：
安装更高版本的 Python：
# macOS
brew install python@3.12
# Ubuntu / Debian
sudo apt update
sudo apt install python3.12 python3.12-venv
# 安装后验证
python3.12 --version然后重新运行安装脚本。
❌ 网络连接失败
症状：
Failed to connect to raw.githubusercontent.com
# 或
Could not fetch URL https://pypi.org/...解决方案：
# 1. 检查网络是否通畅
ping -c 3 github.com
# 2. 如果不通，设置代理
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
# 3. 再次尝试安装
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash❌ 代理设置问题
症状：
Connection timed out
# 或
curl: (7) Failed to connect to 127.0.0.1 port 7890解决方案：
# 1. 确认代理软件是否正在运行
# 2. 确认代理端口是否正确（在代理软件中查看）
# 3. 测试代理是否可用
curl -x http://127.0.0.1:7890 https://www.google.com
# 4. 如果不再需要代理，取消设置
unset http_proxy https_proxy❌ command not found: hermes
症状：
hermes: command not found解决方案：
# 1. 确认安装是否成功完成
ls ~/.local/bin/hermes
# 2. 确认 PATH 是否包含安装路径
echo $PATH
# 3. 重新加载 Shell 配置
source ~/.bashrc # Linux
source ~/.zshrc # macOS
# 4. 如果还不行，手动添加 PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # Linux
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # macOS
source ~/.bashrc # 或 source ~/.zshrc❌ 还是不行？
如果以上方案都没有解决你的问题：
- 运行
hermes doctor查看详细诊断信息 - 到 GitHub Issues 搜索或提交问题
- 在提交 Issue 时附上
hermes doctor的输出，这样维护者能更快帮你定位问题
✅ 小结
干得漂亮！👏 在这一章里，我们：
- ✅ 检查了系统前置条件
- ✅ 用一行命令安装了 Hermes Agent
- ✅ 验证了安装成功
- ✅ 完成了首次启动
- ✅ 用
hermes doctor做了健康检查
墨鱼 🦑 已经在你的终端里安家了！接下来，让我们了解更多安装方式。
👉 下一章：第2章 源码安装