亲测有效！本地部署 Hermes Agent 完整记录，从此拥有 24 小时在线的 AI 员工

关于HermesAgent是什么？可以看《关于爱马仕Hermes Agent是什么？》；

关于WSL2和Ubuntu的安装，可以看《WSL2和Ubuntu安装记录》；

关于Ubuntu的迁移，可以看《Ubuntu迁移记录》；

接下来接着Ubuntu迁移记录接着往下记录安装HermesAgent的过程。

01 第一次安装

首先进入WSL2的Ubuntu的终端，在Ubuntu终端中粘贴并运行下面的指令代码：

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

1.1 指令功能

作用是从 GitHub 拉取官方安装脚本，并直接在本地 bash 中执行，完成 Hermes Agent 及其运行依赖的全自动安装。

执行截图如下：

1.2、安装日志解析

1. 系统与基础工具安装
   ✅ 系统识别：检测到当前系统为 linux (ubuntu)，x86_64 架构。
   ✅ uv 安装：将 Python 包管理工具 uv 安装到 ~/.hermes/bin 目录，成功安装 uv 0.11.26。
   uv 是高性能 Python 包 / 环境管理工具，用来替代传统 pip，大幅提升 Python 依赖安装速度。

2. Python 环境安装

• 检测系统 Python 3.11，发现不存在，自动通过 uv 下载安装。

• ✅ 成功安装 Python 3.11.15，耗时 12.62 秒。

• ⚠️ PATH 警告（重要）

warning: '/home/leigong/.local/bin' is not on your PATH.

含义：刚安装的 Python 可执行文件所在目录，没有加入系统环境变量 PATH。后果：直接输入 python3.11 会提示 “命令不存在”。

1. 配套依赖检测
   ✅ Git：已找到 Git 2.34.1，满足要求。
   ✅ Node.js：系统原本没有，自动安装 Node.js 22 LTS（v22.23.1）到 ~/.hermes/node/ 目录，用于支持浏览器相关工具能力。

2. 网络连通性检查（关键警告）
   ⚠️ 核心问题

Could not reach https:/IP省略/.com/Network checks failed.

含义：脚本无法访问 DuckDuckGo 搜索引擎，网络连通性校验未通过。影响：安装流程本身可能还能继续走完；但后续 pip 依赖下载、网页搜索功能 大概率会失败。这是国内环境最常见的问题：GitHub、DuckDuckGo 等境外站点访问受限。

脚本给出的官方提示：如果后续 pip 安装失败，请检查网络 / DNS 后重试。

1. 可选系统依赖
   正在检查两个可选工具：
   ripgrep：快速全文文件搜索，提升 Agent 文件检索速度；
   ffmpeg：用于 TTS 语音消息功能。
   提示：这两个包需要 sudo 权限通过系统包管理器安装，Hermes Agent 本体不需要 root 权限。

1.3、操作建议

根据上面指令的执行情况，根据AI建议先 Ctrl+C 中断安装，配置好终端代理（能访问 GitHub、境外源）后再重新执行安装命令，否则后续 Python 依赖拉取大概率会报错失败。

于是先按Ctrl+C 中断安装：

02 前置环境优化

前面的一键安装失败的情况下，又搜索了几个安装教程，结合AI问答，进行了下面的操作，下面是操作过程记录。

2.1、替换系统apt源

# 备份原源文件sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak# 替换为清华镜像源sudo sed -i ”s@http://.*archive.ubuntu.com@https://mirrors.tuna.tsinghua.edu.cn@g” /etc/apt/sources.listsudo sed -i ”s@http://.*security.ubuntu.com@https://mirrors.tuna.tsinghua.edu.cn@g” /etc/apt/sources.list# 更新源缓存sudo apt update

执行截图如下：截图1：

截图2：

2.2、配置uv国内PyPI源

Hermes 使用 uv 作为 Python 包管理器，提前配置清华镜像源，避免依赖下载超时：​​​​​​​

# 创建 uv 配置目录mkdir -p ~/.config/uv# 写入镜像源配置cat > ~/.config/uv/uv.toml << EOF[pypi]index-url = ”https://pypi.tuna.tsinghua.edu.cn/simple”EOF

