Hermes Agent 原理与实战——第2章 安装、配置与首次对话

本章将引导你从零搭建一套可投入实际使用的 Hermes Agent 运行环境。依次完成程序安装、选择模型 provider（服务提供商）配置、验证对话正常运行，同时介绍常见故障排查思路。

实操经验准则：若 Hermes 无法完成一轮完整对话，暂时不要添加更多功能。优先保证基础对话正常跑通，再逐步叠加网关（Gateway）、技能（Skills）、定时任务（Cron）、语音模块、路由分发等附加能力。

1. 安装 Hermes Agent 方案

当前 Hermes Agent 提供三类部署方案，按需选择：

• 命令行（CLI）版本：适合追求轻量化部署、或是需要将 Hermes 集成至自有工作流的用户。通过终端直接安装，配置灵活、资源占用更低。
• 官方 Hermes Desktop 桌面版：原生图形化客户端，采用 Electron 开发。本质为 CLI 封装的可视化外壳，不拓展内核底层能力，功能边界与命令行版本完全一致；安装时同时部署 Hermes CLI 环境，客户端仅作为可视化操作入口；整体使用上性能偏差，体积偏大。
• **中文社区桌面版（Hermes-CN-Desktop）：**国内开源社区维护的二次发行版。基于开源代码 Fork 深度本土化改造，并非 Nous Research 官方分支；针对国内用户优化交互体验、适配本土模型接口，新增多项易用性增强特性。

下面对这三种安装方式进行介绍。

2. 命令行（CLI）版本

2.1 安装命令行（CLI）版本

一、Linux / macOS/ WSL2 / Android (Termux) 用户

官方原版安装（跟踪 main 分支）：

1
2
3

# Linux / macOS / WSL2 / Android (Termux)
# 适合国际/ GitHub直连用户
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

国内镜像安装（速度最快）：

1
2

# 国内用户优先使用（解决GitHub下载慢问题）
curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

安装脚本会在 ~/.hermes/hermes-agent 创建一个受管理的隔离环境（独立的 uv 托管解释器和 venv），这是唯一受支持的安装方式 —— 包括开发用途。请勿使用 pip install hermes-agent。

安装程序自动处理一切：包括安装所有依赖（Python、Node.js、ripgrep、ffmpeg）、仓库克隆、虚拟环境、全局 hermes 命令配置。

执行以下操作：

1. 检测 / 装好 uv；
2. 用 uv 创建 Python 3.11 虚拟环境；
3. 装好 ripgrep、ffmpeg、Node.js；
4. 把仓库克隆到 ~/.hermes/hermes-agent/；
5. 在 ~/.hermes/hermes-agent/ 下执行 uv pip install -e ".[all]"；
6. 把 hermes 软链到 ~/.local/bin/hermes。

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

1
2

# Linux / macOS / WSL2 / Android (Termux) 方式安装
source ~/.bashrc   # 或 source ~/.zshrc

二、Windows 用户

1、基于 WSL2 安装（window下推荐）：

请先安装 WSL2 或查看Windows 10/11 安装 WSL2 指南，然后在 WSL2 终端中运行同上述 Linux / macOS命令。

1
2
3
4
5
6

# 以下二选一：
# 适合国际/ GitHub直连用户
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# 国内用户优先使用（解决GitHub下载慢问题）
curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

window下推荐 WSL2 原因：Hermes Agent 原生面向 Linux 环境设计，WSL2 提供了最接近生产部署环境的兼容性，避免 Windows 下的适配问题和"环境不一致"隐患。

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

1
2

# Linux / macOS / WSL2 / Android (Termux) 方式安装
source ~/.bashrc   # 或 source ~/.zshrc

2、基于Windows 原生 PowerShell 安装：

打开 PowerShell 并运行：

1
2
3
4

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

# 国内用户优先使用（解决GitHub下载慢问题）
irm https://res1.hermesagent.org.cn/install.ps1 | iex

安装程序处理一切：uv、Python 3.11、Node.js 22、ripgrep、ffmpeg，以及一个便携式 Git Bash（PortableGit——一个自包含的 Git-for-Windows 发行版，附带 bash.exe 和 Hermes 用于 shell 命令的完整 POSIX 工具链；在 32 位 Windows 上安装程序会回退到 MinGit，后者缺少 bash，终端工具和 agent 浏览器功能将被禁用）。它将仓库克隆到 %LOCALAPPDATA%\hermes\hermes-agent，创建虚拟环境，并将 hermes 添加到用户 PATH。安装完成后请重启终端（或打开新的 PowerShell 窗口）以使 PATH 生效。

