Hermes 的简单用法：安装 配置

Hermes 完整全流程手册

一、前置依赖

1. Node.js 18+（配套npm，用于全局安装Hermes CLI）
2. ≥ Python3.10（你本地Python3.13 + Miniconda）
3. Ollama（可选，本地离线模型使用）

二、Hermes CLI 本体安装 & 校验

1. 全局安装

# 卸载旧版本
pip uninstall -y hermes-agent
# 全局全新安装最新版
pip install hermes-agent

2. 验证安装成功

hermes --version

提示命令不存在：将npm全局路径加入系统Path，重启终端

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

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

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

适用：轻度网页可视化、查看会话/日志/模型配置

方式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 永久保存