夜雨聆风最近Harmes Agents爆火，作为一款功能强大的AI智能代理工具，它能自动完成复杂任务、集成多种技能，不管是日常办公还是技术调试都能派上大用场。但很多新手卡在了安装环节，要么依赖缺失，要么命令报错，要么不知道怎么配置。
今天这篇保姆级教程，全程图文逻辑（无多余复杂术语），覆盖Windows、Mac、Linux三大系统，四种安装方式（一键脚本、手动安装、Docker部署、本地免费运行），从前置准备到安装完成、首次配置，再到常见报错解决，手把手教你搞定，新手也能轻松上手！
一、前置准备（必看！避免安装失败）
不管用哪种安装方式，先确认你的设备满足基础条件，提前做好准备，能少走90%的弯路。
1. 设备与系统要求
Mac：macOS 10.15及以上（Intel/Apple Silicon均可）
Linux：Ubuntu 20.04+、CentOS 8+等主流发行版（推荐Ubuntu，兼容性最好）
Windows：原生不支持，需先安装WSL2（详细步骤见下文）
硬件：至少4GB内存（推荐8GB+），确保网络通畅（需访问GitHub、国外服务器）
2. 必备基础工具（提前安装）
所有系统都需要提前安装Git（用于拉取仓库代码），不同系统安装方式如下：
Mac：打开终端，输入
git --version，若提示未安装，按照系统提示点击“安装”即可（自带命令行安装工具）；Linux（Ubuntu）：终端输入
sudo apt update && sudo apt install git -y，回车执行即可；Windows（WSL2）：进入WSL2终端，输入
sudo apt update && sudo apt install git -y安装。
3. 特殊准备（Windows用户必做）
由于Harmes Agents不支持原生Windows，需先安装WSL2（Windows子系统），步骤如下（简单3步）：
打开“控制面板”→“程序”→“启用或关闭Windows功能”，勾选“适用于Linux的Windows子系统”“虚拟机平台”，点击确定，重启电脑；
重启后，打开Microsoft Store，搜索“Ubuntu”，下载并安装（任意版本均可，推荐22.04）；
安装完成后，打开Ubuntu，按照提示设置用户名和密码，等待初始化完成（首次打开可能需要几分钟），即可进入WSL2终端。
⚠️ 注意：WSL2安装过程中若提示“虚拟机平台未启用”，重新检查步骤1，确保勾选正确并重启。
二、四种安装方式（按需选择，新手优先一键脚本）
推荐优先级：一键脚本安装（新手首选） → 本地Ollama免费安装（零成本） → Docker部署（VPS/生产环境） → 手动安装（高级用户/开发调试）
方式1：一键脚本安装（最快最省心，新手首选）
这种方式无需手动安装依赖，脚本会自动检测并安装Python、Node.js、ripgrep、ffmpeg等所有必需工具，2分钟即可完成安装，适合大多数用户。
操作步骤（Mac/Linux/WSL2通用）
打开终端（Mac/Linux直接打开，Windows打开WSL2的Ubuntu终端）；
复制以下命令，粘贴到终端，回车执行（建议手动输入，避免复制多余空格）：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
等待安装完成（过程中会自动下载依赖，耗时根据网络速度而定，耐心等待，不要中断）；
安装完成后，刷新终端环境（必做！否则无法识别hermes命令）：
Bash用户（大部分Linux/Mac默认）：输入
source ~/.bashrc回车；Zsh用户（部分Mac/Linux）：输入
source ~/.zshrc回车。
验证安装：输入 hermes --version，若显示版本号（如Hermes Agent v0.8.0），说明安装成功！
方式2：本地Ollama免费安装（零成本，无需API Key）
如果不想使用OpenAI、Anthropic等付费API，这种方式完全免费，通过Ollama运行本地模型，无需API Key，适合预算有限的新手。
操作步骤（Mac/Linux/WSL2通用）
安装Ollama：终端输入以下命令，回车执行：
curl -fsSL https://ollama.com/install.sh | sh
启动Ollama服务：输入
ollama serve回车（保持终端窗口打开，不要关闭）；新打开一个终端，下载模型（推荐llama3.1，轻量且好用）：
ollama pull llama3.1
安装Harmes Agents（同方式1的一键脚本命令）：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
刷新终端环境（同方式1步骤4），然后执行 hermes setup，在配置向导中选择“Ollama”作为提供商，完成配置即可。
方式3：Docker部署（VPS/生产环境首选）
适合有VPS（云服务器）或需要容器化部署的用户，可实现后台运行、数据持久化，适合长期使用。
操作步骤（所有支持Docker的系统通用）
确保已安装Docker（若未安装，参考Docker官方文档安装）；
拉取Harmes Agents官方镜像：
docker pull nousresearch/hermes-agent:latest
创建数据目录（用于持久化配置、记忆和技能，避免容器删除后数据丢失）：
mkdir -p ~/.hermes
首次配置（交互式，设置API Key等信息）：
docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup
启动Gateway服务（后台运行，可通过浏览器访问）：
docker run -d --name hermes -v ~/.hermes:/opt/data -p 8000:8000 nousresearch/hermes-agent hermes gateway run
验证部署：打开浏览器，输入 http://localhost:8000，若能看到Web界面，说明部署成功。
⚠️ 注意：若在VPS上部署，需开放8000端口，才能通过公网访问。
方式4：手动安装（高级用户/开发调试）
适合需要完全控制安装过程、修改源码或固定版本的高级用户，步骤稍多，但可灵活配置。
操作步骤（Mac/Linux/WSL2通用）
安装uv包管理器（替代pip，更快更稳定）：
curl -LsSf https://astral.sh/uv/install.sh | sh克隆仓库（带子模块，避免依赖缺失）：
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git进入仓库目录：
cd hermes-agent创建并激活虚拟环境：
uv venv venv --python 3.11 source .venv/bin/activate
安装依赖（推荐完整安装，功能最全）：
uv pip install -e ".(all)"安装终端工具后端（必需，否则无法使用核心功能）：
uv pip install -e "./mini-swe-agent" uv pip install -e "./tinker-atropos"
（可选）安装Node.js依赖（部分技能需要）：
npm install
验证安装：输入 hermes --version，显示版本号即成功。
三、安装后首次配置（必做！否则无法正常使用）
无论哪种安装方式，安装完成后都需要进行简单配置，主要是设置LLM提供商和API Key（Ollama方式无需API Key）。
启动配置向导
终端输入以下命令，启动交互式配置向导：
hermes setup
配置核心步骤
选择推理提供商：按需选择，新手推荐这两种：
免费入门：OpenRouter（有大量免费模型，无需付费）；
本地免费：Ollama（已安装Ollama的用户选择）；
付费使用：OpenAI、Anthropic等（需提前获取API Key）。
输入API Key（Ollama方式跳过）：
若选择OpenRouter，需先注册OpenRouter账号，获取API Key，粘贴到终端即可；
API Key会自动保存到
~/.hermes/.env文件，无需手动管理。
选择默认模型：推荐新手选择免费模型（如nvidia/nemotron-3-super-120b-a12b:free），足够日常使用。
完成配置：按照向导提示，一路回车即可完成配置，配置文件会保存到
~/.hermes/config.yaml。启动Harmes Agents
配置完成后，终端输入以下命令，即可启动Harmes Agents，开始使用：
hermes
启动成功后，会看到欢迎横幅，显示当前使用的模型和可用工具，输入指令即可让AI代理完成任务。
四、常见报错排查（新手必看！高效解决问题）
安装过程中遇到报错不要慌，以下是最常见的5种报错及解决方法，覆盖90%的问题。
报错1：
command not found: hermes
解决方法：未刷新终端环境，执行对应命令刷新：
Bash用户： source ~/.bashrcZsh用户： source ~/.zshrc
若仍不行，手动将~/.local/bin添加到PATH即可。
报错2：
No module named yaml/dotenv
解决方法：依赖安装不完整，手动安装缺失依赖：
pip install pyyaml python-dotenv
报错3：
安装脚本执行失败，提示“网络超时”
解决方法：网络问题，建议切换网络（如手机热点），或重试几次命令；若仍失败，手动下载安装脚本，本地执行。
报错4：
Docker部署后，浏览器无法访问8000端口
解决方法：检查容器是否正常运行（docker ps），若未运行，执行 docker start hermes；同时检查端口是否开放（VPS需在安全组开放8000端口）。
报错5：
Windows WSL2中安装，提示“权限不足”
解决方法：在命令前加上sudo，如 sudo curl ...，输入WSL2的密码即可执行。
五、后续使用小技巧（新手进阶）
切换模型：无需重新配置，终端输入 hermes model，即可交互式选择其他模型；
安装技能：终端输入
hermes skills install技能名称，可安装办公、安全、开发等各类技能；编辑配置：若需修改配置，可直接编辑
~/.hermes/config.yaml文件，修改后保存即可生效；查看帮助：输入
hermes --help，可查看所有可用命令，快速了解功能。
最后总结
新手优先选择「一键脚本安装」，最快最省心；预算有限选「Ollama免费安装」，零成本上手；有VPS或生产需求选「Docker部署」，稳定持久；高级用户或需要调试源码选「手动安装」。
按照本文步骤操作，基本不会遇到无法解决的问题，安装完成后，就可以体验Harmes Agents的强大功能啦～
