Hermes Agent 安装教程：从零装到能聊天（手把手 · 2026 实测）

Hermes Agent 是 Nous Research 出的一个「终端里的 AI 智能体」：它不只会聊天，还能读写你电脑上的文件、执行命令、上网查资料、跑定时任务，还能接到 Telegram、Discord 这些聊天软件上，手机也能用。

这篇教程按我自己装一遍的顺序写，每一步都有命令，遇到会卡住的地方我都标了出来。照这个顺序做，20 分钟内能跑起来第一次对话。本文在 Linux（Debian 系）上实测，版本 v0.19.0，macOS / WSL2 的命令完全一样，Windows 原生和安卓 Termux 我单独标注。

一、开工前先搞清三件事

别看教程长，装之前只需要想清楚三个问题，它们决定后面走哪条路：

装在哪台机器：Linux / macOS / WSL2 最顺；Windows 原生也支持（用 PowerShell / 有专门的安装命令）；安卓可以装在 Termux 里。
用哪个模型：这是唯一真正会卡住新手的步骤。不想折腾就去开 Nous Portal 订阅，一条命令搞定；要用自己的 Key（OpenRouter、DeepSeek、Kimi、智谱、Gemini 等）也完全可以，后面有对照表。
要不要接聊天软件：建议先别接。命令行聊通了，再花 5 分钟接 Telegram。顺序反过来最容易出现「装好了但没人能给它发消息」的挫败。

另外有一条硬门槛先记住：模型上下文至少 64K（64000 tokens）。低于这个数的模型 Hermes 会直接拒绝启动——它要多步调用工具，上下文太小记不住事。主流的云端模型都远超这个值；自己跑本地模型时记得把上下文调够（llama.cpp 用 --ctx-size 65536，Ollama 用 -c 65536）。

二、准备环境（大部分东西不用你装）

安装脚本会自动处理 Python、Node.js、ripgrep、ffmpeg 这些依赖，你唯一需要确认的是 git 已经装好，Linux 上再多两个小工具：

git --version

# Debian / Ubuntu 上如果没装，先补这几个
sudo apt update && sudo apt install -y git curl xz-utils

# 如果之后要装带界面的桌面版，还需要编译工具
sudo apt install -y build-essential

macOS 上如果提示缺 git，装一次 Xcode 命令行工具即可：xcode-select --install。

三、安装：一条命令

Linux / macOS / WSL2 / 安卓 Termux

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows 原生

在 PowerShell 里运行：

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

想要图形界面版

去官网下载 Hermes Desktop 安装包，双击安装即可（macOS 版仅支持 Apple Silicon，Intel 芯片的 Mac 不在支持范围内）。已经用命令行装过的，随时可以补上桌面端：hermes desktop。

安装脚本干了什么

它会自动完成：装 uv（Python 包管理器）→ 用 uv 装 Python 3.11 环境 → 装 Node.js（浏览器自动化、WhatsApp 桥接要用）→ 装 ripgrep 和 ffmpeg → 克隆仓库 → 建虚拟环境 → 把 hermes 命令放到你的 PATH → 引导你配置模型服务商。

装到哪里了

安装方式	代码位置	hermes 命令	数据目录
普通用户安装（推荐）	`~/.hermes/hermes-agent/`	`~/.local/bin/hermes`	`~/.hermes/`
root 安装（共享机器）	`/usr/local/lib/hermes-agent/`	`/usr/local/bin/hermes`	`/root/.hermes/`

装完必须做的一步

source ~/.bashrc     # zsh 用户改成 source ~/.zshrc
hermes --version     # 有版本号输出就说明装好了

卡住的话：提示 hermes: command not found，八成是没重新加载 shell，或者 ~/.local/bin 不在 PATH 里。执行 export PATH="$HOME/.local/bin:$PATH"，再把这一行写进 ~/.bashrc。国内网络如果 curl 拉不下来，先给终端挂个代理再跑安装命令，比如 export https_proxy=http://127.0.0.1:7890。

四、选模型、填 Key（最容易卡住的一步）

进入交互式选择：

hermes model

最省事的走法：Nous Portal

一个订阅覆盖 300 多个模型，还顺带打开「工具网关」（联网搜索、图像生成、语音合成、云浏览器都不再单独要 Key）：

