Ai专栏：1.WSL2 Ubuntu 安装 Hermes Agent 完整指南：从零到跑通

WSL2 Ubuntu 安装 Hermes Agent 完整指南：从零到跑通

一篇来自一线 IT 运维的实际安装记录，不是翻译官方文档。

Hermes Agent 是什么

Hermes Agent 是 Nous Research 在 2026 年 2 月发布的开源自主 AI 智能体框架，MIT 协议。两个月内 GitHub 斩获 6.4 万星，到 5 月全球 Token 消耗量已经超过了同赛道的 OpenClaw。

它不是一个套壳聊天机器人，也不是绑在 IDE 上的代码补全工具。它住在你的服务器上，有持久记忆、会自动写技能文档、能接微信/飞书/钉钉/Telegram 等 15+ 个消息平台，还内置了定时任务调度和浏览器自动化。你用得越久，它就越了解你的工作习惯。

核心能力清单：

持久记忆：跨会话记住你的偏好、项目、环境，不用每次重讲一遍
自动技能创建：解决一个难题后自己写 SKILL.md，下次遇到同类问题直接复用
多平台消息网关：一个网关进程通吃 CLI、Telegram、Discord、Slack、WhatsApp、微信、飞书、钉钉
定时自动化：内置 cron 调度器，日报、备份、巡检全都可以无人值守
并行子智能体：隔离的子进程，独立对话和终端，多任务并行
完整浏览器控制：导航、点击、输入、截图、视觉分析

对于做运维和开发的人来说，它就像雇了一个 7x24 小时值班的初级同事，不抱怨、不请假、越干越熟练。

为什么选 WSL2 + Ubuntu

先说结论：Windows 用户最稳的玩法就是 WSL2 里跑 Ubuntu，然后装 Hermes。

三个原因：

兼容性最好。Hermes 的安装脚本对 Debian 系（Ubuntu/Debian）支持最完善，apt 装依赖零摩擦。原生 Windows PowerShell 也能装，但那是实验性的，浏览器自动化、终端交互等高级功能在 WSL2 下表现更稳定。
国内镜像加速。中文社区提供了 res1.hermesagent.org.cn 镜像安装脚本，优先走国内可直连的下载链路，不用折腾代理。
运维友好。WSL2 里跑的东西可以直接用 systemd 管（Win11 已原生支持），也能用 Windows 端的任务计划程序做兜底，灵活性拉满。

我一开始想过用 Rocky Linux 10.1，毕竟 CentOS 停更后 Rocky 是 RHEL 生态的接班人。但 Hermes 安装脚本对 dnf 的支持不如 apt 成熟，加上 Rocky 默认开 SELinux，要多绕几道弯，没必要跟自己过不去。实战选了 Ubuntu，一路绿灯。

环境准备

WSL2 装 Ubuntu

如果你的 Windows 还没装 WSL2，PowerShell 管理员模式一条命令搞定：

1	`wsl --install -d Ubuntu`

装完重启，开始菜单会多一个 Ubuntu 图标，点开设置用户名密码即可。

确认是 WSL2 版本：

1
2
3

wsl -l -v
# NAME      STATE           VERSION
# Ubuntu    Running         2

Ubuntu 基础依赖

进 Ubuntu 终端，先把系统更新了再加上必备工具：

1 2	`sudo apt update && sudo apt upgrade -y sudo apt install -y curl git build-essential python3 python3-full`

Ubuntu 26.04 自带的 Python 3.14 完全满足 Hermes 的 3.11+ 要求，不用额外折腾 Python 版本。

安装 Hermes Agent

一条命令安装

国内网络直接用中文社区镜像：

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

如果你网络环境能直连 GitHub，也可以用官方源：

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

安装脚本自动干的事：

步骤	做了什么
检测 OS	识别为 Linux / Ubuntu，走 `apt` 路线装系统级依赖
安装 uv	Python 包管理器，替代 pip，速度快一个数量级
安装 Python 3.11	通过 uv 自动拉取，不污染系统已有的 Python
克隆仓库	代码放到 `~/.hermes/hermes-agent/`
创建虚拟环境	`venv` 隔离依赖
安装 Python 依赖	核心包 + 可选组件
配置 PATH	创建 `~/.local/bin/hermes` 软链接，全局可用
下载 Node.js	为浏览器自动化准备运行时

整个过程 3 到 5 分钟，取决于网络。

装完后重载 shell 环境：

1	`source ~/.bashrc`

配置向导详解

执行 hermes setup 进入交互式配置向导。几个关键步骤逐一说明。