执行截图如下：

03 再次尝试安装

执行完上面的前置环境优化步骤，再次尝试一键安装指令：执行截图如下：截图1：

截图2：

3.1、成功部分解析

截图前半段是 Ubuntu 系统通过 apt 安装可选依赖的输出，整体全部成功：

1. 系统自动安装了ripgrep、ffmpeg以及它们依赖的大量系统库（音视频编解码、图形渲染、文本处理等底层组件）；

2. 最终明确标记：

• ✅ ripgrep installed（快速文件搜索工具安装完成）

• ✅ ffmpeg installed（音视频处理 / 语音播报依赖安装完成）

安装流程随后进入下一步：将 Hermes Agent 源码仓库克隆到本地 ~/.hermes/hermes-agent/ 目录。

• 脚本优先尝试 SSH 协议克隆（失败，属于正常现象：你本地没有配置 GitHub SSH 密钥）；

• 自动回退到 HTTPS 协议克隆，此时出现致命错误。

3.2、仓库克隆失败

Git 发起 HTTPS 连接时，SSL/TLS 加密握手失败（底层使用 gnutls 加密库），最终无法拉取 GitHub 上的代码仓库，整个安装流程在此中断。

国内环境的核心原因

和上一步出现的 DuckDuckGo 连通性失败是同一类问题：

1. GitHub 境外服务器访问受限，网络连接被干扰 / 中断，导致加密握手无法完成；

2. 如果你本地有代理但没有给 Git 配置，Git 仍然走直连，就会触发这个报错；

3. 极少数情况是系统 CA 证书过期、Git 版本过低导致的兼容问题。

3.3、使用 GitHub 镜像手动克隆

通过国内镜像站提前把仓库克隆到指定路径，脚本检测到仓库已存在会自动跳过克隆步骤。

测试也不成功！

04 再再次安装

前面折腾了半天都不行，又找了个视频教程，跟着操作，这次使用的是一个中国大陆镜像；

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

指令执行截图：截图1：

截图2：

4.1、核心问题解析

Hermes Agent 安装流程的第 2 步（Python 运行环境准备），安装中断的根本原因是 uv 配置文件格式错误，导致 uv 工具无法正常启动，进而 Python 3.11 安装失败。

1. 已完成的进度

• ✅ 系统检测：未找到系统自带的 Python 3.11

• ✅ uv 包管理器安装成功：版本 0.11.14，安装路径 ~/.local/bin

• ✅ 安装脚本已适配国内镜像下载 uv（域名 res1.hermesagent.org.cn）

2. 报错详情与原因

错误核心信息：​​​​​​​

error: Failed to parse: `.config/uv/uv.toml`Caused by: TOML parse error at line 1, column 2unknown field `pypi`

• 含义：uv 读取全局配置文件 ~/.config/uv/uv.toml 时解析失败。

• 后果：uv 工具启动异常，无法继续安装 Python 3.11，整个安装流程终止。

4.2、修复方案

执行以下命令，删除错误配置，写入符合 uv 规范的清华镜像配置：​​​​​​​

# 删除错误的旧配置文件rm -f ~/.config/uv/uv.toml# 创建配置目录并写入正确的镜像配置（index-url 是顶层参数，不需要 [pypi] 包裹）mkdir -p ~/.config/uvcat > ~/.config/uv/uv.toml << EOFindex-url = ”https://pypi.tuna.tsinghua.edu.cn/simple”EOF# 验证uv是否恢复正常，输出版本号即修复成功uv --version

结果没有输出版本号，报错 uv: command not found，接着找原因。。。

4.3、问题原因

报错 uv: command not found 和刚才修改的配置文件无关，核心原因是环境变量 PATH 未生效。

从之前的安装日志可以看到：uv 被成功安装到了 ~/.local/bin 目录，但这个目录没有被加入当前终端的系统路径 PATH 中，所以系统找不到 uv 命令。

修改配置文件的操作本身是正确的，只是 uv 命令本身还没被系统识别到。