2.2 首次启动与 setup 向导

1

hermes setup

setup 是个完整的交互式向导，按顺序引导你：

1. 从 OpenClaw 迁移（若检测到 ~/.openclaw），可跳过；
2. 选模型 Provider —— 可选 Nous Portal、OpenRouter、Anthropic、OpenAI、Z.AI/GLM、Kimi、MiniMax、DeepSeek、HuggingFace、自定义端点等；
3. 填 API Key（或走 OAuth，比如 Nous Portal、Anthropic Max、Codex、GitHub Copilot、MiniMax OAuth）；
4. 选默认 personality（可后续 /personality 切换）；
5. 配置 toolset（默认按平台预设启用一组合理工具）；
6. 可选：要不要现在就配 Gateway（Telegram/Discord 等）。

如需稍后重新配置单项设置，使用以下专用命令：

1
2
3
4
5
6

hermes model          # 选择 LLM 提供商和模型
hermes tools          # 配置启用的工具
hermes gateway setup  # 配置消息平台
hermes config set     # 设置单个配置项
hermes doctor         # 诊断问题
hermes setup          # 或运行完整的设置向导一次性配置所有内容

2.3 选择模型Provider

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

1

hermes model

最简路径：Nous Portal

Nous Portal 是 Hermes Agent 官方配套的统一订阅服务平台，由上游开发团队 Nous Research 运营。单次订阅即可访问 300 + 主流大模型，同时内置 Tool Gateway工具网关。

Tool Gateway 整合网页搜索、网页内容提取、图像生成、TTS 语音合成、云端浏览器自动化能力；启用后无需单独申请 Firecrawl、FAL、BrowserUse 等第三方服务的 API Key，所有工具调用统一通过 Nous 订阅结算。

一键初始化命令：

1	hermes setup --portal

该指令会自动唤起浏览器 OAuth 登录、将 Nous 设置为默认模型 Provider，并开启 Tool 网关，完成后可直接启动对话。

Hermes 原生内置 20 余家主流模型服务商直连适配：OpenAI、Anthropic、Google Gemini、DeepSeek、智谱 GLM、Kimi (Moonshot)、MiniMax、xAI Grok、通义千问、Ollama、NVIDIA NIM 等。

推荐默认选项：

对于大多数初次使用的用户：选择一个 provider，并设置API_KEY、API_BASE_URL（可选）即可。

这里示例是选择Deepseek 的模型deepseek-v4-pro，输入API key，从https://platform.deepseek.com/ 获取。

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

提示：可以随时通过 hermes model 切换 provider——没有锁定。

使用本地运行模型服务（Ollama）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 安装 Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# 拉取模型（如：Hermes 3 8B（Q4_K_M 量化），约 4.7GB，16GB 内存可跑）
ollama pull hermes3:8b
ollama serve    # 启动服务

# 配置 Hermes 使用本地 Ollama：
# 1、在 `hermes model` 中选择`custom`设置 base URL为 http://localhost:11434/v1
# 2、或编辑 ~/.hermes/.env，添加：
# OLLAMA_BASE_URL=http://localhost:11434/v1

2.4 验证安装

1
2
3
4

hermes --version      # 查看版本
hermes doctor         # 诊断环境（检查 12 项）
hermes status         # 查看当前配置
hermes dump           # 导出诊断信息（求助时用）

2.5 运行第一次对话

1
2
3

#开启聊天
hermes            # 经典 CLI
hermes --tui      # 现代 TUI（推荐)

你会看到一个欢迎横幅，显示你的模型、可用工具和 skills：

测试下响应，输入内容：

1

介绍下自己

2.6 尝试核心功能

使用终端

1

❯ 列一下当前目录有哪些文件，并总结下

Agent 会代你执行终端命令并显示结果。

斜杠命令

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

2.7 数据目录布局：~/.hermes/

所有用户级数据都在 $HERMES_HOME（默认 ~/.hermes/）下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

