快速入门

本指南将引导您从零开始，搭建一个能够经受实际使用考验的Hermes系统。完成安装、选择服务提供商、验证聊天功能正常运行，并在遇到问题时准确知道该怎么做。

更喜欢观看视频？

Onchain AI Garage 制作了一系列关于安装、设置和基本命令的详细教程视频，如果您更倾向于通过视频学习，这是一个很好的配套资料。更多信息，请查看完整的Hermes智能体教程与用例播放列表。

适用人群

全新入门，希望找到最短路径快速搭建工作环境
切换服务提供商，希望避免配置错误导致的时间浪费
为团队、机器人或持续运行的工作流配置 Hermes
受够了"安装好了，但还是没反应"的情况

最快路径

选择与你的目标匹配的行：

目标	首先执行此操作	然后执行此操作
我只想让 Hermes 在我机器上运行起来	`hermes setup`	运行一次真实的聊天并验证它是否响应
我已知道我要用的提供商	`hermes model`	保存配置，然后开始聊天
我想要一个机器人或持续运行的设置	在 CLI 工作正常后运行 `hermes gateway setup`	连接 Telegram、Discord、Slack 或其他平台
我想要一个本地或自托管模型	`hermes model` → 自定义端点	验证端点、模型名称和上下文长度
我想要多提供商回退	先运行 `hermes model`	只有在基础聊天功能正常工作后，才添加路由和回退机制

经验法则： 如果 Hermes 无法完成一次正常的聊天，就不要急着添加更多功能。先确保一个干净、连贯的对话能够正常运行，然后再逐步叠加网关、定时任务、技能、语音或路由功能。

1. 安装 Hermes 智能体

选项 A — pip (最简单)：

pip install hermes-agent
hermes postinstall     # 可选：安装 Node.js、浏览器、ripgrep、ffmpeg + 运行设置

PyPI 发布版本跟踪标记的版本（主/次版本），而不是 main 分支上的每次提交。要获取最前沿版本，请使用选项 B。

选项 B — git 安装脚本 (跟踪 main 分支)：

# 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

一个订阅覆盖 300+ 个模型以及工具网关（网页搜索、图像生成、TTS、云浏览器）。在全新安装时：

hermes setup --portal

这会一次性完成登录、将 Nous 设为你的提供商，并启用工具网关。

好的默认选项：

提供商	简介	如何设置
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` (也接受 `Z_AI_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 前沿模型——无需 API 密钥（`hermes_cli/models.py` 中的模型名称可能在版本间变化）	`hermes model` → MiniMax (OAuth)
MiniMax	MiniMax 国际端点	设置 `MINIMAX_API_KEY`
MiniMax China	中国区 MiniMax 端点	设置 `MINIMAX_CN_API_KEY`
Alibaba Cloud	通过 DashScope 访问 Qwen 模型	设置 `DASHSCOPE_API_KEY` (Qwen 编码计划也接受 `ALIBABA_CODING_PLAN_API_KEY`)
Hugging Face	通过统一路由访问 20+ 开放模型 (Qwen, DeepSeek, Kimi 等)	设置 `HF_TOKEN`
AWS Bedrock	通过原生 Converse API 访问 Claude, Nova, Llama, DeepSeek	IAM 角色或 `aws configure` (指南)
Azure Foundry	Azure AI Foundry 托管的模型	设置 `AZURE_FOUNDRY_API_KEY` + `AZURE_FOUNDRY_BASE_URL`
Google AI Studio	通过直接 API 访问 Gemini 模型	设置 `GOOGLE_API_KEY` / `GEMINI_API_KEY`
Google Gemini (OAuth)	通过 `google-gemini-cli` OAuth 流程访问 Gemini——无需密钥	`hermes model` → Google Gemini (OAuth)
xAI	通过直接 API 访问 Grok 模型	设置 `XAI_API_KEY`
xAI Grok OAuth	SuperGrok / Premium+ 订阅，无需 API 密钥	`hermes model` → xAI Grok OAuth
NovitaAI	多模型 API 网关	设置 `NOVITA_API_KEY`
StepFun	Step Plan 模型	设置 `STEPFUN_API_KEY`
Xiaomi MiMo	小米托管的模型	设置 `XIAOMI_API_KEY`
Tencent TokenHub	腾讯托管的模型	设置 `TOKENHUB_API_KEY`
Ollama Cloud	托管的 Ollama 模型	设置 `OLLAMA_API_KEY`
LM Studio	本地桌面应用，提供 OpenAI 兼容 API	设置 `LM_API_KEY` (如果非默认，还需设置 `LM_BASE_URL`)
Qwen OAuth	Qwen Portal 浏览器 OAuth——无需 API 密钥	`hermes model` → Qwen OAuth
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 智能体后端 (启动本地 `copilot` CLI)	`hermes model` (需要 `copilot` CLI + `copilot login`)
自定义端点	VLLM, SGLang, Ollama，或任何 OpenAI 兼容 API	设置基础 URL + API 密钥

对于大多数初次用户：选择一个提供商，除非你清楚为什么要更改，否则接受默认值。完整的提供商目录，包括环境变量和设置步骤，请查看提供商页面。

最小上下文：64K tokens

Hermes 智能体要求模型至少具有 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个最大的目录。

智能体将代替你运行终端命令并显示结果。

斜杠命令

输入 / 可以看到一个所有命令的自动完成下拉菜单：

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

多行输入

按 Alt+Enter、Ctrl+J 或 Shift+Enter 可以添加新行。Shift+Enter 需要一个能将其作为不同序列发送的终端（默认支持 Kitty / foot / WezTerm / Ghostty；启用 Kitty 键盘协议后，iTerm2 / Alacritty / VS Code 终端也支持）。Alt+Enter 和 Ctrl+J 在所有终端中都有效。

中断智能体

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

6. 添加下一层

仅在基础聊天正常工作后进行。选择你需要的：

机器人或共享助手

hermes gateway setup    # 交互式平台配置

连接 Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant 或 Microsoft Teams。

自动化和工具

hermes tools — 为每个平台调整工具访问权限
hermes skills — 浏览并安装可重用的工作流
Cron — 仅在你的机器人或 CLI 设置稳定后使用

沙盒终端

出于安全考虑，在 Docker 容器或远程服务器中运行智能体：

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` 并确认提供商、模型和认证
自定义端点“有效”但返回乱码	错误的基地址、模型名称，或者实际上不兼容 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、Email、Home Assistant、Teams 等
工具和工具集 — 探索可用功能
AI 提供商 — 完整的提供商列表和设置详情
技能系统 — 可重用的工作流和知识
技巧和最佳实践 — 高级用户技巧

更喜欢观看视频？​

适用人群​

最快路径​

1. 安装 Hermes 智能体​

2. 选择提供商​

设置如何存储​

3. 运行你的第一次聊天​

4. 验证会话是否正常工作​

5. 尝试主要功能​

使用终端​

斜杠命令​

多行输入​

中断智能体​

6. 添加下一层​

机器人或共享助手​

自动化和工具​

沙盒终端​

语音模式​

技能​

MCP 服务器​

编辑器集成 (ACP)​

常见故障模式​

恢复工具包​

快速参考​

后续步骤​