1. 先确认 uv 文件已安装

执行以下命令，确认 uv 可执行文件本身存在：

ls ~/.local/bin/uv

如果能正常输出文件路径，说明安装包完好，只是路径问题。

2. 临时生效（当前终端立即可用）

执行安装脚本提示的环境加载命令：

source ~/.local/bin/env

执行后再验证：

uv --version

能正常输出版本号即生效。

3. 永久生效（重启终端也能用）

把路径写入 bash 配置文件，以后打开终端自动加载：​​​​​​​

echo 'export PATH=”$HOME/.local/bin:$PATH”' >> ~/.bashrcsource ~/.bashrc

再次测试可以看到版本号。

05 再再再次安装

问题解决完，再次执行

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

执行截图：

06 向导配置

6.1、模式选择

经过多次尝试，终于安装成功，进入初始化向导配置界面。

上下方向键切换选项，回车 / 空格确认选择，ESC 取消。

6.1.1、三个选项详细解析

1. Quick Setup (Nous Portal) — 快速配置（官方推荐）

• 模式说明：通过 Nous 官方门户进行 OAuth 授权登录，无需手动填写任何 API Key，官方直接提供模型服务和工具能力。

• 适用场景：能正常访问境外网络、有 Nous 账号、想快速上手不想折腾配置的用户。

• 国内注意：该模式依赖境外的 Nous Portal 服务，国内网络大概率无法正常完成登录和调用，不推荐国内用户选择。

  1. Full setup — 完整自定义配置

• 模式说明：全手动配置所有内容，包括模型服务商、API 密钥、工具权限、运行参数等，所有资源都由你自己提供。

• 适用场景：有自己的 API Key（如 OpenAI、Anthropic、DeepSeek、通义千问等），想自定义使用的模型、控制工具权限的用户。

• 国内建议：国内用户优先选择此项，可以接入国内可稳定访问的模型服务，不受官方门户的网络限制，可控性更强。

1. Blank Slate — 空白极简模式

• 模式说明：只保留最基础的核心运行能力，所有扩展功能、工具默认全部关闭，后续按需手动逐个开启。

• 适用场景：追求极简、想完全掌控功能开关，或者只需要基础对话能力的高级用户。

6.1.2、国内环境选择建议

这里优先选择Full setup，自行接入国内可稳定访问的大模型 API，是最稳妥、可控性最高的方案。

6.2、终端执行后端选择

这是 Hermes Agent 配置向导中的终端执行后端选择步骤，用来决定 Agent 执行 Shell 命令、运行代码、操作文件时，在什么环境里运行。当前默认选中的是「保持本地模式」，上下键切换、回车确认。

6.2.1、选项说明

6.2.2、操作建议

结合你的 WSL 本地环境和入门阶段，直接回车选择Keep current (local)即可：

1. 本地模式无需额外安装依赖，配置完成后立刻就能使用 Agent 的全部能力；

2. 该设置不是永久固定的，后续可随时通过hermes config edit修改为 Docker 等其他模式；

3. Modal、Daytona 等云端方案在国内网络环境下连通性差，不推荐选择。

6.3、消息平台接入

这是 Hermes Agent 初始化配置向导中的消息平台接入选择页，用于配置 Agent 可对接的外部聊天、协作与通知平台。配置完成后，Agent 可以脱离终端，在对应平台接收用户指令、执行任务并返回结果。

• 操作方式：方向键上下移动光标，空格键勾选 / 取消对应平台，回车键确认进入下一步，ESC 取消配置。

• 当前状态：列表中所有平台均为未配置（not configured）状态，可按需选择。

6.3.1、平台分类解析

国内主流平台

海外与小众平台

包含 Mattermost、Signal、Discord、Slack、Telegram、WhatsApp、Email、Microsoft Teams、Google Chat 等海外协作工具，以及 Home Assistant（智能家居控制）、IRC、Matrix、ntfy 等技术向小众平台。这类平台国内日常使用场景少，且多数存在网络访问限制。

6.3.2、操作建议