~/.hermes/
├── config.yaml             # 非机密配置
├── .env                    # 机密：API Key、Token、OAuth refresh token 等
├── SOUL.md                 # 人格/身份文件
├── memories/
│   ├── MEMORY.md           # 环境/约定记忆，约 800 token
│   └── USER.md             # 用户画像，约 500 token
├── skills/                 # 技能根目录
│   ├── plan/               # 内置：规划技能
│   ├── github-pr-workflow/ # 内置：GH PR 流
│   └── openclaw-imports/   # 从 OpenClaw 迁移过来的
├── hooks/                  # 网关 hooks（HOOK.yaml + handler.py）
├── plans/                  # /plan 技能输出位置
├── hermes.db               # SQLite：会话、任务、cron、轨迹
├── kanban.db               # SQLite：Kanban 任务
├── checkpoints/            # 文件改动 checkpoint 快照
├── plugins/                # 用户安装的插件
├── profiles/               # Profile 隔离目录（多份身份/配置）
├── logs/                   # 运行日志
└── hermes-agent/           # 源码（如果是用户级安装）

理解这套布局，后续做备份、迁移、Profile 切换都会得心应手。

2.8 Profile：一台机器运行多个身份

如果你希望在同一台机器上区分"工作 Hermes"和"个人 Hermes"，或者区分"中国区 Kimi"和"国际 Anthropic"，Profile 机制正是为此设计。

profile 是一个独立的 Hermes 主目录。每个 profile 拥有自己的目录，其中包含各自的 config.yaml、.env、SOUL.md、记忆、会话、技能、cron 任务和状态数据库。profile 让你可以为不同用途运行独立的 agent——编程助手、个人机器人、研究 agent——而不会混淆 Hermes 状态。

一、Profile 完全隔离范围

每个 Profile 在 ~/.hermes/profiles/<name>/ 下拥有完全独立的数据集合：

这意味着你可以为工作 Profile 配置 Anthropic Claude 模型和严谨的工具集，为个人 Profile 配置 OpenRouter 上的轻量模型和自由风格人格——两者在同一台机器上完全隔离、独立运行。

二、Profile 基本操作

1
2
3
4

hermes profile list              # 列出所有 Profile
hermes profile create work       # 创建名为 "work" 的新 Profile
hermes profile use work          # 切换到 work profile，后续命令均在其下
hermes profile use default       # 切回默认 Profile

也可以通过环境变量临时切换（仅在当次启动生效）：

1

HERMES_PROFILE=work hermes       # 仅本次启动使用 work profile

2.9 配置的存储方式

Hermes 将配置分为"机密"和"普通配置"两层，两者分开存储，分别写入 ~/.hermes/.env 和 ~/.hermes/config.yaml 两个独立文件。

• ~/.hermes/.env（机密）：所有密钥、Token 等敏感凭证，以 KEY=VALUE 格式存储，每行一条。
• ~/.hermes/config.yaml（非机密）：常规业务配置、非密钥配置，如：模型、toolset、UI 主题、cron、Gateway 等结构化配置。

通过 CLI 设置值是最简便的方式，执行命令时，Hermes 会自动识别配置属性，将参数写入对应的配置文件，避免人工操作失误：

1
2
3

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.yaml 使用 YAML 格式，承载所有非机密的配置项。以下是核心配置块的常见配置示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

# ==================== 模型与 Provider ====================
model: anthropic/claude-opus-4.6       # 主对话模型标识
provider: anthropic                     # Provider 标识

# 回退模型链（主模型不可用时的备选）
fallback_models:
  - openrouter/anthropic/claude-3.5-sonnet
  - openrouter/openai/gpt-5

# ==================== 终端后端 ====================
terminal:
  backend: docker                       # local | docker | ssh | modal | daytona | singularity
  cwd: "."                              # Gateway/cron 工作目录（CLI 使用启动目录）
  timeout: 180                          # 每条命令超时（秒）
  env_passthrough: []                   # 转发到沙箱执行的环境变量名
  docker:
    image: ghcr.io/nousresearch/hermes-sandbox:latest
    read_only: true
    docker_run_as_host_user: false      # 以宿主机用户身份运行容器
    docker_mount_cwd_to_workspace: false # 挂载当前目录到 /workspace
    docker_forward_env:                 # 转发到容器的环境变量
      - GITHUB_TOKEN
    docker_volumes:                     # 宿主机目录挂载
      - /home/user/projects:/workspace/projects
      - /home/user/data:/data:ro        # :ro 表示只读
  persistent_shell: true                # 保持长期运行的 shell 会话
  file_sync_max_mb: 100                 # 远程同步文件大小上限（MB）
  file_sync_enabled: true               # 会话结束时同步远程文件

