技爪网
技爪网

技术问题排障知识库

首页/软件安装与配置/Hermes Agent 上手指南：安装、模型配置、网关接入与第一次真正跑起来
软件安装与配置

Hermes Agent 上手指南：安装、模型配置、网关接入与第一次真正跑起来

这篇文章不讲空概念，只解决一个问题：你把 Hermes Agent 装上之后，怎么尽快把它真正跑起来。从安装、模型配置、CLI 使用到 Gateway 接入，一步步带你打通。

发布时间：2026年4月10日 16:21阅读量：1

这篇文章不讲空概念，只解决一个问题：

你把 Hermes Agent 装上之后，怎么尽快把它真正跑起来。

Hermes 官方文档给出的路径其实很清晰：先安装，再选模型/provider，然后用 CLI 或 Messaging Gateway 进入第一次会话。它支持 Linux、macOS、WSL2 和 Android/Termux；原生 Windows 目前不支持，Windows 用户要先装 WSL2。

官方还提供了交互式 hermes setup、hermes model、hermes gateway setup 等命令，把安装、模型配置、消息入口配置都串起来了。

如果你是第一次接触 Hermes，可以把它理解成两种入口：

  • CLI 入口：直接在终端里用 hermes 开聊
  • Gateway 入口：把 Hermes 接到 Telegram、Discord、Slack、WhatsApp 等平台，然后通过消息入口跟它对话

官方 README 也明确把这两条路分开列了出来。

一、先弄明白：Hermes 到底是怎么跑起来的

Hermes 真正工作起来，通常要打通这几层：

  1. 程序已安装
  2. 至少有一个可用的 LLM provider
  3. 终端/工具权限基本可用
  4. 你选择了 CLI 或 Gateway 作为入口

官方 Quickstart 也是按这个顺序来的：安装 Hermes、设置 provider、开始聊天，然后再去尝试终端工具、网关接入和定时任务。

这点很重要，因为很多新手的误区是：

以为安装成功就等于已经能用了。

实际上，Hermes 只是把程序装到了你的机器上；真正能不能干活，还取决于你有没有配好模型，以及你准备从终端还是消息入口使用它。

二、安装 Hermes Agent：最快的方式是什么？

官方给出的最快安装方式是一行命令：

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

安装完成后，重新加载 shell：

bash
source ~/.bashrc  # 或 source ~/.zshrc

然后你就可以直接输入：

bash
hermes

来启动终端聊天界面。官方 Quickstart 和 README 都给了这条安装路径。

支持哪些系统？

按 Hermes 官方文档，目前快速安装主要覆盖：

  • Linux
  • macOS
  • WSL2
  • Android / Termux

而 Windows 原生环境不支持，官方要求 Windows 用户先安装 WSL2，再在 WSL2 终端里执行安装命令。

如果你不想走一键安装呢？

官方也提供了完整的手动安装路径，包括：

bash
git clone --recurse-submodules
用 uv 创建 Python 3.11 虚拟环境
uv pip install -e ".[all]"

如果你只想装核心 agent，不需要 Telegram/Discord/cron 等附加能力，也可以只装基础依赖。浏览器自动化和 WhatsApp bridge 则需要额外安装 Node.js 依赖。

三、安装之后第一步，不是乱试命令，而是先配模型

Hermes 至少要有一个可用的 LLM provider，才能真正工作。官方文档写得很直接：

You need at least one provider configured to use Hermes.

最简单的做法，就是运行：

bash
hermes model

或者直接跑完整向导：

bash
hermes setup

如果你只想配置某一部分，也可以这样：

bash
hermes setup model

这些命令都来自 Hermes 官方 Quickstart 和 CLI 命令参考。

Hermes 支持哪些 provider？

官方文档列出的主流路径包括：

| Provider | 配置方式 | |----------|---------| | Nous Portal | OAuth，订阅型 | | OpenAI Codex | ChatGPT OAuth | | Anthropic | 可用 Claude Code auth 或 Anthropic API key | | OpenRouter | 通过 API key 接很多模型 | | GitHub Copilot | OAuth | | Z.AI / GLM | API key | | Kimi / Moonshot | API key | | 自定义 endpoint | Ollama、vLLM 等自托管方案 |

如果你是新手，我建议你这样选：

  • 想最省事：优先试 hermes model
  • 已经有 OpenRouter key：直接走 OpenRouter
  • 想跑本地模型：走 Ollama 或自定义 endpoint
  • 你本来就有 Claude / Codex / Copilot 路线：直接按官方向导选对应 provider

