Hermes 的简单用法(安装、配置)

Hermes 完整全流程手册

先说说这个工具的定位：一个能帮你统一管理多种AI模型的命令行助手，支持本地离线、云端聚合，还有好几种界面可以选择。无论你是习惯终端敲命令的老手，还是偏爱图形界面的新手，这套工具都能满足。下面咱们就把整个安装、配置、使用流程拆开来说清楚。

一、前置依赖

动手之前，先看看环境是否就绪：

1. Node.js 18+
   （配套npm一起装好，后面全局安装Hermes CLI要用的）

2. Python ≥ 3.10
   （你本地如果是Python 3.13 + Miniconda，完全OK）

3. Ollama
   （可选，用于本地离线模型，不想折腾云端的话这个挺实用）

二、Hermes CLI 本体安装 & 校验

1. 全局安装

先卸载掉旧版本，再装新的，干净利落：

pip uninstall -y hermes-agent
pip install hermes-agent

2. 验证安装成功

hermes --version

如果提示命令不存在，多半是npm全局路径没加到系统Path里，重启终端试试。

三、4种Hermes UI界面：安装、启动、使用

Hermes提供了四种不同的交互界面，覆盖从服务器到日常桌面的所有场景，按需选一种就行。

方式1：终端TUI（无需额外安装，开箱即用）

最轻量的方式，不需要装任何额外组件，装好Hermes本体就能用。

1. 基础启动：

hermes --tui
# 接续上次会话
hermes --tui --continue
# 开发调试模式
hermes --tui --dev

2. 默认永久开启TUI（省得每次都要加参数）：

# PowerShell临时生效
$env:HERMES_TUI=1
hermes
# 永久：系统用户变量新增 HERMES_TUI=1

3. 适用场景：服务器无图形界面、代码快速调试——终端党最爱。

方式2：内置Web Dashboard（自带，零额外安装）

同样不需要额外装东西，通过浏览器访问即可：

# 默认端口9119，自动弹出浏览器 http://127.0.0.1:9119
hermes dashboard
# 自定义端口
hermes dashboard --port 9120
# 不自动开浏览器
hermes dashboard --no-open
# 局域网其他设备访问
hermes dashboard --host 0.0.0.0 --port 9119

适用：轻度网页可视化、查看会话/日志/模型配置——比TUI直观，又比桌面端轻巧。

方式3：增强第三方WebUI（hermes-web-ui，功能完整版）

如果需要更丰富的管理功能，可以装这个增强版：

1. 安装：

npm install -g hermes-web-ui

2. 启动：

hermes-web-ui start  # 访问 http://localhost:8648

3. 备用方案——源码或Docker部署：

# 源码
git clone https://github.com/nesquena/hermes-webui.git
cd hermes-webui
.start.bat

# Docker
docker pull ghcr.io/nesquena/hermes-webui
docker compose up -d

适用：多项目管理、数据统计、团队局域网协作——适合进阶用户和团队使用。

方式4：Hermes Desktop 独立桌面GUI（Electron客户端）

如果你追求桌面应用的体验，还有一个独立的桌面客户端：

1. Ollama一键拉起：

ollama launch hermes-desktop --model llama3:8b

2. Windows exe安装包：双击桌面图标直接打开。

适用：高频日常使用，独立窗口、文件拖拽、系统通知——长期使用者首选。

UI选型速查表

UI类型	额外安装	最简启动命令	载体	适用场景
终端TUI	无需	hermes --tui	终端	开发、服务器
内置Dashboard	无需	hermes dashboard	浏览器9119	临时网页查看
增强WebUI	npm全局	hermes-web-ui start	浏览器8648	多项目/团队
Desktop桌面	exe安装包	双击图标	独立软件窗口	长期日常使用

四、Hermes 模型完整配置（核心新增章节）

模型配置是整个工具的灵魂，搞明白了后面才能用得顺手。这里把所有配置方式一次性讲清楚。

4.1 配置文件基础（Windows路径）

所有配置统一存放在用户目录的 .hermes 文件夹里，主要涉及两个文件：

1. config.yaml：持久化配置，存放默认模型、提供商、参数等（注意：不存密钥）。
2. .env：存放API Key、密钥、服务地址——敏感信息单独放，安全又清晰。
3. 一键打开编辑的方法：

hermes config edit
# 查看当前全部配置
hermes config show
# 配置健康自检（排查密钥/模型连通报错）
hermes doctor

4.2 四种模型配置操作方式（优先级：单次CLI > 会话临时 > 全局持久 > 配置文件）

