安装 Hermes Agent

Hermes Agent 的安装本身不复杂。真正容易出错的是：脚本跑完后 shell 找不到 hermes 命令、provider（推理服务商）没配置、~/.hermes/ 这个配置目录看不懂、Termux 或 WSL2 环境误用、或者一上来就接 Gateway（消息网关）和 cron（定时任务）导致问题叠在一起没法定位。

官方资料：Installation、Quickstart、GitHub README。

支持环境

官方安装脚本现在覆盖五类环境：

Termux（Android 终端模拟器）走同一个 install.sh，但安装器会自动检测并切换到 Android 专用流程：用 Termux pkg 装系统依赖（git、python、nodejs、ripgrep、ffmpeg），用 python -m venv 创建虚拟环境，自动设 ANDROID_API_LEVEL 让 Python wheel（预编译包）能正确构建，并装精简的 .[termux] extra。浏览器和 WhatsApp bootstrap（启动）这类不稳定能力默认不启用。

一行安装

POSIX 系（Linux、macOS、WSL2、Termux）执行：

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

原生 Windows 打开 PowerShell（早期测试，遇坑可切 WSL2）：

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

安装前只需要先确认 git 可用：

git --version

官方安装器会自动处理常见依赖：uv（Python 包管理器）、Python、Node.js、ripgrep（高速正则搜索）、ffmpeg（音视频处理）等（具体版本号按官方 Installation 页 当前要求为准，避免在教程里写死）。不要在安装前手动混装一堆 Python / Node 环境——先让安装器走完，再按报错补缺口；提前装的版本反而容易和安装器期望版本冲突。

安装器会做什么

安装器主要完成五件事：

1. 检查系统和依赖。
2. 克隆 Hermes Agent 仓库。
3. 创建 Python virtualenv（虚拟环境，把 Hermes 的依赖和系统 Python 隔离）。
4. 注册全局 hermes 命令（在 ~/.local/bin/ 下放一个 symlink 指向真正的入口脚本）。
5. 引导你进入 LLM provider（推理服务商）配置——填 OpenAI / Anthropic / Nous Portal 等家的 API key 或 OAuth 凭据。

安装成功的标准不是「脚本没有红字」，而是 hermes 命令能被当前 shell 找到，并能进入帮助或模型配置。脚本跑通了 ≠ 装好了——下一节验收命令入口才是真的标准。

安装目录

POSIX 系普通用户安装后，先记住这三个位置：

~/.hermes/hermes-agent/    Hermes Agent 源码（仓库本体 + virtualenv）
~/.local/bin/hermes        全局命令入口，通常是指向源码内启动脚本的 symlink
~/.hermes/                 配置、auth、skills、sessions、memory、logs（用户数据，可备份）

如果用 root-mode（sudo curl ... | sudo bash）做系统级安装，官方路径会变成类似：

/usr/local/lib/hermes-agent/    系统级源码位置（FHS 标准）
/usr/local/bin/hermes           系统级命令入口
/root/.hermes/ 或 HERMES_HOME   root 用户数据目录

原生 Windows 安装路径不同：源码放在 %LOCALAPPDATA%\hermes\hermes-agent，自带的 portable Git 放在 %LOCALAPPDATA%\hermes\git，hermes 加进用户级 PATH（不是系统级，不要 admin），数据在 %LOCALAPPDATA%\hermes。装完一定要重启终端或开新 PowerShell 窗口，PATH 才会生效。

个人学习和单用户机器优先用普通用户安装。共享服务器或统一运维场景才考虑 root-mode，并且要单独规划每个用户的 HERMES_HOME 环境变量和密钥边界——不要让所有用户共享一份 ~/.hermes/ 数据。

安装后第一步

POSIX 系安装完成后先重载 shell，让新加进 PATH 的 hermes 命令在当前终端生效。bash 用户：

source ~/.bashrc

zsh 用户：

source ~/.zshrc

原生 Windows 用户关掉当前 PowerShell 窗口、开个新窗口，或在当前窗口运行 $env:Path 看 %LOCALAPPDATA%\hermes 是否在里面。

然后验收命令入口：

hermes --help
hermes model

hermes --help 能输出帮助，说明 PATH 基本没问题。hermes model 能进入交互配置，说明下一步可以配置 provider。

不要一开始全开功能

第一次安装后的顺序应该是：

install -> PATH check -> hermes model -> first chat -> session resume
（安装 → PATH 验证 → 配 provider → 第一次对话 → 会话恢复）

不要反过来先接 Telegram、Discord、Slack、WhatsApp、cron、MCP（模型上下文协议）、skills 或 browser automation（浏览器自动化）。基础对话还没跑通时，功能开得越多，排障越慢——同一个问题既可能在模型层、也可能在 toolset、也可能在 backend，最后变成「哪都可能错」。

常见问题

hermes: command not found

先重载 shell（source ~/.zshrc 或 ~/.bashrc），再检查 ~/.local/bin 是否真的在 PATH 里：

echo $PATH | tr ':' '\n' | grep '\.local/bin'

如果你用的是 zsh 却只改了 .bashrc，当前 shell 不会自动读到——这是最常见误区。原生 Windows 上则是没重启 PowerShell。

API key not set 或 provider 拒绝调用

运行 hermes model 重新配置 provider。密钥应该写入 Hermes 的配置路径（~/.hermes/auth.json 或 .env），不要贴进公开仓库、普通 Markdown、shell 历史命令或团队聊天群——一旦提交进 git 历史就很难真正撤回。

Termux 编译失败

先确认你在 Termux 原生环境里直接执行官方脚本，不是在 Android 上套了不受支持的 Linux 容器（如某些"Linux on Android" 应用）。再看 官方 Termux guide。

原生 Windows：装完了但找不到命令

99% 是 PATH 没刷新。关掉当前 PowerShell 窗口、开新窗口，再 hermes --help。还不行就检查 $env:Path 里有没有 %LOCALAPPDATA%\hermes。

更新后配置异常

先跑诊断命令，让 Hermes 自己告诉你哪里坏了：

hermes doctor
hermes config check

必要时再做配置迁移，不要直接 rm -rf ~/.hermes/——那会一并删掉你所有的 session、memory 和已配的 skill。

安装验收清单

安装完成后至少确认下面 6 条。任何一条不过，先停下排查，不要继续往下接 provider、Gateway 或 cron：

• git --version 正常输出。
• hermes --help 能打印帮助。
• hermes model 能打开 provider 配置交互界面。
• ~/.hermes/ 目录已创建（POSIX）或 %LOCALAPPDATA%\hermes 已创建（Windows native）。
• 你能用一句话解释 config.yaml、.env、skills、sessions、memory 和 logs 大致放在哪里、各管什么。
• 没有把任何 API key 写进公开文件、git 仓库或 shell history。

下一步

官方资料

• Installation 完整页
• Quickstart
• Termux 专项 guide
• Updating & Uninstalling
• GitHub README