大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



🤵‍♂️ 个人主页：

目录

一、前言

二、系统要求详解（必看，避免踩坑）

2.1 软件依赖要求（全系统通用）

2.2 端口要求（必开放，否则无法访问）

2.3 不同系统兼容性对比

三、Windows 系统安装（WSL2 环境，新手详细分步）

3.1 前置准备：启用 WSL2（必须）

3.2 前置准备：更新 Ubuntu 子系统

3.3 一键部署 Hermes-Agent（推荐，新手首选）

3.4 手动安装（适合网络受限、无法使用一键脚本的用户）

3.5 安装验证（必做，确认安装成功）

3.6 初始化配置（关键步骤，必做）

四、Ubuntu 系统安装（稳定性**，推荐新手/开发环境）

4.1 系统前置准备

4.2 一键安装（推荐，新手首选）

4.3 手动安装（适合网络受限、自定义配置的用户）

4.4 启动服务与访问 WebUI

4.5 配置开机自启（可选，生产环境推荐）

五、macOS 系统安装（适合苹果用户，操作简单）

5.1 前置准备

5.2 一键安装（推荐，新手首选）

5.3 brew 安装（可选，已装 brew 用户）

5.4 启动服务与初始化配置

六、源码编译安装（开发者/自定义配置）

七、Hermes-Agent 常用命令（必记，方便管理）

八、常见问题与解决方案（新手必看，避坑指南）

8.1 问题1：一键脚本卡死，光标闪烁不加载

8.2 问题2：Python 环境报错“externally-managed-environment”

8.3 问题3：启动后报错“AuthenticationError (HTTP 401)”

8.4 问题4：WebUI 无法访问，提示“无法连接到服务器”

8.5 问题5：macOS 提示“无法打开 hermes，因为它来自身份不明的开发者”

8.6 问题6：微信网关无法登录，无二维码或扫码无响应

---

> 适合：AI Agent 学习者、开发者、个人办公效率提升、轻量自动化场景

> 系统：Windows10/11（需WSL2）、Ubuntu20.04/22.04、macOS12+

> 内容：系统配置对比、软件依赖说明、一键脚本安装、手动安装、源码编译、初始化配置、常用命令、常见报错解决方案（附实操提示）

> 难度：新手友好（一键脚本）→ 进阶（手动安装）→ 自定义（源码编译）

Hermes-Agent 是由 Nous Research 打造的开源自主 AI Agent，主打“越用越聪明”的自我进化特性，内置闭环学习系统和四层记忆架构，支持 40+ 内置工具，可接入 Telegram、Discord、微信、钉钉等多平台网关，实现跨场景自动化交互、工具调用和任务执行。

Hermes-Agent 分为社区版（免费，适合个人/小型团队），不支持原生 Windows 系统，Windows 用户需先安装 WSL2（Windows 子系统），以下是详细的硬件和软件要求，含最低/推荐配置对比：

Hermes-Agent 依赖 Python、Node.js 等基础环境，一键脚本会自动安装大部分依赖，手动安装需提前准备以下软件，避免出现“依赖缺失”“版本不兼容”报错：

Hermes-Agent 运行需要开放以下端口，避免防火墙拦截，导致 WebUI 无法访问、网关连接失败或模型交互异常：

Hermes-Agent 不支持原生 Windows 系统，Windows 用户需通过 WSL2 模拟 Linux 环境部署，不同系统的安装难度、稳定性略有差异，新手可优先选择推荐系统：

Hermes-Agent 不支持原生 Windows 系统，必须通过 WSL2（Windows 子系统）模拟 Linux 环境部署，步骤分为“启用 WSL2 → 安装 Ubuntu 子系统 → 部署 Hermes-Agent”，以 Windows11 为例，Windows10 操作一致：

1. 按下 Win+R，输入 powershell，右键选择“以管理员身份运行”（必须管理员权限，否则无法启用 WSL2）；
2. 输入以下命令，启用 WSL2 和虚拟机平台功能：

3. Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux -All -NoRestart Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -All -NoRestart
4. 命令执行完成后，重启电脑（必须重启，否则功能不生效）；
5. 重启后，打开 Microsoft Store，搜索“Ubuntu”，选择“Ubuntu 22.04 LTS”安装（免费）；
6. 安装完成后，启动 Ubuntu 子系统，等待初始化完成，设置用户名和密码（记住密码，后续执行 sudo 命令需用到）；
7. 验证 WSL2 是否启用：在 Ubuntu 终端中输入 wsl --status，提示“默认分发版：Ubuntu”即成功。

启动 Ubuntu 子系统后，先更新系统包管理器，安装基础依赖，避免后续安装报错：