hermes setup --portal

这一条命令会帮你登录、把 Nous 设为服务商、打开工具网关。

首次运行 `hermes setup` 会给你三个模式

Quick Setup（推荐）：用 Nous Portal 的 OAuth 登录，不用管 API Key，模型和工具一次配好。
Full Setup：每一项都自己选，适合自带 Key 的人。
Blank Slate（空白起步）：只保留最基本的推理 + 文件工具 + 终端工具，联网、浏览器、记忆、技能、定时任务等一律不启用；适合想要极简、完全可控的 agent。之后可以用 hermes tools 逐个打开。

自带 Key 的常用服务商对照

服务商	怎么配
OpenRouter	填入 API Key（多模型统一入口，新手友好）
Anthropic（Claude）	OAuth 登录（需要 Max 套餐 + 额外额度）或直接填 API Key
OpenAI Codex	设备码授权登录，用 Codex 系列模型
DeepSeek	设 `DEEPSEEK_API_KEY`
Kimi / Moonshot	设 `KIMI_API_KEY`（国内版 `KIMI_CN_API_KEY`）
智谱 GLM / Z.AI	设 `GLM_API_KEY` 或 `ZAI_API_KEY`
Google Gemini	设 `GOOGLE_API_KEY` 或 `GEMINI_API_KEY`
xAI（Grok）	设 `XAI_API_KEY`，或走 SuperGrok 订阅的 OAuth
阿里云百炼（Qwen）	设 `DASHSCOPE_API_KEY`
本地模型（Ollama / LM Studio / vLLM）	选 Custom Endpoint，填 base URL + Key（本地可随便填），确认模型名和上下文长度

配置存在哪、怎么改

Hermes 把机密和普通配置分开存，这一点值得养成习惯：

密钥 / Token → ~/.hermes/.env
普通设置 → ~/.hermes/config.yaml

改配置最稳的方式是用命令行，它会自动帮你写到正确的文件里：

hermes config set model anthropic/claude-opus-4.6
hermes config set OPENROUTER_API_KEY sk-or-xxxxxxxx
hermes config get model

千万不要把 API Key 写进 config.yaml。那个文件是准备给你备份、分享、甚至提交到 git 的，而 .env 是只给你自己看的。

五、第一次对话，以及怎么算装好了

hermes            # 经典命令行界面
hermes --tui      # 新版 TUI 界面（推荐，能用鼠标选中、界面更清爽）

进去之后会看到一条欢迎横幅，上面写着当前用的模型、可用工具和技能。先用一句容易验证的话试水，别一上来就让它重构项目：

当前目录下有哪些文件？哪个看起来是这个项目的主入口？
把当前磁盘占用前 5 名的目录列出来。

这四点都满足，说明你装对了：

横幅上显示的模型和服务商是你刚选的那个；
Hermes 能正常回复，不报错、不空白；
它真的调用了一次工具（终端、读文件、联网搜索）；
能连续聊好几轮，不是只回一句就断。

想接着上次的会话继续：

hermes --continue     # 简写 hermes -c

六、先把这几条命令抄下来

命令	作用
`hermes`	开始聊天
`hermes --tui`	新版界面（推荐）
`hermes model`	换服务商 / 换模型
`hermes setup`	完整配置向导
`hermes tools`	按平台开关工具
`hermes doctor`	体检、诊断问题
`hermes update`	升级到最新版
`hermes gateway`	启动消息网关（接聊天软件）
`hermes sessions list`	查看历史会话
`hermes --continue`	继续上次会话
`hermes config set/get`	改 / 看单项配置
`hermes backup` / `hermes import`	整机备份 / 换机器恢复

聊天界面里还有几个快捷操作值得先试：

输入 / 会弹出所有斜杠命令：/help 帮助、/tools 看工具、/model 当场换模型、/save 存会话。
多行输入：Alt+Enter 或 Ctrl+J（所有终端都支持）；Shift+Enter 要看终端是否支持。
它跑太久想打断：直接输入新消息回车，当前任务会被打断并切到你的新指令；Ctrl+C 也可以。

七、进阶第一步：接到 Telegram（手机也能用）

命令行玩顺了再来这一步。整个过程 5 分钟：

1. 找 @BotFather 建机器人