# ==================== 工具集配置 ====================
toolsets:
  hermes-cli:
    - web
    - terminal
    - file
    - browser
    - vision
    - skills
    - memory
    - session_search
    - todo
    - clarify
    - code_execution
    - delegation
    - cronjob
  hermes-telegram:
    - web
    - search
    - terminal
    - file
    - vision
    - skills
    - memory
    - todo
    - send_message

配置优先级

当同一配置项存在于多个来源时，按以下优先级（从高到低）解析：

通用规则：敏感信息（API 密钥、Bot Token、密码）应存放在 .env 中。其余所有内容（模型、终端后端、压缩设置、记忆限制、工具集）应存放在 config.yaml 中。当两者同时设置时，config.yaml 对非敏感设置具有更高优先级。

2.10 升级：hermes update

1
2
3

hermes update          # 拉 main 并 uv pip install -e .[all]
hermes update --check  # 仅检查
hermes update --branch foo  # 切换分支

升级后建议：

1
2
3

hermes config check
hermes config migrate
hermes doctor

迁移会把老 schema 的 config.yaml 升级到新版本（保留你的所有自定义）。

2.11 排错：hermes doctor

hermes doctor 会逐项检查：

• Python / Node 版本；
• uv、ripgrep、ffmpeg 是否在 PATH；
• ~/.hermes/.env / config.yaml 是否可读、字段是否合法；
• 当前 Provider 的 Key 是否能成功 ping 接口；
• 模型上下文长度是否 ≥ 64K；
• 终端后端是否可用（docker daemon、ssh 通连、modal token 等）；
• Gateway 平台依赖是否齐全（如 discord.py[voice] for Discord VC）。

输出会逐条标红/标黄，并给出修复建议。如果你在 issues 里求助，附上 hermes doctor 的输出会大幅提升被回答的速度。

2.12 从 OpenClaw 迁移

如果你之前在用 OpenClaw：

1
2
3
4

hermes claw migrate              # 交互式迁移（full 预设）
hermes claw migrate --dry-run    # 只预览要迁哪些
hermes claw migrate --preset user-data   # 不带 secret
hermes claw migrate --overwrite  # 覆盖已存在

会迁移：SOUL.md、MEMORY.md、USER.md、用户技能（→ ~/.hermes/skills/openclaw-imports/）、命令白名单、IM 平台配置、TTS 资产、AGENTS.md、白名单内的 API Key。

2.13 卸载与重置

完全卸载：

1
2
3

rm -rf ~/.hermes
rm -f ~/.local/bin/hermes
# Root 安装：sudo rm -rf /usr/local/lib/hermes-agent /usr/local/bin/hermes

只重置配置而保留代码：

1
2
3

mv ~/.hermes/config.yaml ~/.hermes/config.yaml.bak
mv ~/.hermes/.env        ~/.hermes/.env.bak
hermes setup

2.14 一次完整的新机器开局演练

把上面的内容串起来，一次完整开局大约长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 1) 安装
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
# 国内用户优先使用安装命令（解决GitHub下载慢问题，替换上面一行）
# curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash
source ~/.bashrc

# 2) 初始化（选 模型provider，填 Key）
hermes setup

# 3) 先试一下能不能聊
hermes
> 介绍下？

# 4) 试一下 Agent 调工具
> 列一下当前目录有哪些文件，并总结下

# 5) 让它学一点关于你的事
> 我在 Ubuntu 22.04 上工作，喜欢简洁回答，项目都放在 ~/code/

# 6) 让它给自己写第一条记忆
> 把上面这些信息记到记忆里

# 7) 看看它写了啥
cat ~/.hermes/memories/MEMORY.md
cat ~/.hermes/memories/USER.md

# 8) 升级、体检
hermes update
hermes doctor

到这里你已经完成了"零基础上手"。

3. 官方 Hermes Desktop 桌面版

Hermes Desktop 是 Nous Research 官方推出的 Hermes Agent 原生图形桌面客户端，提供一站式可视化操作台：聊天交互、配置管理、智能体监控、任务调度、网关管理全部图形化操作，兼顾新手与开发者。与 Hermes CLI 共用同一套智能体内核、统一数据目录 ~/.hermes。桌面端与命令行完全互通，配置、对话会话、持久记忆、技能、API 密钥双向实时同步；会话支持跨界面接续，你可以在桌面发起对话，切换到终端 CLI 继续执行任务。

3.1 安装官方 Hermes Desktop 桌面版

