快速入门

本指南带您从零开始搭建一个能够应对实际使用的 Hermes 环境。完成安装、选择提供商、验证聊天是否正常工作，并了解出现问题时该怎么处理。

更喜欢视频教程？

Onchain AI Garage 制作了一套涵盖安装、配置和基础命令的大师班演示——如果您更喜欢跟着视频操作，这是本页的绝佳补充。更多内容请查看完整的 Hermes Agent 教程与使用案例播放列表。

适合谁阅读

全新用户，想以最短路径完成配置
正在切换提供商，不想因配置错误浪费时间
为团队、机器人或全天候工作流搭建 Hermes
厌倦了"安装好了但什么都不做"的困境

最快路径

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

目标	首先做这件事	然后做这件事
我只想让 Hermes 在我的机器上运行	`hermes setup`	进行一次真实聊天并验证其响应
我已经知道要用哪个提供商	`hermes model`	保存配置，然后开始聊天
我想要机器人或全天候配置	CLI 正常运行后执行 `hermes gateway setup`	连接 Telegram、Discord、Slack 或其他平台
我想要本地或自托管模型	`hermes model` → 自定义端点	验证端点、模型名称和上下文长度
我想要多提供商故障转移	先执行 `hermes model`	基础聊天正常后再添加路由和故障转移

经验法则： 如果 Hermes 无法完成一次正常聊天，先不要添加更多功能。先让一次干净的对话跑通，再叠加网关、定时任务、技能、语音或路由。

1. 安装 Hermes Agent

运行一行安装命令：

# Linux / macOS / WSL2 / Android（Termux）
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Android / Termux

如果您在手机上安装，请参阅专用的 Termux 指南，了解已测试的手动安装路径、支持的额外功能以及当前 Android 特有的限制。

Windows 用户

请先安装 WSL2，然后在 WSL2 终端中运行上述命令。

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

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

详细的安装选项、前置条件和故障排查，请参阅安装指南。

2. 选择提供商

这是最重要的配置步骤。使用 hermes model 进行交互式选择：

hermes model

推荐选项：

提供商	介绍	配置方式
Nous Portal	订阅制，零配置	通过 `hermes model` 进行 OAuth 登录
OpenAI Codex	ChatGPT OAuth，使用 Codex 模型	通过 `hermes model` 进行设备码认证
Anthropic	直接使用 Claude 模型——Max 计划 + 额外用量积分（OAuth），或按量付费 API 密钥	`hermes model` → OAuth 登录（需要 Max + 额外积分），或 Anthropic API 密钥
OpenRouter	跨多种模型的多提供商路由	输入您的 API 密钥
Z.AI	GLM / 智谱托管模型	设置 `GLM_API_KEY` / `ZAI_API_KEY`
Kimi / Moonshot	Moonshot 托管的编程和聊天模型	设置 `KIMI_API_KEY`（或 Kimi-Coding 专用的 `KIMI_CODING_API_KEY`）
Kimi / Moonshot China	中国区 Moonshot 端点	设置 `KIMI_CN_API_KEY`
Arcee AI	Trinity 模型	设置 `ARCEEAI_API_KEY`
GMI Cloud	多模型直接 API	设置 `GMI_API_KEY`
MiniMax（OAuth）	通过浏览器 OAuth 使用 MiniMax-M2.7——无需 API 密钥	`hermes model` → MiniMax（OAuth）
MiniMax	国际 MiniMax 端点	设置 `MINIMAX_API_KEY`
MiniMax China	中国区 MiniMax 端点	设置 `MINIMAX_CN_API_KEY`
阿里云	通过 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`
自定义端点	VLLM、SGLang、Ollama 或任何 OpenAI 兼容 API	设置 base URL + API 密钥

对于大多数首次用户：选择一个提供商，除非您清楚为什么要更改，否则接受默认值。包含所有提供商环境变量和配置步骤的完整目录请访问提供商页面。

最小上下文：64K tokens

Hermes Agent 需要至少 64,000 tokens 上下文窗口的模型。上下文窗口较小的模型无法为多步骤工具调用工作流维持足够的工作记忆，将在启动时被拒绝。大多数托管模型（Claude、GPT、Gemini、Qwen、DeepSeek）都轻松满足此要求。如果您运行本地模型，请将其上下文大小设置为至少 64K（例如 llama.cpp 的 --ctx-size 65536 或 Ollama 的 -c 65536）。

提示

您可以随时通过 hermes model 切换提供商——没有锁定。完整的支持提供商列表和配置详情，请参阅 AI 提供商。

配置如何存储

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

密钥和令牌 → ~/.hermes/.env
非密钥配置 → ~/.hermes/config.yaml

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

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

3. 开始第一次聊天

hermes            # 经典 CLI
hermes --tui      # 现代 TUI（推荐）

您将看到包含模型、可用工具和技能的欢迎横幅。使用一个具体且易于验证的提示：

选择您的界面

Hermes 内置两种终端界面：经典的 prompt_toolkit CLI 和更新的带模态覆盖层、鼠标选择和非阻塞输入的 TUI。两者共享相同的会话、斜杠命令和配置——分别用 hermes 和 hermes --tui 体验一下。

用 5 条要点总结这个仓库，并告诉我主要入口点是什么。

检查我的当前目录，告诉我看起来是主项目文件的是什么。

帮我为这个代码库设置一个干净的 GitHub PR 工作流。

成功的标志：

横幅显示您选择的模型/提供商
Hermes 回复没有错误
如果需要，它可以使用工具（终端、文件读取、网络搜索）
对话可以正常进行多于一轮

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

4. 验证会话正常工作

在继续之前，确认恢复功能可以工作：

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

这应该将您带回刚才的会话。如果没有，请检查您是否在相同的配置文件中，以及会话是否实际保存了。这在您之后管理多个配置或多台机器时非常重要。

5. 尝试核心功能

使用终端

❯ 我的磁盘使用情况如何？显示最大的 5 个目录。

Agent 代表您运行终端命令并显示结果。

斜杠命令

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

命令	功能
`/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    # 交互式平台配置

