本指南带你从零开始搭建一个能够应对实际使用的 Hermes 环境。完成安装、选择 provider（服务提供商）、验证对话正常运行，并了解出现问题时的处理方法。

适用人群

• 全新用户，想以最短路径完成可用配置
• 正在切换 provider，不想因配置错误浪费时间
• 为团队、机器人或长期运行的工作流配置 Hermes
• 厌倦了"安装成功但什么都做不了"的情况

最快路径

根据你的目标选择对应行：

目标	先做这步	再做这步
只想让 Hermes 在本机跑起来	hermes setup	运行一次真实对话并验证有响应
已知道要用哪个 provider	hermes model	保存配置，然后开始聊天
想搭建机器人或长期运行的服务	CLI 正常后运行 hermes gateway setup	接入 Telegram、wx、飞书 或其他平台
想使用本地或自托管模型	hermes model → 自定义 endpoint	验证 endpoint、模型名称和上下文长度
想要多 provider 故障转移	先运行 hermes model	基础对话正常后再添加路由和故障转移

经验法则： 如果 Hermes 无法完成一次正常对话，暂时不要添加更多功能。先让一次完整对话跑通，再逐步叠加 gateway、cron、skills、语音或路由。

1. 安装 Hermes Agent

一行安装命令（Linux / macOS / WSL2）

基于 git 的安装方式，跟踪 main 分支，可立即获取最新变更：

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

Windows（原生，PowerShell）— 早期 Beta

早期 BETA

原生 Windows 支持处于早期 beta 阶段。常见路径下可正常安装和运行，但尚未像我们的 POSIX 安装程序那样经过广泛测试。遇到问题请提交 issue。目前在 Windows 上最稳定的方案是在 WSL2 内使用上方的 Linux/macOS 一行命令。

打开 PowerShell 并运行：

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

安装步骤如下：

执行安装命令后，等待安装：

等待环境安装与hermes安装成功后，会出现如下提示：

默认选择第一个快速配置即可：

选择快速配置后，会出现如下提示，该提示为选择你的模型供应商，选择对应模型，并按照提示输入base url与api key 即可

配置好后，选择终端运行方式（默认本地）与消息推送平台（即接入平台）

这里推荐选择微信：

选择微信后，会生成一个二维码，用本人微信扫码即可完成链接：

复制浏览器打开即可扫码绑定：

绑定后，其他配置默认即可，配置后即可完成安装。

安装程序处理一切：uv、Python 3.11、Node.js 22、ripgrep、ffmpeg，以及一个便携式 Git Bash（PortableGit——一个自包含的 Git-for-Windows 发行版，附带 bash.exe 和 Hermes 用于 shell 命令的完整 POSIX 工具链；

在 32 位 Windows 上安装程序会回退到 MinGit，后者缺少 bash，终端工具和 agent 浏览器功能将被禁用）。它将仓库克隆到 %LOCALAPPDATA%\hermes\hermes-agent，创建虚拟环境，并将 hermes 添加到用户 PATH。安装完成后请重启终端（或打开新的 PowerShell 窗口）以使 PATH 生效。

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

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

2. 选择 Provider

这是最重要的配置步骤。使用 hermes model 以交互方式完成选择：

hermes model

推荐默认选项：