1. 选择模型提供商

支持 40+ 个提供商，从 OpenAI 到国产大模型全覆盖。光标上下移动，空格选中，回车确认。

国内用户推荐这几个：

提供商	理由
DeepSeek	便宜量足，API 直连无额外层，注册即用
Qwen Cloud / DashScope Coding	阿里系，Coding Plan 套餐对编程场景优化，企业级 SLA
Kimi Coding Plan	月之暗面，api.kimi.com，编程场景有针对性优化
Z.AI / GLM	智谱清华系，国内直连稳定

我选了 DeepSeek，后续随时能用 hermes model 切到别家。

2. 终端后端

选 Local（默认），直接在本机跑。除非你有 Docker 或远程 SSH 执行的特殊需求。

3. 消息平台

建议先 Skip。配消息网关需要 Telegram Bot Token、企业微信应用凭证之类的，会让首次配置拖得很长。先把核心跑通，之后用 hermes gateway setup 补。

4. 配置完毕

向导结束后配置文件落在 ~/.hermes/ 下：

~/.hermes/
├── config.yaml   # 主配置
├── .env          # API Key 等敏感信息
├── SOUL.md       # 人设定义
├── skills/       # 技能库
├── memories/     # 长期记忆
├── sessions/     # 会话记录
├── cron/         # 定时任务
└── logs/         # 日志

安装后诊断

跑 hermes doctor，它会逐项检查环境状态。我的实际输出如下：

◆ Python Environment
  ✓ Python 3.14.4
  ✓ Virtual environment active

◆ Required Packages
  ✓ OpenAI SDK / Rich / PyYAML / HTTPX / Croniter ...

◆ Configuration Files
  ✓ ~/.hermes/.env file exists
  ✓ API key configured
  ✓ Config version up to date (v23)

◆ Command Installation
  ✓ ~/.local/bin/hermes → correct target

◆ Tool Availability
  ✓ clarify / code_execution / cronjob / terminal / delegation
  ✓ file / memory / session_search / skills / todo / tts / kanban

◆ Memory Provider
  ✓ Built-in memory active

核心 12 个工具全部绿：终端执行、代码运行、文件操作、记忆管理、技能系统、定时任务、子智能体委派、TTS 等，日常对话和工作完全够用。

黄色告警的基本都是可选功能：ripgrep / Node.js / docker 未装，浏览器工具因此暂时不可用。下面逐个补上。

补充可选组件

装 ripgrep（推荐）

文件搜索速度提升明显，一行搞定：

1	`sudo apt install -y ripgrep`

装 Node.js + npm（给浏览器自动化用）

安装脚本已经下了 Node.js 22 的 tarball 并解压，node -v 能正常工作。但 Hermes 用的精简版 tarball 不带 npm，导致后续装不了浏览器引擎。

确认问题：

1 2	`node -v # ✓ v22.22.1 npm -v # ✗ command not found`

Node.js 22 内置了 corepack（包管理器管理工具），用它启用 npm：

1 2	`corepack enable npm npm -v # 输出 11.15.0`

到此 Node.js + npm 都就绪了。

装浏览器引擎（Playwright Chromium）

npm 有了之后，先装项目依赖，再下载浏览器：

1
2
3

cd ~/.hermes/hermes-agent
npm install
hermes doctor --fix

如果看到这个报错：

1	`ERROR: Playwright does not support chromium on ubuntu26.04-x64`

那是因为 Playwright 1.60 还没适配 Ubuntu 26.04（2026 年 4 月发布的 Resolute Raccoon）。实际兼容性没问题，只是版本检测太严格。临时改一下 /etc/os-release 绕过：

# 临时改成 24.04 骗过 Playwright
sudo sed -i 's/VERSION_ID="26.04"/VERSION_ID="24.04"/' /etc/os-release
npx playwright install chromium
# 改回来
sudo sed -i 's/VERSION_ID="24.04"/VERSION_ID="26.04"/' /etc/os-release

最后再跑一次诊断确认：

1	`hermes doctor`

其他可选工具

按需来，不装也能用：

# Docker（隔离容器执行）
sudo apt install -y docker.io

# 消息网关的 Telegram/Discord 支持
hermes gateway setup

# 网页搜索（需要 API Key）
# 在 ~/.hermes/.env 里配置 FIRECRAWL_API_KEY 或 TAVILY_API_KEY

最终诊断结果

全部补完后 hermes doctor 的输出：

