快速上手 Hermes Agent

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

官方资料：Quickstart、Configuration、Providers、Slash Commands Reference、GitHub README。

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

最短路径

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

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

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

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

选择 provider

Provider 是第一次配置里最关键的部分。Hermes 支持的 provider 阵容很广（截至本文核验日，按官方 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。

进入交互配置：

hermes model

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

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

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

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

配置写在哪里

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

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

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

# 模型（注意：具体模型名按官方推荐为准，不要在教程里写死版本号）
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：

hermes

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

hermes --tui

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

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

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

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

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

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

验证 session 恢复

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

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

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

试三个基础能力

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

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

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

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

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

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

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

安装后没有重载 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 段对应——常见故障的恢复命令速查：

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 和密钥。

最小验收

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

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

并能回答四个问题：

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

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

快速上手 Hermes Agent

最短路径

按目标挑路径

选择 provider

配置写在哪里

第一次对话

验证 session 恢复

试三个基础能力

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

工具系统

记忆系统

技能系统

消息网关

常见失败模式

Recovery Toolkit · 排障工具集

最小验收

下一步

规划学习路径

第一个稳定闭环

官方资料

本页目录