---
title: "快速上手 Hermes Agent"
description: "从安装、provider、第一次对话、session 恢复到下一层能力，跑通 Hermes Agent 的最小稳定闭环。"
verifiedAt: "2026-05-09"
---

快速上手的目标**不是**把 Hermes Agent 的所有功能打开，而是得到一个**稳定、可恢复、可排障**的基础对话。只有这个基础闭环稳定，后面的工具、记忆、skills（技能）、Gateway（消息网关）、cron（定时）、MCP（模型上下文协议）和自动化才有意义。

官方资料：[Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)、[Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)、[Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)、[Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands)、[GitHub README](https://github.com/NousResearch/hermes-agent)。

> [!NOTE]
> **先给结论**：第一次只做四件事：① 安装；② 配置一个 provider（推理服务商）；③ 完成一次普通对话；④ 用 `hermes --continue` 恢复 session（会话）。**任何 Gateway、cron、skills、MCP 都放到这四步之后**——基础不稳就开扩展，故障会叠加成「哪都可能错」。

## 最短路径

下面五步是 Hermes 第一次能跑起来必须按顺序通过的检查点。任何一步失败都**停在当前层排障**，不要跳着走：

```mermaid
flowchart LR
    A[1 安装 install.sh] --> B[2 重载 shell<br/>验证 PATH]
    B --> C[3 hermes model<br/>配 provider]
    C --> D[4 hermes<br/>第一次对话]
    D --> E[5 hermes --continue<br/>恢复 session]
    E -.稳定后才开扩展.-> F[Gateway / cron / skills / MCP / 自动化]
    style F fill:#fde2e2,stroke:#c43d3d
```

```bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc   # zsh 用户改用 source ~/.zshrc；原生 Windows 关掉 PowerShell 重开即可
hermes model       # 进入 provider 交互配置
hermes             # 第一次对话
hermes --continue  # 恢复刚才的 session
```

这五步分别验证：① 命令安装、② shell PATH 生效、③ 模型 provider 可用、④ 普通对话能完成、⑤ session 持久化。**任何一步失败就停在当前层排障，不要继续添加新能力**——把锅留小，比把锅留大易修。

## 按目标挑路径

> 与官方 _The fastest path_ 表对照——挑一行最贴合你当前目标的执行：

| 目标 | 先做这一步 | 再做这一步 |
| --- | --- | --- |
| 我只想让 Hermes 在本机能跑 | `hermes setup`（向导式装机） | 跑一次真实对话验证它会回 |
| 我已经知道用哪家 provider | `hermes model`（直接配） | 存好配置，开始聊天 |
| 我想做 bot 或 always-on（常驻）服务 | 先把 CLI 跑稳，再 `hermes gateway setup` | 接 Telegram / Discord / Slack 等平台 |
| 我要用本地或自建模型 | `hermes model` → 选 _custom endpoint_ | 验证 endpoint URL、模型名、上下文长度 |
| 我要多 provider fallback（备用切换） | `hermes model` 先把主路径跑稳 | 基础对话稳定后再加 routing 和 fallback |

> [!IMPORTANT]
> **判断准则**：如果 Hermes 连一次普通对话都跑不通，**不要继续添加任何功能**——先让一次干净的对话工作起来，再分层叠加 Gateway、cron、skills、voice、routing。

## 选择 provider

Provider 是第一次配置里最关键的部分。Hermes 支持的 provider 阵容很广（截至本文核验日，按官方 [Providers 页](https://hermes-agent.nousresearch.com/docs/integrations/providers) 当前列表为准）：

- **国际订阅 / API**：Nous Portal、OpenAI Codex、Anthropic Claude、OpenRouter、AWS Bedrock、NVIDIA NIM、Hugging Face、Vercel AI Gateway、GitHub Copilot（含 ACP）。
- **中国区主流**：Z.AI（GLM / 智谱）、Kimi / Moonshot（含中国区端点）、MiniMax（OAuth / 国际 / 中国区）、Alibaba Cloud Qwen（通义千问 DashScope）、DeepSeek。
- **小众与试验**：Arcee AI、GMI Cloud、Kilo Code、OpenCode Zen / Go 等。
- **自定义 endpoint**：vLLM、SGLang、Ollama、llama.cpp 或任何 OpenAI 兼容 API。

进入交互配置：

```bash
hermes model
```

第一次选择 provider 时按这三个标准：

1. **你最容易拿到稳定凭据**——OAuth 比 API key 更不容易出 typo；国际卡有困难就走中国区 provider。
2. **该 provider 在你当前网络下延迟和可用性稳定**——能复用现有梯子的优先国际，没梯子优先中国区直连。
3. **模型上下文窗口不低于官方要求**——下一段细说。

> [!IMPORTANT]
> **最小上下文 64K tokens**：Hermes 启动时会拒绝上下文窗口 < 64,000 tokens 的模型——长会话、工具调用、文件阅读和 session 恢复都需要足够工作记忆。多数托管模型（Claude / GPT / Gemini / Qwen / DeepSeek）默认满足；本地模型需要显式设：llama.cpp 用 `--ctx-size 65536`，Ollama 用 `-c 65536`。

> [!TIP]
> 选错了不会被锁死——**任何时候都可以 `hermes model` 切换 provider**，配置和 session 都不丢。

## 配置写在哪里

Hermes 把**密钥**和**普通配置**分开放：

```text
~/.hermes/.env         API keys、tokens、secrets（敏感数据，不进 git）
~/.hermes/config.yaml  model、backend、toolsets 等非密钥配置（可进 git）
```

优先用 CLI 写非密钥配置（直接编辑 yaml 容易破坏缩进）：

```bash
# 模型（注意：具体模型名按官方推荐为准，不要在教程里写死版本号）
hermes config set model openrouter/anthropic/claude-sonnet-4
hermes config set terminal.backend docker
```

API key 优先在 `hermes model` 交互里粘贴或写到 `~/.hermes/.env`（`KEY=value` 一行一条）。**不要**手动把密钥复制到教程、README、GitHub issue、公开 gist 或团队聊天记录里——一旦进了 git 历史或聊天截图，撤回成本极高。

## 第一次对话

启动经典 CLI：

```bash
hermes
```

或启动现代 TUI（带鼠标支持的终端 UI，富界面）：

```bash
hermes --tui
```

执行后你会看到 Hermes 的欢迎信息（含当前 provider 和 model 名），下面会出现一个**输入提示符**——直接打字、回车，就是和 Hermes 对话。退出按 `Ctrl+C` 两次（或输入 `/exit` / 按 `Ctrl+D`）。

第一次任务要**小、明确、可验证**。不要一上来让 Hermes 重构项目、部署服务或接管数据库——出错时你分不清问题是模型、prompt、工具还是配置。

推荐第一条 prompt（**复制粘贴到提示符后回车**）：

```text
请检查当前目录，说明这是什么项目，并列出你会先查看的 3 个文件。不要修改任何文件。
```

成功标准（任一不满足就停在这层排障）：

- ✅ 欢迎信息里能看到当前 provider 和 model 名。
- ✅ Hermes 能正常回复，回复内容紧扣你的提问。
- ✅ 没有 API key、网络、context 或 provider 报错。
- ✅ 如果调用了工具，你能看懂它为什么调用（read 哪个文件、跑了什么命令）。
- ✅ 它**没有**在未授权情况下修改文件。

## 验证 session 恢复

完成第一次对话后**立刻**测试恢复：

```bash
hermes --continue
# 短参数等价：
hermes -c
```

如果无法恢复上一轮上下文，先修 session。Hermes 的长期使用全部依赖 session 管理——Gateway、多平台对话、memory、skills 和自动化都需要稳定的会话基础；session 不稳，上层全部白搭。

## 试三个基础能力

**① 只读理解**（最安全的能力，确认模型在做事）：

```text
总结当前目录结构，指出最可能的入口文件。不要修改文件。
```

**② 斜杠命令**（slash commands，CLI 的快捷指令）——输入：

```text
/
```

应该能看到命令补全，常见有 `/help`（帮助）、`/tools`（查看工具）、`/model`（查看 / 切换模型）、`/usage`（用量）、`/insights`（行为洞察）、`/history`（历史 session 列表）、`/clear`（清空当前对话）、`/exit`（退出）（完整清单按官方 [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands) 当前列表为准；实际清单跟 toolset 和已装 skill 联动，每装一个 skill 会自动多一条 `/<skill-name>` 命令）。

**③ 中断**——能中断才能继续试更长任务：

```text
如果任务运行太久，发送一条新消息或按 Ctrl+C 中断。
```

能中断，才适合继续试更长任务；中断不响应说明 TUI 或 session 状态有问题。

## 只在基础闭环稳定后加下一层

<Cards>
  <Card title="工具系统" description="配置 web / terminal / file / browser / memory / cron 等 toolsets——按当前任务最小启用。" href="/docs/hermes/official/01-user-guide/tools" />
  <Card title="记忆系统" description="MEMORY.md（项目记忆）、USER.md（用户偏好）、session_search（历史检索）的写入门槛。" href="/docs/hermes/official/01-user-guide/memory" />
  <Card title="技能系统" description="用 skill 存放可复用工作流和过程性知识——但外部 skill 安装前必须 inspect。" href="/docs/hermes/official/01-user-guide/skills" />
  <Card title="消息网关" description="接 Telegram / Discord / Slack / WhatsApp / Signal / Email / DingTalk / Feishu 等平台前先做 allowlist。" href="/docs/hermes/official/01-user-guide/messaging" />
</Cards>

Gateway、cron 和后台自动化都会**扩大权限面**——基础对话不稳定时不要接。等于在裂缝上加压，故障传导路径会变长难追。

## 常见失败模式

按出现频率从高到低，先看符合自己症状的那条：

- **安装后没有重载 shell** → `hermes: command not found`。POSIX 跑 `source ~/.bashrc` / `~/.zshrc`；原生 Windows 关掉 PowerShell 重开。
- **provider key 写错或写到错位置** → 401/403/拒绝调用。重跑 `hermes model` 走交互配置。
- **本地模型 context 低于 64K** → 启动时直接被拒。给 llama.cpp 加 `--ctx-size 65536`，Ollama 加 `-c 65536`。
- **第一次任务太大** → 出错时无法判断是 provider、工具、prompt 还是 backend 报错。换小任务回测。
- **没验证 `--continue` 就接 Gateway** → Gateway 收到消息但回复丢失。先把单机 session 跑稳。
- **工具权限开太多** → 基础对话报错被 terminal、browser、MCP 的层层报错淹没。临时把 toolset 降到最小再排障。

## Recovery Toolkit · 排障工具集

> 与官方 _Recovery Toolkit_ 段对应——常见故障的恢复命令速查：

```bash
hermes doctor              # Hermes 自查：版本、依赖、配置、权限
hermes config check        # 配置文件语法和必填字段校验
hermes config show         # 打印当前生效配置（注意密钥会脱敏）
hermes model               # 重新走 provider 交互配置
hermes sessions list       # 看历史 session 列表
hermes sessions browse           # 交互浏览历史 session（也可 hermes sessions list 看清单）
# 跨 session 全文搜索由 agent 自己调用 session_search 工具完成（在对话里让它"搜下 X"即可）
```

不到迫不得已**不要 `rm -rf ~/.hermes/`**——它会一并删掉所有 session、memory、已配 skill 和密钥。

## 最小验收

你应该能完成这条链路（**任一步失败就停下排障**）：

```bash
hermes --help     # PATH 生效
hermes model      # 能进 provider 配置
hermes            # 能完成一次普通对话
hermes --continue # 能恢复 session
```

并能回答四个问题：

- 当前使用哪个 provider 和 model？
- 密钥写在哪个文件？（应该是 `~/.hermes/.env`，**不**是 `config.yaml`）
- `config.yaml` 在哪里？里面有什么字段？
- session 能不能恢复？最近一次 session 的 ID 你能找到吗？

回答不了，就继续停在 quickstart，**不要**进入工具系统、记忆、技能、Gateway 或自动化。

## 下一步

<Cards>
  <Card title="规划学习路径" description="跑通基础闭环后，按经验和目标选择后续文档——挑一条贴近你目标的路径开干。" href="/docs/hermes/official/00-getting-started/learning-path" />
  <Card title="第一个稳定闭环" description="想理解为什么不要一开始全开功能是教程铁律，读原理篇的闭环章节。" href="/docs/hermes/understanding/02-first-stable-loop" />
</Cards>

## 官方资料

- [Quickstart 完整页](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)（含视频版）
- [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)
- [Providers 完整目录](https://hermes-agent.nousresearch.com/docs/integrations/providers)
- [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands)
- [GitHub README](https://github.com/NousResearch/hermes-agent)
