2026 Hermes Agent 保姆级安装部署完全教程：
macOS / Linux / VPS 从零到跑通，含 Telegram 与 7×24 常驻

对象：已在 GitHub 关注 Nous Research / hermes-agent（MIT，社区 Star 约 17.4 万量级热度）、却卡在「装不上 / Gateway 起不来 / Telegram 无响应」的开发者。范围：本文只讲 安装、验收、Gateway 常驻与频道接入，不展开三层记忆架构——记忆与选型见 Hermes 7×24 与三层记忆选型文。结果：按官方 v0.14.x 脚本，30～90 分钟内在 macOS、Linux 或 MacDate 租用的 Mac mini M4 上跑通 hermes doctor 与手机 Telegram 触达。🛠️📱

Hermes Agent 安装部署与 Telegram Gateway 常驻示意

2026 年 6 月，Hermes Agent（Nous Research，MIT 开源，当前稳定线 v0.14.x）已是许多开发者「个人 Jarvis」的首选：一行 curl -fsSL https://get.hermes-agent.org | bash 即可在 macOS 与 Linux 落地 CLI，再通过 hermes gateway 把 Telegram、Discord 接到常驻进程。与 三层记忆与 VPS/Mac mini 选型文、30 天实测与 Skill 复利文 不同，本篇是纯安装部署 How-To：从环境表、六步命令到 MacBook / VPS / Mac mini M4 对照，帮你避开「脚本跑一半断网」「Bot Token 写错环境变量」「笔记本合盖 Gateway 挂掉」三类高频坑。若你计划在远程 macOS 上 7×24 跑 Hermes，租用流程见 按天租用 Mac FAQ，套餐见 Mac mini M4 定价页。

目录 · TABLE OF CONTENTS

  1. 01 安装前三大痛点：脚本、Gateway、Telegram
  2. 02 环境要求对照表：macOS / Linux / VPS
  3. 03 六步安装：curl → setup → doctor → gateway → Telegram
  4. 04 Telegram：BotFather、Token 与 hermes gateway
  5. 05 宿主对照：MacBook vs VPS vs Mac mini M4
  6. 06 三条硬核数据与常见报错
  7. 07 转化段：何时把安装迁到租用 Mac mini M4

01. 安装前三大痛点：脚本、Gateway、Telegram

社区 Issue 与 MacDate 客服工单里，Hermes 安装阶段（非记忆调优）重复率最高的三类问题如下——对号入座可节省数小时排错：

  1. curl 安装中断或 PATH 未生效：公司代理、老旧 bash、或安装后未重开 shell，导致 hermes 命令找不到；有人混用 pip 旧版与官方脚本，版本漂移至非 v0.14.x 行为。对策：用官方域名 get.hermes-agent.org 唯一入口，安装后执行 hermes doctor 而非猜测目录。
  2. Gateway 未常驻：只跑了 CLI 对话，未执行 hermes gateway setup / start / install，Telegram 消息无人监听；或在 MacBook 上未禁用休眠，合盖后进程冻结。对策：Linux 用 hermes gateway install 注册 systemd；macOS 用 LaunchAgent 或租用机房 Mac mini 7×24 在线。
  3. Telegram Token 与 allowlist 配置错误：把 Token 写进聊天窗口泄露、未 export TELEGRAM_BOT_TOKEN、或 Bot 未 /start 就期望回复。对策：BotFather 重建 Token 后走 hermes gateway setup 向导，手机端先对 Bot 点 Start 再测。
📌 与姊妹篇分工：记忆架构、Closed Learning Loop、Hindsight MPS 避坑见 选型文；30 天 Skill 体积与月租实测见 实测文。本篇只保证「能装、能连、能 7×24 收消息」。

官方安装脚本在后台会自动处理多数依赖：通过 uv 拉取 Python 3.11、安装 Node.js 22、补齐 ripgrep 与 ffmpeg，并把仓库克隆到 ~/.hermes/hermes-agent/，全局 hermes 命令写入 PATH。无头服务器若不需要浏览器自动化，可加 bash -s -- --skip-browser 跳过 Camoufox 等大体积组件，缩短首次安装时间。安装成功终端应出现 ✅ Hermes Agent installed at ~/.hermes 一类提示——若没有，不要继续配置 Telegram，先解决 doctor 报错。

02. 环境要求对照表：macOS / Linux / VPS

开始 curl 之前，对照下表自检——Hermes 本体轻量，但 Gateway 与 Telegram API 依赖稳定出站 HTTPS：