四、最稳的入门方案：先用 OpenRouter 跑通

如果你的目标是先把 Hermes 跑起来，而不是一上来就追求最复杂的本地部署，那么 OpenRouter 往往是最省心的一条路。

官方文档把它列为一类标准云端 provider，通常通过 API key 配置；安装文档的 troubleshooting 里也把 API key not set 的修复指向了 hermes model 或直接配置 key。

最简单的做法是：

bash
hermes model

然后在交互向导里选 OpenRouter，填入你的 API key 和模型。

如果你更习惯自己配环境变量，也可以按官方文档把 key 放进 ~/.hermes/.env。

五、如果你想跑本地模型，Ollama 是最容易上手的一条路

Hermes 官方文档专门给了 Ollama 集成说明，而且把它称为 Local Models, Zero Config。

典型流程是：

先拉模型并启动 Ollama：

bash
ollama pull qwen2.5-coder:32b
ollama serve

然后运行：

bash
hermes model

选择：

  • Custom endpoint (self-hosted / VLLM / etc.)
  • URL 填 http://localhost:11434/v1
  • API key 这一步可以跳过
  • 模型名填你本地的模型，比如 qwen2.5-coder:32b

这些步骤都来自 Hermes 官方 provider 文档。

但本地模型有一个特别容易翻车的点：上下文长度

Hermes 官方文档明确提醒：

Ollama 默认上下文长度往往太低。对于带工具调用的 agent 场景，至少建议 16k–32k；如果只有 4k，上来就可能被 system prompt 和 tool schema 占满。

官方甚至直接说：这是一号集成误区。

所以你最好在启动 Ollama 时显式设置：

bash
OLLAMA_CONTEXT_LENGTH=32768 ollama serve

或者把 num_ctx 写进自定义 Modelfile。官方还建议用 ollama ps 看 CONTEXT 列确认是否生效。

这一步非常关键。很多人以为本地模型接上了，结果 Hermes 一跑工具就变傻，大概率不是 Hermes 坏了，而是上下文窗口太短。

六、第一次真正开聊：CLI 模式怎么用？

当模型/provider 配好后，最直接的入口就是：

bash
hermes

官方 Quickstart 写得很简单：输入这条命令后，你会看到欢迎界面，其中会显示当前模型、可用工具和技能；接着直接输入消息并按 Enter 就可以开始对话。

官方还给了一个典型示例：让 Hermes 帮你查看磁盘使用情况和最大的目录。

你第一次测试时，不要一上来就让它干特别复杂的事情。

更建议按这个顺序来：

  1. 先发一句普通问题
  2. 再让它做一个终端类的小任务
  3. 再试 Slash Commands
  4. 最后再折腾 Gateway

这样能最快确认：

  • 模型能回话
  • 工具能调用
  • 终端 backend 没有明显问题

七、终端权限这件事，一开始要保守一点

Hermes 默认的 terminal backend 是：

yaml
terminal:
  backend: local

官方配置文档说明，local 模式下，命令会直接在你的机器上运行，而且没有隔离；它拥有和你当前用户同等的文件系统访问能力。文档也明确提醒：如果你不想让工具权限这么直接，可以用 hermes tools 关掉不想开的工具，或者把 backend 切到 Docker。

新手更稳的建议

如果你只是第一次体验，可以先用本地模式测试。

但如果你准备让 Hermes 真的跑命令、改文件、长期挂着，建议尽快考虑 Docker 隔离：

bash
hermes config set terminal.backend docker

官方 Quickstart 也把 Docker 和 SSH 明确列为更安全的运行方式。

这点很重要，因为 Hermes 不是只能聊天，它是真的会调工具、跑命令。

你越早建立权限边界的意识，后面越不容易慌。

八、接入 Gateway：让 Hermes 不只活在终端里

如果你想通过手机或聊天平台跟 Hermes 对话，就要用到 Gateway。

Hermes 官方文档把 Messaging Gateway 定义为一个长期运行的进程：它负责接收来自各个平台的消息、把会话路由到对应 session store，并且还会顺带运行 cron scheduler。

最简单的网关配置方式

先执行：

bash
hermes gateway setup

这是官方推荐的交互式配置方式。它会让你用方向键选择平台、配置必要参数，并在结束时询问你是否启动或重启 gateway。

如果你想把 Gateway 安装成服务，则可以用：