◆ External Tools
  ✓ git
  ✓ ripgrep (rg)
  ✓ Node.js
  ✓ agent-browser (Node.js)
  ✓ Playwright Chromium

◆ Tool Availability
  ✓ browser        ← 装上了
  ✓ clarify
  ✓ code_execution
  ✓ cronjob
  ✓ terminal
  ✓ delegation
  ✓ file
  ✓ memory
  ✓ session_search
  ✓ skills
  ✓ todo
  ✓ tts
  ✓ kanban

13 个核心工具全部就绪，包括浏览器自动化。黄色的都是可选高级功能：image_gen / video_gen 需要对应 API Key，messaging / discord 需要配消息平台，web 搜索需要 Firecrawl 或 Tavily 的 Key，不是刚需。

开始使用

hermes

进入交互式 CLI，和你选的大模型直接对话。支持多行编辑、命令补全、历史回溯、流式输出。

几个常用操作：

hermes model              # 切换模型
hermes tools              # 管理启用的工具
hermes config set         # 单独改某个配置项
hermes gateway setup      # 配置消息平台
hermes gateway            # 启动消息网关
hermes update             # 更新到最新版
hermes doctor             # 环境诊断

常用命令速查

┌──────────────────────────────────────────────────────────┐
│  分类          │  命令                   │  说明          │
├──────────────────────────────────────────────────────────┤
│  对话          │  hermes                 │  启动交互式 CLI │
│  模型管理      │  hermes model           │  切换模型提供商 │
│  工具管理      │  hermes tools           │  启用/禁用工具  │
│  配置管理      │  hermes config set      │  修改单项配置   │
│  配置向导      │  hermes setup           │  重新全量配置   │
│  诊断修复      │  hermes doctor          │  环境检查       │
│               │  hermes doctor --fix    │  自动修复       │
│  更新          │  hermes update          │  拉最新代码     │
│  消息网关      │  hermes gateway setup   │  配消息平台     │
│               │  hermes gateway          │  启动网关       │
│               │  hermes gateway install  │  注册 systemd   │
│  状态查看      │  hermes status          │  查看当前配置   │
│  迁移          │  hermes claw migrate    │  从 OpenClaw 迁 │
└──────────────────────────────────────────────────────────┘

常见坑与处理

`hermes: command not found`

1 2	`source ~/.bashrc # 或者关掉终端重开`

Node.js 有但 npm 不存在

安装脚本用的精简 tarball 不带 npm。Node.js 22 内置了 corepack，一行启用：

1 2	`corepack enable npm npm -v`

Playwright 提示不支持当前 Ubuntu 版本

Ubuntu 26.04 用户会遇到 Playwright does not support chromium on ubuntu26.04-x64。临时改版本号绕过，装完改回来。详见上文”装浏览器引擎”那节。

更新后配置丢失

1 2	`hermes config check hermes config migrate`

API Key 提示未设置

1
2
3

hermes model     # 重新走一遍模型选择
# 或直接写
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxx

小结

整个安装过程从零开始，去掉等待下载的时间，实际动手不超过 10 分钟。核心体验：

安装简单：一条 curl 命令，脚本全自动处理依赖
配置直观：交互式向导，上下左右选就行，不用手写 yaml
诊断完善：hermes doctor 把问题定位得很清楚，不会让你瞎猜
国内友好：中文社区镜像解决了 GitHub 访问慢的老问题

关于 Ubuntu 26.04 的兼容性问题：Hermes 本身完全正常，只是 Playwright 的版本检测还没跟上 2026 年 4 月发布的 Ubuntu 新版本。一行 sed 临时改版本号就能绕过，不影响功能。

装好之后真正好玩的部分才开始：让它帮你查日志、写脚本、做巡检日报、定时推送消息。一个会自己写技能文档、越用越懂你的 AI 智能体，值得花这十几分钟。

环境信息：Windows 11 + WSL2 + Ubuntu 26.04 LTS + Hermes Agent（2026 年 5 月）

中文社区：https://hermesagent.org.cn

GitHub：https://github.com/NousResearch/hermes-agent

Ai > Hermes-Agent

#Ai #Hermes-Agent

Ai专栏：1.WSL2 Ubuntu 安装 Hermes Agent 完整指南：从零到跑通

http://bote798.github.io/2026/05/23/Ai专栏：1-WSL2-Ubuntu-安装-Hermes-Agent-完整指南：从零到跑通/

作者

bote798

发布于

2026年5月23日

更新于

2026年5月23日

许可协议

Jenkins Day 3-4 错误总结与解决方案下一篇