1. 入门阶段：直接空选回车跳过

本地终端交互已经可以完整使用 Hermes Agent 的全部核心能力（代码执行、文件操作、工具调用等）。此处无需勾选任何平台，直接按回车进入下一步即可，避免增加不必要的配置复杂度。

1. 后续可随时增配

所有平台都支持后续按需配置，无需在初始化时一次性完成：

hermes setup gateway

执行上述命令可重新进入平台配置向导，也可以直接编辑~/.hermes/config.yaml手动添加参数。

1. 平台选型参考

• 团队协作场景优先选择飞书、钉钉、企业微信，官方开放 API 接入稳定、合规性高；

• 个人微信接入依赖第三方协议适配，存在账号风控风险，稳定性相对一般，仅建议尝鲜使用；

• 海外平台多数需要配合代理使用，国内环境下使用成本较高。

6.4、CLI 终端模式工具能力

这是 Hermes Agent 初始化配置中的CLI 终端模式工具能力开关页，用于选择 Agent 在终端交互时可以调用的能力集合。操作方式：方向键移动光标，空格键切换勾选状态，回车键确认保存，ESC 取消配置。

当前大部分核心本地能力已默认勾选，部分依赖额外 API、专属模型或第三方服务的工具处于未开启状态。

6.4.1、已勾选工具（核心能力，推荐保留）

这些是 Hermes Agent 的核心功能，多数可在本地直接运行，无需额外密钥，覆盖绝大多数日常 Agent 使用场景：

6.4.2、未勾选工具（扩展能力，按需开启）

这类工具需要额外 API 密钥、专属模型或第三方账号，且部分在国内网络环境下可用性有限：

6.4.3、操作建议

1. 入门阶段直接回车确认即可

默认勾选的工具已经覆盖了代码执行、文件操作、终端控制、任务规划等 90% 以上的核心场景，足够满足本地 Agent 的日常使用需求。扩展工具后续可随时通过配置文件开启。

1. 国内环境适配提醒

• 网页搜索功能默认依赖 DuckDuckGo，国内直连无法使用，完成配置后需给 Hermes 配置代理，或替换为国内可用的搜索源。

• 视觉、生图类工具需要对应模型支持，你当前使用的商汤日日新需确认是否开放对应能力的 API，暂不建议开启。

• X、Spotify 等海外服务无需开启，国内网络环境下无法正常使用。

1. 后续调整方式

配置完成后，可随时执行hermes config edit编辑配置文件，开关对应工具，无需重新走完整向导。

6.5、浏览器自动化后端选型页

这是 Hermes Agent 配置向导中的浏览器自动化后端选型页，对应你之前勾选的「Browser Automation」工具，决定网页浏览、点击、表单填写、页面抓取等自动化操作由哪套浏览器引擎执行。

操作方式：方向键上下切换，回车 / 空格确认，ESC 取消。当前默认选中官方推荐的免费本地方案。

6.5.1、各选项详细解析

6.5.2、操作建议

1. 常规使用直接回车确认 Local Browser

这是最稳妥、零成本的选择，能满足网页信息提取、简单页面交互等绝大多数需求，且完全在本地 WSL 环境运行，不存在境外服务的网络问题。

安装向导会自动配套下载 Chromium 运行依赖，无需手动额外安装。

1. 特殊场景可后续切换

如果后续需要应对反爬严格的网站，再执行hermes config edit手动切换为 Camofox 方案即可，配置可随时修改，无需重走向导。

1. 不推荐云端方案

所有带「subscription」「paid」标识的云端浏览器服务，在国内网络环境下普遍访问不稳定，且需要额外付费，普通用户无需考虑。

6.6、Chromium 安装失败

这是配置向导的非致命错误场景：Chromium 浏览器本体下载失败，但向导没有中断，自动跳过并继续推进后续功能安装。

6.7、文本转语音（TTS）引擎选型

这是 Hermes Agent 配置向导的文本转语音（TTS）引擎选型步骤，对应语音播报功能，决定 Agent 输出文本时的语音合成服务。当前光标默认停在官方推荐的免费方案 Microsoft Edge TTS 上。

