2026 Hermes Agent 保姆级安装教程：macOS / Linux / WSL2 一键部署、Telegram 接入与 7×24 常驻排错

约 16 分钟阅读 · MACCOME

📌 若你已在 GitHub 上看到 Hermes Agent 逼近 17 万 Stars、却卡在「装完找不到命令 / Telegram 不回消息 / 升级后配置丢了」，本文就是面向当天要跑通的保姆级 Runbook。谁适合读：要在 macOS、Linux 或 WSL2 上部署 v0.15.x、并计划接 Telegram 7×24 的开发者。你会得到：可复制的一键安装、hermes doctor 验收、模型与 Gateway 配置、12 项报错对照，以及常驻主机选型结论。结构：痛点 → 环境表 → 八步落地 → 硬数据 → 平台对比 → FAQ。

六道安装坑：为什么「只看 README」常常装不顺

2026 年 5 月底，Nous Research 将 Hermes 推到 v0.15.2，并同步提供 pip install hermes-agent 与经典 curl | bash 双轨。社区热度高，但安装帖往往跳过下面这些「真实卡点」：

  1. PATH 未刷新：脚本把 hermes 写入 ~/.zshrc，未 source 就报 command not found——最常见，也最容易误判为「安装失败」。
  2. 混用系统 Python 与 venv：直接 python3 -m hermes 可能缺 dotenv；正确入口是 ~/.hermes/hermes-agent/venv/bin/hermes。
  3. 只装 CLI、未配大脑：能进交互界面却立刻报 API key not set，因跳过 hermes setup / hermes model。
  4. Gateway 与 CLI 混淆：Telegram 需要 hermes gateway 长进程；只跑 hermes 对话，手机端永远收不到回复。
  5. Telegram 群聊隐私模式：Bot 默认只听 / 命令；未在 BotFather 关 Group Privacy 就以为「Bot 坏了」。
  6. 升级半迁移：v0.14 → v0.15 后字段偏移，需 hermes config check && hermes config migrate，否则出现 Missing config after update。

与 OpenClaw 的一句话差异：OpenClaw 强在多渠道 Gateway 与 npm/Compose 运维生态；Hermes 强在跨会话 MEMORY.md / USER.md、任务后自动沉淀 Skill 与 MCP 扩展。概念与硬件选型可先看站内 三层记忆架构文；首月体验见 30 天实测文——本篇只解决「装得上、连得上、守得住」。

环境要求：你真正需要准备什么

官方安装脚本会自动处理 Python 3.11（via uv）、Node.js 22、ripgrep、ffmpeg；你只需保证 git 可用且能访问 GitHub raw 与所选 LLM API。

项目 最低 推荐（生产 Gateway）
系统 macOS 12+、Ubuntu 20.04+、WSL2 macOS 14+（Apple Silicon）/ Ubuntu 24.04 LTS
内存 4 GB（仅云端 API + Gateway） 16 GB（浏览器自动化 + 多 Skill 缓存）
磁盘 约 1.5 GB（含 Skills） 20 GB SSD（日志 + SQLite WAL）
网络 可拉 GitHub raw 稳定低延迟 LLM API 出口
Windows PowerShell 原生脚本（Early Beta） WSL2 + Linux 一键脚本（官方最稳路径）
warning

无头服务器：不需要浏览器自动化时，可加 --skip-browser 跳过 Camoufox 相关依赖，节省磁盘与内存。

八步落地：从一行命令到 Telegram 在线

以下步骤在 macOS / Linux / WSL2 通用；远程 Mac 上 SSH 登录后执行与本地无异。

  1. 一键安装：执行官方脚本（见下方代码块）。成功标志为终端输出 ✅ Hermes Agent installed at ~/.hermes。
  2. 刷新 Shell：source ~/.zshrc（或 source ~/.bashrc），新开终端亦可。
  3. 健康检查：hermes doctor 自检约 12 项（Python、Node、PATH、API Key 等）；hermes --version 应显示 v0.15.x。
  4. 配置模型：新手跑 hermes setup；已有 Key 用 hermes model 或 hermes config set OPENROUTER_API_KEY sk-or-xxxx 写入 ~/.hermes/.env。
  5. 冒烟对话：执行 hermes，输入「列出当前目录文件」等轻量任务，确认工具链可调用。
  6. 创建 Telegram Bot：在 Telegram 找 @BotFather → /newbot → 保存 Token；用 @userinfobot 获取你的数字 ID。
  7. 配置 Gateway：hermes gateway setup 选 Telegram 并粘贴 Token；或手动写入 TELEGRAM_BOT_TOKEN 与 TELEGRAM_ALLOWED_USERS。
  8. 常驻服务：测试用 hermes gateway；生产用 hermes gateway install && hermes gateway start（macOS launchd / Linux systemd）。