检查项 macOS（本机 / MacDate 节点） Linux（VPS / 云主机） 说明
操作系统 macOS 14+（Apple Silicon 或 Intel） Ubuntu 22.04+ / Debian 12+ / RHEL 系 WSL2 可用但 Gateway 常驻建议原生 Linux
磁盘 ≥ 10 GB 可用 ≥ 10 GB 可用 ~/.hermes/ 初期通常 < 500 MB
内存 8 GB 可跑 Gateway + 云端 API 2 GB 最低，4 GB 推荐 本地 Ollama 另计，安装教程不依赖 GPU
网络 可访问 get.hermes-agent.org、api.telegram.org 机房出站通常更稳 无需 inbound 公网端口即可 Telegram 长轮询
依赖 Xcode CLT 或 curl、git curl、git、build-essential（部分插件） 脚本会提示缺失包
LLM API OpenAI / Anthropic / 兼容端点 Key hermes setup 交互写入，勿提交 Git

03. 六步安装：curl → setup → doctor → gateway → Telegram

以下路径在 macOS 与 Linux 通用（租用 MacDate 节点时先 ssh admin@[IP]，流程相同）。预计 30～45 分钟完成基础验收，含 Telegram 配对再加 15 分钟。

  1. 登录宿主并检查出站：curl -I https://get.hermes-agent.org 返回 200/301 即可。VPS 新手建议先读 SSH 与租用 FAQ。
  2. 官方一键安装：执行 curl -fsSL https://get.hermes-agent.org | bash，等待 v0.14.x CLI 写入 PATH；若提示重开终端，执行 source ~/.zshrc 或 source ~/.bashrc。
  3. 交互配置：运行 hermes setup，按向导填入 LLM Provider 与 API Key；确认 ~/.hermes/ 已创建且当前用户可写。
  4. 健康检查：hermes doctor 应全部绿色或仅警告可忽略项；若有 Node/Python 版本告警，按 doctor 输出修复后再继续。
  5. Gateway 初始化：hermes gateway setup 选择频道类型；7×24 场景接着 hermes gateway install（服务化）或 hermes gateway start（前台调试）。
  6. 端到端验收：另开终端 hermes status 或查看 gateway 日志，手机 Telegram 发「ping」收到回复即安装闭环完成；退租或换机前 tar czf hermes-backup.tar.gz ~/.hermes/。
# 2. 官方一键安装（macOS / Linux 相同） $ curl -fsSL https://get.hermes-agent.org | bash # 3～4. 配置与健康检查 $ hermes setup $ hermes doctor # 5. Gateway：setup → 服务化或前台启动 $ hermes gateway setup $ hermes gateway install $ hermes gateway start # 查看 Gateway 状态 $ hermes gateway status

调试阶段可前台跑 hermes gateway start 观察日志；确认无误后再 install 交给 launchd/systemd，避免「后台静默失败」却以为已 7×24 在线。

3.1 给 Agent 装大脑：hermes setup 与 LLM 提供商

安装脚本只解决 CLI 与 Gateway 骨架，真正对话能力来自 LLM API。新手优先跑交互向导 hermes setup；已有 Key 的用户可用 hermes model 单独切换。所有密钥应写入 ~/.hermes/.env 并 chmod 600，禁止提交到 Git 仓库。

提供商 适合场景 配置方式
OpenRouter 多模型实验、成本可控 hermes config set OPENROUTER_API_KEY sk-or-...
Anthropic Claude 长上下文、工具调用稳 API Key 或 OAuth（Max 计划）
OpenAI GPT 系列、生态插件多 API Key
Ollama / 本地端点 隐私敏感、离线实验 Base URL + 可选 Key；Mac mini M4 16GB 可跑 7B～14B
GitHub Copilot 已有订阅、开发向任务 hermes model 内 OAuth 授权

配置完成后执行 hermes 进入交互 CLI，发送「列出当前目录文件」或「总结今日 AI 新闻」做冒烟测试；若报 API key not set，说明 setup 未写入对应环境变量，重跑 hermes setup 或手动编辑 ~/.hermes/.env。

3.2 Windows 与 WSL2 说明

Windows 原生 PowerShell 安装脚本尚处早期阶段；生产环境推荐 WSL2 + 本文 Linux 命令。在 WSL2 内执行 curl -fsSL https://get.hermes-agent.org | bash 后，Gateway 常驻由 systemd 管理；若需从 Windows 宿主机访问 WSL 内服务，注意防火墙与端口转发，Telegram 长轮询仍只需出站 HTTPS，一般无需映射 inbound 端口。

04. Telegram：BotFather、Token 与 hermes gateway