Provider	说明	配置方式
Nous Portal	订阅制，零配置	通过 hermes model 进行 OAuth 登录
OpenAI Codex	ChatGPT OAuth，使用 Codex 模型	通过 hermes model 进行设备码认证
Anthropic	直接使用 Claude 模型——Max 计划 + 额外用量积分（OAuth），或按 token 付费的 API key	hermes model → OAuth 登录（需要 Max + 额外积分），或 Anthropic API key
OpenRouter	跨多个 provider 的多模型路由	输入 API key
Z.AI（公司在用）	GLM / Zhipu 托管模型	设置 GLM_API_KEY / ZAI_API_KEY
Kimi / Moonshot	Moonshot 托管的编程和对话模型	设置 KIMI_API_KEY（或 Kimi-Coding 专用的 KIMI_CODING_API_KEY）
Kimi / Moonshot China	中国区 Moonshot endpoint	设置 KIMI_CN_API_KEY
Arcee AI	Trinity 模型	设置 ARCEEAI_API_KEY
GMI Cloud	多模型直连 API	设置 GMI_API_KEY
MiniMax (OAuth)	通过浏览器 OAuth 使用 MiniMax-M2.7，无需 API key	hermes model → MiniMax (OAuth)
MiniMax	国际版 MiniMax endpoint	设置 MINIMAX_API_KEY
MiniMax China	中国区 MiniMax endpoint	设置 MINIMAX_CN_API_KEY
Alibaba Cloud	通过 DashScope 使用 Qwen 模型	设置 DASHSCOPE_API_KEY
Hugging Face	通过统一路由器使用 20+ 开源模型（Qwen、DeepSeek、Kimi 等）	设置 HF_TOKEN
AWS Bedrock	通过原生 Converse API 使用 Claude、Nova、Llama、DeepSeek	IAM 角色或 aws configure（指南）
Kilo Code	KiloCode 托管模型	设置 KILOCODE_API_KEY
OpenCode Zen	按需付费访问精选模型	设置 OPENCODE_ZEN_API_KEY
OpenCode Go	$10/月订阅，访问开源模型	设置 OPENCODE_GO_API_KEY
DeepSeek	直接访问 DeepSeek API	设置 DEEPSEEK_API_KEY
NVIDIA NIM	通过 build.nvidia.com 或本地 NIM 使用 Nemotron 模型	设置 NVIDIA_API_KEY（可选：NVIDIA_BASE_URL）
GitHub Copilot	GitHub Copilot 订阅（GPT-5.x、Claude、Gemini 等）	通过 hermes model 进行 OAuth，或设置 COPILOT_GITHUB_TOKEN / GH_TOKEN
GitHub Copilot ACP	Copilot ACP agent 后端（在本地启动 copilot CLI）	hermes model（需要 copilot CLI + copilot login）
Vercel AI Gateway	Vercel AI Gateway 路由	设置 AI_GATEWAY_API_KEY
Custom Endpoint	VLLM、SGLang、Ollama 或任何兼容 OpenAI 的 API	设置 base URL + API key

对于大多数初次使用的用户：选择一个 provider，接受默认值（除非你明确知道为何要修改）。

你可以随时通过 hermes model 切换 provider——没有锁定。

配置的存储方式

Hermes 将密钥与普通配置分开存储：

• 密钥和 token → ~/.hermes/.env
• 非密钥配置 → ~/.hermes/config.yaml

通过 CLI 设置值是最简便的方式，系统会自动将值写入正确的文件：

hermes config set model anthropic/claude-opus-4.6hermes config set terminal.backend dockerhermes config set OPENROUTER_API_KEY sk-or-...

3. 运行第一次对话

hermes            # 经典 CLIhermes --tui

你会看到一个欢迎横幅，显示你的模型、可用工具和 skills。使用一个具体且易于验证的 prompt（提示词）：

成功的标志：

• 横幅显示你选择的模型/provider
• Hermes 无错误地回复
• 需要时能够使用工具（终端、文件读取、网页搜索）
• 对话可以正常进行超过一轮

如果以上都正常，你已经过了最难的部分。

4. 验证会话功能

继续之前，确认恢复功能正常：

hermes --continue    # 恢复最近的会话hermes -c            # 简写形式

这应该会带你回到刚才的会话。如果不行，检查你是否在同一个 profile 下，以及会话是否实际已保存。当你同时管理多个配置或多台机器时，这一点很重要。

5. 尝试核心功能

斜杠命令

输入 / 查看所有命令的自动补全下拉列表：

命令	功能
/help	显示所有可用命令
/tools	列出可用工具
/model	交互式切换模型
/personality pirate	尝试一个有趣的人格
/save	保存对话

多行输入