6.7.1、选项分类与国内适配性

1. 可用的免费方案

1. 不推荐的海外付费方案

Nous Subscription、OpenAI TTS、xAI TTS、ElevenLabs、Mistral、Google Gemini TTS 均为海外云端付费服务，需要对应平台的 API 密钥，国内网络访问受限，且需要额外付费，普通用户无需考虑。

1. 跳过选项

Skip - keep defaults / configure later：暂不配置，保持默认，后续可手动调整。适合暂时用不到语音功能、想快速走完向导的用户。

6.7.2、操作指导

1. 想保留语音功能

   ：直接按回车确认当前选中的Microsoft Edge TTS即可，无需额外配置，开箱即用。

2. 想快速收尾向导

   ：按向下方向键移动到最后一项Skip，回车确认跳过。语音播报属于非核心扩展功能，完全不影响 Agent 对话、代码执行、文件操作等核心能力。

6.8、视觉分析后端选型

这是 Hermes Agent 配置向导的视觉分析后端选型步骤，对应图像识别、图片内容分析能力，决定 Agent 处理图片输入时调用哪套多模态模型服务。当前默认选中官方推荐的「自动适配」模式。

6.8.1、各选项解析

6.8.2、操作建议

结合当前的配置进度，建议直接选择 Skip 跳过，原因如下：

1. 视觉分析属于非核心扩展功能，完全不影响 Agent 对话、代码执行、文件操作、任务规划等核心能力。

2. 你当前的主模型（商汤日日新）接口地址尚未修正，即便选择 Auto 模式也无法正常调用视觉能力。

3. 后续等核心对话功能调通后，如果需要图片分析能力，可以再通过自定义 OpenAI 兼容接口的方式，单独接入商汤的多模态模型，配置逻辑和主模型一致。

操作：按向下方向键移动到 Skip 选项，按回车确认即可。

6.9、网页搜索服务商选型

这是 Hermes Agent 配置向导的网页搜索服务商选型步骤，对应联网搜索、网页抓取功能，决定 Agent 执行联网信息检索时调用的搜索引擎后端。当前默认选中的 Nous 订阅方案需要境外门户登录，国内网络无法正常使用。

6.9.1、选项分类与国内适配性

1. 海外付费 / 订阅类（不推荐国内用户选择）

包括Nous Subscription、Firecrawl 付费版、Exa、Parallel、Tavily、xAI Web Search等，均为海外云端搜索服务，需要对应平台 API 密钥或订阅付费，国内网络访问受限，普通用户无需考虑。

1. 免费 / 自托管类（国内可用性有限）

1. 跳过选项

Skip - keep defaults / configure later：暂不配置，保持默认状态，后续可手动调整。

6.9.2、操作指导

建议直接选择 Skip 跳过，原因如下：

1. 网页搜索属于扩展功能，完全不影响 Agent 核心的对话、代码执行、文件操作、任务规划等能力。

2. 列表内所有搜索源均为海外服务，国内直连普遍存在网络不稳定、超时的问题，即使配置完成也很难正常使用。

3. 后续如果需要联网搜索能力，可以在配置代理后，再手动切换为 DuckDuckGo 等免费方案，或自行部署 SearXNG 等自托管搜索服务。

07 安装完成

Hermes Agent主体程序已全部安装完成，配置向导也已执行完毕，终端已回到命令行提示符状态。使用的是中国大陆镜像适配版本，默认跳过了境外源下载的 Chromium 等组件，和之前安装过程中遇到的超时现象一致，属于预期内的适配处理。

08 API配置

前面配置的不太对，这里重新配置：这里链接日日新当前免费的API：

命令行配置：​​​​​​​

hermes config set model.provider customhermes config set model.base_url https://token.sensenova.cn/v1hermes config set model.api_key ”$SENSENOVA_API_KEY”# 替换为您的 API Keyhermes config set model.name sensenova-6.7-flash-litehermes config set model.default custom/sensenova-6.7-flash-lite

09 你好Hermes

最后，打开界面，发个你好试试。