在 Telegram 里搜 @BotFather → 发送 /newbot → 起个显示名（随便写）→ 起个用户名（必须以 bot 结尾，比如 my_hermes_bot）→ BotFather 会给你一串 Token，长这样：

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

这个 Token 等于机器人密码，任何人拿到都能控制你的机器人，别截图发群里。万一泄露了，在 BotFather 里用 /revoke 立刻作废重发。

2. 拿到你自己的数字 ID

注意：是你的数字 ID，不是用户名。给 @userinfobot 发条消息，它会立刻回你一串数字，记下来。

3. 让 Hermes 接上它

hermes gateway setup      # 选 Telegram，按提示填 Token 和你的数字 ID

不想走向导也可以手写配置，加到 ~/.hermes/.env：

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

TELEGRAM_ALLOWED_USERS 就是白名单，一定要填，多个用户用逗号分隔。不填等于把你的机器人开放给所有人，别人一搜到就能指挥它跑命令。

4. 启动

hermes gateway

几秒钟后机器人就上线了，在 Telegram 里给它发条消息试试。

顺手做两个可选优化：用 BotFather 的 /setcommands 配上命令菜单（help、new、sethome 就够用）；在群里想让它看到所有消息，得关掉 Privacy Mode（默认它是看不到群消息的）。

八、安全设置：别让它乱动你的系统

AI 智能体能执行命令，这既是它的价值也是风险点。花两分钟做这几件事：

陌生项目里别开 --yolo。默认情况下危险命令会先问你，这个确认千万别嫌烦。
用沙箱跑：让终端在 Docker 容器里执行，或干脆放到一台单独的机器上。

hermes config set terminal.backend docker    # 容器隔离
hermes config set terminal.backend ssh       # 远程机器执行

密钥只放 ~/.hermes/.env，别进配置文件、别进聊天记录。
白名单必填：就像上面 Telegram 那步，任何时候都别留「谁都能用」的口子。

九、常见故障速查（新手最容易踩的）

现象	多半是	怎么办
`hermes: command not found`	PATH 没加载	`source ~/.bashrc`，或手动加 `~/.local/bin`
能启动，但回复空白 / 报错	服务商鉴权或模型选错	重跑 `hermes model`，确认服务商、模型名、Key
自定义端点"能通"但输出乱码	base URL 或模型名不对，或压根不兼容 OpenAI 协议	换个客户端先验证端点，再回来填
网关起来了，但没人能发消息	Token、白名单或平台配置没完成	重跑 `hermes gateway setup`，再看 `hermes gateway status`
`hermes --continue` 找不到会话	换了 profile，或会话根本没保存	`hermes sessions list` 确认，检查是不是同一个 profile
模型时好时坏、偶尔降级	fallback / 路由配得太激进	先把路由和降级关掉，基础聊天稳了再加

感觉哪里不对时的恢复顺序（照着敲一遍，基本都能回到已知状态）：

hermes doctor
hermes model
hermes setup
hermes sessions list
hermes --continue
hermes gateway status

十、基础跑通后，最值得先试的几个能力

不要一次全开，按需加：

技能（Skills）：SKILL.md 形式的操作手册，装好之后自动变成斜杠命令。hermes skills browse 看有什么、hermes skills search kubernetes 搜、hermes skills install openai/skills/k8s 装（安装前会先做安全扫描）。装完在对话里直接 /k8s 部署到测试环境 就行。

hermes skills browse
hermes skills search docker

定时任务：等网关或命令行稳定了再上，可以让它每天早上汇总指定内容发到你手机上。
语音模式：

cd ~/.hermes/hermes-agent
uv pip install --python ./venv/bin/python -e ".[voice]"

装完在对话里 /voice on，按 Ctrl+B 开始录音（自带本地语音识别，不用额外花钱）。

接 MCP 服务器（比如 GitHub 官方 MCP），写进 ~/.hermes/config.yaml：

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxx"

编辑器集成：跑 hermes acp，就能在支持的编辑器里直接用（标准安装已包含该组件）。

十一、升级、卸载、换机器

hermes update                     # 升级到最新版
hermes backup                     # 完整备份（含配置和历史）
hermes import                     # 在新机器上恢复
hermes uninstall                  # 卸载

换电脑不用重装重配：hermes backup 出来的包在另一台机器上 hermes import 就能接着用。