Telegram 是 Hermes 最常见的移动端触达面，配置顺序不要跳步：

  • 在 Telegram 搜索 @BotFather，发送 /newbot，按提示取名，获得形如 123456789:AAH... 的 Token。
  • 在服务器上 仅通过环境变量注入，勿写进 shell 历史明文：export TELEGRAM_BOT_TOKEN="你的Token"；可写入 ~/.hermes/.env 并 chmod 600（若 setup 向导支持）。
  • 运行 hermes gateway setup，选择 Telegram，粘贴或读取环境变量；按提示配置 allowlist / 私聊策略，防止 Bot 被陌生人刷爆 Token 配额。
  • 执行 hermes gateway start 或 hermes gateway install 后，用手机打开 Bot 对话，点击 Start，再发测试消息；若超时，先 hermes doctor 再查主机是否休眠或防火墙拦截出站。
# BotFather 拿到 Token 后 $ export TELEGRAM_BOT_TOKEN="123456789:AAExample..." $ hermes gateway setup $ hermes gateway start # 可选：注册为开机自启服务 $ hermes gateway install

Discord 频道步骤类似，只是 Token 来源换为 Discord Developer Portal；若你同时需要企业 IM 网关，可与 Hermes 分机部署，避免一个 Gateway 进程扛过多频道导致重启牵连。

05. 宿主对照：MacBook vs VPS vs Mac mini M4

「装得上」不等于「适合 7×24」——安装教程收尾时，请根据下表选择最终常驻宿主（非安装命令差异）：

维度 主力 MacBook Linux VPS（2C4G） Mac mini M4（自购 / MacDate 租用）
安装命令 curl 官方脚本，与文档一致 相同 macOS 原生，可选 Ollama 同机
7×24 Gateway 合盖休眠、出差断网 systemd 易常驻 低功耗静音，适合桌下/机房
Telegram 延迟 取决于当前网络 跨国 RTT 可能 +50～200ms MacDate 香港节点至大陆常 15～30ms
数据隔离 ~/.hermes/ 与日常开发混用 磁盘随实例释放需备份 独占裸机，退租 NIST 擦除前可 tarball
推荐阶段 本机 10 分钟试装 低成本验证 Gateway 长期 7×24 + macOS 栈

许多读者在 MacBook 上完成 §03 六步 后，再把 ~/.hermes/ 打包迁移到 MacDate 节点——迁移后务必重跑 hermes doctor 与 hermes gateway install。深度 TCO 与记忆连续性理由见 选型文。

06. 三条硬核数据与常见报错

  • ① 官方安装入口唯一推荐：curl -fsSL https://get.hermes-agent.org | bash——与 GitHub README 同步，避免第三方 fork 脚本夹带旧版 v0.13 行为；装完后 hermes --version 应显示 v0.14.x 线。
  • ② 社区热度：Nous Research 旗下 Hermes 项目在 GitHub 累计 Star 约 17.4 万 量级（MIT 协议），安装文档更新频率高，遇到 Breaking Change 优先查 Release Note 再跑 hermes doctor。
  • ③ Gateway 资源占用：仅 Telegram + 云端 API 时，常驻进程内存通常 < 300 MB，2C4G VPS 或 8GB Mac mini 均绰绰有余；瓶颈多在 LLM API 配额而非安装本身。
报错信息 常见原因 处理办法
hermes: command not found PATH 未刷新 source ~/.zshrc 或新开终端
API key not set 未配置 LLM hermes setup 或编辑 ~/.hermes/.env
Missing config after update v0.14 升级后字段迁移 hermes config check && hermes config migrate
Telegram 群聊无响应 Bot 隐私模式未关 BotFather 关闭 Group Privacy 后踢出再拉入群
gateway connect timeout 出站被墙或 Token 错误 curl -I https://api.telegram.org + 核对 Token

若 doctor 提示记忆插件但本文阶段可跳过，待跑通频道后再读 30 天实测文 调优 Skill 与 MCP 扩展。

07. 转化段：何时把安装迁到租用 Mac mini M4

在主力 MacBook 上完成安装教程只解决「会不会装」；要 Hermes 7×24 收 Telegram、Cron 准时触发、Gateway 不因合盖失联，你需要一块愿意常通电的宿主。自购 Mac mini M4 是买断路线；若尚在验证 v0.14.x 工作流、或不愿让 ~/.hermes/ 污染日常开发机，MacDate 按天/弹性租用 Mac mini M4 让你用同一套 curl | bash 与 hermes gateway install 在远程 macOS 裸机上复现本教程，独立公网 IP、退租前 tarball 备份、释放时 NIST 擦除——与任何第三方「Hermes 租赁」品牌无关。定价与 SSH 细节：套餐页、租用 FAQ；记忆为何值得 7×24：选型文。

延伸阅读