# 更新系统包列表 sudo apt update -y && sudo apt upgrade -y # 安装基础依赖（curl、git 等，部分可能已默认安装） sudo apt install -y curl git

Hermes-Agent 提供官方一键部署脚本，可自动安装 Python、Node.js、uv 等依赖，克隆源码并配置环境，步骤如下（全程在 Ubuntu 终端执行）：

1. （可选，国内用户必做）配置网络镜像，解决 GitHub 访问慢、脚本卡死问题： # Git 镜像加速 git config --global url."https://mirror.ghproxy.com/https://github.com".insteadOf "https://github.com" # pip 镜像加速（后续安装 Python 依赖用） pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ pip config set install.trusted-host mirrors.aliyun.com
2. 执行官方一键安装脚本（外网源）： curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
3. 如果国内访问较慢、出现超时报错，替换为国内镜像脚本： curl -fsSL https://mirror.ghproxy.com/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
4. 执行脚本后，会提示“是否安装 ripgrep 和 ffmpeg”，输入 y 并回车（ripgrep 提升文件搜索速度，ffmpeg 支持音频功能）；
5. 安装过程约5~10分钟（取决于网络速度和电脑配置），脚本会自动完成依赖安装、源码克隆和环境配置；
6. 安装完成后，重新加载 Shell 配置，确保 hermes 命令全局可用： # bash 用户执行 source ~/.bashrc # zsh 用户执行（macOS 默认，Ubuntu 可选） source ~/.zshrc

如果一键脚本安装失败，可通过离线包手动安装，步骤如下（全程在 Ubuntu 终端执行）：

1. 准备 Hermes-Agent 离线安装包（需自行下载，示例版本：hermes-agent-2026.4.8.zip），将安装包放入 Ubuntu 子系统的 /mnt/d/Downloads 目录（对应 Windows 的 D 盘 Downloads 文件夹）；
2. 进入安装包所在目录，安装解压工具： cd /mnt/d/Downloads sudo apt update && sudo apt install -y unzip
3. 解压安装包，进入解压后的文件夹： unzip hermes-agent-2026.4.8.zip cd hermes-agent-2026.4.8
4. 创建并激活 Python 虚拟环境（避免污染系统 Python 环境，防止权限报错）： python3 -m venv hermes source hermes/bin/activate激活成功后，终端会显示 (hermes) 前缀。
5. 用国内源安装 Python 依赖，避免卡顿： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
6. 安装 Hermes-Agent 并配置全局命令： pip install . sudo ln -s ~/hermes/bin/hermes /usr/local/bin/hermes

安装完成后，必须验证是否成功，避免后续无法启动或使用：

1. 在 Ubuntu 终端中输入以下命令，查看 Hermes-Agent 版本： hermes --version
2. 如果输出版本号（如 v0.8.0 (v2026.4.8)），说明安装成功；
3. 启动 Hermes-Agent 测试： hermes start
4. 启动成功后，打开 Windows 浏览器，输入以下地址，即可访问 Hermes-Agent WebUI： http://localhost:8000

首次启动 Hermes-Agent 后，需要进行初始化配置，绑定模型、设置网关等，步骤如下（支持交互式向导，新手友好）：

1. 执行初始化配置命令，启动交互式向导： hermes setup
2. 按终端提示逐步操作：
   1. 第一步：选择配置模式，新手选择 quick setup（快速配置），按回车确认；
   2. 第二步：选择模型提供商，推荐新手选择DeepSeek 或 豆包（国内可用，有免费额度），输入对应序号；
   3. 第三步：输入模型 API Key（需提前在对应模型开放平台注册获取），粘贴后按回车；
   4. 第四步：配置网关（可选），如需接入微信、钉钉等平台，按空格勾选对应平台，按回车确认；
   5. 第五步：设置默认工具（可选），新手直接按回车默认即可，后续可在 WebUI 中修改。
3. 当终端提示 “Setup completed successfully” 时，初始化配置完成，重启 Hermes-Agent 生效： hermes restart

📌 提示：API Key 报错时，需检查 Key 是否正确、是否过期，或在配置文件中重新修改（配置文件路径：~/.hermes/config.yaml）。

Ubuntu 20.04/22.04 是 Hermes-Agent 最兼容的系统，安装难度最低，无需额外配置虚拟化，支持一键脚本、手动安装两种方式，步骤如下：

先更新系统包管理器，安装基础依赖，关闭临时防火墙（测试用，生产环境需配置防火墙规则）：

# 更新系统包列表 sudo apt update -y && sudo apt upgrade -y # 安装基础依赖（curl、git 等） sudo apt install -y curl git wget # 临时关闭防火墙（测试用，避免拦截端口） sudo ufw disable