bash
hermes gateway install
hermes gateway start
hermes gateway status

官方 CLI 参考说明：

  • install：安装成用户服务（Linux 是 systemd user service，macOS 是 launchd）
  • start：启动服务
  • status：查看状态
  • restart / stop：重启或停止服务

这些命令都写在官方 CLI reference 和 Messaging Gateway 文档里。

第一次接网关，推荐怎么做？

我的建议是：

  1. 先用 CLI 跑通
  2. 再选一个你最熟的平台接入
  3. 不要第一次就同时配 4 个平台

因为 Gateway 是入口扩展，不是基础可用性的前提。

先确认 Hermes 在终端里能工作，再让它进入 Telegram、Slack 或 Discord，会稳很多。

九、CLI 和 Gateway 的使用习惯，有什么不一样？

Hermes 官方 README 把这两种入口并列说明了：

  • CLI 下，直接 hermes
  • Messaging 平台下，先 hermes gateway setup + hermes gateway start，然后给 bot 发消息

同时，很多 Slash Commands 是共通的，比如：

| 命令 | 作用 | |------|------| | /new 或 /reset | 开新会话 | | [provider:model] | 切模型 | | /retry | 重试 | | /undo | 撤销 | | /compress | 压缩上下文 | | /usage | 查看用量 | | /skills | 管理技能 |

这些都在官方 README 里列得很清楚。

所以你可以把它理解成：

CLI 是本地驾驶舱，Gateway 是远程入口。

两边的核心能力并没有完全割裂，只是使用场景不同。

十、第一次跑起来后，最值得你立刻做的 4 件事

1）确认当前模型真的能正常回答

最简单的方式就是直接问一句话，不要一上来就让它跑复杂任务。

如果连普通对话都不稳，先回头查 provider。

2）确认终端 backend 是你想要的

默认是 local，但这意味着 Hermes 直接碰你的机器。

如果你打算长期用，尽快考虑 Docker。

3）确认工具开关是否合理

官方 Quickstart 直接给了：

bash
hermes tools

这个命令可以配置不同平台可用的工具。

4）确认 Gateway 是否真的在运行

如果你已经接了消息平台，但 bot 没回应，优先看：

bash
hermes gateway status

这是最直接的第一步。

十一、常见问题：为什么装好了还是跑不起来？

最常见的几类原因，其实官方文档都已经暗示了：

问题 1：hermes: command not found

安装文档的 troubleshooting 里明确写了，先重新加载 shell，或者检查 PATH。

问题 2：API key / provider 没配好

官方建议直接跑：

bash
hermes model

如果还是不稳，再看 config 或 ~/.hermes/.env。

问题 3：本地 Ollama 虽然接上了，但工具调用很差

优先怀疑 context length，不要先怀疑 Hermes。

问题 4：Gateway 配完了但没反应

先看服务是不是启动了，而不是立刻重装。

问题 5：不知道哪里出问题

直接运行：

bash
hermes doctor

官方安装文档明确说，这个命令会告诉你缺了什么、该怎么修。

十二、给新手的一条最稳路线

如果你不想被一堆选项绕晕，我建议你按下面这个顺序来：

路线 A：最快跑通

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

先装、先选 provider、先在 CLI 开始对话。

路线 B：想玩本地模型

bash
ollama pull qwen2.5-coder:32b
OLLAMA_CONTEXT_LENGTH=32768 ollama serve
hermes model
hermes

在 hermes model 里把 endpoint 指向 http://localhost:11434/v1，API key 留空。

路线 C：想从手机上直接用

bash
hermes model
hermes gateway setup
hermes gateway install
hermes gateway start

然后去你接入的平台给 bot 发消息。

十三、本文结论

如果你只想记住一句话，那就是：

Hermes 真正跑起来，不是装完就结束，而是安装 + provider + 入口三步打通。

最稳的顺序始终是：

  1. 先装 Hermes
  2. 先配一个可用模型
  3. 先在 CLI 里验证
  4. 再接 Gateway
  5. 再去考虑 Docker、SSH、Cron、Skills 这些更高级的东西

官方文档其实已经把路铺好了。你真正要做的，不是一上来全懂，而是先跑通第一条链路。

问题求助

没能解决你的问题？直接问我

如果你遇到任何技术问题无法解决，可以在这里提交求助。我会尽快查看并回复你。

支持作者

如果这篇文章帮到了你，可以支持我

扫码打赏，支持我持续更新原创排障文章。

打赏二维码