快速开始

本指南会带你从零开始，完成一套经得起真实使用的 Hermes 配置：完成安装、选择大模型提供商（provider）、验证聊天可正常工作，并在出问题时知道该怎么处理。

这篇文档适合谁

刚开始接触，希望用最短路径完成可用配置的人
正在切换大模型提供商（provider），不想把时间浪费在配置错误上的人
想为团队、机器人或常驻运行工作流部署 Hermes 的人
已经受够“装好了，但还是什么都做不了”的人

最快路径

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

目标	先做这个	然后做这个
只想让 Hermes 在机器上跑起来	`hermes setup`	运行一次真实对话，验证能正常回复
已经知道自己要用哪个大模型提供商（provider）	`hermes model`	保存配置，然后开始聊天
想要一个 bot 或常驻运行的配置	CLI 能正常工作后运行 `hermes gateway setup`	连接 Telegram、Discord、Slack 或其他平台
想要本地或自托管模型	`hermes model` → 自定义端点	验证端点地址、模型名称和上下文长度
想要多提供商 fallback	先运行 `hermes model`	等基础聊天跑通后再添加路由和 fallback

经验法则： 如果 Hermes 连一段正常聊天都无法完成，就先不要继续叠加功能。先让一次干净的对话跑通，再去加网关、cron、技能、语音或路由。

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 guide，其中包含经过验证的手动安装路径、支持的 extra，以及当前 Android 特有的限制。

Windows 用户

请先安装 WSL2，然后在 WSL2 终端里运行上面的命令。

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

source ~/.bashrc   # or source ~/.zshrc

关于更详细的安装选项、前置要求和故障排除，请参阅 Installation guide。

2. 选择大模型提供商（provider）

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

hermes model

常见情况下的推荐默认方案：

场景	推荐方案
最少阻力	Nous Portal 或 OpenRouter
已有 Claude 或 Codex 的认证	Anthropic 或 OpenAI Codex
想要本地/私有推理	Ollama 或任何兼容 OpenAI 的自定义端点
想要多提供商路由	OpenRouter
有自定义 GPU 服务器	vLLM、SGLang、LiteLLM 或任何兼容 OpenAI 的端点

对于大多数第一次使用的人来说：先选一个大模型提供商（provider），除非你明确知道自己为什么要改，否则接受默认值就好。包含环境变量和配置步骤的完整大模型提供商（provider）目录可见 Providers 页面。

最小上下文：64K tokens

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

提示

你可以随时通过 hermes model 切换大模型提供商（provider），不存在锁定。完整的受支持大模型提供商（provider）列表及配置细节，请参阅 AI Providers。

配置是如何存储的

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

Secrets 和 tokens → ~/.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            # classic CLI
hermes --tui      # modern TUI (recommended)

你会看到一个欢迎横幅，其中显示当前模型、可用工具和技能。建议先用一个明确、容易验证结果的提示词：

选择你的界面

Hermes 自带两种终端界面：经典的 prompt_toolkit CLI，以及较新的 TUI，后者支持模态浮层、鼠标选择和非阻塞输入。两者共享相同的会话、斜杠命令和配置，你可以分别用 hermes 和 hermes --tui 试试看。

Summarize this repo in 5 bullets and tell me what the main entrypoint is.

Check my current directory and tell me what looks like the main project file.

Help me set up a clean GitHub PR workflow for this codebase.

成功的表现是：

横幅里显示了你选择的模型 / 大模型提供商（provider）
Hermes 可以正常回复且不报错
有需要时它能调用工具（终端、文件读取、网页搜索）
对话可以正常连续进行，不止一轮

如果这些都正常，你就已经跨过最难的部分了。

4. 验证会话是否可恢复

继续之前，先确认恢复会话可正常工作：

hermes --continue    # Resume the most recent session
hermes -c            # Short form

这应该会把你带回刚才的会话。如果没有，请检查自己是否还在同一个 profile 中，以及会话是否真的被保存了。等你开始同时管理多套配置或多台机器时，这一点会非常重要。

5. 试试关键功能

使用终端

❯ What's my disk usage? Show the top 5 largest directories.

agent 会代你执行终端命令并展示结果。

斜杠命令

输入 /，可以看到所有命令的自动补全下拉列表：

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

多行输入

按 Alt+Enter 或 Ctrl+J 可以换行。非常适合粘贴代码或撰写更详细的提示词。

中断 agent

如果 agent 花的时间太久，直接输入一条新消息并按回车即可。它会中断当前任务并切换到你的新指令。Ctrl+C 也可以。

6. 继续叠加下一层能力

前提是基础聊天已经跑通。接下来按需选择：

Bot 或共享助手

hermes gateway setup    # Interactive platform configuration

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

自动化和工具

hermes tools — 按平台调节工具访问权限
hermes skills — 浏览并安装可复用工作流
Cron — 请等到你的 bot 或 CLI 配置稳定之后再启用

沙盒终端

如果你更关注安全性，可以让 agent 运行在 Docker 容器或远程服务器中：

hermes config set terminal.backend docker    # Docker isolation
hermes config set terminal.backend ssh       # Remote server

语音模式

pip install "hermes-agent[voice]"
# Includes faster-whisper for free local speech-to-text

然后在 CLI 中执行：/voice on。按 Ctrl+B 开始录音。详见 Voice Mode。

技能

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

或者直接在聊天会话里使用 /skills。

MCP 服务器

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

编辑器集成 (ACP)

pip install -e '.[acp]'
hermes acp

详见 ACP Editor Integration。

常见故障模式

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

症状	可能原因	修复方法
Hermes 打开了但回复为空或出错	大模型提供商（provider）认证或模型选择错误	重新运行 `hermes model`，确认提供商、模型和认证信息
自定义端点"能用"但返回乱码	Base URL、模型名称错误，或实际上不兼容 OpenAI	先在独立的客户端验证端点
网关启动了但没人能给它发消息	Bot token、允许列表或平台配置不完整	重新运行 `hermes gateway setup` 并检查 `hermes gateway status`
`hermes --continue` 找不到旧会话	切换了 profile 或会话从未保存	检查 `hermes sessions list` 并确认你在正确的 profile 中
模型不可用或 fallback 行为异常	提供商路由或 fallback 设置过于激进	在基础提供商稳定之前不要开启路由
`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 指南 — 熟悉终端交互界面
Configuration — 自定义你的配置
消息网关 — 连接 Telegram、Discord、Slack、WhatsApp、Signal、Email 或 Home Assistant
AI 大模型提供商 — 查看完整的大模型提供商（provider）列表和配置细节
工具与工具集 — 探索可用能力
技能系统 — 了解可复用的工作流与知识组织方式
技巧与最佳实践 — 进阶使用技巧

这篇文档适合谁​

最快路径​

1. 安装 Hermes Agent​

2. 选择大模型提供商（provider）​

配置是如何存储的​

3. 运行第一次聊天​

4. 验证会话是否可恢复​

5. 试试关键功能​

使用终端​

斜杠命令​

多行输入​

中断 agent​

6. 继续叠加下一层能力​

Bot 或共享助手​

自动化和工具​

沙盒终端​

语音模式​

技能​

MCP 服务器​

编辑器集成 (ACP)​

常见故障模式​

恢复工具包​

快速参考​

下一步​