一键脚本自动安装所有依赖、克隆源码、配置环境，步骤如下：

（可选，国内用户必做）配置网络镜像，提升下载速度：

# Git 镜像加速 git config --global url."https://mirror.ghproxy.com/https://github.com".insteadOf "https://github.com" # pip 镜像加速 pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ pip config set install.trusted-host mirrors.aliyun.com # npm 镜像加速（用于安装 Node.js 依赖） npm config set registry https://mirrors.cloud.tencent.com/npm/ --global

执行官方一键安装脚本：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

国内访问慢，替换为国内镜像脚本：

curl -fsSL https://mirror.ghproxy.com/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

1. 按提示输入 y，安装 ripgrep 和 ffmpeg，等待安装完成（约5~8分钟）；
2. 重新加载 Shell 配置，确保 hermes 命令全局可用：source ~/.bashrc
3. 验证安装： hermes --version输出版本号即成功。

克隆 Hermes-Agent 源码：

 mkdir -p ~/hermes-agent && cd ~/hermes-agent git clone https://github.com/NousResearch/hermes-agent.git .国内克隆慢，替换为国内镜像：git clone https://mirror.ghproxy.com/https://github.com/NousResearch/hermes-agent.git

安装 Python 虚拟环境，避免权限报错：

sudo apt install -y python3-venv python3 -m venv hermes-venv source hermes-venv/bin/activate

安装 Python 依赖：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

安装 Node.js 依赖（用于 WebUI）：

 cd webui npm install

安装 Hermes-Agent 并配置全局命令：

 cd .. pip install . sudo ln -s ~/hermes-agent/hermes-venv/bin/hermes /usr/local/bin/hermes

1. 启动 Hermes-Agent 服务： hermes start
2. 启动成功的标志：终端提示 “Hermes Agent started successfully on port 8000”；
3. 访问 WebUI：打开浏览器，输入 http://localhost:8000（远程服务器输入 http://服务器IP:8000）；
4. 初始化配置：参考“3.6 初始化配置”步骤，完成模型绑定和网关设置，即可正常使用。

为避免重启系统后重新启动服务，可配置开机自启，步骤如下：

# 创建系统服务文件 sudo nano /etc/systemd/system/hermes-agent.service

粘贴以下内容（替换路径为自己的 Hermes-Agent 安装路径）：

[Unit] Description=Hermes-Agent Service After=network.target [Service] User=root WorkingDirectory=/root/hermes-agent ExecStart=/root/hermes-agent/hermes-venv/bin/hermes start Restart=always [Install] WantedBy=multi-user.target

保存退出（Ctrl+O → 回车 → Ctrl+X），执行以下命令启用开机自启：

sudo systemctl daemon-reload sudo systemctl enable hermes-agent sudo systemctl start hermes-agent

macOS 12+ 支持一键脚本、brew 安装两种方式，步骤简单，稳定性高，无需额外配置虚拟化，以下是详细步骤：

如果未安装 brew（macOS 包管理器），先安装 brew（可选，brew 安装依赖更方便）：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，验证 brew：brew -v，输出版本号即成功。

1. （可选，国内用户必做）配置网络镜像： # Git 镜像加速 git config --global url."https://mirror.ghproxy.com/https://github.com".insteadOf "https://github.com" # pip 镜像加速 pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ pip config set install.trusted-host mirrors.aliyun.com
2. 执行一键安装脚本：curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
3. 国内访问慢，替换为国内镜像脚本：curl -fsSL https://mirror.ghproxy.com/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
4. 按提示输入 y，安装 ripgrep 和 ffmpeg，等待安装完成（约5~8分钟）；
5. 重新加载 Shell 配置： source ~/.zshrc
6. 验证安装： hermes --version输出版本号即成功。

1. 用 brew 安装 Python 3.11 和 Node.js 22： brew install python@3.11 node@22
2. 克隆 Hermes-Agent 源码： mkdir -p ~/hermes-agent && cd ~/hermes-agent git clone https://github.com/NousResearch/hermes-agent.git .
3. 创建并激活 Python 虚拟环境： python3 -m venv hermes-venv source hermes-venv/bin/activate
4. 安装依赖并部署： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple cd webui && npm install && cd .. pip install .

# 启动 Hermes-Agent 服务 hermes start # 初始化配置（绑定模型、网关） hermes setup

启动成功后，浏览器打开 http://localhost:8000，即可访问 WebUI 进行后续操作。

⚠️ 注意：macOS 终端可能会提示“无法打开 hermes，因为它来自身份不明的开发者”，解决方案：系统设置 → 隐私与安全性 → 允许“hermes”运行。

