快速开始

更喜欢观看视频？

Onchain AI Garage 整理了一份关于安装、配置及基础命令的大师级实操教程——如果你更倾向于跟随视频操作，它是本页面的绝佳伴侣。欲了解更多内容，请查看 完整的 Hermes Agent 教程与用例 播放列表。

适用人群

• 纯新手，且希望以最短路径完成可用配置。
• 正在更换服务商，且不想在配置错误上浪费时间。
• 正在为团队、机器人或全天候工作流设置 Hermes。
• 厌倦了 “安装成功了，但还是没反应” 的情况。

最快路径

选择符合你目标的行：

目标	第一步	第二步
只想让 Hermes 在机器上跑起来	hermes setup	进行一次真实对话并验证响应
已经确定了服务商	hermes model	保存配置，然后开始聊天
想要机器人或全天候运行设置	在 CLI 运行成功后执行 hermes gateway setup	连接 Telegram、Discord、Slack 或其他平台
想要本地或自托管模型	hermes model → 自定义端点	验证端点、模型名称和上下文长度
想要多服务商故障切换 (Fallback)	先执行 hermes model	仅在基础聊天可用后，再添加路由和切换功能

经验法则： 如果 Hermes 无法完成一次正常的聊天，请先不要添加更多功能。先确保能进行一次干净的对话，然后再叠加网关 (gateway)、定时任务 (cron)、技能 (skills)、语音 (voice) 或路由功能。

1. 安装 Hermes Agent

选项 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	基于订阅制，零配置	通过 hermes model 进行 OAuth 登录
OpenAI Codex	ChatGPT OAuth，使用 Codex 模型	通过 hermes model 进行设备代码验证
Anthropic	直接使用 Claude 模型 —— Max 方案 + 额外使用额度 (OAuth)，或按 Token 计费的 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_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
阿里云 (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 代理后端（启动本地 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	设置基础 URL + API 密钥

对于大多数初次使用的用户：选择一个服务商，除非你明确知道为什么要修改，否则请接受默认设置。包含环境变量和设置步骤的完整服务商目录请参考 服务商(Providers) 页面。

最小上下文要求：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 将敏感信息与普通配置分开存放：

• 敏感信息与 Token → ~/.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 模式（推荐）

你会看到一个欢迎横幅，显示当前模型、可用工具(tools)和技能(skills)。请使用一个具体且易于验证的提示词：

选择你的界面

Hermes 附带两种终端界面：经典的 prompt_toolkit CLI，以及支持模态叠加层、鼠标选择和非阻塞输入的现代 TUI。两者共享相同的会话、斜杠命令和配置 —— 你可以通过 hermes 和 hermes --tui 分别尝试。

• 用 5 个要点总结这个仓库，并告诉我也主入口点是什么。
• 检查我当前的目录，告诉我哪个看起来像是主项目文件。
• 帮我为这个代码库设置一个干净的 GitHub PR 工作流。

成功的标志：

• 横幅显示了你选择的模型/服务商。
• Hermes 正常回复，无报错。
• 如果需要，它可以调用工具（终端、读取文件、网页搜索）。
• 对话可以正常持续多轮。

如果这一切运行正常，那么你已经跨过了最难的部分。

4. 验证会话功能

在继续下一步之前，请确保能够恢复会话：

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

这应该带你回到刚刚进行的会话。如果没有成功，请检查你是否处于同一个配置文件 (profile) 中，以及会话是否实际保存。当你稍后需要在多个设置或机器之间切换时，这一点至关重要。

5. 尝试核心功能

使用终端

> 我的磁盘占用情况如何？显示前 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 在所有终端中均可使用。

中断智能体

如果智能体执行时间过长，直接输入新消息并按回车即可 —— 这会中断当前任务并切换到你的新指令。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 开始录音。详见 语音模式。

技能 (Skills)

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，确认服务商、模型和认证信息
自定义端点 “可用” 但返回废话	基础 URL、模型名称错误，或并非真正的 OpenAI 兼容接口	先在独立客户端中验证该端点
网关已启动但无人能发送消息	机器人 Token、白名单或平台设置不完整	重新运行 hermes gateway setup 并检查 hermes gateway status
hermes --continue 找不到旧会话	切换了配置文件或会话从未保存	检查 hermes sessions list 并确认你处于正确的配置文件中
模型不可用或出现奇怪的回退行为	服务商路由或回退 (Fallback) 设置过于激进	在基础服务商稳定前，保持路由功能关闭
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 服务商和模型
hermes tools	配置各平台启用的工具
hermes setup	完整设置向导（一次性配置所有内容）
hermes doctor	诊断问题
hermes update	更新至最新版本
hermes gateway	启动消息网关
hermes --continue	恢复上次会话

后续步骤

• CLI 指南 —— 精通终端界面
• 配置 —— 自定义你的设置
• 消息网关 —— 连接 Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, Teams 等
• 工具与工具集 —— 探索可用功能
• AI 服务商 —— 完整服务商列表及设置详情
• 技能系统 —— 可重用的工作流与知识库
• 技巧与最佳实践 —— 高级用户指南