方式1：交互式向导（新手推荐，全自动）

hermes model

流程很简单：选择提供商 → 填入API密钥 → 选择默认模型，一键写入配置+env文件，省心。

方式2：CLI命令快速设置（无需手动改文件）

# 设置全局默认模型+密钥示例
# OpenRouter聚合平台（200+模型，推荐）
hermes config set OPENROUTER_API_KEY sk-or-v1-xxx
hermes config set model 模型名称

# 本地Ollama离线模型（无需密钥）
hermes config set model ollama/qwen2.5:7b
hermes config set OPENAI_BASE_URL http://localhost:11434/v1

# DeepSeek国内大模型
hermes config set DEEPSEEK_API_KEY sk-xxx
hermes config set model deepseek/deepseek-chat

方式3：会话内动态切换（TUI/Web界面通用）

进入hermes聊天会话后，用斜杠命令切换模型，不需要退出当前对话：

# 仅当前会话生效，退出重置
/model ollama/llama3.2
# --global 永久保存为全局默认
/model openrouter/gemini-2.5-pro --global

方式4：手动编辑 config.yaml 完整模板

# ~/.hermes/config.yaml
model:
  provider: ollama  # openrouter / openai / anthropic / deepseek
  default: qwen2.5:7b
  base_url: http://localhost:11434/v1  # ollama本地地址，云端可删除
  temperature: 0.7  # 创造力参数
  max_tokens: 8000
# 多提供商统一配置
provider:
  default: openrouter
  models:
    ollama: llama3.2
    openrouter: anthropic/claude-3.5-sonnet
    deepseek: deepseek-chat
# 轻量辅助模型（识图、摘要、压缩对话）
auxiliary:
  vision:
    provider: openrouter
    model: gpt-4o-mini

密钥单独写入 .env：

# ~/.hermes/.env
OPENROUTER_API_KEY=sk-or-v1-xxxx
DEEPSEEK_API_KEY=sk-xxxx
ANTHROPIC_API_KEY=sk-ant-xxxx
# Ollama无需密钥

4.3 主流模型提供商一键配置模板

下面把几个常用提供商的配置方式单独列出来，照着做就行了。

1）本地 Ollama（离线免费，隐私优先）

1. 先启动ollama后台：ollama serve
2. Hermes配置：

hermes config set model ollama/qwen2.5:7b
hermes config set OPENAI_BASE_URL http://127.0.0.1:11434/v1

无需API Key，完全本地推理——隐私控的首选。

2）OpenRouter（聚合全平台模型，推荐）

1. 官网获取sk-or-v1密钥
2. 配置：

hermes config set OPENROUTER_API_KEY sk-or-v1-xxx
hermes config set model openrouter/anthropic/claude-3.5-sonnet

3）DeepSeek（国内友好、性价比高）

hermes config set DEEPSEEK_API_KEY sk-xxx
hermes config set model deepseek/deepseek-chat

4）OpenAI / Claude 直连

# OpenAI
hermes config set OPENAI_API_KEY sk-xxx
hermes config set model gpt-4o

# Claude
hermes config set ANTHROPIC_API_KEY sk-ant-xxx
hermes config set model claude-3.5-sonnet

4.4 启动UI时指定模型（单次生效，不修改全局配置）

如果你只是想临时换个模型试试，不用改配置，直接在启动命令里指定：

# TUI启动，临时使用本地ollama
hermes --tui --provider ollama --model llama3.2

# Web Dashboard启动，临时切换OpenRouter
hermes dashboard --model openrouter/gemini-2.5-pro

4.5 模型配置常见故障排查

1. 模型调用失败
   ：执行 hermes doctor 自动检测密钥、连通性、上下文长度，一步到位。

2. 切换模型重启失效
   ：单次CLI参数优先级高于配置文件，检查启动命令是否带了 --model。

3. Ollama连接超时
   ：确认 ollama serve 后台在运行，base_url地址写对了没。

4. API 401报错
   ：.env内密钥复制有误，重新执行 hermes config set 覆盖一下。

五、完整最简使用流程

最后，把整个流程浓缩成几步，照着做就能跑起来：

1. 安装Hermes：npm install -g @hermesai/cli
2. 配置模型（二选一）：
   • 本地离线：hermes model → 选择ollama，拉取qwen2.5
   • 云端聚合：hermes config set OPENROUTER_API_KEY xxx
3. 打开UI（按需选择）：
   • 终端调试：hermes --tui
   • 浏览器简易面板：hermes dashboard
4. 会话内切换模型：/model 模型名 --global 永久保存