LLM 提供商怎么选（2026 实操口径）

日常工具调用 + 云端路由：OpenRouter 或多模型实验首选；企业 Claude 走 Anthropic API/OAuth；零配置可试 Nous Portal（hermes setup --portal）。本地隐私场景对接 Ollama 时在 hermes model 填 Base URL。v0.15 另支持 Grok provider 与 x_search 工具——按任务在 hermes tools 中启用即可。

bash
# 官方一键安装（macOS / Linux / WSL2）
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 无头服务器可选
# curl -fsSL .../install.sh | bash -s -- --skip-browser

source ~/.zshrc
hermes doctor
hermes setup

# Telegram Gateway（交互向导）
hermes gateway setup
hermes gateway install
hermes gateway start
hermes gateway status
bash
# Linux 系统级 Gateway（开机自启，需 root）
sudo hermes gateway install --system
sudo hermes gateway start --system
journalctl -u hermes-gateway -f

可引用硬数据：版本、Stars 与 Skill 复利前提

  • GitHub Stars（2026-06 口径）：约 174,720，MIT 协议，日榜常客——安装前可在仓库 Releases 核对当前 tag（稳定线 v0.15.2 / 2026.5.29.2）。
  • 安装体积：含默认 Skills 注册表约 1.5 GB；Gateway 常驻典型内存约 4.2 GB（含浏览器自动化时，M4 UMA 上更平滑）。
  • Skill 复利（社区实测，链 30 天文）：30 天内 Skill 数量 3 → 19，同类任务 token 约降 38%——前提是主机 7×24 在线，否则闭环中断。

12 项常见报错对照表

报错 / 现象 原因 处理
hermes: command not found PATH 未加载 source ~/.zshrc 或新开终端
API key not set 未配置 LLM hermes model / 写入 ~/.hermes/.env
Missing config after update 升级迁移未完成 hermes config check && hermes config migrate
No module named 'dotenv' 误用系统 Python 使用 venv 内 hermes 可执行文件
Telegram 群聊无响应 隐私模式 / 未重邀入群 BotFather 关 Group Privacy，踢出再拉入
Gateway 启动即退出 Token 或用户 ID 错误 核对 TELEGRAM_ALLOWED_USERS 为纯数字 ID

部署平台对比：笔记本、VPS 与租 Mac Mini M4

装通 Hermes 只解决「能跑」；Telegram 生产与 Skill 复利解决「能一直跑」。

平台 7×24 可用性 Skill 复利 适合
个人 MacBook 合盖即断（≈60%） 频繁中断 POC、当日调试
x86 VPS 4GB ≈99.5% 稳定但缺 macOS 原生路径 纯 Linux 用户、无 Camoufox 需求
树莓派 4B 8GB ≈88% I/O 瓶颈、长任务易超时 玩票，不建议生产 Gateway
租 Mac Mini M4 机房 30 天在线 launchd 守护 + UMA 要 Telegram 生产 + macOS Skill 路径

收束：装通只是第一步，常驻才决定 Agent 是否「越用越省」

按本文八步，大多数读者可在 30–60 分钟 内完成 Hermes CLI + Telegram Gateway 首通。三条替代方案的短板也很明确：(a) 笔记本无法可靠 7×24，Gateway 与 Skill 写入会断档；(b) 低配 VPS 缺少 macOS 上最省心的 curl | bash 与 Camoufox 浏览器 Skill 路径；(c) 自购 Mac Mini 把 Capex、宽带与机房噪音全部压在自己身上。

若你已验证 Hermes 能替你省下重复劳动、又希望 固定月费、十分钟 SSH 上岗、退租前可打包 ~/.hermes/，MACCOME 独占 Mac Mini M4 云节点通常是更优解：真实 Apple Silicon、launchd 原生守护，与本文安装命令完全兼容。选型与 TCO 可继续读 架构决策文，并在 租赁价格页 按区域下单。

常见问题

Hermes Agent 和 OpenClaw 能装在同一台 Mac 上吗？

可以，但配置目录分离（~/.hermes vs ~/.openclaw），注意内存与磁盘。OpenClaw 运维文见站内安装对比博客；Hermes 装通后若要 7×24，建议专用主机或 租赁节点。

v0.15 可以用 pip 安装吗？

可以：pip install hermes-agent && hermes。仍建议首次跑 hermes doctor。与 git 安装脚本二选一即可，避免混用两套 venv。

Gateway 日志在哪里看？

前台模式直接看终端；systemd 用 journalctl -u hermes-gateway -f；macOS 用户服务可用 hermes gateway status。更多运维见 帮助中心。

退租前如何迁移 Hermes 数据？

打包整个 ~/.hermes/（含 skills/、memories/、sessions SQLite）即可在新机恢复。MACCOME 退租前支持自助清机；迁移步骤见帮助中心。