按 Alt+Enter、Ctrl+J 或 Shift+Enter 换行。Shift+Enter 需要终端能将其作为独立序列发送（Kitty / foot / WezTerm / Ghostty 默认支持；iTerm2 / Alacritty / VS Code 终端需启用 Kitty 键盘协议）。Alt+Enter 和 Ctrl+J 在所有终端中均可使用。

中断 Agent

如果 agent 响应时间过长，输入新消息并按 Enter——这会中断当前任务并切换到你的新指令。Ctrl+C 同样有效。

6. 添加下一层功能

仅在基础对话正常后进行。按需选择：

机器人或共享助手

hermes gateway setup    # 交互式平台配置

接入授权的聊天工具或办公软件中

自动化与工具

• hermes tools — 按平台调整工具访问权限
• hermes skills — 浏览并安装可复用的工作流
• Cron — 仅在机器人或 CLI 配置稳定后使用

沙箱终端

为了安全起见，在 Docker 容器或远程服务器中运行 agent：

hermes config set terminal.backend docker    # Docker 隔离hermes config set terminal.backend ssh       # 远程服务器

Skills&MCP

Skill 是 Hermes 中以 SKILL.md（或同类标记文件）定义的可复用工作流与知识模块，本质是注入到 Agent 上下文的增强提示词 + 可选脚本。

• 作用：教 Agent "如何完成某类特定任务"——包含触发条件、思考步骤、注意事项、配套脚本/模板。
• 性质：纯提示词扩展，运行在 Agent 的上下文窗口内，不自己启动外部服务。
• 举例：定义一个 code-review.skill.md教 Hermes 按团队的规范走查 PR；定义 deploy-staging.skill.md描述部署前的检查清单和执行的 shell 脚本。
• 特点：按需加载（匹配任务时才注入上下文），节省 Token，适合封装领域知识、SOP、多步骤工作流。

MCP 是 Anthropic 提出的开放标准协议（AI 界的 USB-C 接口），Hermes 通过它连接外部 MCP Server，把第三方服务暴露为 Agent 可调用的 Tool。

• 作用：让 Hermes "访问外部系统并执行实际操作"——文件系统、数据库、GitHub、Slack、内部 API 等。
• 性质：Client-Server 架构，Hermes（Client）连接 MCP Server（stdio 或 HTTP），动态发现工具、资源、Prompt 模板，底层仍通过 Function Calling 调用。
• 举例：配置 @modelcontextprotocol/server-filesystem让 Hermes 读写指定目录；配置 GitHub MCP Server 让 Hermes 查 Issue / 创建 PR。
• 特点：标准化接入、免为每个服务写专用适配代码、可按 Server 粒度过滤暴露哪些工具。

常见故障模式

以下是最容易浪费时间的问题：

现象	可能原因	解决方法
Hermes 启动但回复为空或异常	Provider 认证或模型选择有误	重新运行 hermes model，确认 provider、模型和认证信息
自定义 endpoint "可用"但返回乱码	base URL、模型名称有误，或实际上不兼容 OpenAI	先用独立客户端验证该 endpoint
Gateway 启动但无法收到消息	Bot token、白名单或平台配置不完整	重新运行 hermes gateway setup 并检查 hermes gateway status
hermes --continue 找不到旧会话	切换了 profile 或会话从未保存	检查 hermes sessions list，确认你在正确的 profile 下
模型不可用或出现异常的故障转移行为	Provider 路由或故障转移设置过于激进	在基础 provider 稳定之前关闭路由
hermes doctor 标记配置问题	配置值缺失或已过期	修复配置，在添加功能前重新测试普通对话

恢复工具包

当感觉有问题时，按以下顺序操作：

1. hermes doctor
2. hermes model
3. hermes setup
4. hermes sessions list
5. hermes --continue
6. hermes gateway status

这个顺序能让你快速从"感觉哪里不对"回到已知的正常状态。

快速参考

命令	说明
hermes	开始聊天
hermes model	选择 LLM provider 和模型
hermes tools	配置每个平台启用的工具
hermes setup	完整配置向导（一次性配置所有内容）
hermes doctor	诊断问题
hermes update	更新到最新版本
hermes gateway	启动消息 gateway
hermes --continue	恢复上次会话