安装官方 Hermes Desktop 桌面版，请从官网 Hermes Desktop 安装器 选择对应的系统版本下载并运行，会同时安装命令行与桌面应用。

安装程序运行后，显示界面如下：

点击Launch Hermes 按钮即可进入主界面。

3.2 配置模型provider

在聊天界面右上角，点击齿轮图标，进入配置界面：

首先配置model 提供商，点击左侧的Model选型，点击set up provider。

在弹出的界面中，如果没有找到需要的模型提供商，点击右下脚I have an API key 按钮。

选择对应的模型提供商，输入API key即可。

3.3 运行第一次对话

回答聊天主界面，在窗口下方对话输入框右侧，可以选择聊天的模型。

输入如：介绍下，能正常回复内容，则说明模型配置正确。

4. 中文社区桌面版（Hermes-CN-Desktop）

Hermes Agent CN Desktop（Hermes Agent 中文社区桌面版） 是 Hermes Agent 中文社区推出的桌面客户端，原生支持 Windows 与 macOS 系统。项目基于 Tauri v2、Rust、React 和 TypeScript 构建，包含 Hermes-CN-Core 中文社区修改版的 Hermes Agent 内核。

该项目并非 Nous Research 官方分支，针对国内用户优化交互体验、适配本土模型接口，新增多项易用性增强特性。

亮点：

• 一键安装，使用门槛极低：针对 Windows 和 macOS 用户适配，下载安装后配置 API Key 或本地模型端点即可使用。
• 轻量，跨平台：Tauri 使用系统 WebView，不需要随应用打包 Chromium，安装包体积小，支持 Windows 及 macOS。
• 内置独立 Hermes Agent 内核：桌面端支持安装、更新、签名校验、健康检查和回滚本地 Hermes Agent 内核。
• 面向 Agent 的完整 UI：支持聊天、流式输出、附件、MCP 工具、Skills、Memory、Profiles、定时任务、LaTeX/Mermaid 渲染和运行时健康面板。
• 中文模型与平台生态：覆盖主流云端模型服务商和 Ollama、vLLM、LM Studio、llama.cpp 等本地部署方案，并提供飞书等平台接入配置；
• 生产级传输桥：生产模式下通过 Rust command 代理 REST 与上传；Gateway 使用官方 /api/ws，打包态必要时通过 Rust WS 中继绕过 WebView 限制，并集中处理鉴权。
• YOLO 模式开关：「设置 → 常规」底部独立的「高风险操作」区提供开关，开启需二次确认，自动批准危险命令（对应后端 HERMES_YOLO_MODE），切换后自动重启内核生效，详见 docs/yolo-mode.md。

4.1 安装中文社区桌面版（Hermes-CN-Desktop）

1. 下载安装包

访问桌面版官网 desktop.hermesagent.org.cn 或 GitHub Releases 下载对应平台的安装包。

根据你的操作系统选择：

2. 安装

• Windows：双击 .exe 安装程序，按向导完成安装。
• macOS：打开 .dmg，将应用拖拽到 应用程序 文件夹。
• Linux：.deb 包使用 dpkg -i 安装；.AppImage 直接赋予执行权限后运行。

3. 首次启动初始化

安装完成后启动 Hermes，客户端会自动完成以下初始化步骤：

• 检测系统环境
• 下载/初始化 Hermes-CN-Core 内核
• 安装 Python 依赖与 Skills
• 配置运行环境

💡 耗时提示：全新环境首次安装可能需要 5~15 分钟（需下载 Python 运行时、ffmpeg、技能模块等）。

4.2 配置模型provider

安装完成后，首次启动显示界面如下：

需要配置至少一个 模型Provider 才能开始对话。Hermes-CN-Desktop 原生适配国内主流模型服务商及本地部署方案。

在配置页面，选择模型提供商（这里是deepseek）—>填写API key —>选择（或填写）模型ID—>保存配置，并测试连接—>连接成功后，设为当前模型即可。

4.3 运行第一次对话

配置完成后，回到工作台主界面，点击 新建对话 或直接在输入框中输入内容。

使用一个具体且易于验证的 prompt 来测试：

1

请检查当前的目录结构，总结当前文件夹的内容，

如果一切正常，你应该看到：

• Hermes 能够无错误地回复你的消息
• 需要时能够调用工具（如读取文件、执行终端命令、网页搜索）
• 对话可以正常进行多轮交互。

显示界面如下 ：

5. 常见报错速查

快速参考