Hermes Agent 中文文档
GitHub

快速上手

本指南将带你从零开始，完成一个能在实际使用中稳定运行的 Hermes 配置。包括安装、选择提供商、验证正常对话，以及遇到问题时的处理方法。

本文目标读者

  • 初次接触 Hermes，希望找到最短上手路径
  • 正在切换 LLM 提供商，不想在配置错误上浪费时间
  • 为团队、机器人或常驻工作流设置 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

:::tip Android / Termux 如果你在手机上安装，请参阅专门的 Termux 指南，了解已验证的手动安装路径、支持的扩展包以及当前 Android 特有的限制。

:::tip Windows 用户 请先安装 WSL2，然后在 WSL2 终端内运行上面的命令。
安装完成后，重新加载 shell：

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

详细的安装选项、前置要求和故障排除，请参阅安装指南。

2. 选择提供商

这是设置过程中最重要的一步。使用 hermes model 进行交互式选择：

hermes model

推荐的默认选择：

场景 推荐路径
最省事 Nous Portal 或 OpenRouter
已有 Claude 或 Codex 授权 Anthropic 或 OpenAI Codex
想要本地/私有推理 Ollama 或任何兼容 OpenAI 的自定义端点
想要多提供商路由 OpenRouter
拥有自定义 GPU 服务器 vLLM、SGLang、LiteLLM 或任何兼容 OpenAI 的端点

对于大部分首次使用的用户：选择一个提供商，除非你知道为什么要修改，否则接受默认设置。完整的提供商目录、环境变量和设置步骤请见 AI 提供商 页面。

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

你可以随时使用 `hermes model` 切换提供商——没有供应商锁定。所有支持的提供商和设置详情请见 [AI 提供商](../integrations/providers.html)。

设置存储方式

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

最简便的设置方式是通过 CLI：

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

hermes config set 会自动将值写入正确的文件。

3. 运行第一次对话

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

你会看到欢迎横幅，显示当前模型、可用工具和技能。使用具体且容易验证的提示词：

:::tip 选择界面 Hermes 提供两种终端界面：经典的 prompt_toolkit CLI 和更新的 TUI，后者支持模态覆盖层、鼠标选择和非阻塞输入。两者共享相同的会话、斜杠命令和配置——可以分别尝试 hermes 和 hermes --tui。 

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

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

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

成功标志：

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

4. 验证会话功能

在继续之前，确保会话恢复功能正常：

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

这应该能回到你刚才的会话。如果不行，检查你是否在同一个配置文件下，以及会话是否真的保存了。这在后续管理多个设置或多台机器时非常重要。

5. 尝试关键功能

使用终端

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

Agent 会代你运行终端命令并展示结果。

斜杠命令

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

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

多行输入

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

中断 Agent

如果 Agent 执行任务耗时过长，输入新消息并按 Enter——它会中断当前任务并切换到你的新指令。Ctrl+C 也有效。

6. 添加进阶功能

只有在基础对话正常工作后再添加。根据需求选择：

机器人或共享助手

hermes gateway setup    # 交互式平台配置

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

自动化与工具

沙盒终端

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

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

语音模式

pip install "hermes-agent[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）

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

详见 ACP 编辑器集成。

常见故障模式

这些问题最浪费时间：

现象 可能原因 解决方法
Hermes 打开但回复为空或乱码 提供商认证或模型选择错误 重新运行 hermes model，确认提供商、模型和认证信息
自定义端点"能用"但返回垃圾内容 基础 URL、模型名称错误，或不是真正的 OpenAI 兼容端点 先用其他客户端验证端点
网关启动了但没人能发消息 机器人令牌、白名单或平台设置不完整 重新运行 hermes gateway setup 并检查 hermes gateway status
hermes --continue 找不到旧会话 切换了配置文件或会话未保存 检查 hermes sessions list，确认你在正确的配置文件下
模型不可用或出现奇怪的故障转移行为 提供商路由或故障转移设置过于激进 在基础提供商稳定前保持路由关闭
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 恢复上次会话

下一步