连接 Telegram、Discord、Slack、WhatsApp、Signal、电子邮件、Home Assistant 或 Microsoft Teams。

自动化与工具

hermes tools — 按平台调整工具访问权限
hermes skills — 浏览和安装可复用工作流
定时任务 — 只在机器人或 CLI 配置稳定后使用

沙箱终端

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

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

语音模式

# 从 Hermes 安装目录（curl 安装程序将其放置在
# Linux/macOS 的 ~/.hermes/hermes-agent 或 Windows 的 %LOCALAPPDATA%\hermes\hermes-agent）：
cd ~/.hermes/hermes-agent
uv pip install -e ".[voice]"
# 包含 faster-whisper，提供免费本地语音转文字

然后在 CLI 中：/voice on。按 Ctrl+B 录音。参阅语音模式。

技能

hermes skills search kubernetes
hermes skills install openai/skills/k8s

或在聊天会话中使用 /skills。

MCP 服务器

# 添加到 ~/.hermes/config.yaml
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

编辑器集成（ACP）

ACP 支持随标准 [all] 额外组件一起提供，因此 curl 安装程序已经包含了它。只需运行：

hermes acp

（如果安装时没有 [all]，请先运行 cd ~/.hermes/hermes-agent && uv pip install -e ".[acp]"。）

参阅 ACP 编辑器集成。

常见失败模式

这些是最浪费时间的问题：

症状	可能原因	解决方法
Hermes 打开但回复为空或损坏	提供商认证或模型选择有误	重新运行 `hermes model` 并确认提供商、模型和认证
自定义端点"工作"但返回乱码	base URL、模型名称错误，或实际上与 OpenAI 不兼容	先在单独的客户端验证端点
网关启动但无人能发消息	机器人令牌、允许列表或平台配置不完整	重新运行 `hermes gateway setup` 并检查 `hermes gateway status`
`hermes --continue` 找不到旧会话	切换了配置文件或会话从未保存	检查 `hermes sessions list` 并确认您在正确的配置文件中
模型不可用或出现奇怪的回退行为	提供商路由或回退配置过于激进	在基础提供商稳定之前关闭路由
`hermes doctor` 标记配置问题	配置值缺失或过时	修复配置，在添加功能之前重新测试基础聊天

恢复工具包

当出现问题时，按此顺序操作：

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

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

快速参考

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

下一步

CLI 指南 — 掌握终端界面
配置 — 自定义您的设置
消息网关 — 连接 Telegram、Discord、Slack、WhatsApp、Signal、电子邮件、Home Assistant、Teams 等
工具与工具集 — 探索可用功能
AI 提供商 — 完整提供商列表和配置详情
技能系统 — 可复用的工作流和知识
技巧与最佳实践 — 高级用户技巧

更喜欢视频教程？​

适合谁阅读​

最快路径​

1. 安装 Hermes Agent​

2. 选择提供商​

配置如何存储​

3. 开始第一次聊天​

4. 验证会话正常工作​

5. 尝试核心功能​

使用终端​

斜杠命令​

多行输入​

中断 Agent​

6. 添加下一层功能​

机器人或共享助手​

自动化与工具​

沙箱终端​

语音模式​

技能​

MCP 服务器​

编辑器集成（ACP）​

常见失败模式​

恢复工具包​

快速参考​

下一步​