适合需要修改源码、自定义功能、开发插件的开发者，步骤如下（全系统通用，以 Ubuntu 为例）：

1. 克隆 Hermes-Agent 源码： git clone https://github.com/NousResearch/hermes-agent.git cd hermes-agent国内克隆慢，替换为国内镜像：git clone https://mirror.ghproxy.com/https://github.com/NousResearch/hermes-agent.git .
2. 安装 Python 虚拟环境和依赖： python3 -m venv hermes-venv source hermes-venv/bin/activate pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple pip install -r requirements-dev.txt # 开发依赖，用于编译和测试
3. 安装 Node.js 依赖（用于 WebUI 编译）： cd webui npm install npm run build # 编译 WebUI 静态文件 cd ..
4. 编译 Hermes-Agent 源码： python setup.py sdist bdist_wheel
5. 安装编译后的包： pip install dist/*.whl
6. 验证编译安装： hermes --version
7. 启动服务并测试自定义功能： hermes start

📌 提示：修改源码后，需重新执行 python setup.py sdist bdist_wheel 和 pip install dist/*.whl，再重启服务生效。

整理了最常用的 Hermes-Agent 命令，涵盖启动、停止、配置、查看状态等，复制即可使用，适配所有系统：

整理了新手安装 Hermes-Agent 时最常见的问题，附详细解决方案，解决“脚本卡死、环境报错、模型失败、网关连接异常”等核心问题：

原因：官方脚本需连接国外 GitHub，国内网络无代理，无法下载资源，导致脚本卡死。

解决方案：

1. 放弃官方脚本，采用离线包手动安装（参考对应系统的手动安装步骤）；
2. 或配置 Git 镜像加速（参考各系统的镜像配置步骤），重新执行一键脚本；
3. 如果仍卡死，更换网络（如手机热点），重新执行脚本。

原因：Ubuntu/macOS 系统禁止直接在系统 Python 环境安装第三方包，未创建虚拟环境导致权限报错。

解决方案：

1. 创建并激活 Python 虚拟环境： python3 -m venv hermes source hermes/bin/activate
2. 激活虚拟环境后（终端显示 (hermes) 前缀），重新安装依赖： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

原因：模型 API Key 过期、错误，或配置文件中模型参数不正确，无法连接模型接口。

解决方案：

1. 获取有效 API Key：去对应模型开放平台（DeepSeek、豆包、通义千问）注册，创建并复制 API Key；
2. 编辑 Hermes 配置文件： nano ~/.hermes/config.yaml
3. 粘贴自定义模型配置（以 DeepSeek+豆包为例），替换自己的 API Key： custom_providers: - name: deepseek base_url: https://api.deepseek.com/v1 api_key: 你的DeepSeek API Key model: deepseek-chat - name: doubao base_url: https://ark.cn-beijing.volces.com/api/v3 api_key: 你的豆包API Key model: doubao-1-5-pro-32k-character- default_provider: deepseek
4. 保存退出（Ctrl+O → 回车 → Ctrl+X），重启 Hermes-Agent：hermes restart。

原因：服务未启动成功、端口被占用、防火墙拦截，或 WSL2 端口未映射。

解决方案：

1. 查看服务状态：hermes status，确认服务为“running”，未启动则执行 hermes start；
2. 检查端口是否被占用（以8000端口为例）： # Linux/macOS/WSL2 lsof -i:8000 # 结束占用进程（替换进程ID） kill -9 进程ID
3. Windows（WSL2）用户：检查 WSL2 端口映射，执行以下命令映射8000端口： netsh interface portproxy add v4tov4 listenport=8000 listenaddress=0.0.0.0 connectport=8000 connectaddress=$(wsl hostname -I)
4. 关闭防火墙（临时测试），重新访问 WebUI。

原因：macOS 安全机制限制，未允许未知开发者的程序运行。

解决方案：

1. 打开“系统设置” → 点击“隐私与安全性”；
2. 下拉到“安全性”部分，找到“无法打开 hermes，因为它来自身份不明的开发者”，点击右侧的“允许”；
3. 重新在终端执行 hermes –version，即可正常运行。

原因：缺少微信依赖，或电脑微信版本过高（高版本会被风控，无法挂钩 Hermes-Agent）。

解决方案：

1. 安装微信依赖： pip install wcferry qrcode
2. 配置微信网关（编辑 config.yaml），添加以下内容： gateway: enabled: true providers: - type: wechat name: wechat enable: true mode: wcferry
3. 安装电脑微信3.9.8.15版本（必须这个版本），登录后重启网关：hermes gateway，扫码即可连接。