‍♂️ 个人主页小李同学_LSH的主页✍ 作者简介LLM学习者 希望大家多多支持我们一起进步如果文章对你有帮助的话欢迎评论 点赞 收藏 加关注目录一、前言二、系统要求详解必看避免踩坑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 启动服务与访问 WebUI4.5 配置开机自启可选生产环境推荐五、macOS 系统安装适合苹果用户操作简单5.1 前置准备5.2 一键安装推荐新手首选5.3 brew 安装可选已装 brew 用户5.4 启动服务与初始化配置六、源码编译安装开发者/自定义配置七、Hermes-Agent 常用命令必记方便管理八、常见问题与解决方案新手必看避坑指南8.1 问题1一键脚本卡死光标闪烁不加载8.2 问题2Python 环境报错“externally-managed-environment”8.3 问题3启动后报错“AuthenticationError (HTTP 401)”8.4 问题4WebUI 无法访问提示“无法连接到服务器”8.5 问题5macOS 提示“无法打开 hermes因为它来自身份不明的开发者”8.6 问题6微信网关无法登录无二维码或扫码无响应 适合AI Agent 学习者、开发者、个人办公效率提升、轻量自动化场景 系统Windows10/11需WSL2、Ubuntu20.04/22.04、macOS12 内容系统配置对比、软件依赖说明、一键脚本安装、手动安装、源码编译、初始化配置、常用命令、常见报错解决方案附实操提示 难度新手友好一键脚本→ 进阶手动安装→ 自定义源码编译一、前言Hermes-Agent 是由 Nous Research 打造的开源自主 AI Agent主打“越用越聪明”的自我进化特性内置闭环学习系统和四层记忆架构支持 40 内置工具可接入 Telegram、Discord、微信、钉钉等多平台网关实现跨场景自动化交互、工具调用和任务执行。与其他 AI Agent 不同Hermes-Agent 无需复杂的框架依赖支持一行命令快速部署同时兼顾开发者自定义需求可通过修改源码扩展功能、切换模型提供商。本文针对不同系统提供完整的安装流程补充详细的表格对比、分步命令注释和新手避坑指南全程可复制粘贴解决国内用户“网络卡顿、环境报错、模型配置失败”等核心问题确保零基础也能顺利完成部署。二、系统要求详解必看避免踩坑Hermes-Agent 分为社区版免费适合个人/小型团队不支持原生 Windows 系统Windows 用户需先安装 WSL2Windows 子系统以下是详细的硬件和软件要求含最低/推荐配置对比配置类型CPU内存磁盘网络最低配置2核Intel i5/AMD Ryzen 5 及以上4GB可用内存≥2GB10GBSSD优先用于存储依赖、模型缓存和配置文件能访问外网下载依赖、拉取源码国内用户建议配置镜像开放8000、8080端口推荐配置4核及以上8GB本地运行模型需16GB20GB SSD稳定外网可配置代理或镜像优化访问速度开放相关端口见下文开发配置8核及以上16GB30GB SSD稳定外网可访问 GitHub、PyPI、npm 等资源库2.1 软件依赖要求全系统通用Hermes-Agent 依赖 Python、Node.js 等基础环境一键脚本会自动安装大部分依赖手动安装需提前准备以下软件避免出现“依赖缺失”“版本不兼容”报错依赖软件版本要求作用安装提示Python3.10推荐3.11Hermes-Agent 核心运行环境处理工具调用、模型交互和任务执行一键脚本自动安装手动安装需避免使用系统自带Python易权限报错Node.jsv22支持 WebUI 界面运行、前端交互和部分工具插件一键脚本自动安装无需手动配置环境变量Git2.30克隆 Hermes-Agent 源码、拉取配置文件源码编译/手动部署需用WindowsWSL2/Linux/macOS 可通过包管理器或官网安装curl/wget无明确版本要求能正常使用即可下载安装脚本、依赖包和镜像资源Linux/macOS/WSL2 默认自带无需额外安装uvPython包管理器最新版高效安装 Python 依赖替代传统 pip提升安装速度一键脚本自动安装手动安装需单独执行命令ffmpeg可选无明确版本要求支持 TTS 语音消息、音频处理相关功能安装过程中脚本会提示是否安装按需选择即可2.2 端口要求必开放否则无法访问Hermes-Agent 运行需要开放以下端口避免防火墙拦截导致 WebUI 无法访问、网关连接失败或模型交互异常端口号用途是否必须开放备注8000Hermes-Agent WebUI 访问端口默认是新手默认使用可通过配置文件自定义修改8080网关通信端口用于多平台微信、钉钉等连接是需接入外部平台时未接入外部平台时可无需开放5000模型 API 通信端口自定义模型时使用否默认使用官方模型接口无需开放本地部署模型时需开放此端口供 Hermes-Agent 调用2.3 不同系统兼容性对比Hermes-Agent 不支持原生 Windows 系统Windows 用户需通过 WSL2 模拟 Linux 环境部署不同系统的安装难度、稳定性略有差异新手可优先选择推荐系统系统安装难度稳定性推荐安装方式注意事项Windows10/11WSL2中中一键脚本安装WSL2 内执行必须先启用 WSL2 并安装 Ubuntu 子系统否则无法部署国内网络需配置镜像Ubuntu20.04/22.04低高一键脚本安装推荐、Docker 部署系统兼容性最佳包管理器可直接安装基础依赖适合新手和开发环境macOS12低高一键脚本安装、brew 安装需开启终端权限内存建议8GB避免运行卡顿M1/M2芯片兼容良好三、Windows 系统安装WSL2 环境新手详细分步Hermes-Agent 不支持原生 Windows 系统必须通过 WSL2Windows 子系统模拟 Linux 环境部署步骤分为“启用 WSL2 → 安装 Ubuntu 子系统 → 部署 Hermes-Agent”以 Windows11 为例Windows10 操作一致3.1 前置准备启用 WSL2必须按下WinR输入powershell右键选择“以管理员身份运行”必须管理员权限否则无法启用 WSL2输入以下命令启用 WSL2 和虚拟机平台功能Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux -All -NoRestartEnable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -All -NoRestart命令执行完成后重启电脑必须重启否则功能不生效重启后打开 Microsoft Store搜索“Ubuntu”选择“Ubuntu 22.04 LTS”安装免费安装完成后启动 Ubuntu 子系统等待初始化完成设置用户名和密码记住密码后续执行 sudo 命令需用到验证 WSL2 是否启用在 Ubuntu 终端中输入wsl --status提示“默认分发版Ubuntu”即成功。3.2 前置准备更新 Ubuntu 子系统启动 Ubuntu 子系统后先更新系统包管理器安装基础依赖避免后续安装报错# 更新系统包列表 sudo apt update -y sudo apt upgrade -y # 安装基础依赖curl、git 等部分可能已默认安装 sudo apt install -y curl git3.3 一键部署 Hermes-Agent推荐新手首选Hermes-Agent 提供官方一键部署脚本可自动安装 Python、Node.js、uv 等依赖克隆源码并配置环境步骤如下全程在 Ubuntu 终端执行可选国内用户必做配置网络镜像解决 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执行官方一键安装脚本外网源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执行脚本后会提示“是否安装 ripgrep 和 ffmpeg”输入y并回车ripgrep 提升文件搜索速度ffmpeg 支持音频功能安装过程约5~10分钟取决于网络速度和电脑配置脚本会自动完成依赖安装、源码克隆和环境配置安装完成后重新加载 Shell 配置确保 hermes 命令全局可用# bash 用户执行source ~/.bashrc# zsh 用户执行macOS 默认Ubuntu 可选source ~/.zshrc3.4 手动安装适合网络受限、无法使用一键脚本的用户如果一键脚本安装失败可通过离线包手动安装步骤如下全程在 Ubuntu 终端执行准备 Hermes-Agent 离线安装包需自行下载示例版本hermes-agent-2026.4.8.zip将安装包放入 Ubuntu 子系统的 /mnt/d/Downloads 目录对应 Windows 的 D 盘 Downloads 文件夹进入安装包所在目录安装解压工具cd /mnt/d/Downloadssudo apt update sudo apt install -y unzip解压安装包进入解压后的文件夹unzip hermes-agent-2026.4.8.zipcd hermes-agent-2026.4.8创建并激活 Python 虚拟环境避免污染系统 Python 环境防止权限报错python3 -m venv hermessource hermes/bin/activate激活成功后终端会显示 (hermes) 前缀。用国内源安装 Python 依赖避免卡顿pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple安装 Hermes-Agent 并配置全局命令pip install .sudo ln -s ~/hermes/bin/hermes /usr/local/bin/hermes3.5 安装验证必做确认安装成功安装完成后必须验证是否成功避免后续无法启动或使用在 Ubuntu 终端中输入以下命令查看 Hermes-Agent 版本hermes --version如果输出版本号如 v0.8.0 (v2026.4.8)说明安装成功启动 Hermes-Agent 测试hermes start启动成功后打开 Windows 浏览器输入以下地址即可访问 Hermes-Agent WebUIhttp://localhost:80003.6 初始化配置关键步骤必做首次启动 Hermes-Agent 后需要进行初始化配置绑定模型、设置网关等步骤如下支持交互式向导新手友好执行初始化配置命令启动交互式向导hermes setup按终端提示逐步操作第一步选择配置模式新手选择quick setup快速配置按回车确认第二步选择模型提供商推荐新手选择DeepSeek或豆包国内可用有免费额度输入对应序号第三步输入模型 API Key需提前在对应模型开放平台注册获取粘贴后按回车第四步配置网关可选如需接入微信、钉钉等平台按空格勾选对应平台按回车确认第五步设置默认工具可选新手直接按回车默认即可后续可在 WebUI 中修改。当终端提示“Setup completed successfully”时初始化配置完成重启 Hermes-Agent 生效hermes restart 提示API Key 报错时需检查 Key 是否正确、是否过期或在配置文件中重新修改配置文件路径~/.hermes/config.yaml。四、Ubuntu 系统安装稳定性最佳推荐新手/开发环境Ubuntu 20.04/22.04 是 Hermes-Agent 最兼容的系统安装难度最低无需额外配置虚拟化支持一键脚本、手动安装两种方式步骤如下4.1 系统前置准备先更新系统包管理器安装基础依赖关闭临时防火墙测试用生产环境需配置防火墙规则# 更新系统包列表 sudo apt update -y sudo apt upgrade -y # 安装基础依赖curl、git 等 sudo apt install -y curl git wget # 临时关闭防火墙测试用避免拦截端口 sudo ufw disable4.2 一键安装推荐新手首选一键脚本自动安装所有依赖、克隆源码、配置环境步骤如下可选国内用户必做配置网络镜像提升下载速度# 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按提示输入y安装 ripgrep 和 ffmpeg等待安装完成约5~8分钟重新加载 Shell 配置确保 hermes 命令全局可用source ~/.bashrc验证安装hermes --version输出版本号即成功。4.3 手动安装适合网络受限、自定义配置的用户克隆 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 依赖用于 WebUIcd webui npm install安装 Hermes-Agent 并配置全局命令cd .. pip install . sudo ln -s ~/hermes-agent/hermes-venv/bin/hermes /usr/local/bin/hermes4.4 启动服务与访问 WebUI启动 Hermes-Agent 服务hermes start启动成功的标志终端提示“Hermes Agent started successfully on port 8000”访问 WebUI打开浏览器输入http://localhost:8000远程服务器输入http://服务器IP:8000初始化配置参考“3.6 初始化配置”步骤完成模型绑定和网关设置即可正常使用。4.5 配置开机自启可选生产环境推荐为避免重启系统后重新启动服务可配置开机自启步骤如下# 创建系统服务文件 sudo nano /etc/systemd/system/hermes-agent.service粘贴以下内容替换路径为自己的 Hermes-Agent 安装路径[Unit] DescriptionHermes-Agent Service Afternetwork.target [Service] Userroot WorkingDirectory/root/hermes-agent ExecStart/root/hermes-agent/hermes-venv/bin/hermes start Restartalways [Install] WantedBymulti-user.target保存退出CtrlO → 回车 → CtrlX执行以下命令启用开机自启sudo systemctl daemon-reload sudo systemctl enable hermes-agent sudo systemctl start hermes-agent五、macOS 系统安装适合苹果用户操作简单macOS 12 支持一键脚本、brew 安装两种方式步骤简单稳定性高无需额外配置虚拟化以下是详细步骤5.1 前置准备如果未安装 brewmacOS 包管理器先安装 brew可选brew 安装依赖更方便/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)安装完成后验证 brewbrew -v输出版本号即成功。5.2 一键安装推荐新手首选可选国内用户必做配置网络镜像# 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执行一键安装脚本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按提示输入y安装 ripgrep 和 ffmpeg等待安装完成约5~8分钟重新加载 Shell 配置source ~/.zshrc验证安装hermes --version输出版本号即成功。5.3 brew 安装可选已装 brew 用户用 brew 安装 Python 3.11 和 Node.js 22brew install python3.11 node22克隆 Hermes-Agent 源码mkdir -p ~/hermes-agent cd ~/hermes-agentgit clone https://github.com/NousResearch/hermes-agent.git .创建并激活 Python 虚拟环境python3 -m venv hermes-venvsource hermes-venv/bin/activate安装依赖并部署pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simplecd webui npm install cd ..pip install .5.4 启动服务与初始化配置# 启动 Hermes-Agent 服务 hermes start # 初始化配置绑定模型、网关 hermes setup启动成功后浏览器打开http://localhost:8000即可访问 WebUI 进行后续操作。⚠️ 注意macOS 终端可能会提示“无法打开 hermes因为它来自身份不明的开发者”解决方案系统设置 → 隐私与安全性 → 允许“hermes”运行。六、源码编译安装开发者/自定义配置适合需要修改源码、自定义功能、开发插件的开发者步骤如下全系统通用以 Ubuntu 为例克隆 Hermes-Agent 源码git clone https://github.com/NousResearch/hermes-agent.gitcd hermes-agent国内克隆慢替换为国内镜像git clone https://mirror.ghproxy.com/https://github.com/NousResearch/hermes-agent.git .安装 Python 虚拟环境和依赖python3 -m venv hermes-venvsource hermes-venv/bin/activatepip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simplepip install -r requirements-dev.txt # 开发依赖用于编译和测试安装 Node.js 依赖用于 WebUI 编译cd webuinpm installnpm run build # 编译 WebUI 静态文件cd ..编译 Hermes-Agent 源码python setup.py sdist bdist_wheel安装编译后的包pip install dist/*.whl验证编译安装hermes --version启动服务并测试自定义功能hermes start 提示修改源码后需重新执行python setup.py sdist bdist_wheel和pip install dist/*.whl再重启服务生效。七、Hermes-Agent 常用命令必记方便管理整理了最常用的 Hermes-Agent 命令涵盖启动、停止、配置、查看状态等复制即可使用适配所有系统命令作用备注hermes --version查看 Hermes-Agent 版本验证安装是否成功hermes start启动 Hermes-Agent 服务启动后 WebUI 可正常访问hermes stop停止 Hermes-Agent 服务停止后无法访问 WebUI 和网关hermes restart重启 Hermes-Agent 服务修改配置、源码后需重启生效hermes status查看服务运行状态显示“running”为正常运行hermes setup重新初始化配置可重新绑定模型、配置网关hermes model单独配置模型提供商和 API Key无需重新执行完整初始化hermes gateway启动网关连接微信、钉钉等平台需提前在配置中勾选对应平台hermes logs查看服务运行日志排查启动失败、模型报错、网关连接异常等问题hermes update更新 Hermes-Agent 到最新版本更新后需重启服务生效hermes uninstall卸载 Hermes-Agent卸载后需手动删除配置文件路径~/.hermes八、常见问题与解决方案新手必看避坑指南整理了新手安装 Hermes-Agent 时最常见的问题附详细解决方案解决“脚本卡死、环境报错、模型失败、网关连接异常”等核心问题8.1 问题1一键脚本卡死光标闪烁不加载原因官方脚本需连接国外 GitHub国内网络无代理无法下载资源导致脚本卡死。解决方案放弃官方脚本采用离线包手动安装参考对应系统的手动安装步骤或配置 Git 镜像加速参考各系统的镜像配置步骤重新执行一键脚本如果仍卡死更换网络如手机热点重新执行脚本。8.2 问题2Python 环境报错“externally-managed-environment”原因Ubuntu/macOS 系统禁止直接在系统 Python 环境安装第三方包未创建虚拟环境导致权限报错。解决方案创建并激活 Python 虚拟环境python3 -m venv hermessource hermes/bin/activate激活虚拟环境后终端显示 (hermes) 前缀重新安装依赖pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple8.3 问题3启动后报错“AuthenticationError (HTTP 401)”原因模型 API Key 过期、错误或配置文件中模型参数不正确无法连接模型接口。解决方案获取有效 API Key去对应模型开放平台DeepSeek、豆包、通义千问注册创建并复制 API Key编辑 Hermes 配置文件nano ~/.hermes/config.yaml粘贴自定义模型配置以 DeepSeek豆包为例替换自己的 API Keycustom_providers:- name: deepseekbase_url: https://api.deepseek.com/v1api_key: 你的DeepSeek API Keymodel: deepseek-chat- name: doubaobase_url: https://ark.cn-beijing.volces.com/api/v3api_key: 你的豆包API Keymodel: doubao-1-5-pro-32k-character-250715default_provider: deepseek保存退出CtrlO → 回车 → CtrlX重启 Hermes-Agenthermes restart。8.4 问题4WebUI 无法访问提示“无法连接到服务器”原因服务未启动成功、端口被占用、防火墙拦截或 WSL2 端口未映射。解决方案查看服务状态hermes status确认服务为“running”未启动则执行hermes start检查端口是否被占用以8000端口为例# Linux/macOS/WSL2lsof -i:8000# 结束占用进程替换进程IDkill -9 进程IDWindowsWSL2用户检查 WSL2 端口映射执行以下命令映射8000端口netsh interface portproxy add v4tov4 listenport8000 listenaddress0.0.0.0 connectport8000 connectaddress$(wsl hostname -I)关闭防火墙临时测试重新访问 WebUI。8.5 问题5macOS 提示“无法打开 hermes因为它来自身份不明的开发者”原因macOS 安全机制限制未允许未知开发者的程序运行。解决方案打开“系统设置” → 点击“隐私与安全性”下拉到“安全性”部分找到“无法打开 hermes因为它来自身份不明的开发者”点击右侧的“允许”重新在终端执行hermes --version即可正常运行。8.6 问题6微信网关无法登录无二维码或扫码无响应原因缺少微信依赖或电脑微信版本过高高版本会被风控无法挂钩 Hermes-Agent。解决方案安装微信依赖pip install wcferry qrcode配置微信网关编辑 config.yaml添加以下内容gateway:enabled: trueproviders:- type: wechatname: wechatenable: truemode: wcferry安装电脑微信3.9.8.15版本必须这个版本登录后重启网关hermes gateway扫码即可连接。